NWScript Accelerator plugin release thread

[Skywing]

This plugin transparently improves the performance of NWScript by completely replacing the server's NWScript interpreter a new script execution environment that turns compiled NWScript files (*.ncs) into native code. Once converted to native code, scripts run much faster. Scripts that are computationally heavy are most likely to see benefits out of the plugin. No changes to scripts are necessary to observe performance benefits with this plugin. Because the plugin recompiles scripts from *.ncs files to native code on each server startup, there are no extra steps to follow when updating scripts on your module.

The plugin also fixes a bug in the server where CPU and memory usage when the server has no players in it gradually increases over time until a player logs in.

The plugin also enables you to write scripts in C# code (or other CLR languages). This allows much more advanced scripts that can access threading, native sockets, or other extended capabilities. More details about this feature set can be found in this thread. To enable CLR scripts, you must set AllowManagedScripts=1 in the plugin INI file. This option is disabled by default.

Additionally, the plugin includes an enhanced script profiling system that can be used to judge the performance of scripts. The documentation in the plugin package describes how to use the profiling capability (several sample profiler scripts are included).

Installing the plugin will increase memory usage of the nwn2server process for the native code versions of compiled scripts. The plugin represents a trade-off between available memory and script performance. Generally, you can expect that each unique script (*.ncs file) that you run on your server will consume between 64k and 128k of additional memory (the charge is effective the first time the script in question is run since server startup, and not on each run of the script).

There are configuration settings described in the documentation that you can use to tune the plugin's memory usage. The plugin log file includes detailed information about memory usage per script. Additionally, I recommend installing the latest version of xp_bugfix, which for many configurations will free up to 700MB more memory in the server process. Both plugins can be used together, though you must install the dependencies for both plugins if you are going to use both (which is recommended).

The plugin requires that you install the Visual C++ 2010 SP1 runtimes and the .NET 4.0 runtime. Please read the installation instructions included in the zip file.

Plugin version Feb 4 2012 14:33:14 (release 7) + installation instructions:
http://www.nynaeve.net/Skywing/nwn2/xp_AuroraServerNWScript/AuroraServerNWScript.zip

Source code for plugin: http://valera-ext.nynaeve.net/~skywing/nwn2/AuroraServerNWScriptSrc.zip

(Some libraries from the NWN2 Datafile Accessor Library package are used; a link to the source code for those libraries is included in the readme.)

Internally, the plugin works by turning compiled NWScript script files (*.ncs) into .NET MSIL instructions, which the .NET runtime JIT's to native code. Scripts are compiled to native code on the fly the first time they are used by the server in a particular session, so there is no extra step required to update scripts on the module (other than to restart the server).

There are not believed to be any compatibility issues with the alternate interpreter (Ruby/Java) plugins, though only the performance of NWScript scripts is improved.

The plugin allows non-standard compiler extensions, like #define and #ifdef, to be used in GUI, StartingConditional, and other server-compiled scripts. For more information, download the Advanced Script Compiler.

The plugin also fixes several other issues:

- Some unused debugging code in the server causes the server's CPU and memory usage to gradually rise while no players are logged on (dropping off again once a player logs on). This has been an issue in the game since 1.00; the plugin fixes this bug.
- The plugin fixes issues where malformed scripts can crash the server (or worse) through execution stack mismanagement. This has been a problem since 1.00.
- The plugin fixes an issue where using ExecuteScript on a script that takes parameters may crash the server, or cause garbage data to be returned for script arguments. It is still not recommended to rely on this, as servers without the plugin won't work correctly here. This has been a problem since 1.00.

Changelog:

Release 0:

- Initial release

Release 1:

- Fix for code generation issue with scripts that call engine functions taking action-typed arguments and which return an engine structure.

Release 2:

- Fix for similar code generation issue with scripts that call engine functions taking action-typed arguments and which return strings.
- Improved code quality of execution guards (recursion and infinite loop checks).
- Enabled optional, experimental support for the NWScript IR analyzer (set OptimizeIR=1 in AuroraServerNWScript.ini). Please note that the optimization feature is experimental. It may reduce memory usage somewhat, but the .NET Framework is expected to already provide strong optimization to begin with.
- Enabled debug symbols (*.ndb) loading (on by default, controlled via LoadDebugSymbols=0|1 in AuroraServerNWScript.ini). If debug symbols are loaded, stack traces from the JIT engine include symbolic function names.
- Execution errors reported by the reference VM (UseReferenceVM=1) now include a stack trace, similar to that reported by the JIT engine. The stack trace will display symbolic function names if debug symbols were loaded.
- Execution tracing with the reference VM (UseReferenceVM=1) now displays the symbolic function name containing the current program counter if debug symbols were loaded.

Release 4:

- Disabled use of collectable assemblies by the JIT engine to work around a bug in the 4.0 CLR. This means that reloading scripts via the clear script cache command will now leak memory (but avoids a stability issue during code generation). Only users that explicitly use the NWNX4 script function to clear the script cache (added with the plugin) are impacted; currently, there are no known users of this particular functionality as it is primarily oriented towards dev and test scenarios for rapid testing of new scripts.
- Changed code generation to generate action service handler stubs for action services that require the 'slow' call path (those that take or return an engine structure). This reduces code size (memory usage) and allows for easier reading of the IL disassembly of a JIT'd script.
- Fixed a problem where the code size for a script being JIT'd wasn't properly being initialized in all cases. This would very rarely result in a refusal to execute a script (the problem would be readily apparent if one were impacted by it, as all scripts would fail to run).
- If script situation creation failed (low memory or a problem with the script itself), the state of the VM stack was not being properly rolled back for the server to continue. This has been fixed.

Release 5:

- New feature: The Advanced Script Compiler's non-standard compiler extensions can now be used for scripts that enforce parameter checking (most commonly, GUI scripts and StartingConditional scripts, as well as module OnChat scripts and any script used with ExecuteScriptEnhanced). These extensions include basic #ifdef support, greatly expanded internal compiler limitations on the number of constants and variables that can be defined, and many other improvements.
* Detail: The plugin disables parameter checking in the server. The parameter checking breaks with non-standard extensions as the OEI implementation required the server to be able to partially compile scripts on the fly to extract parameter information. The plugin has always supplanted the built-in parameter checking with a version derived from static analysis on the compiled script; this change simply turns off the server's built-in script parse check. Previously, a script that failed the server's built-in parse check (which did not support non-standard extensions) would simply silently fail to execute.
* Detail: Release 8 of the Advanced Script Compiler includes full support for enabling non-standard extensions in the toolset.

- Bugfix: When using UseReferenceVM=0, strings not representable in an 8-bit character set might have gotten partially mangled. This has now been fixed. This issue was most likely to impact non-English language modules.

- Bugfix: When using UseReferenceVM=1, the implementation of the GTFF instruction performed a >= operation and not a > operation. This has been fixed. Production mode (UseReferenceVM=0) is not impacted.

- Bugfix: The behavior of OP_SHRIGHT/OP_USHRIGHT has been changed to match the behavior of the standard server (which implements an unintuitive set of semantics for signed right shifts with both operator>> and operator>>>). Most scripts are unlikely to have been impacted by this change, which impacts both UseReferenceVM=0 and UseReferenceVM=1 modes.
* Detail: The USHRIGHT instruction now implements a signed right shift (arithmetic right shift), i.e. with the sign bit replicated when shifted. This is consistent with the standard server. Previously, it implemented a true unsigned right shift (with the sign bit not replicated).
* Detail: The SHRIGHT instruction now implements the standard server's algorithm for right shift, which, if the amount to shift right was negative, negates the sign of the value, performs the shift, and then negates the sign of the result (or if the amount to shift right was positive, a plain right shift is performed). This is consistent with the standard server. Previously, the instruction implemented a standard signed (arithmetic) right shift.

Release 6:

- Added support for CLR scripts, a major new feature. "Scripts" can now be authored in CLR languages like C#.

- Added support for disabling execution guards.

- Added support for saving code generation output.

- Fixed UTF-8 code point splitting issue.

Release 7:

- Improved the performance of the following engine functions by natively implementing them directly in CLR code (controlled by the new OptimizeActionServiceHandlers=1 option):

* GetStringLength
* GetStringLeft
* GetStringRight
* IntToString
* GetSubString

By directly implementing these engine functions, the overhead of communicating with the game engine from script code is eliminated for these particular engine functions.

- Improved the performance of passing engine structure parameters to engine functions, like GetIsEffectValid or GetIsTalentValid. This yields a 10-20% gain in the number of calls to a function such as GetIsEffectValid that could be made per unit time. Some scripts, such as AI scripts, make heavy use of these functons and consequently see performance improvements when many creatures are running AI.

[Skywing]

I've posted a patch release here:

http://www.nynaeve.net/Skywing/nwn2/xp_AuroraServerNWScript/AuroraServerNWScript.zip

Be sure to copy over all of the DLLs including NWNScriptJIT.dll.

- Fixes a code generation issue relating to scripts with a script function that both returns a return value of an engine structure type and calls an engine function with a parameter of type 'action'. For example, "location testfunc1() { AssignCommand(OBJECT_SELF, ActionWait(0.0f)); return GetStartingLocation(); }".

[GodBeastX]

You're the man Skywing. I'll have to try this out soon.

[Skywing]

Posted version Jul 10 2011 21:06:18 (release 2) with an important bugfix and some additional improvements (including debug symbols loading for better tracing with UseReferenceVM=1 when debugging scripts).

[Zunath]

This sounds awesome! Will have to give it a shot. Thanks for the release

[Skywing]

Posted version Aug 22 2011 18:32:23 (release 4). This release updates ALL of the included DLLs, be sure to update all of them in their associated locations (as described by the readme documentation).

This build incorporates the following changes:

- Disabled use of collectable assemblies by the JIT engine to work around a bug in the 4.0 CLR. This means that reloading scripts via the clear script cache command will now leak memory (but avoids a stability issue during code generation). Only users that explicitly use the NWNX4 script function to clear the script cache (added with the plugin) are impacted; currently, there are no known users of this particular functionality as it is primarily oriented towards dev and test scenarios for rapid testing of new scripts.
- Changed code generation to generate action service handler stubs for action services that require the 'slow' call path (those that take or return an engine structure). This reduces code size (memory usage) and allows for easier reading of the IL disassembly of a JIT'd script.
- Fixed a problem where the code size for a script being JIT'd wasn't properly being initialized in all cases. This would very rarely result in a refusal to execute a script (the problem would be readily apparent if one were impacted by it, as all scripts would fail to run).
- If script situation creation failed (low memory or a problem with the script itself), the state of the VM stack was not being properly rolled back for the server to continue. This has been fixed.

[Nessuno]

I have to warn you about some errors I've met in my PW "Abeir-Toril".

It seems that the plugin interfere with the some doors animation and the kemo sitting system. I will explain better: some doors (custom), they simple don't open, the animation doesn't start.
For the Kemo sitting system, the problem is different. After 2 or 3 times the pc uses the chairs (or kemo animation system) the pc simply disappears and the player must logout and login again to see the pc not invisible.

I'm sure it's the plugin, because I've run some tests and after disabling the plugin, the issue was solved.

Hope to be in some way helpfull to you.
You did anyway a great job, Skywing

[Rasael]

This is awesome, any news on an update? The issue with the doors and Kemo sitting sounds annoying to players. Is there a work around for that or is was it a bug specific to that server only maybe

[Skywing]

[Skywing]

New test release available. I'll update the main download link if there aren't issues reported.

In-test release: http://valera-ext.nynaeve.net/~skywing/nwn2/AuroraServerNWScript.zip

Be sure to upgrade all of the DLLs (remember that NWNScriptJIT* goes into the NWN2 install directory and xp_AuroraServerNWScript* goes into the NWNX4 install directory, if they are not the same directory in your environment).

Changes:

- New feature: The Advanced Script Compiler's non-standard compiler extensions can now be used for scripts that enforce parameter checking (most commonly, GUI scripts and StartingConditional scripts, as well as module OnChat scripts and any script used with ExecuteScriptEnhanced). These extensions include basic #ifdef support, greatly expanded internal compiler limitations on the number of constants and variables that can be defined, and many other improvements.
* Detail: The plugin disables parameter checking in the server. The parameter checking breaks with non-standard extensions as the OEI implementation required the server to be able to partially compile scripts on the fly to extract parameter information. The plugin has always supplanted the built-in parameter checking with a version derived from static analysis on the compiled script; this change simply turns off the server's built-in script parse check. Previously, a script that failed the server's built-in parse check (which did not support non-standard extensions) would simply silently fail to execute.
* Detail: Release 8 of the Advanced Script Compiler includes full support for enabling non-standard extensions in the toolset.

- Bugfix: When using UseReferenceVM=0, strings not representable in an 8-bit character set might have gotten partially mangled. This has now been fixed. This issue was most likely to impact non-English language modules.

- Bugfix: When using UseReferenceVM=1, the implementation of the GTFF instruction performed a >= operation and not a > operation. This has been fixed. Production mode (UseReferenceVM=0) is not impacted.

- Bugfix: The behavior of OP_SHRIGHT/OP_USHRIGHT has been changed to match the behavior of the standard server (which implements an unintuitive set of semantics for signed right shifts with both operator>> and operator>>>). Most scripts are unlikely to have been impacted by this change, which impacts both UseReferenceVM=0 and UseReferenceVM=1 modes.
* Detail: The USHRIGHT instruction now implements a signed right shift (arithmetic right shift), i.e. with the sign bit replicated when shifted. This is consistent with the standard server. Previously, it implemented a true unsigned right shift (with the sign bit not replicated).
* Detail: The SHRIGHT instruction now implements the standard server's algorithm for right shift, which, if the amount to shift right was negative, negates the sign of the value, performs the shift, and then negates the sign of the result (or if the amount to shift right was positive, a plain right shift is performed). This is consistent with the standard server. Previously, the instruction implemented a standard signed (arithmetic) right shift.

[Rasael]

I hope we're going to try this on BG soon, hopefully in a couple of days - I'll get back with the results if and when

[Skywing]

Promoted the testing release to release 5. The download link now points to that release.

[Rasael]

[Edit:] We're going to try use it only for the huge scripts one more time to see if that works

Heya,

We tried using it this weekend and it crashed the server several times so we've had to take it out unless we can figure out what's wrong.

It didn't leave an error log from XP Bugfix but Luna did get this:

[Skywing]

Maximum loop iterations exceeded sounds like an issue with that script. Can you post the source for rh_giant_user_defined (is there a loop in the main/StartingConditional that could potentially be unbounded)?

As far as the crash, is it possible to produce a repro environment that I could look at, or to catch this under the debugger and save a dump for analysis in your environment?

[Rasael]

We're going to try it again without the RH giants script enabled. I've forwarded your PM reply to Luna to so he'll try to see if there's any log or dumpfile we can send you.

I'll ask about the repro too, the module is quite big though.