ACE SQUARED DEDICATED SERVER CONFIGURATION

General

You need to have config.toml configuration file at build_Data/StreamingAssets/config.toml

If this file does not exist it will be auto-generated on first time start of the server.

Here is an example config:

# server name shown on the list
server_name = "EU Ace Squared Server"

# shown upon connection
description = "Best game, please give review on steam!"

# maximum amount of players allowed to be connected at one time (hard limit is 32)
max_players = 32

# first used map when the server starts
map = "2isles"

# first used gamemode when the server starts (must be a registered gamemode)
gamemode = "classicctf"

# whether to show this server on the master server list
broadcast_to_master = true

# game port
port = 30001

# server query port (used for server list querying)
query_port = 30002

# heartbeat port (used to detect stale clients)
heartbeat_port = 30003

# set true to show in modded section of server list
modded = false

# enable to automatically shutdown after some time
# recommended only if your host restarts the process automatically
auto_shutdown = false

# time in seconds before shutdown when auto_shutdown is enabled
shutdown_after = 86400

# server content licensing mode: "free", "mixed", or "dlc"
server_type = "free"

# log retention count
logging_max_archive_files = 10

# max size per archived log file
logging_max_archive_file_size = "1 mb"

# server log level: "trace", "debug", "information", "warning", "error", "fatal"
log_level = "information"

# periodic stats logging interval in seconds; negative disables
log_statistics_interval = -1

# enable remote console
use_rcon = false
rcon_port = 30004
rcon_password = "change-me"

# if true, use moderation records from master backend
use_master_moderation_records = false

RCON

Ace Squared dedicated server includes RCON support for remote administration.

To enable RCON:

  • set use_rcon = true
  • choose the port in rcon_port
  • set rcon_password to a non-empty password

Example:

use_rcon = true
rcon_port = 30004
rcon_password = "replace-this-with-a-strong-password"

Connecting to RCON

You can download an RCON client from RemoteConsoleLib v0.1 release.

After RCON is enabled, connect using:

  • host: 127.0.0.1
  • port: the value of rcon_port
  • password: the value of rcon_password

Security notes

WARNING: At the time of writing, RCON connections are not encrypted.

The dedicated server currently binds the RCON server to 127.0.0.1 only. This means:

  • local connections work directly
  • remote connections do not work unless you create your own secure tunnel

If you need remote access, use a secure tunnel such as SSH port forwarding and then connect your RCON client to the forwarded local port.

Do not expose RCON directly to the public internet. Because the transport is not encrypted, it should only be used locally or through a secure tunnel that you control.

Server type modes

Use server_type in config.toml to control DLC behavior.

Valid values are free, mixed, and dlc.

free

  • Players can join without owning DLC.
  • Gamemodes that require DLC-only content are not registered.

mixed

  • Players can join without owning DLC.
  • DLC and non-DLC content may both exist on the server.
  • A gamemode is registered only if it has at least one free-usable class path.
  • Free-to-play players can only use free-usable classes so DLC content is locked for them.

A class path is free-usable when:

  • The class itself is non-DLC.
  • Equipped items (e.g. jetpacks) are all non-DLC (or empty).
  • Each toolbelt slot has at least one non-DLC option.

dlc

  • Players must own the DLC to join.
  • DLC and non-DLC content can be registered.

WARNING: is_dlc_server is deprecated and should not be used. Use server_type = "free" | "mixed" | "dlc" instead.

NOTE: If you are hosting e.g. on your local machine and want people to connect, you must port forward all used ports. Otherwise other people will not be able to connect. This process is similar to port forwarding any other game server (e.g. minecraft). If you are hosting on cloud server like VPS you may not need to do port forwarding.

Cvars

Server has various cvars. Cvars are used to configure server, even at runtime. You may access these via 'sv.'-prefix in the in-game console, or via the cvars.txt file. At startup cvars are loaded from the file, and saved when changed.

Cvars are split into two groups: default cvars and instance cvars. Default cvars are general configuration (for example respawn time).

Instance cvars are for setting up configuration for classes/items/network behaviours (definitions in .toml files). For example with instance cvars you may change weapon firerate, damage, class run speed, jump height (and many others!)

You may reset all cvars at runtime via /resetcvar command in game. You may also reset all cvars by deleting the cvars.txt file and restarting the server.

You must be authenticated as administrator on the server to be able to use server cvars in-game.

Changing some cvars at runtime will require certain object to respawn, so that the changes take effect. For example if you change flag's zone width, you will need to pickup the flag and then drop it, for the new width to be used (or just restart round or server).

NOTE: there is no cvar validation other than type check - please ensure your values are sane.

For example:

  • certain values should never be negative (such as respawn time)
  • setting certain floats to 0 may cause weird behaviour due to division by zero error
  • if you set explosion radius to something large, it will cause performance issues on the server
  • in min/max config vars, min should be always less than or equal to max. (min <= max)

Environment settings

Environment settings are per-map settings. You have the following settings available:

  • skybox_path (string)
  • lighting_color (string)
  • skybox_color (string)
  • ambient_sfx (string)

More information about setting a custom skybox later in this section.

This is an object by key "environment_settings" in the map config file (json file in the map folder). 0 is used as uninitialized / error / null so if you want to use black color for something you need to use for example #000001, and if you wanna set a small float you need to use 0.00001 for example (cant use zero).

Colors are set as html string, for example #AABBCC.

// example environment settings json property for a map
// with night setting
{
    // ... other map json data
    "environment_settings": {
        "skybox_path" : "Skyboxes/NightSky",
        "lighting_color" : "#808080",
        "skybox_color": "#000001",
        "ambient_sfx": "SfxLarge/YOUR_AMBIENT_SOUND_FILE.ogg"
    }
}

Setting a custom skybox

First of all you need to have 6 images (png format) because the current solution is using 6-sided cubemap.

You need to place these in some place in StreamingAssets (I recommend StreamingAssets/Skyboxes).

These files must be named exactly: front.png, back.png, left.png, right.png, top.png, bot.png.

Finally you just set skybox_path point to the correct skybox. (path is relative to the StreamingAssets directory)

Skyboxes are cached on the client so the server will not retransmit skybox if client already has it.

Remarks

1) Recommended file size for each texture is 1024x1024. Higher file size in general will result in more lag and increased bandwidth usage.
2) There is test skybox in Skyboxes/TestSky for testing purposes, you might want to use this to visualize which skybox side corresponds to which in-game axis.

Setting a custom map ambient sound

Ambient sound in this context means a map specific sound that is looped on the background, it should have quite small volume.

Place your sound file in directory StreamingAssets\SfxLarge, set path to this file (suffix included) in the map's config file in entry ambient_sfx in the environment settings. This path is relative to StreamingAssets directory, much like skybox_path.

Only mp3 and ogg files are supported. Please ensure your ambient sound file's name has either suffix. If you want to change the volume, for now you need to edit the sound file itself.

Light blocks

Voxel is defined as light voxel, if it's alpha value is 1, 2, ..., 254. Alpha values 0 and 255 are reserved and mean the voxel is normal (ie. does not emit light). This alpha value is also the brightness of the voxel.

For now you need to set light voxels via the lua scripting api unfortunately. This is because we are using .VXL file format and it has some limitations. You might wanna just cache light voxel data (positions and RGBA values) per map and then set those light voxels right after the map has loaded (OnWorldLoaded callback).

For setting light blocks just call any relevant api like WorldProxy::SetVoxels with your selected RGBA values.

Using custom blueprints

Blueprint files (both sprite and the blueprint file) must be present on server startup so they will be registered in the resource manager.

Place your custom blueprint in StreamingAssets\Blueprints directory. Custom blueprint's filename must end with .txt suffix.

You should also specify an icon for your custom blueprint. They go to StreamingAssets\Sprites directory and their filename must end with .png suffix. Also blueprint's icon must have the same filename (without) extension as the blueprint file itself, so the icon will be associated with the correct blueprint.

For example if you have blueprint called Blueprints\miniball.txt, you should place your sprite at Sprites\miniball.png. Maximum recommended sprite image size is 256x256 pixels.

Now if the server starts without errors, you can start using the blueprint with a custom lua script.

Note: For best user experience you should include sprite with your blueprint that represents the blueprint itself.

How to make blueprint file

Open goxel and model your blueprint and export as text (at least Goxel 0.14.0 should work), then copy paste this file to the blueprints directory.

Note: every voxel in a single blueprint MUST be connected to every other voxel in 3 cardinal axises (6 cardinal directions), that is forward, right, up. This is so that the voxel linker may link every placed voxel using 6-connectivity.

Authentication

Server administrators and moderators are stored in authlist.txt. Each line is a new entry. First is steamid64, then a pipe character and finally mod/admin string. Modifying this list requires a server restart for the changes to apply.

// example authlist.txt
76561199747576549 | admin
76561198155434643 | admin

Moderation

There are many moderation commands to be used in-game. You may view them via the /help command when authenticated.

Banned players steamid64s are stored in banlist.txt and muted players are stored in mutelist.txt. If you want to ban/mute someone, but they are not on the server, you may add their steamid to this list (without pipe character and rest of the line). Modifying these files requires a server restart for the changes to apply.

Other notes

Due to some server limitations, you should configure your server to restart at least every 24 hours.