Configuration
Documentation on configuring Irminsul
Irminsul is highly flexible and can be configured however you'd like. Irminsul is configured though the config.hjson file located in the server's run directory. If the configuration file can't be located when the server starts, one is created using default values.
The configuration file uses the excellent HJson format, a flavor of JSON supporting comments, and without commas (among other improvements).
Structure
The config.hjson file is comprised of three sections: global settings, HTTP server settings, and game server settings. The global and HTTP sections are simple JSON objects, whereas the game server section is an array of JSON objects, as Irminsul supports multiple game servers, each with their own configuration. One game server is created for every valid entry in the game servers array.
Global settings
# Global settings that affect the entire network/ecosystem
"global": {
"target_version": "4.0.0" # The game version that may connect to this network
"language": "en_US" # The language for Irminsul to use in logs and in-game. Either "en_US" or "zh_CN".
"hide_addresses": true # Whether to prevent the logging of the IP addresses of clients
}The global section is the smallest, and is used to specify settings that affect the entire network.
target_version (string)
The game version that may connect to this network. Defaults to "4.0.0".
language (string)
The language Irminsul will use in logs and in-game. Valid options are "en_US" (English) and "zh_CN" (Simplified Chinese). Using another option will raise a warning and fallback to English. Defaults to "en_US".
hide_addresses (boolean)
Whether to prevent the logging of IP addresses of clients. When enabled, Irminsul will not print players' IP addresses to the console or in log files.
Additionally, Irminsul will try to hide IP addresses from plugins when enabled, but this may not be perfect. As always, do not use plugins you do not trust.
Defaults to true.
HTTP server settings
# The settings used to configure the HTTP server.
# If you do not need the HTTP server, set "enabled" to false.
"http": {
"enabled": true # Whether the HTTP server is enabled
"port": 3000 # The port the HTTP server will run on. End users connect to this.
"ssl": false # Whether the HTTP server should use HTTPS encryption
"client_debugging": false # Whether to enable integration with the game client's debugging/logging system
# A list of target game servers this HTTP server will dispatch to.
# Refer to the example configuration file if you need help building entries for this array.
"targets": [
{
"name": "irminsul" # The internal name of the region
"title": "Irminsul" # The display name of the region, shown to the user at the login screen
"ip": "127.0.0.1" # The IP of the region's game server
"port": 22102 # The port of the region's game server
}
]
}The HTTP section can be used to configure Irminsul's HTTP server, or disable it entirely. The HTTP server consists of an authentication service and a dispatch service.
enabled (boolean)
Whether the HTTP server is enabled. It is recommended to disable the HTTP server if you do not need it to save resources. Defaults to true.
port (int)
The port the HTTP server will run on. This is what end users will connect to from their launchers. Defaults to 3000.
ssl (boolean)
Whether the HTTP server should use HTTPS encryption. Defaults to false.
client_debugging (boolean)
Whether to enable integration with the game client's debugging/logging system. When enabled, Irminsul will listen for logs and stack traces POSTed by the client, parse them, and log them. This is an extremely useful feature for debugging and development, but can get annoying in production. Defaults to false.
targets (JSON array)
A list of target game servers this HTTP server will dispatch to. In other words, a list of regions that will be visible to players that they may connect to, each with a separate game server. By default, this array contains a single entry pointing to the game server created in the default configuration on localhost.
Entries in this array must conform to the standard format:
name (string): The internal name of the region. By convention, this is in snake_case.
title (string): The display name of the region, shown to the user at the login screen.
ip (string): The IP address of the region's game server.
port (int): The port of the region's game server.
Game server settings
# A list of game servers to run, and the settings used to configure each of them.
# If you do not need any game servers, simply leave an empty array. By default, one game server is created.
# Refer to the example configuration file if you need help building entries for this array.
"game_servers": [
{
"port": 22102 # The port this game server will run on.
"sandbox": true # Whether this game server will operate in sandbox mode, unlocking basically everything.
# Configuration for in-game server account, a way to provide an interactive message bot for users
"server_account": {
"enabled": true # Used to enable/disable the entire in-game server account
# Account customization
"account_nickname": "Server" # The in-game display name of the server account
"account_signature": "Server console" # The in-game signature of the server account
# Message sent to users when they join the server
"welcome_message": "Welcome to the server!" # Message sent to players upon joining. Blank to disable.
"welcome_emote": 4010 # Emote sent to players upon joining. Zero to disable.
# Commands
"commands_enabled": true # Toggle the ability to execute commands via the account
}
# Configuration for mail sent to players when they join the server for the first time
"welcome_mail": {
"enabled": true # Used to enable/disable the welcome mail system
"file": "welcome_mail.txt" # The name of the text file containing the welcome mail to use
"subject": "Welcome to Irminsul!" # The subject of the welcome mail
"sender": "Server" # The sender of the welcome mail
}
# List of enabled plugins on this server
"plugins": [
]
}
]The game server section can be used to configure the number of game servers Irminsul will start, and the configuration for each of them.
The game server section consists of a single JSON array of server configurations. For each valid entry in the array, a game server is created using those settings.
Entries in this array must conform to the standard format:
port (int)
The port this game server will run on. Defaults to 22102.
sandbox (boolean)
Whether this game server will operate in sandbox mode, as opposed to realism mode. Choose whichever is more appropriate for your use case.
Sandbox mode unlocks all teleport waypoints, domains, features, characters, areas, etc., as opposed to realism mode, which attempts to emulate the vanilla experience.
Defaults to true.
server_account (JSON object)
Configuration for the in-game server account, a way to create an interactive message bot for users in-game. When enabled, the server account will show up in the chat UI and friends list of all players.
enabled (boolean): Used to enable/disable the entire in-game server account system. Defaults to true.
account_nickname (string): The in-game nickname of the server account. Defaults to "Server".
account_signature (string): The in-game signature of the server account, visible from the friends list. Defaults to "Server console".
welcome_message (string): An optional message sent to players when they connect to the server. Providing an empty string will disable the feature. Defaults to "Welcome to the server!".
welcome_emote (int): An optional emote sent to players when they connect to the server. Providing a value of zero will disable the feature. Defaults to 4010.
commands_enabled (boolean): Used to enable/disable the ability for players to execute server commands by messaging the server account. If disabled, messaging the server account will provide players with a notice that commands are not enabled on the server. Defaults to true.
welcome_mail (JSON object)
Configuration for mail sent to players when they join the server for the first time.
enabled (boolean): Used to enable/disable the entire welcome mail system. Defaults to true.
file (string): The name of a text file containing the welcome mail contents. Defaults to "welcome_mail.txt", which is generated automatically.
subject (string): The subject (title) of the welcome mail. Defaults to "Welcome to Irminsul!".
sender (string): The sender of the mail. Defaults to "Server".
plugins (JSON array)
List of enabled plugins on this game server.
The game server will search for plugins in the plugins directory in the server run directory. Provide the exact file name of the plugin you wish to use. The .jar at the end of plugins is optional.
For more information, refer to the Plugin Installation Tutorial.
Defaults to an empty array.
Last updated