Skip to content

Ember schema

This reference describes native schema 1 for authoring game definitions. For creating, importing, and updating definitions in the panel, see Embers.

Native schema

Definitions can be JSON or YAML, up to 1 MiB. JSON property names are case-sensitive: artUrl and updateUrl use camel case; other compound names use underscores.

This small definition runs a diagnostic process rather than a real game:

{
"schema": 1,
"name": "Example server",
"description": "A minimal Ember for checking startup and console output.",
"images": { "Alpine": "alpine:3.22" },
"startup": "echo Ready; exec sleep 3600",
"startup_shell": "sh",
"work_dir": "/data",
"user": "1000:1000",
"variables": [],
"stop": "^SIGTERM",
"ready": "Ready"
}

The examples below are top-level fragments, not complete definitions. Merge relevant fields into one Ember; do not combine mutually exclusive alternatives.

Property Type Purpose
schema integer Required; 1
name string Required display name
description string Description; empty if omitted
artUrl string Optional artwork URL or panel asset path
updateUrl string Optional definition update source
id, revision string Panel-managed identity and content revision
origin object Optional import attribution and compatibility notes
images object Required nonempty map of image labels to container references
startup string One startup command; alternative to startup_commands
startup_commands object Named startup alternatives; cannot accompany a nonempty startup
startup_shell string sh (default), bash, or ash
work_dir string Required absolute container working directory
user string Required numeric non-root UID or UID:GID
variables array Variable definitions; empty if omitted
installer object Optional installation image, entrypoint, and script
stop string Console command or signal notation; image default if omitted
ready string Simple readiness marker; alternative to readiness
readiness object Structured readiness matchers
log_alerts array Actionable error rules
configs array Configuration-file replacements
required_ports array Container port requirements
savedata_paths array Paths included in save-data backups

Ownership, memberships, Spark placement, resource budgets, host port assignments, schedules, and backup storage/retention are server settings, not Ember properties. Game-state publishing requires a compatible game integration, not an additional Ember schema field.

Identity and metadata

{
"schema": 1,
"name": "My game",
"description": "Dedicated server definition",
"artUrl": "https://example.com/game.png",
"updateUrl": "https://example.com/ember.json"
}
Property Rules
name Nonblank, at most 120 bytes
description Descriptive text; does not affect execution
artUrl HTTPS URL or absolute panel asset path, at most 2,048 bytes; no embedded credentials, whitespace, or control characters
updateUrl Public HTTPS definition source used by the update workflow
id Assigned when importing; omit when authoring a new definition
revision Computed by Campfire from definition content; omit when authoring

Converted definitions may contain origin:

{
"origin": {
"format": "PTDL_v2",
"author": "Example author",
"update_url": "https://example.com/egg.json",
"warnings": ["Review the imported port mappings."]
}
}

format, author, and update_url are strings; warnings is an array of strings. This is provenance, not runtime configuration. The update workflow prefers updateUrl, falling back to origin.update_url. Importing from a URL records that source as the update URL. See definition updates.

Images and startup

{
"images": {
"Java 21": "eclipse-temurin:21-jre",
"Java 25": "eclipse-temurin:25-jre"
},
"startup": "java -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JAR}} nogui",
"startup_shell": "sh",
"work_dir": "/data",
"user": "1000:1000"
}
Property Rules
images At least one label-to-image entry; references must be nonempty, contain no whitespace/nulls, and not begin with -
startup Command template; referenced variables must be declared or built in
startup_shell Shell name only: sh, bash, or ash; must exist in the selected image
work_dir Absolute container path; no comma, newline, or null character
user Positive numeric UID, optionally followed by a numeric GID; root UID is not allowed

The example requires a SERVER_JAR variable. The selected image must contain the runtime and shell, and the game files must be installed separately.

For multiple choices, replace startup with startup_commands:

{
"startup_commands": {
"Normal": "java -jar {{SERVER_JAR}} nogui",
"Diagnostics": "java -verbose:gc -jar {{SERVER_JAR}} nogui"
}
}

Use at most 32 named commands. Names must be nonblank, at most 120 bytes, and have no line breaks or nulls; commands must be nonblank. Servers select a command by name; a single choice can be selected automatically. A nonempty startup and startup_commands cannot coexist. Server-specific overrides are configured under Servers, not in the shared definition.

Placeholders

Use {{NAME}} for a declared variable or built-in environment value. Unknown startup placeholders are rejected. Variable contents remain literal values during startup expansion rather than becoming shell syntax.

