Authoring & examples

Research before declaring

Confirm the official dedicated-server distribution—not just the client’s Steam store page. Record executable topology, working directories, arguments, prerequisite checks, editable settings, stop/save behavior, exact endpoints, readiness and player grammar, world membership and recovery rules.

Do not borrow another game’s ports, parser, save provider or saving Stop without evidence. A process, a listening port, a readiness record, a router rule and an outside-LAN response are separate facts. Missing player evidence is unknown, not a verified zero-player count.

Prefer the game’s own log files

Before choosing redirected console capture, check the official dedicated-server documentation and shipped configuration for a supported file logger. Prefer game-written logs through existing signed launch/settings declarations and supported file readers when they provide the needed records.

Record the exact switch or setting, directory and filename rules, including timestamps and rotation. Establish encoding, complete-line framing, write/flush behavior, retention, readiness/player coverage, secret filtering and reconnection to a verified running process.

A documented option, engine reference or static binary string identifies a candidate; it does not prove an emitted log file or its event grammar. A client error log may not contain the dedicated server’s events. A missing log is unavailable evidence, not successful silent startup. Keep raw secret-bearing files private and sanitize operator/diagnostic views.

Timestamped filenames need an actual supported bounded selection path. No timestamp-selection declaration is active in .110. Do not invent a fixed filename or broaden source paths with unsupported wildcards. Game-owned file handles alone do not prove saving Stop, replay-safe player recovery or bounded rotation.

If game-written logging is unsuitable, document why a fallback is necessary. Historical Process.OutputCapture depends on the original Service’s pipes. The newer .110 direct-file fallback below has a different contract; do not apply the historical Service-lifetime limitation to it.

Direct file output: host .110 and later

Process.NativeFileOutput is an optional declaration requiring minimum host 0.9.110 and a matching catalog version gate before payload download. The frozen .108 SDK does not implement it. It inherits shared stdout/stderr file handles directly into the game, without a Service output pump, resident process host, game controller or command/save channel.

The initial contract requires direct launch with zero launcher handoff, StopKind: KillProcessTree and no OutputCapture. OutputRelativePath and ErrorRelativePath select distinct fixed .log files under the exact private profile NativeLogs directory. Display and LogFile probes bind to stdout.

RetainedFileCount accepts 1–10 total current/retained files per stream, default 3. Retention happens between stopped starts. There is no live byte-size cap or live rotation of the game-owned handle; this is separate from world-backup retention.

Raw output is private and is not sanitized at write time. Operator readers and diagnostic archive paths must sanitize it before exposure. Recovery needs both an independently verified process identity and the original kernel-file identity observation. Missing, replaced or incompatible evidence remains unavailable; file ownership alone proves neither readiness nor a complete player roster.

Terraria’s .110 example keeps nine launch arguments and uses KillProcessTree. It does not guarantee a final save. A stopped backup preserves already-saved files, not unsaved memory. The timestamped Terraria logfile-mirror proposal was rejected because its exclusive handle prevents live readers; it is not an active selector or launch argument.

Player-event ambiguity: host .111

Optional Probes.AmbiguousLinePrefixes requires minimum host 0.9.111. An omitted/null value preserves the earlier declaration. A non-null list contains 1–8 distinct, printable NFC literal prefixes, each 1–128 characters. They are anchored, ordinal comparisons, not regular expressions, and apply only to LogFile/TextPattern PlayerJoin or PlayerLeave probes.

The engine first matches the whole event. If the line also begins with a declared prefix, that observation is unavailable: EventLog roster, names and new activity become unknown. It never fabricates a player, infers zero or silently skips the ambiguity. Ordinary nonmatching chat leaves player state unchanged. A later join, leave or repeated readiness marker does not repair the ambiguous run.

Terraria .111 declares ["<"] because its chat envelope starts with an angle bracket. Genuine angle-prefixed player names can also be ambiguous, so reliable counts are not promised for every name. Prefer independently typed game events where available. This is shared JSON-driven handling, not a new game controller or executable adapter handler.

Choose an existing mechanism

• Reusable, bounded primitives: supported JSON/INI/FlatKeyValue mappings, declared arguments and ports, firewall conditions, reviewed text/JSON/INI/A2S probes, supported file readers and EventLog player folding. Output mechanisms have the version-specific limits above.
• Generic save-set checks: PortableDirectory and, with host 0.9.108, explicit required-file membership and size checks. They do not parse an unfamiliar native save format or prove a successful restore.
• Identity-restricted host behavior: named save-format engines, first-run and credential providers, CoreKeeperGameInfo, ValheimActiveSession and WindRoseSessionLog retain their reviewed restrictions. Historical TerrariaStdinSaveExit behavior must not be treated as the .110 candidate’s stop policy.
• Not enabled by a schema enum: RoleCredentials disk publication remains unregistered. The deferred ConsoleSaveExit owner mechanism is not a general console API.

