ㅤㅤㅤMBII OpenJK "Godfinger" scripting platform

</br>

ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤ

ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤ </br> ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤ ㅤㅤㅤ

</br>

A modular script extension system that allows streamlined rcon & plugin interaction to simplify serverside processing for MBII in python. Aimed to better equip server owners to improve their own creative works, and have more expression over their game servers.

The possibilities of this system allow for myriad of custom logfile implements, such as:

- moderation,
- translations,
- blacklisting,
- kill tracking,
- points tracking,
- complex teamconfig management,
- making custom gamemodes,
- organizing round information,
- fun interactions with chat,
- remote cvar injection,
- smod smsay admin chat commands,
- incorporating shell scripts,
- account systems,
- sql databases,
- AI responses,
- automated asset building,
- integrating other languages,
- discord integration, & more.

</br> </br>

[!IMPORTANT] ** REQUIRES PYTHON 3.12.7+ **

Ensure godfinger folder is installed in Jedi Academy/GameData/.

Ensure your logfile is set to server.log in your server.cfg.

Ensure the following cvars are set in your server.cfg.

• g_logExplicit is "3"
• g_logSync is "1"
• com_logChat is "2"
• g_logClientInfo is "1"
• g_statLog is "1"
• g_statLogFile is statlog.log
• sv_maxOOBRateIP should be at least 3 to prevent rcon rate limiting. If rate limiting persists, increase this value. </br>

THEN,

• set com_logfile "2"
• set com_logSync "1"
• set logfile "2"

</br>

Execute "prepare" script based on platform in ./prepare/os to install dependancy modules, run the "start" or "startDebug" script based on platform in ./start/os, then sufficiently fill out the generated godfingerCfg.json in root directory.

You may now start the godfinger system normally.

</br> </br>

[!NOTE] This system was created initially for the MBII Supremacy Project, now available for public use.</br>Originally created by ViceDice & ACHUTA, redistributed for a public MIT release.

All bugfixes or optimizations may be reviewed and potentially accepted through method of pull requests.</br>All pull requests are asked to be directed at the merge branch before tested approval into upstream dev or main branches.</br></br>We will not accept custom plugins upstream, outside of crucial widespread plugins like RTV, designed for abstract server hosting.

</br> </br>

[!CAUTION]

Known problems

</br>

#1) Python has issues sometimes with dirpathing in json files, so double backslashes \\ may be necessary.</br>e.g: C:\\Program Files (x86)\\SteamCMD\\JKA\\Gamedata\\MBII\\

</br>

#2) 138 is the maximum bytes for svsay, 993 for vstr, and 2048 for general rcon payload in MBII OpenJK.</br>Estimating roughly 5 rcon messages per 0.02 seconds ( 20 milliseconds, 50 fps )

The rcon messaging if rate is limiting will block calling thread until next timeframe, because we have to send/recieve rcon messaging in sync mode.

So i.e, if you send 6 rcons within 20 miliseconds frame time, it will send 5 and then wait for 20 milliseconds and send the 6th rcon afterwards.

</br>

#3) If you don't have GIT natively installed when running the update process as a windows user, and it errors on portable install, 7z_portable.zip is stored using Git LFS. You must download and place it in ./lib/other/win, then run the update process again, or reference release versions with 7Z portable file manager included natively.</br>

Alternatively, and for UNIX users, ensure GIT is installed before using the godfinger platform as a necessary precaution.

</br> </br>

[!NOTE]

Config file documentation

The JSON file format is used for all config files included in this release, and while its usage is convenient for the programmers, it does not allow for in-line commentary to describe the function and usage of various settings in the file. Thus, the following is a brief overview of the config files included in this release.

</br>

godfingerCfg.json

- "Remote"
   - "address"
       - "ip" : The IP address of the server to connect to. In most cases this should be localhost as the script requires access to the log file to function.
        - "port" : The port to connect to. In most cases, should be 29070.
    - "bindAddress" : The address for the script to use as a bind address. In most cases should be the same as the IP.
    - "password" : The server's rcon password. Set in server.cfg.

- "MBIIPath" : File path to the MBII installation to be used.
- "logFilename" : Name of the server log file (defined in server.cfg, default is server.log)
- "serverFileName" : Name of the server executable file to use.
- "logicDelay" : Interval of time to pass between script heartbeat loops.
- "logReadDelay" : Interval of time to pass between retrieval of new log lines to parse.
- "paths" : A list of string paths to append to system path, used to pass import directories for dependancies of plugins and such.
- "restartOnCrash" : If this is set to true, the server will attempt to restart itself if a fatal exception is detected.
- "watchdog" : Process monitoring and auto-restart configuration for the MB2 dedicated server. The RconInterface already monitors the MB2 server process automatically - this setting enables automatic restart when the process dies.
   - "enabled" : If true, enables automatic restart when the MB2 server process dies. The process monitoring is always active in RconInterface.
   - "restartServer" : If true, attempts to restart the MB2 server when it crashes.
   - "serverStartCommand" : Path to the script/executable to start the MB2 server. If left empty (""), Godfinger will automatically set this to the platform-specific autostart scripts by OS.

- "interfaces"
   - "pty" : Pseudo-terminal utilities (https://docs.python.org/3/library/pty.html), used to wrap the mbiided process.
       - "target" : File path to the MBII dedicated server executable.
        - "inputDelay" : Interval of time to pass between terminal heartbeat loops.
   - "rcon" : The typical use of the godfinger script extension system, generic logfile parsing.
    - "Remote"
        - "address"
           - "ip" : The IP address of the server to connect to. In most cases this should be localhost as the script requires access to the log file to function.
           - "port" : The port to connect to. In most cases, should be 29070.
      - "bindAddress" : The address for the script to use as a bind address. In most cases should be the same as the IP.
      - "password" : The server's rcon password. Set in server.cfg.
     - "logFilename" : Name of the server log file (defined in server.cfg, default is server.log)
     - "logReadDelay" : Interval of time to pass between retrieval of new log lines to parse.
    - "Debug"
      - "TestRetrospect" : true/false allows for simulating and recreating active game data for the purpose of test case bugfixing. False is generally considered default.

- "interface" : Where you can specify which interface you wish to use, in this case, "rcon" or "pty", with "rcon" as default.

- "paths" : Where you can specify foreign directories not native to the godfinger root working directory, in the event of private codebases, or other implements with the godfinger system. Default is ".\\"

- "prologueMessage" : String to show when the godfinger system has acknowledged sufficiently starting up, and deployed natively without error.
- "epilogueMessage" : String to show when the godfinger system concludes, and has exited cleanly, safely.

- "Plugins" : A list of plugin names, defined as python package strings (https://docs.python.org/3/tutorial/modules.html#packages), to use with the engine.

</br> </br>

[!IMPORTANT]

Implementing your own plugins

   "Plugins":
   [
       {
           "path":"plugins.shared.pluginfolder.pluginfile"
       }
   ]
}

- "plugins" : do not modify, native plugins dirpath
- "shared" : shared, or private directory, depending on plugins use
- "pluginfolder" : name of your custom plugin folder
- "pluginfile" : name of your custom plugin file, do not add .py extension

Ensure you place the requirements.txt with required dependencies alongside your plugins.

Example of test plugin integration

</br>