|
1 | 1 | # Developing LinuxGSM |
2 | 2 |
|
3 | | -This page has been designed to help you learn how LinuxGSM code works. |
4 | | - |
5 | | -As a user, it will allow you a better understanding of how LinuxGSM works. As a developer, it will help you with adding new servers, fixing bugs, and adding new features. |
6 | | - |
7 | | -## Generalities |
8 | | - |
9 | | -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 the initial 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. |
10 | | - |
11 | | -## Main Executable |
12 | | - |
13 | | -The main executable file `linuxgsm.sh` or `gameserver` is what the user interacts with to run commands. |
14 | | - |
15 | | -`linuxgsm.sh` is 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. |
16 | | - |
17 | | -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. |
18 | | - |
19 | | -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. |
20 | | - |
21 | 3 | ## Modules |
22 | 4 |
|
23 | 5 | Modules are individual bash scripts containing code and functions that complete specific tasks. See the [modules](broken-reference) page for more info. |
24 | 6 |
|
25 | | -## Commands |
26 | | - |
27 | | -Within LInuxGSM there are many commands that a user will run to complete tasks such as start, stop, monitor, and details. Command scripts are stored will all other modules and are always named something like `command_install.sh`. See the [commands](broken-reference) page for more info. |
28 | | - |
29 | | - |
30 | | - |
31 | | -#### Fixes |
32 | | - |
33 | | -`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`. |
34 | | - |
35 | | -#### Core functions |
36 | | - |
37 | | -**core\_dl.sh** |
38 | | - |
39 | | -This is the first script to be run when `gameserver`is executed. This script allows for fetching LinuxGSM core files, but also for downloading big files within kind of an API. |
40 | | - |
41 | | -**core\_functions.sh** |
42 | | - |
43 | | -This is the second script to be run when `gameserver`is executed. This script declares all functions and fetches them when they are required. |
44 | | - |
45 | | -**core\_getopt.sh** |
46 | | - |
47 | | -This is the third and last script to be run when `gameserver`is executed. This script allows for setting and printing available commands to the user. |
48 | | - |
49 | | -**core\_messages.sh** |
50 | | - |
51 | | -This script allows for easy message output and logging. More details about it in the next part. |
52 | | - |
53 | | -#### Messages & Logs |
54 | | - |
55 | | -LGSM has a message/logging framework to avoid painful syntax into scripts. |
56 | | - |
57 | | -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". |
58 | | - |
59 | | -**On-Screen - Automated functions** |
60 | | - |
61 | | -* \[ .... ] | fn\_print\_dots | fn\_print\_dots\_nl |
62 | | -* \[ OK ] | fn\_print\_ok | fn\_print\_ok\_nl |
63 | | -* \[ FAIL ] | fn\_print\_fail | fn\_print\_fail\_nl |
64 | | -* \[ ERROR ] | fn\_print\_error | fn\_print\_error\_nl |
65 | | -* \[ WARN ] | fn\_print\_warn | fn\_print\_warn\_nl |
66 | | -* \[ INFO ] | fn\_print\_info | fn\_print\_info\_nl |
67 | | - |
68 | | -**On-Screen - Interactive messages** |
69 | | - |
70 | | -* Print $gamename $commandaction and jump some lines | fn\_print\_header (used at the beginning of a command) |
71 | | -* Complete! |fn\_print\_complete | fn\_print\_complete\_nl |
72 | | -* Failure! | fn\_print\_failure | fn\_print\_failure\_nl |
73 | | -* Error! | fn\_print\_error2 | fn\_print\_error2\_nl |
74 | | -* Warning! | fn\_print\_warning | fn\_print\_warning\_nl |
75 | | -* Information! | fn\_print\_information | fn\_print\_information\_nl |
76 | | - |
77 | | -**On-Screen End of Line** |
78 | | - |
79 | | -* OK| fn\_print\_ok\_eol | fn\_print\_ok\_eol\_nl |
80 | | -* FAIL | fn\_print\_fail\_eol | fn\_print\_fail\_eol\_nl |
81 | | -* WARN | fn\_print\_warn\_eol | fn\_print\_warn\_eol\_nl |
82 | | -* FAIL | fn\_print\_info\_eol | fn\_print\_info\_eol\_nl |
83 | | -* QUERYING | fn\_print\_querying\_eol | fn\_print\_querying\_eol\_nl |
84 | | -* CHECKING | fn\_print\_checking\_eol | fn\_print\_checking\_eol\_nl |
85 | | -* CANCELED | fn\_print\_canceled\_eol | fn\_print\_canceled\_eol\_nl |
86 | | -* REMOVED | fn\_print\_removed\_eol | fn\_print\_removed\_eol\_nl |
87 | | -* UPDATE | fn\_print\_update\_eol | fn\_print\_update\_eol\_nl |
88 | | - |
89 | | -**Logging** |
90 | | - |
91 | | -Syntax: `fn_script_log "Message goes here."` Output: `## Feb 28 14:56:58 ut99-server: Monitor: Message goes here.` |
92 | | - |
93 | | -* Simple action log | fn\_script\_log |
94 | | -* PASS (a successful test) | fn\_script\_log\_pass |
95 | | -* FATAL (an error has interrupted LGSM) | fn\_script\_log\_fatal |
96 | | -* ERROR | fn\_script\_log\_error |
97 | | -* WARN | fn\_script\_log\_warn |
98 | | -* INFO | fn\_script\_log\_info |
99 | | - |
100 | | -#### Checks |
101 | | - |
102 | | -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. |
103 | | - |
104 | | -There are several checks available: |
105 | | - |
106 | | -* check\_config.sh checks for a missing config file or a wrong parameter. |
107 | | -* check\_deps.sh checks for missing dependencies and contains requirements |
108 | | -* check\_glibs.sh checks if the server has the correct Glibc version or a fix available. |
109 | | -* check\_ip.sh automatically identifies the server interface IP. |
110 | | -* check\_logs.sh checks if log files exist. |
111 | | -* check\_permissions.sh checks ownership & permissions of scripts, files and directories |
112 | | -* check\_root.sh checks if the user tried to run the script as root |
113 | | -* check\_status.sh checks the process status of the server. Either online or offline |
114 | | -* check\_steamcmd.sh checks if SteamCMD is installed correctly |
115 | | -* check\_system\_dir.sh checks if systemdir is accessible |
116 | | -* check\_system\_requirements.sh checks RAM requirements (maybe more into the future) |
117 | | -* check\_tmuxception.sh checks and prevents server start from tmux or screen |
118 | | - |
119 | | -**core\_exit.sh** |
120 | | - |
121 | | -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 |
122 | | - |
123 | | -* Normal exit: exitcode=0 |
124 | | -* FATAL exitcode=1 |
125 | | -* ERROR: exitcode=2 |
126 | | -* WARN: exitcode=3 |
127 | | - |
128 | | -#### Server installation |
129 | | - |
130 | | -Installing a new server is mainly done through two scripts: |
131 | | - |
132 | | -* install\_server\_files.sh |
133 | | -* install\_config.sh |
134 | | - |
135 | | -Sometimes, another script is required, such as for TeamSpeak 3: `update_ts3.sh` |
136 | | - |
137 | | -#### Versioning |
138 | | - |
139 | | -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"` |
140 | | - |
141 | | -### Testing and debugging your code |
142 | | - |
143 | | -#### Working from your own GitHub branch |
144 | | - |
145 | | -You will usually be developing onto your own repo. Using your own repo instead of the original one is quite easy. |
146 | | - |
147 | | -1. Display your main "gameserver" file on GitHub, and select "Raw". |
148 | | -2. Make a test user, login to it |
149 | | -3. wget your Raw link and chmod +x the script. |
150 | | -4. Edit your "gameserver" file by changing GitHub information to your username and repo and branch. |
| 7 | +## |
151 | 8 |
|
152 | | - ```bash |
153 | | - ## Github Branch Select |
154 | | - # Allows for the use of different function files |
155 | | - # from a different repo and/or branch. |
156 | | - githubuser="YourUsername" |
157 | | - githubrepo="YourRepository" |
158 | | - githubbranch="YourBranchName" |
159 | | - ``` |
| 9 | +## |
160 | 10 |
|
161 | | -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. |
| 11 | +## |
162 | 12 |
|
163 | | -#### How to test |
| 13 | +## |
164 | 14 |
|
165 | | -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. |
166 | 15 |
|
167 | | -#### Oops, I found a bug! |
168 | 16 |
|
169 | | -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. |
| 17 | +#### |
170 | 18 |
|
171 | | -1. It's caused by your own code parts and you know how to fix it: Just go on and fix it. |
172 | | -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. |
173 | | -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. |
| 19 | +## |
0 commit comments