Precaching assets: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(11 intermediate revisions by 9 users not shown)
Line 1: Line 1:
To provide a smooth loading of assets for a typical game session, it is important that the engine does as much work as possible to load those assets before the session begins. By doing this, the player's experience is not disturbed by interruptions as the engine tries to load assets in the middle of a session, often causing "hitching", lag or delays in rendering. With precaching, the assets are already loaded and are immediately ready for use. To do this, entities must declare and precache the assets they intend to use before the session starts. There are multiple utility functions in place to achieve this.
{{LanguageBar}}
{{tabsBar|main=gs|base=Precaching assets}}
To provide a smooth loading of assets for a typical game session, it is important that the engine does as much work as possible to load those assets before the session begins. By doing this, the player's experience is not disturbed by interruptions as the engine tries to load assets in the middle of a session, often causing "hitching", lag or delays in rendering. With precaching, the assets are already loaded and are immediately ready for use. To do this, [[entity|entities]] must declare and precache the assets they intend to use before the session starts. There are multiple utility [[function|functions]] in place to achieve this.


== Functions ==
== Functions ==
The <code>Precache()</code> function is available to all descendants of the <code>CBaseEntity</code> class and must be called in the <code>Spawn()</code> function of each entity. All assets used by the entity (models, sounds, VCD, decals) must be declared in this function to be used. Assets may not be precached outside of this function.   
The <code>Precache()</code> function is available to all descendants of the <code>CBaseEntity</code> class and must be called in the <code>Spawn()</code> function of each entity. All assets used by the entity ([[model|models]], [[sound|sounds]], [[VCD]], [[decal|decals]]) must be declared in this function to be used. Assets may not be precached outside of this function.   


Assets are precached using the functions described below.
Assets are precached using the functions below.


=== PrecacheModel ===
* [[PrecacheModel]]
Used to precache a model or material.
* [[PrecacheMaterial]]
<pre>
* [[PrecacheScriptSound]]
int CBaseEntity::PrecacheModel(
* [[PrecacheParticleSystem]]
    const char *name
* [[PrecacheStandardParticleSystem]]
)
* [[PrecacheGibsForModel]]
</pre>
* [[PrecacheFileWeaponInfoDatabase]]
'''Parameters'''
* [[PrecacheInstancedScene]]
* <i>name</i>
* [[PrecachePhysicsSoundByStringIndex]]
** Filename of the model to load
* [[PrecachePhysicsSounds]]
'''Return Value'''
* [[PrecachePointTemplates]]
* Reference index for the model.
* [[PrecacheVGuiScreen]]
* [[PrecacheVGuiScreenOverlayMaterial]]
* [[UTIL_PrecacheDecal]]
* [[UTIL_PrecacheOther]]
* [[UTIL_PrecacheOtherGrenade]]


=== PrecacheScriptSound ===
{{todo|transfer the remaining functions to their own articles}}
Used to precache a sound script as declared in a sound script file.
<pre>
void CBaseEntity::PrecacheScriptSound(
    const char *soundname
)
</pre>
'''Parameters'''
* <i>soundname</i>
** Name of sound script to precache.
'''Remarks'''
* Sound script must be declared in the sound script manifest document.         
'''Return Value'''
* None.


