Runfiles - SteamServerUI/SteamServerUI GitHub Wiki

SteamServerUI Runfile Documentation

Introduction

A runfile is the heart of SteamServerUI (SSUI), defining how to launch and manage a game server. Each runfile is a JSON configuration file that specifies the game's Steam App ID, executables, and command-line arguments. This documentation explains the structure and purpose of runfiles, along with how to create or modify them for your specific game server needs.

File Format

Runfiles follow a standard naming convention and are stored with a .ssui extension:

run{GameName}.ssui

Where {GameName} must start with an uppercase letter and contain only alphanumeric characters (no spaces).

Example: runValheim.ssui, runSatisfactory.ssui, runStationeers.ssui

Runfile Structure

A runfile consists of the following main sections:

Section Description
meta Basic information about the runfile
architecture Target architecture for the server (e.g., "linux", "windows")
steam_app_id The Steam App ID for the game server
steam_login_required Whether Steam login is required (boolean)
windows_executable Path to the Windows server executable
linux_executable Path to the Linux server executable
args Command-line arguments categorized by type

Full Example

{
  "meta": {
    "name": "Stationeers",
    "version": "1.1"
  },
  "architecture": "linux",
  "steam_app_id": "600760",
  "steam_login_required": false,
  "windows_executable": "./rocketstation_DedicatedServer.exe",
  "linux_executable": "./rocketstation_DedicatedServer.x86_64",
  "args": {
    "basic": [
      {
        "flag": "-nographics",
        "default": "",
        "required": true,
        "requires_value": false,
        "description": "Run without graphics",
        "type": "bool",
        "ui_label": "Disable Graphics",
        "ui_group": "Basic",
        "weight": 10
      },
      // More basic arguments...
    ],
    "network": [
      // Network-related arguments...
    ],
    "advanced": [
      // Advanced configuration arguments...
    ]
  }
}

Section Details

Meta Section

"meta": {
  "name": "GameName",
  "version": "1.1"
}
  • name: Must match the game name in the filename
  • version: Runfile specification version

Architecture and Executables

"architecture": "linux",
"steam_app_id": "600760",
"steam_login_required": false,
"windows_executable": "./game_server.exe",
"linux_executable": "./game_server.x86_64"
  • architecture: Preferred architecture ("linux" or "windows")
  • steam_app_id: Numeric Steam App ID for the game server
  • steam_login_required: Whether Steam credentials are needed (currently unused)
  • windows_executable: Path to Windows executable (must end with .exe)
  • linux_executable: Path to Linux executable (must not end with .exe)

Arguments Section

Arguments are categorized into three groups: basic, network, and advanced.

"args": {
  "basic": [ /* Basic arguments */ ],
  "network": [ /* Network arguments */ ],
  "advanced": [ /* Advanced arguments */ ]
}

Each argument object has the following properties:

Property Description
flag The command-line flag/parameter (e.g., -port)
default Default value for the argument
required Whether the argument is required (boolean)
requires_value Whether the argument needs a value (boolean)
description Human-readable description of the argument
type Data type: "string", "int", or "bool"
special Special handling instructions (e.g., "space_delimited")
ui_label Label displayed in the UI
ui_group Grouping in the UI ("Basic", "Network", "Advanced")
weight Sorting weight (lower values appear first)
min Minimum value (for "int" type)
max Maximum value (for "int" type)
disabled Whether the argument is disabled (boolean)

Argument Types and Validation

String Arguments

{
  "flag": "ServerName",
  "default": "My Game Server",
  "required": true,
  "requires_value": true,
  "description": "Name of the server",
  "type": "string",
  "ui_label": "Server Name",
  "ui_group": "Basic",
  "weight": 80
}
  • No specific validation beyond being a string

Integer Arguments

{
  "flag": "GamePort",
  "default": "27016",
  "required": true,
  "requires_value": true,
  "description": "Main game port",
  "type": "int",
  "min": 1024,
  "max": 49151,
  "ui_label": "Game Port",
  "ui_group": "Network",
  "weight": 200
}
  • Must be a valid integer
  • Can have optional min and max values for validation

Boolean Arguments

{
  "flag": "-nographics",
  "default": "",
  "required": true,
  "requires_value": false,
  "description": "Run without graphics",
  "type": "bool",
  "ui_label": "Disable Graphics",
  "ui_group": "Basic",
  "weight": 10
}
  • Valid values: "true", "false", or empty string
  • When requires_value is false, the flag is simply included or excluded

Special Handling

Space-Delimited Arguments

{
  "flag": "-LOAD",
  "default": "Moon Moon",
  "required": true,
  "requires_value": true,
  "description": "Initial game save to load",
  "type": "string",
  "special": "space_delimited",
  "ui_label": "Load Savegame",
  "ui_group": "Basic",
  "weight": 30
}
  • special: "space_delimited" splits the value on spaces and adds each part as a separate argument
  • Example command line: -LOAD Moon Moon (not -LOAD "Moon Moon")

Argument Ordering

Arguments are sorted by:

  1. weight (primary sorting key)
  2. ui_group (secondary sorting key, with "Basic" < "Network" < "Advanced")

Lower weights appear first in the command line.

Validation Rules

Runfiles are validated to ensure:

  1. SteamAppID is non-empty and numeric
  2. WindowsExecutable ends with .exe (if provided)
  3. LinuxExecutable does not end with .exe (if provided)
  4. Meta.Name is non-empty
  5. Required arguments with requires_value have values
  6. Integer arguments have valid integer values
  7. Boolean arguments have valid boolean values

Creating a New Runfile

To create a new runfile:

  1. Choose a name that starts with an uppercase letter and contains only alphanumeric characters
  2. Create a JSON file named run{YourGameName}.ssui
  3. Follow the structure outlined above
  4. Include all required fields and arguments
  5. Test the runfile with SteamServerUI

Debugging a Runfile

If your runfile isn't working as expected:

  1. Check the SteamServerUI logs for validation errors
  2. Verify the Steam App ID is correct
  3. Ensure executable paths are correct
  4. Confirm required arguments have appropriate values
  5. Test the generated command line manually to identify issues

Example: Minimal Valid Runfile

{
  "meta": {
    "name": "MinimalGame",
    "version": "1.1"
  },
  "architecture": "linux",
  "steam_app_id": "123456",
  "windows_executable": "./server.exe",
  "linux_executable": "./server",
  "args": {
    "basic": [
      {
        "flag": "-port",
        "default": "27015",
        "required": true,
        "requires_value": true,
        "description": "Server port",
        "type": "int",
        "ui_label": "Port",
        "ui_group": "Basic",
        "weight": 10
      }
    ],
    "network": [],
    "advanced": []
  }
}

This documentation should help you understand, create, and modify runfiles for SteamServerUI to manage your game servers efficiently.