Lifecycle Hooks
Architect Agent supports a system to execute custom scripts at certain steps during a game servers lifecycle.
These are to be placed in the `lifecycle_hooks` directory:
Windows
Supported scripting systems: Batch, PowerShell, Python (2, 3)
File name format: `lifecycle.{hook}.{extension}`
Supported extensions: bat, ps1, py
Linux
Supported scripting systems: Bash, Python (2, 3)
File name format: `lifecycle.{hook}.{extension}`
Supported extensions: sh, py
Multiple lifecycle hook scripts
You can have multiple scripts for each type of hook, by adding a number after the hook event string. `lifecycle.{hook}-{index}.{extension}`
Example:
- lifecycle.pre-start.bat
- lifecycle.pre-start-2.bat
Hook Events
Architect supports the following lifecycle hooks:
| Hook | Details | Blocking |
|---|---|---|
| pre-start | Executed before each game server start. | Yes |
| started | Executed after the game server process has been started. | No |
| stopped | Executed after the game server process has exited. | Yes |
| crashed | Executed after the game server process has exited and a crash was detected. | Yes |
While a lifecycle hook (or other internal start step such as backup) is running, server status exposes `current_procedure` with a value such as `lifecycle_pre-start:lifecycle.pre-start.bat` so you can see what the agent is waiting on.
Force-kill during pre-start
`pre-start` hooks are blocking. By default, a force-kill during an in-flight startup does not terminate the running script — the script finishes naturally, then the start is abandoned (later hooks and the game process are not started).
To allow force-kill to terminate the running pre-start script immediately, set the following in your `config.toml` and restart the agent:
[config_system]
force_kill_allow_script_termination = true
Default is `false`. See Configuration.
Environment Variables
| CF_SERVER_ROOT | Absolute path to server root directory |
|---|---|
| CF_SERVER_ID | Custom server identifier |
| CF_TITLE | Title code of the game server |
| CF_SERVER_PID (only for started) | PID of the game server |
| CF_GAME_PORT | Game port |
| CF_QUERY_PORT | Query port (if supported by title) |
| CF_RCON_PORT | RCon port (if supported by title) |
| CF_GAME_HOST | Custom interface allocation as configured |
| CF_RUNTIME (only for stopped, crashed) | Timestamp of when the game server process was started |
Python Script Execution
Python 2 has been deprecated by the maintainer
The agent supports the execution of Python (2, 3) scripts instead of plain shell scripts. This requires that a valid Python interpreter has been installed on the system. By default, the system wide Python interpreter will be used including all global site packages maintained by the primary installation. To change to a specific interpreter/installation, the config.toml file needs to be adjusted.
The availability of Python script execution, depends on your systems PATH variable. It must include the Python interpreter, otherwise all Python scripts will be omitted.
Python installed via the Windows Store will only be recognized if a valid system PATH variable exists to the interpreter directly.