Script Caching

From NWN Lexicon
Jump to: navigation, search


This no longer functions in NWN:EE and will be removed from the toolset view at some point. One major reason is as the below states, it can decrease performance since the game can manage loading scripts into memory itself more effectively.

Script Caching

What it is:

Script caching refers to assigning certain scripts to a cache, so that they are held in RAM while the game is running to decrease the time it takes to call them up to execute. This is because scripts held in RAM fire much faster than scripts on the hard drive. Thus, the more frequently a script is called, the more time is saved by caching it. Why then, would you not cache all scripts? Because there's a finite amount of RAM, and it's needed for many things. Filling it with cached scripts prevents it from being used for those other things.

Why you should no longer cache scripts in NWN-Server:
Tutorial script-cache.jpg

Script caching is accomplished by placing names of scripts into the Edit/Cached Scripts tab in the toolset. The toolset instructions on that tab indicate that frequently executed scripts should be cached in order to 'improve server performance'. THIS IS NO LONGER ACCURATE. In 1.65, Bioware added an autocacher to NWN-Server to handle this functionality. Yet script caching still has its - limited - uses for single player (SP) modules, e.g. modules that are exclusively run by the NWN-client. Therefore the "Cached Scripts" tab and instructions were not removed. Unfortunately the instructions have not been updated to make it clear, that caching scripts for a multiplayer (MP) module (e.g. a module hosted by NWN-Server) actually hurts server performance. If you are hosting a MP module through NWN-Server, ADDING ANY SCRIPTS AT ALL TO THE CACHE LIST WILL HURT SERVER PERFORMANCE, BECAUSE THEY WILL OCCUPY MEMORY THAT NWN-SERVER COULD HAVE USED FOR OTHER PURPOSES.

While there has been some debate on the Bioware forums about this, none of it is well founded. I personally spent literal weeks testing and profiling (NWN-Server performance) to hone my cache, using the NWNX Profiler and two months of profiling logs from two different servers hosting the same module (at no small cost to performance during those months), and including scripts from the most fired to the least, beginning with the 3000 kilobytes recommended by the (now inaccurate) Cached Scripts tab, and reducing it from there to the point of optimal server performance, at roughly 2100 kilobytes. Then Georg Zoeller informed me that it was no longer necessary to cache scripts for modules hosted by NWN-Server, and I removed all my cached scripts, which resulted in a MASSIVE performance increase. Here is the link to that post (specifically Georg's second post):

In short, there's no logical reason to believe you can outperform the autocacher of the NWN-Server, and even extraordinary amounts of work failed to do so in my case. In summary: If you host a module with NWN-Server, just do not cache scripts - if you do, you're shooting yourself in the foot.

-- FunkySwerve

NOTE: This is the updated Script Caching tutorial from the 1.64 version of the Lexicon. As mentioned in the new tutorial above, this information is only relevant for SP modules run exclusively by the NWN-client. It is obsolete for MP modules hosted by NWN-Server from version 1.65 forward.

When you try to decide which scripts to use with the script caching feature (Module->Properties->Cached Scripts) you'll need to know how it works:

To put it simply, this functionality allows you to cache compiled scripts (.ncs) into RAM, thus speeding up their execution time.
According to tests done by a community member on a SP module run by the NWN-client (patch 1.68 and 1.69), calling a (trivial) non-cached script via ExecuteScript() blocks the client for roughly 10 msec, wherease calling the same (trivial) cached script via ExecuteScript blocks the client for roughly 2.5 msec. More information about the relative performance of various nwnscript functions run by the NWN-client can be found under the following link:


Do cache those scripts that are used most frequently in your SP module. For example onHeartbeat scripts, onSpawn scripts for commonly used monsters and so on should be cached, whereas caching an onRested event script may not yield any noticeable performance increase at all.

Do cache scripts ONLY FOR SINGLE PLAYER (SP) modules. Multiplayer (MP) modules hosted by NWN-Server use an autocaching mechanism from patch 1.65 onwards, which by far outperforms any manual caching strategy you can hope to implement! However, for SP modules (run by the NWN-client) access time to scripts held in memory (ie caching) is faster - roughly a factor of 4 - than access time to scripts on a harddrive. So, the more often a script is called (by a player, a creature, etc), the more performance gain you get.


Don't cache '#include' files. They are not actually compiled as such, in fact they can't be, as there is no 'void main' function. The '#include' files are actually treated as if they are part of the script that uses them, and are compiled as part of that script. So for example, nw_i0_spells is used in many of the nw_s?_* spellscripts, so a copy of the code in nw_i0_spells is placed inside every nw_s?_* spellscript that '#includes' that file and then the whole script is compiled.

Don't cache too many scripts. Each cached script takes up a little bit of RAM on your computer, so, the more RAM you have, the more scripts you can cache. However, just because you can, it doesnt mean you should. Cache too many scripts, and the game might actually run more slowly. Also, when you distribute your module don't forget that other players may have less memory on their machine than you do. According to past experience, allocating a total of 2000K to 3000K for all of your cached scripts has proven to be a decent choice. Now that RAM has become cheap and plentiful, you might be able to allocate more. However, this has not been tested.

 author: FunkySwerve, Georg Zoeller, motu99, editor: Grimlar, Mistress, contributor: Kookoo