Campfire supplies these reserved environment values as strings. Do not redeclare their names or STARTUP as Ember variables.

Built-in Meaning and units
SERVER_PORT First mapped container port, not the public host port. With no mappings, falls back to the Ember’s first required port; empty if neither exists.
SERVER_IP Container listen address, 0.0.0.0; not the Spark’s public game address.
SERVER_MEMORY Configured memory limit in MiB, without a suffix; for example, 2048.
SERVER_CPU Configured CPU allocation as a percentage of one core: 100 is one core and 250 is 2.5 cores.
SERVER_THREADS Empty; Campfire does not assign a CPU-thread list.
SERVER_DISK Configured game-data disk limit in MiB, without a suffix; 0 means no configured limit. This is not free disk space.
SERVER_SWAP 0; additional container swap is disabled.

For example, -Xmx{{SERVER_MEMORY}}M appends the unit expected by Java. Resource values describe configuration, not live CPU or memory usage.

Installer

{
"installer": {
"image": "alpine:3.22",
"entrypoint": "/bin/sh",
"script": "#!/bin/sh\nset -eu\nmkdir -p /mnt/server/world\n"
}
}
Property Type and rules
image Container image reference, validated like a runtime image
entrypoint sh, bash, ash, /bin/sh, /bin/bash, or /bin/ash
script Shell script text executed by the chosen entrypoint

The installer uses its own image, independently of the runtime image. Its shell must exist in that image. Game files are installed into /mnt/server. Omitting installer means the definition supplies no installation script; importing an Ember never runs installation or accepts a game’s EULA. Treat scripts as executable code and use trusted sources.

Variables and validation

{
"variables": [
{
"name": "SERVER_JAR",
"default": "server.jar",
"required": true,
"editable": true,
"hidden": false,
"pattern": "^[A-Za-z0-9_.-]+\\.jar$",
"validation": { "type": "string", "min_length": 1, "max_length": 128 }
},
{
"name": "MAX_PLAYERS",
"default": "20",
"required": true,
"editable": true,
"validation": { "type": "integer", "min": 1, "max": 100 }
},
{
"name": "ENABLE_PVP",
"default": "0",
"editable": true,
"validation": { "type": "boolean" }
}
]
}
Variable property Type Rules / omitted value
name string Unique, matching ^[A-Z][A-Z0-9_]*$; reserved names are forbidden
default string Default value, including numeric and boolean values; empty if omitted
required boolean Reject empty values; defaults to false
editable boolean Allow per-server edits; defaults to false, fixing the value to its default
hidden boolean Hide from ordinary server forms; defaults to false
pattern string Optional Go/RE2-compatible regex, at most 512 bytes; use anchors for a whole-value match
validation object Optional typed constraints below

Values are strings in the environment, even when validation checks numeric or boolean content. Values must be valid UTF-8, at most 8,192 bytes, with no nulls. Hidden values are still supplied to the game and can be included in portable backups; hiding a field is not encryption.

Validation property Type Meaning
type string Required within validation: string, integer, numeric, or boolean
format string Optional url, valid only for string variables
nullable boolean Allow an empty, non-required value to bypass pattern/type checks; defaults to false
min, max number Numeric bounds for integer or numeric
min_length, max_length integer String-length bounds measured in Unicode characters
choices array of strings Exact allowed values; empty/omitted means unrestricted

Boolean values are the strings "0" and "1", shown as toggles in the UI. Integer values must fit a signed 64-bit integer. URL values must be absolute URLs with a host; empty optional URLs remain allowed subject to other constraints. Bounds must be consistent, and required takes precedence over nullable.

Required ports

{
"required_ports": [
{
"container": 25565,
"protocol": "tcp",
"description": "Game connections"
},
{ "container": 25565, "protocol": "udp", "description": "Query traffic" }
]
}

Each entry specifies a container integer from 1–65535, a protocol of tcp or udp, and an optional description of at most 80 bytes without control characters. Declare each protocol separately when both are needed.

These are container requirements. Each server reserves host ports from its Spark’s allocations; the definition neither opens firewalls nor configures forwarding.

Configuration files

