Introduction to Crysis server-side modding
13.02.2018 21:43:43Link to post
In relation to the end of my activities in Crysis, i found it fair to hand over my knowledge about Crysis modding to you, so you can become stand-alone and can take over the future of Crysis multiplayer, without always relying on few "chosen" people who "know the stuff" to somehow do it as you want.
If you don't want to learn anything about Crysis modding and just want to setup own server and add features as easily as possible, download and use one of the existing SSMs (Server-Side Modifications).
Most up to date are:
* SafeWriting /faq_own_ssm_server.php
* CryFire http://crysis1.com/forum/viewthread.php?thread_id=87
Otherwise continue reading.
This knowledge cannot be found anywhere on the internet, there aren't any official guides (well there is some little documentation for CryEngine but that's not really sufficient), crymod.com and crydev.com were disabled and Crysis fans have always been sharing this info from one to another only via messangers and talking in game chat. It's about time it will be written at some "googlable" place.
It's quite a lot of information, you don't need to read everything at once. Read one chapter, experiment little bit, and when you think you understood it well, continue with next one.
So let's get started.
Game files structure
If you look at Crysis installation directory, it looks like this
Important for us are folders BinXY and Game.
BinXY contains libraries and executables of the game engine, Bin32 for 32-bit platform and Bin64 for 64-bit platform.
These files contain so called machine code (program in form of hardware instructions for CPU),
The machine code is compiled from C++ source codes, which only their author has. These files cannot be modified (well actually they can, but it's extremely difficult and time consuming and requires very advanced IT knowledge) without having their original source codes, which are the property of CryTek and are not available to public. Except for CryGame.dll, which i will talk about later.
Folder Game contains all game assets like 3D objects, textures, sounds, music, maps, vehicle definitions and behaviour scripts.
All of these can be modified quite easily if you know the correct format or have a tool for manipulating with it. For multiplayer and server-side logic we are interested in vehicle parameters written in XML (textual data format) and code of game modes written in Lua (high level programming language).
Modifying game files
Crysis offers you 3 ways to modify data in Game directory.
1. Most intuitive but least usefull is to change those files directly. The files with extension .PAK are basically ZIP archives with zero compression, so they can be opened in WinRAR, 7zip or other archive manager. Inside is a directory structure with a lot of files that can be opened in text editor or some other tool.
You can edit or replace these files directly, but you will have hard time reverting your changes back without a backup.
2. Better is the way used by patch 1.2, which creates new archive ZPatch1.pak. The directory structure inside ZPatch1 is exactly same as directory structure in the other PAK archives. Those files in ZPatch archive replace files in other PAK archives on the same path.
Archives are loaded in alphabetical order. Files in archives loaded later overwrite files in archives loaded sooner. For example if you have archives MyModA.pak, MyModB.pak and MyModC.pak, and all of them contain file Scripts/GameRules/InstantAction.lua, the one in MyModC.pak will be the final one used by the game.
You can pickup one of the existing PAK archives, delete everything from it what you don't want to change, then rename it to something that is alphabetically behind the other files, like zzMyMod.pak and then edit the files inside.
As long as your archive is there, it will be used by the game instead of the original files. If you want to revert the changes, you simply delete your archive or move it outside of the directory and it will use the original files again.
3. The best way and most preferred one when creating mods is to put it inside a Mods directory and load by a startup parameter. The game allows you to create a directory called Mods, inside which you can store multiple mods which you downloaded or created and chose which one to start game with by command line parameter. Every mod has its own directory which structure is the same as Crysis main directory, e.g. can contain Bin32 and Game.
All PAK archives put in Crysis/Mods/YourModName/Game will be loaded as last and can overwrite files in archives in Crysis/Game.
So to make your own mod, first you create directory Mods in Crysis root directory (if it doesn't already exists) and then inside it you create directory named after your mod. Inside it you create dir Game and you put your PAK archive with modified game files there.
Then when starting a game or server, you can select which mod directory shall be loaded by a command line parameter -mod YourModName. This can be done in 2 ways:
a) by opening a command line, switching to your Crysis directory, and typing Crysis.exe -mod YourModName
b) by creating a BAT file which will execute the command when you click on it.
And now back to the CryGame.dll, which i mentioned earlier. It is the only library, whose C++ source codes are published and available as Crysis Mod SDK. You can download it, open the project in Visual Studio 2005 or 2008, edit the code and recompile it into a new library. This library then goes to Crysis/Mods/YourModName/BinXY and when loaded with parameter -mod, it replaces the CryGame.dll from Crysis/BinXY.
!!!BIG FAT WARNING!!!This is for advanced modders only. You need to know the C++ programming language. Making a mistake in C++ code will make your game or server crash without any error message, and you won't know where the mistake is. You must be sure you know what you're doing.
Here is how to make the Mod SDK working and create your own mod DLL.
1. Download and install Microsoft Visual C++ 2008
Microsoft has canceled all downloads and support for 2005 and 2008 versions, but Mod SDK project was made in 2005, so we need them for compatibility reasons.
Fortunatelly I still have it on my mediafire here: http://www.mediafire.com/file/fowpz58cly1dwbe/vcpp_setup_english.exe
2. Download and install Windows SDK
3. Hack VC++ to not require registration according to this article:
Official registration links are dead and registering old IDEs is not supported anymore, so we must work around it.
4. Download this prepared Mod SDK
which is a version stripped off all tools (only CryGame.dll source codes) and prepared to be opened and compiled in VC++ 2008.
Extract it into Crysis root directory and rename Crysis/Mods/CrysisMod to Crysis/Mods/YourModName.
You can download the original Mod SDK with all tools included and project file for VC++ 2005
but then you will need some manual tweaking to make it compile.
5. Open the project in VC++
Project file is Crysis/Mods/YourModName/Code/CrysisMod.sln
Rename the Solution and Project after the name of your mod.
Make any changes to the C++ code you want and click Build YourModName
Modifying Lua scripts and XML definitions
The easiest way to modify the game without risk of crashing unexpectedly is to change text-based scripts and data inside GameData.pak (of course through the 3rd method by placing copies in Crysis/Mods/YourModName/Game directory). These files are simple text and can be opened in any text editor, however i recommend you to install Notepad++ or PSPad or some other multirole editor with syntax highlighting.
You will need to learn the Lua programming language, but don't worry, unlike C++, this is maybe the easiest language in the world and making mistakes won't crash your game or server and will print out nice understandable error message instead.
Find some tutorials for Lua via google and start reading the game scripts, it shouldn't take you more than 2 days to get into it.
I will be talking about modifying server scripts to change multiplayer, because that's the only thing i have experience with. Client-side and singleplayer modding will probably be very simmilar, you will just be editing different scripts in different files.
For us, the most important place will be GameData.pak and ZPatch1.pak (which overwrites files in GameData.pak), especially directories Scripts/GameRules, Scripts/Entities/Items/XML and Scripts/Entities/Vehicles/Implementations/XML.
XML files of Items or Vehicles contains various parameters and numbers, that can be changed to modify the gameplay. For example speed of rocket shot from rocket launcher can be set in file Scripts/Entities/Items/XML/Ammo/Multiplayer/
Not all of these parameters can be modified in server however. Some of them requires to be changed in client (game of connected player). When you change a parameter value in the server and it really affects multiplayer and all players inside the server, we call that parameter "server-side". If that parameter needs to be changed in game of every single player connected to the server to take effect, we call that parameter "client-side". Unfortunatelly, there is no list of server-side and client-side parameters, it must be found by experimenting. Example of server-side parameter is the already mentioned rocket speed. Example of client-side parameter is radar scan time.
And yes, this can be used for cheating, but protecting against these cheats is very easy by enabling file modification checks at server with command sv_cheatprotection = 1. But remember, if you modify some XML file on server with file checks enabled, all players will get kicked, because their file (original) will be different server's file (modified). To prevent this, we use file Scripts/Network/Protect.xml. It contains a list of all files and directories, that should be checked for manipulation, and you can also add exceptions there. For every file you modify at the server, you must add line of this format
Basic script files for modifying multiplayer logic are
At the top of these files, you can find some values, that can be changed without understanding the code below, like respawn protection duration or prices of weapons.
The following code defines action, that should be done, when
- game starts
- game ends
- player connects
- player disconnects
- player respawns
You can try adding something very simple (like message) and see what happens.
Lua <-> C++ interconnection
Lua scripts are called from game engine (from DLLs in BinXY), when something specific happens. For example when player connects to a server, CryGame.dll calls Lua InstantAction.Server:OnClientConnect, lua then sets its own things up and returns control back to CryGame.dll.
The connection goes in the other direction too, Lua script can call C++ functions in DLLs and it very often does so. Everywhere you see something.game:Something(...), something.item:Something(), something.weapon:Something(), something.vehicle:Something() or something.actor:Something() or even System.Something(), it is call to C++.
When you work with Mod SDK and you write own C++ code, you can add own function bindings and then call them from your own Lua code.
This method is very common in modern games, not just Crysis, and have many advantages.
How to get oriented in Crysis Lua environment
When you start reading the original Lua scripts, you will soon notice, that there are some frequently called functions or methods, like
I cannot give you a complete list of such functions, because the list would be several pages long and even then it probably wouldn't be complete.
The best way to find out what to call to do what you want (well at least that's how i did it) is to remind some event that leads to that thing happening and then finding the code which does it.
For example, i want to know, how to change player's health. Wait, when does player's health get changed? Ah, when he gets hit by other player. So i use WinRAR search tool and then notepad search tool to find word "hit" and go through the search results. In InstantAction.lua i see
That might be what i'm looking for, aand .... bingo, target.actor:SetHealth(health)
How SSMs work
What Server-Side Modifications like SafeWriting, CryFire, Patiot, Aegis, ... do is that they hook GameRules scripts and functions. Hook is a programming method, when you find a place in a code, where something important for you is happening, and you add there a call to your own function. For example you want do something when a player is killed, so you add a call to your function like this
In your function OnKill you can do whatever you want, like display a message to everyone, give special rewards for streaks of kills, calculate KDR, etc. SSMs hook a lot of functions from the original Crysis scripts and add a lot of new functionality, including scanning chat messages for commands, etc.
SSMs then usually contain sophisticated command systems, ban systems, spawning systems, which allow their admin to have full control over the server via chat commands, server console commands and configuration files.
It is common for SSMs, but not neccessary, to have a custom DLL (that is a modified CryGame.dll using Mod SDK). It adds a tons of new possibilities and opportunity to change low level behaviour, that can't be changed in Lua (like checking player requests and detecting spoof cheats), and add features that can't be programmed in lua (like networking, HTTP connection).
If you want to create own SSM from scratch, there is good series of tutorials from Zi: https://www.youtube.com/watch?v=d48GCEbcGhc&list=PLltGMgMA9-jNOrYb61B7gzH6rn-h6lMJ8&index=1
How to run a dedicated server
Unlike other games, basic Crysis installation already contains dedicated server and allows every player to start his own. The server application is located in BinXY/CrysisDedicatedServer.exe. The server acts like console or terminal, where you can write commands and which displays messages about what is happening.
In the server console, you can do 2 things: execute commands and set variables. Example of variable is 'sv_servername' or 'g_respawntime' (we call them CVars - configuration variables), and example of command is 'map plantation' or 'kick youda'. List of all possible commands and cvars (well maybe not all) can be found here: https://pastebin.com/5QUN0hBF
To initialize your server and make it available for others to join, you must set at least
There are lots of other things that you can set and if you don't want to enter these commands manually everytime you start the server, you can put them into a configuration file loaded when the server starts. CrysisDedicatedServer by default searches for file autoexec.cfg in Crysis root directory (i.e. Crysis/autoexec.cfg) and if it finds it, it automatically loads it. Such cfg file can look like this:
Now if you want to start a server with your newly created mod, you will create a bat file with starting command like this
The server, when started, will automatically create files Server.log and server_profile.txt. Later you may want to add own levelrotation and your Crysis root directory is starting to get messy.
That's why we use special directory for server files and param -root. First create new directory for your server files, for example "Server", and move all server files there.
Then edit your starting bat file and add parameter -root "path_to_server_dir". There is a windows command line macro "%~dp0", that automatically expands to the current path where the file is, you can use it instead of manually entering the path.
The server root path is then accessible via cvar sys_root (usefull for scripting).
This approach has one more advantage, and that is you can have multiple servers in just 1 Crysis installation. You can experiment with different mods, have one server for each of them, or you can run one IA server and one PS, it's up to you.
You can set up a list of maps, that will automatically cycle on the server. To do that create a text file called levelrotation.xml. Format of that file looks like following:
randomize="0" means maps will change deterministically according to this order in the file, with "1" maps will change randomly. With tag <setting setting="..."/> you can specify any command that will be executed when the map starts.
If i missed something important, that you need to know, please let me know.
If you run into problems with server modding and need help, contact me on Skype as Youda008, on Discord as Youda#6731 or via email as Youda008@gmail.com