Configuration Guide

January 17, 2026 · View on GitHub

Valhalla can be configured using TOML configuration files or environment variables. This guide covers all available configuration options.

Configuration Methods

TOML Configuration Files

Each server type has its own configuration file:

config_login.toml - Login server
config_world.toml - World server
config_channel_<N>.toml - Channel servers (one per channel)
config_cashshop.toml - Cash shop server

Environment Variables

For containerized deployments, configuration can be set via environment variables. Variable names follow this pattern:

VALHALLA_<SECTION>_<KEY>=value

For example:

[login]
clientListenAddress = "0.0.0.0"

Becomes:

VALHALLA_LOGIN_CLIENTLISTENADDRESS=0.0.0.0

Command Line Flags

All server executables accept the following flags:

Flag	Required	Description	Example
`-type`	Yes	Server type to start	`-type login`, `-type world`, `-type channel`, `-type cashshop`
`-config`	No	Path to TOML config file	`-config config_login.toml`
`-metrics-port`	No	Port for Prometheus metrics	`-metrics-port 9000` (default)
`-channels`	No	Amount of Channels when running in dev mode	`-channels 2` (default)

Example Commands

# Login server with custom config
./Valhalla -type login -config config_login.toml

# World server with default config and custom metrics port
./Valhalla -type world -metrics-port 9001

# Channel server
./Valhalla -type channel -config config_channel_1.toml

Database Configuration

All server types require database configuration.

Parameter	Type	Description	Default
`address`	string	Database server address	`127.0.0.1`
`port`	string	Database server port	`3306`
`user`	string	Database username	`root`
`password`	string	Database password	`password`
`database`	string	Database name	`maplestory`

Environment Variable Prefix: VALHALLA_DATABASE_

Example

[database]
address = "127.0.0.1"
port = "3306"
user = "root"
password = "password"
database = "maplestory"

Configuration section: [login]

Parameter	Type	Description	Default	Env Variable
`clientListenAddress`	string	Address to listen for client connections	`0.0.0.0`	`VALHALLA_LOGIN_CLIENTLISTENADDRESS`
`clientListenPort`	string	Port for client connections	`8484`	`VALHALLA_LOGIN_CLIENTLISTENPORT`
`serverListenAddress`	string	Address to listen for server connections	`0.0.0.0`	`VALHALLA_LOGIN_SERVERLISTENADDRESS`
`serverListenPort`	string	Port for server connections	`8485`	`VALHALLA_LOGIN_SERVERLISTENPORT`
`withPin`	bool	Enable PIN code requirement	`false`	`VALHALLA_LOGIN_WITHPIN`
`autoRegister`	bool	Auto-create accounts on login attempt	`false`	`VALHALLA_LOGIN_AUTOREGISTER`
`packetQueueSize`	int	Size of packet processing queue	`512`	`VALHALLA_LOGIN_PACKETQUEUESIZE`
`latency`	int	Simulated latency in milliseconds (for testing)	`0`	`VALHALLA_LOGIN_LATENCY`
`jitter`	int	Simulated jitter in milliseconds (for testing)	`0`	`VALHALLA_LOGIN_JITTER`

Auto-Register Feature

When autoRegister = true:

New accounts are automatically created when users attempt to login with non-existent credentials
Default values: gender=0, dob=1111111, eula=1, adminLevel=0, PIN="1111"
Security Note: Only enable this for development or private servers. Disable for production.

Example

[login]
clientListenAddress = "0.0.0.0"
clientListenPort = "8484"
serverListenAddress = "0.0.0.0"
serverListenPort = "8485"
withPin = false
autoRegister = false
packetQueueSize = 512
latency = 0
jitter = 0

World Server Configuration

Configuration section: [world]

Parameter	Type	Description	Default	Env Variable
`message`	string	World server message displayed to players	`message`	`VALHALLA_WORLD_MESSAGE`
`ribbon`	int	Ribbon type (0=none, 1=event, 2=new, 3=hot)	`2`	`VALHALLA_WORLD_RIBBON`
`expRate`	float	Experience rate multiplier	`1.0`	`VALHALLA_WORLD_EXPRATE`
`dropRate`	float	Drop rate multiplier	`1.0`	`VALHALLA_WORLD_DROPRATE`
`mesosRate`	float	Mesos rate multiplier	`1.0`	`VALHALLA_WORLD_MESOSRATE`
`loginAddress`	string	Login server address	`127.0.0.1`	`VALHALLA_WORLD_LOGINADDRESS`
`loginPort`	string	Login server port	`8485`	`VALHALLA_WORLD_LOGINPORT`
`listenAddress`	string	Address to listen for connections	`0.0.0.0`	`VALHALLA_WORLD_LISTENADDRESS`
`listenPort`	string	Port to listen on	`8584`	`VALHALLA_WORLD_LISTENPORT`
`packetQueueSize`	int	Size of packet processing queue	`512`	`VALHALLA_WORLD_PACKETQUEUESIZE`

