Skip to content

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

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions