Configuration Guide

This document covers all configuration options available in openRoads, including server tick system, spawning, display settings, and runtime options.

Configuration Files

config.ini

The main configuration file is located at config/config.ini. This file uses a simple INI format with sections and key-value pairs.

# openroads/config/config.ini

[Routines]
# Time for the nightly cleanup to run (24-hour format, HH:MM)
NightlyCleanupTime=03:00

# Enable active room cleanup (only rooms with players)
ActiveRoomCleanup=true

[Spawning]
# Server tick configuration
ServerTickSpeed=1000        # Milliseconds per server tick (1000ms = 1 second)
SpawnCheckInterval=30       # How many ticks between spawn checks (30 ticks = 30 seconds with 1s ticks)
SpawnProbability=0.3        # Probability of spawning when conditions are met (0.3 = 30% chance)

World Configuration Files

• world/formatted_rooms.json: Room definitions and properties

• world/players.json: Player data storage

• world/enemies.json: Enemy definitions and spawn settings

Server Tick System

The server tick system provides precise timing control for enemy spawning and other game mechanics.

Tick Configuration

ServerTickSpeed (milliseconds)

• Default: 1000ms (1 second per tick)

• Range: 100ms - 5000ms recommended

• Purpose: Controls how frequently the server processes game events

• Performance Impact: Lower values = higher CPU usage but more responsive gameplay

SpawnCheckInterval (ticks)

• Default: 30 ticks

• Range: 1 - 300 ticks recommended

• Purpose: How many ticks between enemy spawn attempts

• Calculation: Actual time = SpawnCheckInterval × ServerTickSpeed

SpawnProbability (0.0 - 1.0)

• Default: 0.3 (30% chance)

• Range: 0.0 (never) to 1.0 (always)

• Purpose: Probability of spawning when all conditions are met

Configuration Scenarios

High Performance Server

ServerTickSpeed=500         # 0.5 second ticks
SpawnCheckInterval=60       # Check every 30 seconds
SpawnProbability=0.4        # 40% spawn chance

• Use case: Powerful server, want responsive gameplay

• Effect: More frequent processing, moderate spawn rate

Standard Server

ServerTickSpeed=1000        # 1 second ticks  
SpawnCheckInterval=30       # Check every 30 seconds
SpawnProbability=0.3        # 30% spawn chance

• Use case: Most servers, balanced performance

• Effect: Standard timing for most installations

Low Resource Server

ServerTickSpeed=2000        # 2 second ticks
SpawnCheckInterval=15       # Check every 30 seconds
SpawnProbability=0.2        # 20% spawn chance

• Use case: Limited server resources

• Effect: Less frequent processing, lower spawn rate

Enemy Spawning Configuration

Max Instances Enforcement

Each enemy type has a max-instances value in world/enemies.json:

{
  "rat": {
    "mechanics": {
      "max-instances": "2",
      "ticks-to-make": "1",
      "min-wander": "750",
      "max-wander": "756"
    }
  }
}

Enforcement Rules:

• Current count: System tracks how many instances of each enemy exist

• Spawn blocking: If current instances >= max instances, no new spawns

• Instance cleanup: Old enemies are automatically removed to free up slots

Spawn Timing Calculation

Formula: Actual Cooldown = ticks-to-make × ServerTickSpeed

Examples:

• Rat: 1 tick × 1000ms = 1 second cooldown

• Orc: 3 ticks × 1000ms = 3 second cooldown

• Dragon: 100 ticks × 1000ms = 100 second cooldown

Routine Configuration

Cleanup Settings

NightlyCleanupTime

• Format: HH:MM (24-hour format)

• Default: 03:00

• Purpose: When to run the nightly cleanup routine

ActiveRoomCleanup

• Type: Boolean (true/false)

• Default: true

• Purpose: Whether to clean up rooms that have active players

Runtime Configuration

Command-Line Flags

• --cleanup-every-minute: Forces cleanup to run every minute instead of at the scheduled time (useful for testing)

Environment Variables

Currently, openRoads does not use environment variables for configuration. All settings are managed through the config.ini file.

Performance Tuning

Tick Speed Impact

Faster Ticks (500ms):

• ✓ More responsive gameplay

• ✓ Precise timing control

• ✗ Higher CPU usage

• ✗ More frequent processing

Slower Ticks (2000ms):

• ✓ Lower CPU usage

• ✓ Better for resource-limited servers

• ✗ Less precise timing

• ✗ Potential gameplay delays

Spawn Check Frequency

More Frequent Checks (every 10 ticks):

• ✓ Enemies spawn more consistently

• ✓ Better world population

• ✗ Higher processing overhead

Less Frequent Checks (every 60 ticks):

• ✓ Lower processing overhead

• ✓ Burst spawning behavior

• ✗ Uneven enemy distribution

Monitoring & Debugging

Debug Logging

The system provides detailed logging to help administrators understand behavior:

SPAWN: DEBUG: rat can spawn (instances: 0/2)
SPAWN: DEBUG: orc at max instances (5/5)
SPAWN: DEBUG: skeleton spawn cooldown active (waited 2s, need 4s)
SPAWN: INFO: Spawned rat in room 750

Log Levels:

• DEBUG: Detailed decision information

• INFO: Successful events and major actions

• WARNING: Failed operations and configuration issues

• ERROR: System errors and invalid configurations

Key Metrics to Monitor

1. Spawn Success Rate: How often spawns succeed vs. fail

2. Instance Counts: Current vs. maximum instances per enemy

3. Cooldown Effectiveness: Are enemies spawning too frequently?

4. Server Performance: CPU usage during tick processing

Configuration Validation

The system validates configuration values on startup and will log warnings for:

• Invalid time formats

• Missing configuration files

• Unrecognized configuration keys

• Invalid numeric values

• Out-of-range parameters

World Configuration

Room Format

Rooms are defined in world/formatted_rooms.json using the following structure:

{
  "roomID": {
    "Short": "Room Title",
    "Long": "Detailed room description that can span multiple lines.",
    "Exits": {
      "north": "destinationRoomID",
      "east": "anotherRoomID"
    },
    "Items": [],
    "Players": [],
    "Enemies": [],
    "ItemDesc": "There is %s here."
  }
}

Room Properties

Property	Description
Short	Brief title of the room
Long	Detailed description shown when entering
Exits	Map of directions to destination room IDs
Items	List of items present in the room
Players	List of players currently in the room
Enemies	List of enemies present in the room
ItemDesc	Template for displaying items (uses %s placeholder)

Player Configuration

Player data is stored in world/players.json with the following structure:

{
  "playerName": {
    "Alias": "displayName",
    "Element": "fire",
    "CurrentRoomID": "startingRoom",
    "Brief": false
  }
}

Player Properties

Property	Description
Alias	Display name shown to other players
Element	Player's elemental affinity
CurrentRoomID	Room where player is currently located
Brief	Whether player uses brief room descriptions

Troubleshooting

Common Issues

Configuration not loading:

• Check file permissions on config/config.ini

• Verify the file exists and is readable

• Check for syntax errors in the INI format

Enemies not spawning:

1. Check max instances aren't exceeded

2. Verify ticks-to-make cooldowns

3. Confirm valid room ranges

4. Check spawn probability settings

Too many enemies:

1. Reduce max-instances in enemy definitions

2. Increase ticks-to-make cooldowns

3. Lower SpawnProbability

4. Enable cleanup routines

Performance problems:

1. Increase ServerTickSpeed (slower ticks)

2. Reduce SpawnCheckInterval frequency

3. Monitor CPU usage during peak times

4. Consider server hardware upgrades

Cleanup not running:

• Verify NightlyCleanupTime format is correct

• Check server logs for error messages

• Ensure the server has been running long enough to reach the cleanup time

Best Practices

1. Backup your config: Always backup config.ini before making changes

2. Test changes: Use --cleanup-every-minute to test cleanup settings

3. Monitor logs: Check server logs after configuration changes

4. Gradual changes: Make small incremental changes rather than large ones

5. Performance testing: Monitor server performance after tick speed changes

6. Balance gameplay: Ensure spawn rates provide good player experience

Tuning Guidelines

If enemies spawn too frequently:

• Increase ticks-to-make values in enemy definitions

• Decrease SpawnProbability

• Increase SpawnCheckInterval

If enemies spawn too rarely:

• Decrease ticks-to-make values

• Increase SpawnProbability

• Decrease SpawnCheckInterval

If server performance is poor:

• Increase ServerTickSpeed (slower ticks)

• Increase SpawnCheckInterval

• Decrease SpawnProbability