Natural Selection Wiki
Natural Selection Wiki
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:

  • LaunchPad (Spark Launch Pad): a packaging/publishing tool and starting point for the other tools and docs
  • Spark Editor
  • Builder
  • Model viewer
  • Cinematic editor
  • Decoda

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.


Navigate to your Natural Selection 2 Steam folder Steam\steamapps\common\Natural Selection 2 and launch LaunchPad.exe. Make sure that Steam is running and you are logged in before launching it. Under no circumstance should you start the LaunchPad.exe from the x64 folder.

  • Step 1: Create a new Mod by clicking on New.
  • Step 2: Select a Path for the Mod and a Name to be displayed on the Steam Workshop.
  • Step 3: Open the Input folder on the left and paste files that require building in the correct subfolder.
  • Step 4: Start the Builder and Build your Mod. Make sure to properly Exit the Builder under File.
  • Step 5: Open the Output folder on the left and copy your files which don't require building into their respective folder.
  • Step 6: Under Configure you can edit the Name, add a description and give additional information.
  • Step 7: Publish the Mod to Steam (visibility can only be public but can be changed in the Steam Workshop afterwards.
  • Optionally you can replace preview.jpg in the Mod's folder with any 512x512 Pixel jpg to be the picture shown for your mod in the Workshop. You can also add videos and images on the Workshop page.

    Another guide to publishing a ns2 mod on the steam workshop can be found here on the forums.


    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[]