{
"configs": [
{
"path": "server.properties",
"parser": "properties",
"create": true,
"values": {
"server-port": "{{SERVER_PORT}}",
"max-players": "{{MAX_PLAYERS}}"
}
},
{
"path": "settings.json",
"parser": "json",
"values": { "network.port": "{{SERVER_PORT}}" }
}
]
}
Property Type Meaning
path string Contained relative file path; no absolute path, .. component, backslash, or null
parser string One of the parsers below
values object Replacement selectors mapped to strings, optionally containing variable placeholders
create boolean Create a missing file and parent directories; defaults to false
Parser Selector syntax
properties Property name, such as server-port
json, yaml Dot-separated keys, numeric array indices, and whole-component * wildcards, such as servers.0.port or servers.*.port
ini key, section.key, or [section.with.dots].key
file Line prefix to match; the replacement supplies the line text

Selectors must be nonempty, at most 1,024 bytes, and contain no control characters. JSON/YAML selectors have at most 32 components and do not support bracket-array syntax or partial-component wildcards. Properties replacements cannot contain line breaks; INI and plain-file replacements must be single lines without nulls. Parsing and rewriting can normalize formatting.

Configuration value types

JSON/YAML replacements preserve an existing string’s type, even when the text looks numeric or boolean. Existing numbers and booleans keep their type when the replacement converts successfully; otherwise the replacement becomes text.

For missing keys, true/false become booleans and valid JSON numbers become numbers. Other values remain strings, including leading-zero values such as 001. Large integer literals retain precision. Wildcards evaluate each matched value separately. To force numeric-looking text to stay a string, have the installer create that key as a string first.

Readiness and shutdown

{
"readiness": {
"any": [
{ "value": "Server ready", "ignore_case": true },
{ "value": "Listening on port [0-9]+", "regex": true }
]
},
"stop": "stop"
}
Property Rules
ready Simple text marker; omit when using readiness
readiness.any 1–16 alternative matchers; any match signals readiness
Matcher value 1–512 bytes; no variable placeholders
Matcher regex Treat value as a RE2-compatible regex; defaults to false
Matcher ignore_case Case-insensitive matching; defaults to false
stop One line, at most 1,024 bytes, with no null; supports variable placeholders

Literal matchers use substring matching, and terminal color codes are ignored. Use either "ready": "Server ready" or the structured readiness object, not both. Readiness recognizes log output; it is not a game-port health probe.

A stop value such as stop or quit is a console command. Signal notation starts with ^: ^C means SIGINT, and ^SIGTERM or ^TERM select SIGTERM. Supported Linux signal names are validated; arbitrary caret-prefixed commands are rejected. Omitting stop uses the image’s default stop behavior.

Actionable console errors

{
"log_alerts": [
{
"title": "Minecraft EULA requires acceptance",
"message": "Read the EULA. If you agree, set eula=true in eula.txt and restart.",
"severity": "error",
"phase": "runtime",
"any": [
{ "value": "You need to agree to the EULA", "ignore_case": true }
],
"action": { "type": "open_file", "path": "eula.txt" }
}
]
}
Rule property Rules
title Nonblank, 1–120 bytes, no control characters
message Nonblank guidance, 1–2,048 bytes, no nulls
severity error or warning
phase runtime or installation; omitted/empty monitors both
any 1–16 alternative matchers with value, regex, and ignore_case
action Optional navigation action below

Alert matcher values are 1–512 bytes on one line without nulls. They use the same literal/RE2 and case rules as readiness. At most 32 alerts are supported; matching conditions must be unique. Rules need no IDs: changing a title, guidance, or order does not reset deduplication or dismissal.

Action Fields
Open a game file {"type":"open_file","path":"eula.txt"}; contained relative path, at most 512 bytes, no control characters
Open server settings {"type":"server_settings"}; no path

Actions navigate to permission-checked interfaces; they never edit files or execute commands. Detection continues without an open browser. See responding to console alerts.

Declaring save data

{
"savedata_paths": [
{ "path": "world", "required": true },
{ "path": "server.properties", "required": true },
{ "path": "plugins/config", "required": false }
]
}
Property Rules
path Literal file or directory path relative to the game-data root, independent of work_dir; at most 1,024 bytes
required Boolean, defaults to false; missing required paths fail backup creation

Use at most 64 distinct, non-overlapping paths. Directories include their contents recursively. Absolute paths, .., globs, shell expansion, symbolic links, special files, the data root itself, and .campfire-backup.json are not allowed.

Missing optional paths are recorded; restoring such a snapshot removes a path created there afterward. At least one selected path must exist. Include saves, player records, configuration, and custom content needed for recovery, not binaries the installer can recreate.

This declaration enables Save data only backups. Without it, only full backups are available. Changes apply to new requests immediately, independently of restart or server-value review. See Game backups for restoration.