New unsupported protocols, formats, credential algorithms, process primitives or JSON vocabulary require reviewed host work. Package-only changes are possible when the installed host already implements the chosen mechanisms. There is no universal “no app updates needed” promise.

Terraria example and host matrix

These are reference input names, not download links or install instructions. The unsigned examples are not reserved signed releases or fully certified adapters.

The .111 bundle includes Abiotic Factor 1.0.6 / sequence 7 and Enshrouded 1.0.5 / sequence 6, both supporting hosts .109–.111. These extend compatibility only. Their fixtures do not establish live game acceptance; all 22 evidence rows remain Not Verified.

A host 0.9.109 needs a separately reviewed, explicitly compatible input. The .109 correction introduced no new SDK vocabulary, but it does not make the .108-only example host-compatible. Do not change bounds merely to force acceptance or reset catalog high-water state.

Required-file fragment

Inside a supported PortableDirectory root, the following illustrates a required member. It is a fragment, not an installable adapter:

{
  "RequiredFiles": [
    { "RelativePath": "main.wld", "MinimumBytes": 1 }
  ]
}

This field requires minimum host 0.9.108 and a compatible catalog gate before package parsing. A non-null list holds 1–16 exact, distinct relative paths selected by the root’s include/exclude rules. Existence is required even when MinimumBytes is zero. Wildcards, traversal, path aliases and file/ancestor conflicts are refused. These are membership/size checks, not world-format certification.

Preserve settings and secrets

Use supported typed settings and mappings, preserve unknown game-written fields and keep password values out of public fixtures, evidence reasons and reports. ExistingObject selects an exact existing JSON array object; it does not create roles, objects or permission policies.

New Password-kind Setup declarations require RandomPassword defaults, a null DefaultValue and MaximumLength of at least 12. Generated setup defaults are temporary, not strong permanent credentials. Preserve existing profiles and explicitly supplied values; never regenerate live credentials as a publication step.

Terraria evidence and known gaps

A separate private .109 signed-candidate run reported on October 26 confirmed captured output, current-run startup readiness, one join and leave, a reliable zero count after leave and one connection in persistent activity history. That is scoped evidence for that run, not certification of these unsigned example bytes or the .110 direct-file behavior.

A later private .110 campaign passed ordinary readiness, join/leave/reconnect and activity-history checks, including actual Service replacement with original-file continuity. Current saved-file backup/export/restore/import preserved three files byte-for-byte and created safety backups; isolated retention checks used copied real saves. Service replacement is not proof of an application binary update.

An earlier October 26 checkpoint reports 9 Verified and 13 Not Verified rows. The ZIP’s dated status is frozen; a later companion report records additional operation checks without rewriting that package. The frozen authoring fixture 110/evidence-110.json still has all 22 rows marked Not Verified. Later evidence must remain separately scoped and bound to the actual candidate. Earlier save-and-exit evidence does not prove a final save with the .110 termination policy.

The later checks loaded the restored/imported world to Ready with zero reported players, retained previous stdout/stderr intact, and confirmed current/prior game logs in a normal diagnostic ZIP without exposing the tested configured game password. That is not a guarantee of universal personal-data removal. A backup attempted while the game was running correctly refused without mutation.

Normal maintenance stopped, backed up and revalidated pinned Terraria 1.4.5.8, then restarted with saved files and the executable pin preserved; it did not upgrade to a newer vendor version. A separate fresh profile used the production downloader/stager to install the real pinned payload, then removed its owned files, profile and log/observation state while unrelated sentinels remained. That isolated removal check launched no game and preserved the accepted profile.

A current managed forward was observed without conflicts. The temporary Windows Firewall rule now applies, but the public TCP nonce probe failed, so external reachability remains unverified. The configured router differs from the detected gateway; this is a routing clue, not proof of a game-protocol failure. Neither router was changed by these checks.

The frozen .110 package retains the known chat-shaped player-event limitation. The .111 declarations add conservative ambiguity handling described above; normal events alone do not establish reliable classification for every native name. Version-specific evidence and remaining acceptance limits are documented separately.

Overnight maintenance/sleep/wake, successful external reachability, adapter-package update notices, configured Discord acceptance, hosted-Portal consistency and an actual app-binary update still need their applicable evidence. Historical evidence files must not be silently rewritten as current full certification. Abiotic Factor and Enshrouded remain incomplete candidates, not accepted releases.

Read the six-command reference ↗

Found a documentation issue? Tell us through Feedback. Do not include credentials or private game data.