=== PrecacheInstancedScene ===
=== PrecacheInstancedScene ===
Line 42: Line 35:
</pre>
</pre>
'''Parameters'''
'''Parameters'''
* <i>pszScene</i>
* ''pszScene''
** Filename of the VCD to precache.
** Filename of the VCD to precache.
'''Return Value'''
'''Return Value'''
Line 56: Line 49:
</pre>
</pre>
'''Parameters'''
'''Parameters'''
* <i>szClassname</i>
* ''szClassname''
** Entity classname to precache assets for.
** Entity classname to precache assets for.
* <i>modelName</i>
* ''modelName''
** Model name to use for this entity.
** Model name to use for this entity.
'''Return Value'''
'''Return Value'''
Line 72: Line 65:
</pre>
</pre>
'''Parameters'''
'''Parameters'''
* <i>name</i>
* ''name''
** Name of the decal to precache.
** Name of the decal to precache.
* <i>preload</i>
* ''preload''
** Whether or not to preload this decal.
** Whether or not to preload this decal.
'''Return Value'''
'''Return Value'''
Line 84: Line 77:
* IVEngineServer::PrecacheDecal
* IVEngineServer::PrecacheDecal
* IVEngineServer::PrecacheGeneric
* IVEngineServer::PrecacheGeneric
== Forcing Precache ==
If you have an entity you will be creating that isn't explicitly placed in the level, you can force precaching by modifying <tt>InitBodyQue</tt> as follows:
<pre>
void InitBodyQue()
{
  CBaseEntity *pEnt = CreateEntityByName("my_entity");
  if ( pEnt )
  {
    pEnt->Precache();
    UTIL_Remove(pEnt);
  }
}
</pre>
Alternatively, certain entities like the player use the PRECACHE_REGISTER definition to force precache.


== Defines ==
== Defines ==
* PRECACHE_WEAPON_REGISTER
* PRECACHE_WEAPON_REGISTER
* CLIENTEFFECT_REGISTER_BEGIN
* CLIENTEFFECT_REGISTER_BEGIN
{{otherlang:en}}
{{otherlang:en:ru|Precaching Assets:ru}}


[[Category:Programming]]
[[Category:Programming]]

Latest revision as of 09:46, 16 March 2025

English (en)Translate (Translate)

To provide a smooth loading of assets for a typical game session, it is important that the engine does as much work as possible to load those assets before the session begins. By doing this, the player's experience is not disturbed by interruptions as the engine tries to load assets in the middle of a session, often causing "hitching", lag or delays in rendering. With precaching, the assets are already loaded and are immediately ready for use. To do this, entities must declare and precache the assets they intend to use before the session starts. There are multiple utility functions in place to achieve this.

Functions

The Precache() function is available to all descendants of the CBaseEntity class and must be called in the Spawn() function of each entity. All assets used by the entity (models, sounds, VCD, decals) must be declared in this function to be used. Assets may not be precached outside of this function.

Assets are precached using the functions below.

Todo: transfer the remaining functions to their own articles

PrecacheInstancedScene

Used to precache a VCD file. 

void PrecacheInstancedScene(
     char const *pszScene
)

Parameters

  • pszScene
    • Filename of the VCD to precache.

Return Value

  • None.

UTIL_PrecacheOther

Utility function that will call the Precache() function for an entity that will be referenced or created during the lifetime of the calling entity. This is often used for weapons that will create a child entity (like a grenade) dynamically during the course of a session. 

void UTIL_PrecacheOther(
     const char *szClassname,
     const char *modelName
)

Parameters

  • szClassname
    • Entity classname to precache assets for.
  • modelName
    • Model name to use for this entity.

Return Value

  • None.

UTIL_PrecacheDecal

Used to precache a decal. 

int UTIL_PrecacheDecal(
     const char *name,
     bool preload
)

Parameters

  • name
    • Name of the decal to precache.
  • preload
    • Whether or not to preload this decal.

Return Value

  • Reference index for the decal model.

More

  • IEngineSound::PrecacheSound
  • IVEngineServer::PrecacheSentenceFile
  • IVEngineServer::PrecacheDecal
  • IVEngineServer::PrecacheGeneric

Forcing Precache

If you have an entity you will be creating that isn't explicitly placed in the level, you can force precaching by modifying InitBodyQue as follows: 

void InitBodyQue()
{
  CBaseEntity *pEnt = CreateEntityByName("my_entity");
  if ( pEnt )
  {
    pEnt->Precache();
    UTIL_Remove(pEnt);
  }
}

Alternatively, certain entities like the player use the PRECACHE_REGISTER definition to force precache.

Defines

  • PRECACHE_WEAPON_REGISTER
  • CLIENTEFFECT_REGISTER_BEGIN
Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Precaching_assets&oldid=466852"