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!"

# port of the game server
port = 60010

# maximum amount of players allowed to be connected at one time
max_players = 32

# first used gamemode when the server starts. this must be one of
# registered gamemodes.
gamemode = "babel"

# basically whether to show our server on the master server or not
broadcast_to_master = true

# port for querying the game server for e.g. server list purposes
query_port = 60011

# this port is used to heartbeat ie. disconnect stale clients
heartbeat_port = 60012

# set to true to make your server show on the modded section in server list
modded = true

# enable to automatically shutdown the server after some time. this is recommended only if you have configured the server to automatically start 
# after stopping, so this is sort of auto restart feature.
auto_shutdown = true

# time in seconds, after which the server will shutdown, if auto shutdown is enabled.
shutdown_after = 86400

# first used map when the server starts.
map = "Leaves2"

# whether this server uses DLC content or not. default is false.
# if you want to host server with DLC content you MUST set this to true
# before starting the server. if this is false it effectively means
# that this is F2P server and anyone can connect to it even if they dont
# own the DLC.
is_dlc_server = false

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.