Skip to content

Commit

Permalink
Refactor server Engine configuration setup (#7)
Browse files Browse the repository at this point in the history 
# Update Engine Configuration Setup

## Summary

This pull request introduces new configuration modes for the
`Engine.ini` file, providing more flexibility and control over how
engine settings are configured.

## Motivation and Context

With the evolving needs of the project, it became essential to enhance
the configuration options for the `Engine.ini` file. The addition of
three modes (`full`, `modular`, and `skip`) allows users to tailor the
configuration process to their specific requirements when
`SERVER_SETTINGS_MODE` is set to `auto`.

## Description

The `ENGINE_CONFIG_MODE` environment variable now plays a crucial role
in determining how the engine settings are configured:

- `full`: Includes all settings in the `Engine.ini.template` file,
utilizing environment variables or default values.
- `modular`: Configures settings in the engine file only when the
corresponding environment variable is set and not empty.
- `skip`: Always skips the configuration of settings in the engine file,
regardless of `SERVER_SETTINGS_MODE` being set to `auto`.

The following table summarizes the key variables:

| Variable | Description | Default value | Allowed value |
| -------------------- | ----------------------------------- |
------------- | ----------------------- |
| `ENGINE_CONFIG_MODE` | How `Engine.ini` file is configured | `modular`
| `full`/`modular`/`skip` |

## Testing Instructions

To test these changes:

1. Set `SERVER_SETTINGS_MODE` to `auto`.
2. Adjust `ENGINE_CONFIG_MODE` to `full`, `modular`, or `skip`.
3. Configure individual environment variables related to engine
settings.
4. Run the server and verify that the `Engine.ini` file reflects the
chosen configuration mode and settings.

## Checklist

- [x] I have performed a self-review of my own code
- [x] I have updated the documentation (if necessary)
- [x] My changes do not introduce any breaking changes or bugs
  • Loading branch information
@thejcpalma
thejcpalma authored Mar 4, 2024
2 parents 4d67baa + 4e59a91 commit 2869d6b
Show file tree
Hide file tree
Showing 9 changed files with 248 additions and 109 deletions.
37 changes: 21 additions & 16 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,25 +154,30 @@ ENV DEBIAN_FRONTEND=noninteractive \
# Gameserver start settings
MULTITHREAD_ENABLED=true \
COMMUNITY_SERVER=true \
# Config setting - Warning: using 'auto' will overwrite the settings in the config file with the environment variables
# Config setting - Warning: using 'auto' will overwrite the settings in the PalWorldSettings file with the environment variables
SERVER_SETTINGS_MODE=auto \
# Engine Configuration Mode:
# - 'full' will overwrite the settings in the config file with the environment variables or default values
# - 'modular' will only set the settings in the config file when the corresponding environment variable is set and not empty
# - 'skip' will skip the configuration of the settings in the config file
ENGINE_CONFIG_MODE=modular \
# Engine.ini
LAN_SERVER_MAX_TICK_RATE=120 \
LAN_SERVER_MAX_TICK_RATE= \
NET_SERVER_MAX_TICK_RATE=120 \
CONFIGURED_INTERNET_SPEED=104857600 \
CONFIGURED_LAN_SPEED=104857600 \
MAX_CLIENT_RATE=104857600 \
MAX_INTERNET_CLIENT_RATE=104857600 \
SMOOTH_FRAME_RATE=true \
SMOOTH_FRAME_RATE_UPPER_BOUND=30.000000 \
SMOOTH_FRAME_RATE_LOWER_BOUND=120.000000 \
MIN_DESIRED_FRAME_RATE=60.000000 \
USE_FIXED_FRAME_RATE=false \
FIXED_FRAME_RATE=120.000000 \
NET_CLIENT_TICKS_PER_SECOND=120 \
TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS=30 \
THREADED_RENDERING=true \
THREADED_PHYSICS=true \
CONFIGURED_INTERNET_SPEED= \
CONFIGURED_LAN_SPEED= \
MAX_CLIENT_RATE= \
MAX_INTERNET_CLIENT_RATE= \
SMOOTH_FRAME_RATE= \
SMOOTH_FRAME_RATE_UPPER_BOUND= \
SMOOTH_FRAME_RATE_LOWER_BOUND= \
MIN_DESIRED_FRAME_RATE= \
USE_FIXED_FRAME_RATE= \
FIXED_FRAME_RATE= \
NET_CLIENT_TICKS_PER_SECOND= \
TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS= \
THREADED_RENDERING= \
THREADED_PHYSICS= \
# PalWorldSettings.ini
DIFFICULTY=None \
DAY_TIME_SPEEDRATE=1.000000 \
Expand Down
40 changes: 24 additions & 16 deletions default.env
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,26 +86,34 @@ MULTITHREAD_ENABLED=true
# Enable this if you want your server to show up in the community servers tab, USE WITH SERVER_PASSWORD!
COMMUNITY_SERVER=false

# Config-setting - Warning: Every setting below here will be affected!
# Server Configuration Mode - Warning: Every setting below here will be affected!
# - `auto`: Modify configuration files with by env vars, file will be overwritten always
# - `manual`: Modify only by editing the file directly, environment variables are ignored
SERVER_SETTINGS_MODE=auto

# Engine Configuration Mode (only used when SERVER_SETTINGS_MODE is set to 'auto'):
# - 'full' will overwrite the settings in the config file with the environment variables or default values
# - 'modular' will only set the settings in the config file when the corresponding environment variable is set and not empty
# - 'skip' will skip the configuration of the settings in the config file
ENGINE_CONFIG_MODE=modular

# Engine.ini settings
LAN_SERVER_MAX_TICK_RATE=120
LAN_SERVER_MAX_TICK_RATE=
NET_SERVER_MAX_TICK_RATE=120
CONFIGURED_INTERNET_SPEED=104857600
CONFIGURED_LAN_SPEED=104857600
MAX_CLIENT_RATE=104857600
MAX_INTERNET_CLIENT_RATE=104857600
SMOOTH_FRAME_RATE=true
SMOOTH_FRAME_RATE_UPPER_BOUND=30.000000
SMOOTH_FRAME_RATE_LOWER_BOUND=120.000000
MIN_DESIRED_FRAME_RATE=60.000000
USE_FIXED_FRAME_RATE=false
FIXED_FRAME_RATE=120.000000
NET_CLIENT_TICKS_PER_SECOND=120
TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS=30
THREADED_RENDERING=true
THREADED_PHYSICS=true
CONFIGURED_INTERNET_SPEED=
CONFIGURED_LAN_SPEED=
MAX_CLIENT_RATE=
MAX_INTERNET_CLIENT_RATE=
SMOOTH_FRAME_RATE=
SMOOTH_FRAME_RATE_UPPER_BOUND=
SMOOTH_FRAME_RATE_LOWER_BOUND=
MIN_DESIRED_FRAME_RATE=
USE_FIXED_FRAME_RATE=
FIXED_FRAME_RATE=
NET_CLIENT_TICKS_PER_SECOND=
TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS=
THREADED_RENDERING=
THREADED_PHYSICS=

# PalWorldSettings.ini settings
DIFFICULTY=None
Expand Down
70 changes: 51 additions & 19 deletions docs/ENV_VARS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ Due to the extensive control options, the settings are split into categories:
- [TZ identifiers](#tz-identifiers)
- [Dedicated Server Settings](#dedicated-server-settings)
- [Special Features](#special-features)
- [Server Settings](#server-settings)
- [Cron expression](#cron-expression)
- [Server Settings](#server-settings)
- [Engine Configuration Mode](#engine-configuration-mode)
- [Engine Settings](#engine-settings)
- [Palworld Game Settings](#palworld-game-settings)
- [Webhook Settings](#webhook-settings)
Expand Down Expand Up @@ -73,22 +74,6 @@ These settings control the special features of the server:
| `PLAYER_MONITOR_ENABLED` | Enables player monitoring for the server | `false` | `false`/`true` |
| `PLAYER_MONITOR_INTERVAL` | The interval in seconds for the player monitoring (lower values means more impact on system resources) | `60` | Integer |


### Server Settings

| Variable | Description | Default value | Allowed value |
| ---------------------- | -------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTITHREAD_ENABLED` | Sets options for "Improved multi-threaded CPU " | `true` | `false`/`true` |
| `COMMUNITY_SERVER` | Set to enabled, the server will appear in the Community Server list | `true` | `false`/`true` |
| `SERVER_SETTINGS_MODE` | Whether settings (game and engine) are configured via env vars or via file | `auto` | `auto`: Modified by env vars, file will be overwritten always<br>`manual`: Modified only by editing the file directly, environment variables are ignored |

> [!IMPORTANT]
>
> Take special attention to `SERVER_SETTINGS_MODE`, if you want to change the server settings via environment variables use the default value (`auto`), otherwise change it to `manual` and edit the config file directly.
> The RCON config file will be configured accordingly to the `SERVER_SETTINGS_MODE` value.
> If you change the `SERVER_SETTINGS_MODE` to `manual`, it will grab the settings from the file and ignore the environment variables.
> If you change the `SERVER_SETTINGS_MODE` to `auto`, it will grab the settings from the environment variables and ignore the file.
#### Cron expression

In a Cron-Expression, you define an interval for when to run jobs.
Expand All @@ -100,8 +85,53 @@ Default values for the cron expressions:
- Auto updates: `0 3 * * *` (Every day at 3am)
- Auto backups: `0 * * * *` (Every hour)

### Server Settings

| Variable | Description | Default value | Allowed value |
| --------------------- | ------------------------------------------------------------------- | ------------- | -------------- |
| `MULTITHREAD_ENABLED` | Sets options for "Improved multi-threaded CPU" | `true` | `false`/`true` |
| `COMMUNITY_SERVER` | Set to enabled, the server will appear in the Community Server list | `true` | `false`/`true` |

> [!IMPORTANT]
>
> Take special attention to `SERVER_SETTINGS_MODE`, if you want to change the server settings via environment variables use the default value (`auto`), otherwise change it to `manual` and edit the config file directly.
This setting controls how the server settings files (`PalWorldSettings.ini` and `Engine.ini`) are configured:
- `auto`: will use environment variables to configure the files
- `manual`: will skip the configuration of the files and files will have to be edited manually

| Variable | Description | Default value | Allowed value |
| ---------------------- | --------------------------------------------------------------------------------- | ------------- | --------------- |
| `SERVER_SETTINGS_MODE` | Whether settings are configured via environment variables or manually on the file | `auto` | `auto`/`manual` |

> [!NOTE]
>
> For `PalWorldSettings.ini`, all settings with empty values (e.g. `EXP_RATE=""`) will be overwritten the default value.
> For `Engine.ini` refer to the [Engine Settings](#engine-settings) section for more information.
>
> The rules below apply to both `PalWorldSettings.ini` and `Engine.ini`:
> All settings which are in a wrong format (putting a string in a float variable like `EXP_RATE="very_fast"`) will be ignored and the default value will be used instead.
> Integers on float variables will be converted to floats (e.g. `EXP_RATE=2` will be converted to `2.000000`).
> Floats with more than 6 decimal places will be rounded to 6 decimal places (e.g. `EXP_RATE=2.123456789` will be converted to `2.123457`).
> Variables where we have multiple options (like `DIFFICULTY`) will always be converted to lowercase (e.g. `DIFFICULTY="Normal"` will be converted to `difficulty="normal"`) to maintain consistency.
### Engine Configuration Mode

When `SERVER_SETTINGS_MODE` is set to `auto`, we will use environment variables to configure the engine settings.

The `ENGINE_CONFIG_MODE` environment variable controls how the engine settings are configured:
- `full`: will add all the settings in the Engine.ini.template file with the environment variables values or the default values for those settings
- `modular`: will only set the settings in the engine file when the corresponding environment variable is set and not empty
- `skip`: will always skip the configuration of the settings in the engine file (even if `SERVER_SETTINGS_MODE` to `auto`)

| Variable | Description | Default value | Allowed value |
| -------------------- | ----------------------------------- | ------------- | ----------------------- |
| `ENGINE_CONFIG_MODE` | How `Engine.ini` file is configured | `modular` | `full`/`modular`/`skip` |

### Engine Settings

This section contains all the settings currently adjustable via environment variables, based on the **order** and **contents of the [`Engine.ini.template`](../scripts/config/templates/Engine.ini.template)**.

| Variable | Game setting | Description | Default value | Allowed value |
| ------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------- | ------------------- |
| `LAN_SERVER_MAX_TICK_RATE` | LanServerMaxTickRate | Changes the TickRate of the server, be very careful with this! | `120` | Integer |
Expand Down Expand Up @@ -129,9 +159,9 @@ Default values for the cron expressions:
### Palworld Game Settings

This section lists all the settings currently adjustable via Docker environment variables, based on the **order** and **contents of the DefaultPalWorldSettings.ini**.
Information sources and credits to the following websites:
This section lists all the settings currently adjustable via environment variables, based on the **order** and **contents of the [`PalWorldSettings.ini.template`](../scripts/config/templates/PalWorldSettings.ini.template)** (which is the same as `DefaultPalWorldSettings.ini`).

Information sources and credits to the following websites:
- [Palworld Official Tech Guide](https://tech.palworldgame.com/settings-and-operation/configuration) for the game server documentation
- [Palworld Setting Generator](https://dysoncheng.github.io/PalWorldSettingGenerator/setting.html) for variable descriptions
- [Palworld Unofficial Wiki](https://palworld.wiki.gg/wiki/PalWorldSettings.ini) for variable descriptions
Expand Down Expand Up @@ -341,6 +371,8 @@ Below are the environment variables for each type of webhook message:
> [!NOTE]
>
> `PLAYER_NAME` is a variable that will be replaced with the name of the player that left the server.
> `PLAYER_NAME` is a variable that will be replaced with the name of the player that left the server.
> `PLAYER_NAME` is a variable that will be replaced with the name of the player that left the server.
> Use it on the title and/or description to show the player's name.
| Variable | Description | Default Value |
Expand Down
11 changes: 8 additions & 3 deletions scripts/config/setup_configs.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,17 @@ source "${SERVER_DIR}"/scripts/config/setup_rcon_yaml.sh
# Function to setup the server configs
function setup_configs() {
if [[ -n ${SERVER_SETTINGS_MODE} ]] && [[ ${SERVER_SETTINGS_MODE,,} == "auto" ]]; then
log_warning ">> SERVER_SETTINGS_MODE is set to '${SERVER_SETTINGS_MODE}', using environment variables to configure the server!"
log_warning ">> 'SERVER_SETTINGS_MODE' is set to '${SERVER_SETTINGS_MODE}', environment variables used to configure the server!"
setup_engine_ini
setup_palworld_settings_ini
else
log_warning ">> SERVER_SETTINGS_MODE is set to '${SERVER_SETTINGS_MODE}', NOT using environment variables to configure the server!"
log_warning ">> File ${GAME_SETTINGS_FILE} has to be manually set by user."
log_warning ">> 'SERVER_SETTINGS_MODE' is set to '${SERVER_SETTINGS_MODE}', environment variables NOT used to configure the server!"

# Copy default-config, which comes with SteamCMD to gameserver save location
cp "${GAME_ROOT}/DefaultPalWorldSettings.ini" "${GAME_SETTINGS_FILE}"

log_warning ">> File '${GAME_ENGINE_FILE}' has to be manually set by user."
log_warning ">> File '${GAME_SETTINGS_FILE}' has to be manually set by user."
fi
setup_rcon_yaml
}
50 changes: 29 additions & 21 deletions scripts/config/setup_engine_ini.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,39 +6,47 @@ source "${SERVER_DIR}"/scripts/config/utils.sh

function setup_engine_ini() {
# Setup the engine config file
log_warning ">> Setting up Engine.ini ..."

# Create the config directory if it doesn't exist
mkdir -p "${GAME_CONFIG_PATH}/"

template_file=${SERVER_DIR}/scripts/config/templates/Engine.ini.template
if [[ -n ${ENGINE_CONFIG_MODE} ]] && { [[ ${ENGINE_CONFIG_MODE,,} == "full" ]] || [[ ${ENGINE_CONFIG_MODE,,} == "modular" ]]; }; then
log_warning ">> 'ENGINE_CONFIG_MODE' is set to '${ENGINE_CONFIG_MODE}', environment variables will be used to configure the server!"
log_warning ">> Setting up Engine.ini ..."

cp "${template_file}" "${GAME_ENGINE_FILE}"
template_file=${SERVER_DIR}/scripts/config/templates/Engine.ini.template

cp "${template_file}" "${GAME_ENGINE_FILE}.tmp"

check_and_export "int" "LanServerMaxTickRate" "${LAN_SERVER_MAX_TICK_RATE}" "120"
check_and_export "int" "NetServerMaxTickRate" "${NET_SERVER_MAX_TICK_RATE}" "120"
check_and_export_if_not_empty "int" "LanServerMaxTickRate" "${LAN_SERVER_MAX_TICK_RATE}" "120"
check_and_export_if_not_empty "int" "NetServerMaxTickRate" "${NET_SERVER_MAX_TICK_RATE}" "120"

check_and_export "int" "ConfiguredInternetSpeed" "${CONFIGURED_INTERNET_SPEED}" "104857600"
check_and_export "int" "ConfiguredLanSpeed" "${CONFIGURED_LAN_SPEED}" "104857600"
check_and_export_if_not_empty "int" "ConfiguredInternetSpeed" "${CONFIGURED_INTERNET_SPEED}" "104857600"
check_and_export_if_not_empty "int" "ConfiguredLanSpeed" "${CONFIGURED_LAN_SPEED}" "104857600"

check_and_export "int" "MaxClientRate" "${MAX_CLIENT_RATE}" "104857600"
check_and_export "int" "MaxInternetClientRate" "${MAX_INTERNET_CLIENT_RATE}" "104857600"
check_and_export_if_not_empty "int" "MaxClientRate" "${MAX_CLIENT_RATE}" "104857600"
check_and_export_if_not_empty "int" "MaxInternetClientRate" "${MAX_INTERNET_CLIENT_RATE}" "104857600"

check_and_export "bool" "bSmoothFrameRate" "${SMOOTH_FRAME_RATE}" "true"
check_and_export "float" "SmoothedFrameRateRangeLowerBound" "${SMOOTH_FRAME_RATE_UPPER_BOUND}" "30.000000"
check_and_export "float" "SmoothedFrameRateRangeUpperBound" "${SMOOTH_FRAME_RATE_LOWER_BOUND}" "120.000000"
check_and_export "float" "MinDesiredFrameRate" "${MIN_DESIRED_FRAME_RATE}" "60.000000"
check_and_export "bool" "bUseFixedFrameRate" "${USE_FIXED_FRAME_RATE}" "false"
check_and_export "float" "FixedFrameRate" "${FIXED_FRAME_RATE}" "120.000000"
check_and_export "int" "NetClientTicksPerSecond" "${NET_CLIENT_TICKS_PER_SECOND}" "120"
check_and_export_if_not_empty "bool" "bSmoothFrameRate" "${SMOOTH_FRAME_RATE}" "true"
check_and_export_if_not_empty "float" "SmoothedFrameRateRangeLowerBound" "${SMOOTH_FRAME_RATE_UPPER_BOUND}" "30.000000"
check_and_export_if_not_empty "float" "SmoothedFrameRateRangeUpperBound" "${SMOOTH_FRAME_RATE_LOWER_BOUND}" "120.000000"
check_and_export_if_not_empty "float" "MinDesiredFrameRate" "${MIN_DESIRED_FRAME_RATE}" "60.000000"
check_and_export_if_not_empty "bool" "bUseFixedFrameRate" "${USE_FIXED_FRAME_RATE}" "false"
check_and_export_if_not_empty "float" "FixedFrameRate" "${FIXED_FRAME_RATE}" "120.000000"
check_and_export_if_not_empty "int" "NetClientTicksPerSecond" "${NET_CLIENT_TICKS_PER_SECOND}" "120"

check_and_export "int" "TimeBetweenPurgingPendingKillObjects" "${TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS}" "30"
check_and_export_if_not_empty "int" "TimeBetweenPurgingPendingKillObjects" "${TIME_BETWEEN_PURGING_PENDING_KILL_OBJECTS}" "30"

check_and_export "bool" "rThreadedRendering" "${THREADED_RENDERING}" "true"
check_and_export "bool" "rThreadedPhysics" "${THREADED_PHYSICS}" "true"
check_and_export_if_not_empty "bool" "rThreadedRendering" "${THREADED_RENDERING}" "true"
check_and_export_if_not_empty "bool" "rThreadedPhysics" "${THREADED_PHYSICS}" "true"

envsubst < "${GAME_ENGINE_FILE}" > "${GAME_ENGINE_FILE}.tmp" && mv "${GAME_ENGINE_FILE}.tmp" "${GAME_ENGINE_FILE}"
envsubst < "${GAME_ENGINE_FILE}.tmp" > "${GAME_ENGINE_FILE}" && rm "${GAME_ENGINE_FILE}.tmp"

log_success ">>> Finished setting up Engine.ini!"

trim_file "${GAME_ENGINE_FILE}"
else
log_warning ">> 'ENGINE_CONFIG_MODE' is set to '${ENGINE_CONFIG_MODE}', skipping '${GAME_ENGINE_FILE}' configuration!"
fi

log_success ">>> Finished setting up Engine.ini!"
}
Loading

0 comments on commit 2869d6b

Please sign in to comment.