Add precache-resources-plugin/en.md
Browse Source
Daemon666 committed
parent c11719f9d8
commit 3b8df49f98f8817c86ce95c644b860ff1e8b1ca7
1 changed file
with 70 additions and 0 deletions
precache-resources-plugin/en.md
A
| @@ -0,0 +1,70 @@ | ||
| 1 | +--- | |
| 2 | +title: "Precaching Models, Sounds and Sprites Correctly" | |
| 3 | +excerpt: "Precache models, sounds, sprites and generic files in plugin_precache, understand the path rules, and avoid the precache overflow that crashes map load." | |
| 4 | +category: "plugin-dev" | |
| 5 | +tags: "precache, amxmodx" | |
| 6 | +image: "" | |
| 7 | +read_time: "7 min read" | |
| 8 | +--- | |
| 9 | +<p>If a plugin plays a custom sound, spawns a custom model, or draws a sprite, the file has to be <em>precached</em> — registered with the engine at map start so it gets an index and is offered to clients. Precache in the wrong place, or with the wrong path, and you get one of two failures: a silent no-op where nothing plays, or a hard <code>Host_Error</code> that kills the map. This guide covers the three precache natives, their path rules, and the overflow that catches everyone eventually.</p> | |
| 10 | + | |
| 11 | +<h2>1. Precache in plugin_precache, never later</h2> | |
| 12 | +<p>The engine only accepts precache calls during initialization. AMXX gives you exactly one place: the <code>plugin_precache()</code> forward, which runs before the map spawns entities. Calling a precache native from <code>plugin_init</code>, a command handler, or a task is too late and errors:</p> | |
| 13 | +<pre>#include <amxmodx> | |
| 14 | + | |
| 15 | +new g_smokeSpr | |
| 16 | + | |
| 17 | +public plugin_precache() | |
| 18 | +{ | |
| 19 | + precache_model("models/csb/w_medkit.mdl") | |
| 20 | + precache_sound("csb/heal.wav") | |
| 21 | + g_smokeSpr = precache_model("sprites/smoke.spr") | |
| 22 | +} | |
| 23 | + | |
| 24 | +public plugin_init() | |
| 25 | +{ | |
| 26 | + register_plugin("Precache Demo", "1.0", "CSB") | |
| 27 | +}</pre> | |
| 28 | +<p>Store the returned index for anything you reference later by number — sprites used in temp-entity messages, for instance, are addressed by their precache index, not their path.</p> | |
| 29 | + | |
| 30 | +<h2>2. The path rules differ per native</h2> | |
| 31 | +<p>This is the detail that wastes the most time. The base folder is different for models and sounds:</p> | |
| 32 | +<table> | |
| 33 | +<thead><tr><th>Native</th><th>Path is relative to</th><th>Example</th></tr></thead> | |
| 34 | +<tbody> | |
| 35 | +<tr><td><code>precache_model</code></td><td><code>cstrike/</code></td><td><code>"models/csb/w_medkit.mdl"</code></td></tr> | |
| 36 | +<tr><td><code>precache_sound</code></td><td><code>cstrike/sound/</code></td><td><code>"csb/heal.wav"</code> (no <code>sound/</code> prefix)</td></tr> | |
| 37 | +<tr><td><code>precache_generic</code></td><td><code>cstrike/</code></td><td><code>"sprites/csb/hud.txt"</code></td></tr> | |
| 38 | +</tbody> | |
| 39 | +</table> | |
| 40 | +<p>Models and sprites (both <code>.mdl</code> and <code>.spr</code> go through <code>precache_model</code>) include the folder from <code>cstrike/</code>. Sounds do <strong>not</strong> include <code>sound/</code> — the engine adds it. Writing <code>precache_sound("sound/csb/heal.wav")</code> looks for <code>sound/sound/csb/heal.wav</code> and fails silently.</p> | |
| 41 | + | |
| 42 | +<h2>3. Playing what you precached</h2> | |
| 43 | +<p>A precached sound plays with <code>emit_sound</code> or a client command; the path matches what you precached (again, no <code>sound/</code> prefix for <code>emit_sound</code>):</p> | |
| 44 | +<pre>public heal_effect(id) | |
| 45 | +{ | |
| 46 | + emit_sound(id, CHAN_ITEM, "csb/heal.wav", VOL_NORM, ATTN_NORM, 0, PITCH_NORM) | |
| 47 | +}</pre> | |
| 48 | +<p>A model is assigned by writing the path into an entity's <code>model</code>, or by index for effects. A sprite drawn via a temp entity uses the stored index:</p> | |
| 49 | +<pre>// example: reference the precached sprite by its saved index | |
| 50 | +// (inside a TE message you would write g_smokeSpr as the sprite index)</pre> | |
| 51 | + | |
| 52 | +<h2>4. precache_generic for FastDL and non-auto files</h2> | |
| 53 | +<p>Files the engine does not precache automatically — a sprite referenced only inside an event file, a <code>.txt</code>, extra sounds — still need to be offered to clients for download. <code>precache_generic</code> registers them so they are added to the download list without being loaded as a model or sound. This is how custom-content plugins make sure clients actually receive their files over <a href="/tutorials/fix-fastdl-not-working">FastDL</a>.</p> | |
| 54 | + | |
| 55 | +<h2>5. The overflow that crashes map load</h2> | |
| 56 | +<p>The engine caps how many models and sounds can be precached (historically around 512 models). Every plugin that precaches adds to a <em>shared</em> pool — so a server running twenty content plugins can blow the limit even though no single plugin is unreasonable. When it overflows, map load dies with a message like:</p> | |
| 57 | +<pre>Host_Error: PF_precache_model_I: Model 'models/...' failed to precache because the item count is over the 512 limit.</pre> | |
| 58 | +<p>The fixes are real work, not a flag: remove duplicate precaches (two plugins caching the same model both count), drop unused content, or move rarely-used models to load-on-demand designs. The dedicated walkthrough is <a href="/tutorials/fix-model-overflow-precache">the precache/model overflow fix</a>.</p> | |
| 59 | + | |
| 60 | +<h2>Common errors</h2> | |
| 61 | +<ul> | |
| 62 | +<li><strong>Sound never plays, no error</strong> — you included <code>sound/</code> in the path. Drop it; <code>precache_sound</code> and <code>emit_sound</code> are relative to <code>sound/</code> already.</li> | |
| 63 | +<li><strong><code>failed to precache</code> on map load</strong> — either the file is missing on the server, or you hit the overflow limit. Confirm the file exists at the exact path first, then count total precaches.</li> | |
| 64 | +<li><strong>Model shows as a big red ERROR in-game</strong> — the <code>.mdl</code> was precached but the client never downloaded it. It needs to be on FastDL and, for some files, registered with <code>precache_generic</code>.</li> | |
| 65 | +<li><strong>Precache call from a command or task</strong> — it is ignored or errors. All precaching must happen in <code>plugin_precache</code>.</li> | |
| 66 | +<li><strong>Case-sensitivity on Linux</strong> — <code>Heal.wav</code> and <code>heal.wav</code> are different files on a Linux server. Match the case exactly.</li> | |
| 67 | +</ul> | |
| 68 | + | |
| 69 | +<h2>Verification</h2> | |
| 70 | +<p>Load the plugin, change the map, and watch the server console during load for any <code>failed to precache</code> line — that is your first signal. In-game, trigger the sound and confirm it plays, and confirm the model renders instead of an ERROR sign. To audit total precache pressure across all your plugins, count how many models and sounds each one caches; the overflow is cumulative. For the deep dive on hitting the limit, see <a href="/tutorials/fix-model-overflow-precache">fixing model/precache overflow</a>.</p> | |
| 0 | 71 |
