NS2 Build 276 Modding Update

GhoulofGSG9

The following two posts are also avaible as Google Doc

Build 276 has just entered post production and there won’t be any further code changes.

So it’s time for me to give you some tips what to look out for with the upcoming build when you patch/update your mods.

Overall Build 276 focused mostly on engine features which won’t affect any mod directly.

But there is one LUA feature that might keep some of you busy the next week:

The complete ingame UI was made scalable and some refactoring was done around most of the GUI scripts.

You should look out for the following two new functions:

• SetFontAndSize(fontFamily, fontSize):
  function for text elements to choose a properly scaled version of the font family chosen to avoid blurry fonts when scaling.
• GUIMakeFontScale(guiItem):
  function that checks the current guiItem scale and font choice and automatically chooses the appropriate scale and font to avoid blurriness. Make sure you apply both scale and font size before using this function.

Also you should check your code for the TEST_EVENT method. It was used in almost all NS2 Vanilla scripts and has been removed with build 276. So make sure you remove it out of your code as well.

Now something new and exciting. With Build 276 the old a little dusty “Entry system” gets a new functionality called “Fileload Hooking”.

Also the “Entry System” was renamed to Modloader.

“Fileload Hooking” basically allows you to load your own script literally at any point you want without having to replace any vanilla file anymore. This should make NS2 modding a lot easier.

The documentation of the “new” Modloader and further details can be found in the next post.

Overall most mods will continue to work without any maintenance needed as long as they don’t modify some Vanilla GUI Item directly.

The release candidate is as always from now on available at the Beta Steam branch.

I hope you all success in getting your mods ready for build 276. In case somebody gets stuck at something please use the forum to ask for help

GhoulofGSG9

Introduction:

The NS2 ModLoader allows you to dynamically load your own Lua script via the so called entry points.

The ModLoader is the first script loaded in all Lua VMs except of the GUIView VMs (this includes the Loading and the Menu VM!).

Be aware that ModLoader.lua itself loads Utility.lua so you can use those basic help functions inside your entry file.

Entry points:

Available default entry points:

• Client : loaded after the Client VM has loaded up fully
• Server: loaded after the Server VM has loaded up fully
• Predict: loaded after the Predict VM has loaded up fully
• Shared: loaded prior to the above three entries
• FileHooks: loaded directly after the ModLoader in all VMs

Each entry point can be used by multiple mods at once. The mod loading order is defined by the “Priority” attribute.

Entry files:

The entries are set up by files with the .entry extension inside the lua/entry/ folder. The entry file's name is taken as mod’s name.

Entry files are handled as Lua scripts. The entry points are set up by declaring a global modEntry table like this:

modEntry = {
Client = “lua/TestClient.lua”,
Server = “lua/TestServer.lua”,
Predict = “lua/TestPredict.lua”,
Shared = “lua/TestShared.lua”,
FileHooks = “lua/TestHooks.lua”,
Priority = 5
}

Each of these entry values can also be nil. In case that Priority is nil the default value of 10 is used.

API:

function ModLoader.GetLoadedModNames()
returns an array containing all loaded mod names

function ModLoader.GetModInfo(modName)
returns the entry table of the mod with the given modName

Available FileHook modes:

• pre: Loads the mod script before the given file
• post: Loads the mod script after the given file
• halt: Prevents the given file from getting loaded (in this case also none of the other file hooks is called!)
• replace: Loads the mod script instead of the given file

function ModLoader.SetupFileHook( fileName, hookFileName, mode )
Sets the given mod script at the path hookFileName up for the file at the fileName path using given FileHook mode

returns
boolean : whether or not the hook was setup successfully.
string : error description in case the operation failed.


function ModLoader.RemoveFileHook( fileName, hookFileName, mode )
Removes given mod script hookFileName as hook from the file fileName for given FileHook mode

returns
boolean : whether or not the hook was removed successfully.
string : error description in case the operation failed.

ModLoader.GetFileHooks( fileName, mode )
returns a list of all hook entries of the given file under the fileName path and given mode

Upgrading from the old entry system:

The old “modEntry as string” format is still supported. But it is recommended to use the new table format so the ModLoader won’t have to parse the string.

The current entry system is being loaded earlier than the previous one did, so any custom lua code present in the .entry file may break. It is recommended to move this code to the Shared entry point.

Mods already using the entry system as designed will still work without issues.

GhoulofGSG9

Okay build 276 will be published in about 8 hours.

I wanted to take the time to remind all of you to try to optimize your code towards runtime and to specially avoid using not "jit-able" functions unless you are forced to use them.

A overview of what functions are "jitted" and which aren't is available here (we are currently still using LuaJit 2.0.4 as 2.1 is still beta)

While doing the final build 276 tests with popular NS2 mods we realized that by now some parts of NS2 are rather highly optimized but the mod function hooking into them are not. Which causes at certain clients a difference from up to 50 fps between using the mod or running vanilla (NS2 without mods).

The CDT is well aware that this is not only the mod's fault but moreover caused by the NS2 class design and the lack of a proper modding API. However we hope to find a workaround which works out for all sides.

So if you have any questions about code optimization or there is that one locally declared parameter or function you can't access without using the lua debug library let us know here in the forum.