CLICK HERE to visit the new NS2 Wiki! Please do not rely on any information here as it may be inaccurate and/or out of date! For help with NS2, hop onto the official Discord server!


From NS2 community wiki
Jump to: navigation, search
This article is about the mod development process. For a list of published mods, refer to the NS2 Steam Workshop.

NS2 is meant to be heavily modifiable, with its content creation tools being bundled with the game installation, and all of the game logic being exposed as Lua scripts.

Note: Within this article, "NSROOT" is used to denote the directory that Natural Selection 2 is installed to, e.g. C:\Program Files\Steam\steamapps\common\Natural Selection 2.


Several content creation tools come bundled with the game installation under NSROOT:

Example: Hello World

  1. Create a new empty directory somewhere, e.g C:\mymod. In this example, this directory will be referred to as MODDIR.
  2. Create a subdirectory MODDIR/lua and copy the game file NSROOT/ns2/lua/Client.lua into it.
  3. Edit the copied MODDIR/lua/Client.lua file, and add this line at the bottom of the file:
    Shared.Message('Hello World')
  4. Run the game's ns2.exe with the options -game "MODDIR" -hotload, e.g. ns2.exe -game "c:\mymod" -hotload
  5. Start a new private server.
  6. Once the map has loaded, open the console (default key is ~)
  7. Expected result: You should see the "Hello World" line somewhere in the console log.

Mod structure

A mod is structured as a directory with files that overlay the game definition files at NSROOT/ns2. When the running game tries to load a particular game definition file (such as lua/Client.lua), it will use the file from the mod directory if it exists, otherwise falling back to using the file under NSROOT/ns2.


The optional game_setup.xml file (in a mods directory) controls what the first lua file the Client and Server lua VMs will load, The entrypoint file for the main menu VM is lua\Main.lua this is the very first lua file the game loads when starting up. When you connect to a server the main menu VM is destroyed and the Client VM is created and when you disconnect the Client VM is destroyed menu menu VM created again. The game_setup.xml file also controls title of the ns2 window will be. If your mod doesn't have one in its root directory, the engine will default to loading "NSROOT\ns2\game_setup.xml"

The default game_setup.xml looks like this:

  <description>Natural Selection 2</description>

The description node controls what title of ns2 window will be. If client and server nodes are empty in your game_setup.xml file, the game will default to loading "MODDIR\lua\Client.lua" for the client vm and "MODDIR\lua\Server.lua" for the server VM. If either of those don't exist, the game defaults to loading the normal ns2 entry point lua files "NSROOT\ns2\lua\Client.lua" for the Client VM. and "NSROOT\ns2\lua\Server.lua" for the server VM.


Launching a custom mod can either be done through the command line, or by publishing/loading it through Steam Workshop.

Launching through the command line

This instruction will walk you through launching a mod. For the purpose of this demonstration, we will use an imaginary mod called "mymod".

  • Move the Mod folder mymod into your "....\steam\steamapps\common\natural selection 2\" folder.
  • Right click on ns2.exe and click on send to desktop (create shortcut).
  • Right click the shortcut and select properties.
  • Find the line called target and after the "....\Steam\steamapps\common\natural selection 2\NS2.exe" add: -game mymod -hotload
  • On my computer the target line reads - "F:\Games\Steam\steamapps\common\natural selection 2\NS2.exe" -game mymod -hotload
  • Click the general tab of the properties window.
  • Change the name from "shortcut to ns2" to "mymod".
  • Click OK.
  • Double Click the mymod desktop icon to launch the mod.

The -game commandline argument causes the game engine to search for game files at the address provided. Using -game mymod, would cause the engine to search for the mod folder in the NSROOT folder. You can also specify a full path if you have decided to put your mod files in a different folder i.e. -game "c:\mystuff\mymod". When ever you see MODDIR on this page it means the directory set by the -game commandline.


The guide to publishing a ns2 mod on the steam workshop can be found here


All console output (including Lua errors) is written to a log file in %APPDATA%\Natural Selection 2\ called either log.txt or log-2.txt.

You can also make an error dialog appear whenever a Lua error occurs by launching NS2 with the -debug parameter.

See Also