Skip to content

[Config/Runtime] Define runtime reload and config change event semantics #76

@ogyrec-o

Description

@ogyrec-o

Goal

Define how config changes behave after a runtime/session has already started.

#60 introduced public config schema metadata including reload policy:

  • runtime
  • world_restart
  • reconnect
  • restart

Today that metadata is useful for validation, docs, and future tooling, but the runtime does not yet define a full live config update contract.

Motivation

Some settings can safely change while running, while others must be fixed at startup or world creation.

Examples:

  • visual/client-local settings may be runtime-editable
  • server gameplay balance may require world restart
  • authoritative simulation settings may require reconnect or full restart
  • worldgen parameters may require world recreation or at least new chunks only
  • admission-critical config must not drift silently between server and client

The runtime needs one coherent model instead of ad hoc mod-specific behavior.

Scope

Define:

  • what each reload policy means
  • whether runtime config changes are pushed to guests
  • whether guests receive a config-change callback or must restart
  • how config changes interact with authoritative admission identity
  • how config changes interact with running worlds and persisted saves
  • how invalid updated config is rejected
  • how cross-transport behavior stays consistent for Wasm/native/external/builtin mods

Possible design directions

Option A: no live callback initially

  • runtime means tooling may allow change while running
  • host applies only to future runtime sessions until a later issue adds callbacks
  • simpler and safer for rc8/rc9

Option B: explicit config-change callback

  • guest declares support for config updates
  • host sends old/new resolved config
  • guest accepts/rejects or returns lifecycle output
  • more powerful but larger contract change

This issue should decide the long-term contract before implementation.

Non-goals

  • Do not implement config file generation here.
  • Do not add config UI here.
  • Do not add new active config sources here.
  • Do not make transport-specific config reload paths.

Acceptance criteria

  • Reload policy semantics are documented.
  • Authoritative/session safety rules are clear.
  • Guest-facing behavior is defined for Wasm, native, external, and builtin mods.
  • The design explains how invalid runtime changes fail.
  • The design explains whether already-running sessions receive updates or require restart/reconnect.
  • Follow-up implementation issues are created if the design is too large for one PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:guest-sdkGuest authoring SDK, macros, builders, modder ergonomics, high-level API.area:runtimeRuntime behavior, lifecycle, ticking, session behavior, execution flow.component:docsDocumentation, guides, READMEs, architecture docs, examples docs.future-foundationLong-term foundation, not necessarily blocking rc10.priority:p3Low priority. Nice-to-have, backlog, polish, or distant follow-up.status:confirmedConfirmed bug/request. Reproduced, accepted, or clearly valid.transport:cross-transportShared semantic work that must align across builtin/wasm/native/external.type:architectureLong-term structural / contract / system design work, not just isolated implementation.

    Type

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions