LinuxGSM_ Dev
LinuxGSMDocsDev Docs
Search
⌃K
Links

Developing LinuxGSM

This page has been designed to help you learn how LinuxGSM code works.
As a user, it will allow you for a better understanding of how LinuxGSM works. As a developer, it will help you with adding new servers, fixing bugs and adding new features.

Generalities

The LinuxGSM executable ./gameserver is the main entry point for users, their main interactions will be with this script. However, from a development perspective, this is only the gateway as it simply does initial the bootstrap and points to the commands and modules that are stored elsewhere. LinuxGSM is made up of many smaller (mainly bash) scripts (modules) that interact with each other to complete a set of tasks. A command will complete its set of tasks using the LinuxGSM modules.

Main Executable

The main executable file linuxgsm.sh or gameserver.sh is what the user interacts with to run commands.
linuxgsm.shis designed to be used for the installation of a specific game server. You can run ./linuxgsm.sh install to get a menu of the available servers or ./linuxgsm.sh gameserver to install the specific game server.
To install a specific server linuxgsm.sh first downloads a complete list of all available servers from serverlist.csv. This file contains variables required to identify the server; ${gamename}, ${shortname} and ${servername}. When installing a game server linuxgsm.sh copies itself using the${servername} variable as the script name and inserting the other variables into the copied file. The added variables allow LinuxGSM to know which server the user selected.
A user can also run the install again if they want multiple [[instances]] of the same server. This will give an output of gameserver-2,gameserver-3 etc as the file name.

​

Server Specific Information
Here are the things you need to look after when deploying a new server:
  • ## SteamCMD Login section needs to be present only if the game server requires a steam connection.
  • Paths variables, especially config paths
  • appid="" (steamcmd games only)
  • servicename="" (must be unique)
  • gamename="" (must be unique)
  • engine=""
  • githubuser/repo/branch="" (if you dev on your own github or a branch can help a lot)
Server Settings and start command
This part contains any setting that can be set as a start command for the given server. You will then use fn_parms and its parms="" variable to call those start parameters.

Functions, commands and script files

Script files are located in ${functionsdir}, which is ${rootdir}/lgsm/functions
  • Every single script file must be declared in core_functions.sh
  • Commands are declared in core_getopt.sh, depending on the game or engine
Note: You need to update those files with update-functions command after adding a new one.

Commands

Here are the command functions you might need to alter when adding a new server:
  • command_install.sh - Server installation must work properly
  • command_update.sh - if the given game supports updates (might required to add a file for that matter, for now, we use to add a single file for install and update, like for TeamSpeak 3).
  • command_details.sh - Server details need to be displayed properly
  • command_monitor.sh & monitor_gsquery.sh, query_gsquery.py & query_gsquery.py - You'll need to read carefully and understand this code before altering it.
  • core_getopt.sh - You will define available commands in this one, displayed when the user runs ./gameserver without an argument. Either use an existing opt or make a new one if needed.
  • command_start.sh & command_stop.sh - Of course, your server needs to be able to start and stop properly.
  • command_debug.sh & command_console.sh - Those commands usually work out of the box, but might require some more work. If not using tmux, then console should be disabled for this server in core_getopt.sh.
  • info_config.sh - You might need to read variables out of configuration files such as Rcon information in the case of Squad.

Fixes

command_install.sh runs fix.sh at the end of server installation. If the given server requires a fix, then add fix_gameserver.sh and run it from fix.sh.

Core functions

core_dl.sh
This is the first script to be run when gameserveris executed. This script allows for fetching LinuxGSM core files, but also for downloading big files within kind of an API.
core_functions.sh
This is the second script to be run when gameserveris executed. This script declares all functions and fetches them when they are required.
core_getopt.sh
This is the third and last script to be run when gameserveris executed. This script allows for setting and printing available commands to the user.
core_messages.sh
This script allows for easy message output and logging. More details about it in the next part.

Messages & Logs

LGSM has a message/logging framework to avoid painful syntax into scripts.
Framework syntax is: fn_print_whatever "This is your message" If you want to replace the line afterwards, then reuse fn_print_whatever. If you want a new output on a new line, then use fn_print_whatever_nl. "nl" stands for "new line".
On-Screen - Automated functions
  • [ .... ] | fn_print_dots | fn_print_dots_nl
  • [ OK ] | fn_print_ok | fn_print_ok_nl
  • [ FAIL ] | fn_print_fail | fn_print_fail_nl
  • [ ERROR ] | fn_print_error | fn_print_error_nl
  • [ WARN ] | fn_print_warn | fn_print_warn_nl
  • [ INFO ] | fn_print_info | fn_print_info_nl
On-Screen - Interactive messages
  • Print $gamename $commandaction and jump some lines | fn_print_header (used at the beginning of a command)
  • Complete! |fn_print_complete | fn_print_complete_nl
  • Failure! | fn_print_failure | fn_print_failure_nl
  • Error! | fn_print_error2 | fn_print_error2_nl
  • Warning! | fn_print_warning | fn_print_warning_nl
  • Information! | fn_print_information | fn_print_information_nl
On-Screen End of Line
  • OK| fn_print_ok_eol | fn_print_ok_eol_nl
  • FAIL | fn_print_fail_eol | fn_print_fail_eol_nl
  • WARN | fn_print_warn_eol | fn_print_warn_eol_nl
  • FAIL | fn_print_info_eol | fn_print_info_eol_nl
  • QUERYING | fn_print_querying_eol | fn_print_querying_eol_nl
  • CHECKING | fn_print_checking_eol | fn_print_checking_eol_nl
  • CANCELED | fn_print_canceled_eol | fn_print_canceled_eol_nl
  • REMOVED | fn_print_removed_eol | fn_print_removed_eol_nl
  • UPDATE | fn_print_update_eol | fn_print_update_eol_nl
Logging
Syntax: fn_script_log "Message goes here." Output: ## Feb 28 14:56:58 ut99-server: Monitor: Message goes here.
  • Simple action log | fn_script_log
  • PASS (a successful test) | fn_script_log_pass
  • FATAL (an error has interrupted LGSM) | fn_script_log_fatal
  • ERROR | fn_script_log_error
  • WARN | fn_script_log_warn
  • INFO | fn_script_log_info

Checks

Any script file must run check.sh at some point. Within check.sh, you will then choose what tests to run for a given function. The syntax of check.sh is a bit counter-intuitive: local allowed_commands_array=( ) is the variable where you will enter the functions into which you need to run the following check.
There are several checks available:
  • check_config.sh checks for a missing config file or a wrong parameter.
  • check_deps.sh checks for missing dependencies and contains requirements
  • check_glibs.sh checks if the server has the correct Glibc version or a fix available.
  • check_ip.sh automatically identifies the server interface IP.
  • check_logs.sh checks if log files exist.
  • check_permissions.sh checks ownership & permissions of scripts, files and directories
  • check_root.sh checks if the user tried to run the script as root
  • check_status.sh checks the process status of the server. Either online or offline
  • check_steamcmd.sh checks if SteamCMD is installed correctly
  • check_system_dir.sh checks if systemdir is accessible
  • check_system_requirements.sh checks RAM requirements (maybe more into the future)
  • check_tmuxception.sh checks and prevents server start from tmux or screen
core_exit.sh
This script allows for the use of exit codes which will print different outputs to LinuxGSM logs. Running core_exit.sh defaults exitcode variable to 0 which stands for a proper exit
  • Normal exit: exitcode=0
  • FATAL exitcode=1
  • ERROR: exitcode=2
  • WARN: exitcode=3

Server installation

Installing a new server is mainly done through two scripts:
  • install_server_files.sh
  • install_config.sh
Sometimes, another script is required, such as for TeamSpeak 3: update_ts3.sh

Versioning

At the moment, only the main "gameserver" script has a version number. The syntax is pretty easy, it's all incremental, based on the date: version="YYMMDD"

Testing and debugging your code

Working from your own GitHub branch

You will usually be developing onto your own repo. Using your own repo instead of the original one is quite easy.
  1. 1.
    Display your main "gameserver" file on GitHub, and select "Raw".
  2. 2.
    Make a test user, login to it
  3. 3.
    wget your Raw link and chmod +x the script.
  4. 4.
    Edit your "gameserver" file by changing GitHub information to your username and repo and branch.
    ## Github Branch Select
    # Allows for the use of different function files
    # from a different repo and/or branch.
    githubuser="YourUsername"
    githubrepo="YourRepository"
    githubbranch="YourBranchName"
Now, any command you run will get your own GitHub files, and after any change you make on your repo, ./gameserver uf will grab new files. If you make a change and that ./gameserver uf don't get them, it means you were too quick, and that your curl still has old files in cache; in this case, you'll need to wait a few minutes to get your modifications.

How to test

You need to make sure that all needed commands displayed in opt work properly. So just run ./gameserver to show available commands, then try commands one by one. A common procedure is to first work on command_install, then start, then stop, then debug, then details, then monitor.

Oops, I found a bug!

If you found a bug, either you'll instantly know how to fix it, or you won't. And either it will be a bug caused by your own code or a bug into LinuxGSM itself. So let's address those cases.
  1. 1.
    It's caused by your own code parts and you know how to fix it: Just go on and fix it.
  2. 2.
    It's caused by your own code parts but you got no idea why: Use ./gameserver dev-debug that will add a very detailed log into your rootdir that might help you figure this out. To disable the dev-debug mode, just re-run the command. If you still can't find why it's not working, come get help on Discord's #gsm-development channel or Github issue that might have been created for this issue.
  3. 3.
    You found a bug into LinuxGSM itself. First, you need to be sure that it's really a bug that affects every game, by testing with another game onto the original repo, otherwise, if it only affects your game, you will usually just need to add a clever conditional check to fix the issue.
Getting Started - Previous
Developer Commands
Next - Workflow
Workflow
Last modified 10mo ago