Where to get started modding ns2 code.

Ironsoul

I am having an immensely tough time finding documentation on modifying the natural selection 2 lua files. How do you guys do it? Did you just read the existing lua files and since you already know lua be able to figure it out?

I got a mod I want to make and I'm trying to change stuff but it's just not happening. So, how do I get started?

MCMLXXXIV

Well... most of us started by reading the game's code and working from there. If you use a program like notepad++ and search for the thing you want to change in all the files in the lua directory, you can usually work it out from the comments or the debugger.

What are you trying to modify? Some of the more experienced modders on here might be able to help you start out?

Add me on steam if you like, but I won't be online for a few days as we're moving house. My nickname is Winston Smith (Greeds).

Rio

I got the same problem when I started writing my own mod. Probably the best way is to take a look at the NS2 Lua code and figure out, how things are done and what exactly you want to modify. Of course if your are experienced in Lua, that helps alot. Learning by doing is the best way to go here.
Lua is awesome, because you can simply overwrite NS2 game logic or extend it. You will most likely end up creating Lua files that do exactly that when you start writing your own mod.
You can also take a look at the Lua code of other mods, most of them have their code somewhere or you could just subscribe to a mod in the workshop and the whole mod including the Lua code gets downloaded to your workshop directory (%appdata%/Natural Selection 2/Workshop). You will mostly get an idea on how other mods do things and it's kinda cool, because every mod has it's own style.

I always wonder why no one got the idea to create a "How to mod NS2" tutorial yet.

Ryuu

One of the things I'm still struggling to figure out is how do you develop server side mods?

For example, if I want a simple Hello World server mod, how I develop one to test for myself without (publicly) publishing it to the workshop? Just putting an include at the bottom of server.lua seems to generate consistency errors. How do you hook events like player chat, player fire etc. What's the difference in code/directory structure between a server plugin and a full conversion mod? How exactly do you "simply overwrite NS2 game logic or extend it."?

Seems bizarre that even the most absolute basics of this modding framework that they set up is still completely undocumented. Seriously, why not take like half an hour to write up some seriously basic tutorials instead of using that time to write meaningless articles like this and this. "Read the game code" is fine and all, but why do I have to spend hours crawling through undocumented code when that part of the learning process can be thrown out if a developer could write up some basic tutorials?

Lack of documentation and "just read the code" is what led people's frustrations with Source modding.

DerAkademiker

Run a mod locally
(You don't even have to copy all the lua files. Just copy those you want to mod, Spark will choose those then.)

Audio modding

Publish it on steam workshop for public server integration

Ask server operators to run your mod or run your own server.
If you want to mod something specific and don't know what to do, ask specific questions.
I know what you mean with the documentation, that's why I wrote the audio tutorial.

Rio

Ryuu wrote: »

What's the difference in code/directory structure between a server plugin and a full conversion mod? How exactly do you "simply overwrite NS2 game logic or extend it."?

The difference is that a server plugins only overwrites/adds files or Lua functions to the existing NS2 game play code while full conversion mods usually start from scratch (they could use some basic classes, but they probably drop most of the NS2 code).

There are two approaches to modify the existing NS2 game play code:
1. You could copy the files you want to change from your ns2 folder to your mod folder and change them directly. NS2 will load your files first and if files are missing in your mod folder, it uses the files in the ns2 folder.
2. You could create a file which overwrites existing NS2 Lua functions. That's what I meant with "Lua is awesome because you can simply overwrite NS2 game logic or extend it". Here's a quick example:

local ns2GameRulesCheckGameStart = NS2Gamerules.CheckGameStart
function NS2Gamerules:CheckGameStart()
    local team1Players = self.team1:GetNumPlayers()
    local team2Players = self.team2:GetNumPlayers()
    
    // Only start the game if there are 2 or more players on each team
    if (team1Players >= 2 and team2Players >= 2) then
        ns2GameRulesCheckGameStart(self)
    end
end

Like the name already says, this function checks if the game is ready to start. We only want to start the game if there are 2 or more players on each team.
This code saves the original function called CheckGameStart of the NS2Gamerules table into a variable so we can still access it. In the second step, we override the existing function and extend it with our additional logic. If there are two or more players on each team we just call the original function so it does whatever it's suppose to do.

This way of extending or replacing functions is called hooking functions. There are some helper functions already in NS2 like Class_ReplaceMethod which do the same thing, but I like to hook functions by myself. You can even hook into "system" functions which are not defined in the Lua code itself but in the Spark engine like Locale.ResolveString.

If you want to hook functions, you have to know which ones, that's why you have to go through the NS2 code.
That's why I always open the NS2 project additionally to my mod project in Decoda. Decoda has a function called "Search in files" (Ctrl+Shift+F) which allows you to search for text in all the NS2 Lua files. This function saves me so much time and after a while, you will understand the structure of the NS2 code.