Ribbon Types

0 - No ribbon
1 - Event ribbon (yellow)
2 - New ribbon (green)
3 - Hot ribbon (red)

Example

[world]
message = "Welcome to Valhalla!"
ribbon = 2
expRate = 1.0
dropRate = 1.0
mesosRate = 1.0
loginAddress = "127.0.0.1"
loginPort = "8485"
listenAddress = "0.0.0.0"
listenPort = "8584"
packetQueueSize = 512

Channel Server Configuration

Configuration section: [channel]

Parameter	Type	Description	Default	Env Variable
`worldAddress`	string	World server address	`127.0.0.1`	`VALHALLA_CHANNEL_WORLDADDRESS`
`worldPort`	string	World server port	`8584`	`VALHALLA_CHANNEL_WORLDPORT`
`listenAddress`	string	Address to listen for server connections	`0.0.0.0`	`VALHALLA_CHANNEL_LISTENADDRESS`
`listenPort`	string	Port for server connections	`8685`	`VALHALLA_CHANNEL_LISTENPORT`
`clientConnectionAddress`	string	Address clients connect to (external IP)	`127.0.0.1`	`VALHALLA_CHANNEL_CLIENTCONNECTIONADDRESS`
`packetQueueSize`	int	Size of packet processing queue	`512`	`VALHALLA_CHANNEL_PACKETQUEUESIZE`
`maxPop`	int	Maximum channel population	`250`	`VALHALLA_CHANNEL_MAXPOP`
`latency`	int	Simulated latency in milliseconds (for testing)	`0`	`VALHALLA_CHANNEL_LATENCY`
`jitter`	int	Simulated jitter in milliseconds (for testing)	`0`	`VALHALLA_CHANNEL_JITTER`

Important: Multiple Channels

Each channel requires its own configuration file and process. Channels are numbered starting from 1:

Channel 1: listenPort = 8685
Channel 2: listenPort = 8686
Channel 3: listenPort = 8687
And so on...

Example

[channel]
worldAddress = "127.0.0.1"
worldPort = "8584"
listenAddress = "0.0.0.0"
listenPort = "8685"
clientConnectionAddress = "127.0.0.1"
packetQueueSize = 512
maxPop = 250
latency = 0
jitter = 0

Cash Shop Server Configuration

Configuration section: [cashshop]

Parameter	Type	Description	Default	Env Variable
`worldAddress`	string	World server address	`127.0.0.1`	`VALHALLA_CASHSHOP_WORLDADDRESS`
`worldPort`	string	World server port	`8584`	`VALHALLA_CASHSHOP_WORLDPORT`
`listenAddress`	string	Address to listen for server connections	`0.0.0.0`	`VALHALLA_CASHSHOP_LISTENADDRESS`
`listenPort`	string	Port for server connections	`8600`	`VALHALLA_CASHSHOP_LISTENPORT`
`clientConnectionAddress`	string	Address clients connect to (external IP)	`127.0.0.1`	`VALHALLA_CASHSHOP_CLIENTCONNECTIONADDRESS`
`packetQueueSize`	int	Size of packet processing queue	`512`	`VALHALLA_CASHSHOP_PACKETQUEUESIZE`
`latency`	int	Simulated latency in milliseconds (for testing)	`0`	`VALHALLA_CASHSHOP_LATENCY`
`jitter`	int	Simulated jitter in milliseconds (for testing)	`0`	`VALHALLA_CASHSHOP_JITTER`

Example

[cashshop]
worldAddress = "127.0.0.1"
worldPort = "8584"
listenAddress = "0.0.0.0"
listenPort = "8600"
clientConnectionAddress = "127.0.0.1"
packetQueueSize = 512
latency = 0
jitter = 0

Network Configuration Tips

Local Development

For local testing:

clientConnectionAddress = "127.0.0.1"

LAN/Remote Access

For LAN or internet access, set to your server's external IP:

clientConnectionAddress = "192.168.1.100"  # LAN
# or
clientConnectionAddress = "203.0.113.1"    # Public IP

Docker/Kubernetes

See Docker.md and Kubernetes.md for container-specific networking.

Performance Tuning

Packet Queue Size

Higher values can handle more simultaneous connections but use more memory:

Small servers (1-50 players): 512
Medium servers (50-200 players): 1024
Large servers (200+ players): 2048

Latency Simulation

For development environments mimicking real-world conditions:

latency = 50    # 50ms base latency
jitter = 10     # ±10ms variation

Note: Always set to 0 for production servers.