Skip to content

[Config/Runtime] Add instance/world/user config layers to resolved mod config precedence #75

Description

@ogyrec-o

Goal

Extend the resolved mod config model with explicit instance/world/user config layers.

#60 established the first supported runtime config path:

  • schema defaults from config.schema.toml
  • active values from experience [config."<mod_id>"]
  • stack-layer overrides from [layers.config."<mod_id>"]
  • final resolved config delivered through StartInput.config

That is enough for the first public config contract, but long-term product/server usage needs additional authored layers outside the shipped experience itself.

Motivation

Different audiences need different config ownership:

  • mod author: declares supported settings and defaults in config.schema.toml
  • product/experience author: ships intended defaults in experience.toml
  • stack author: overrides base experience config for a variant
  • server admin: edits local instance/server config without modifying shipped content
  • world owner: may need world-bound config that should persist with a save
  • user/client: may need client-local settings for client-owned or UI-facing mods

These should compose into one final resolved per-mod config rather than adding transport-specific or guest-specific side channels.

Proposed direction

Define a deterministic precedence model, for example:

schema defaults
-> product/experience config
-> stack layer config
-> instance/server config
-> world/save config
-> user/client config

The exact order should be decided in this issue.

The implementation should preserve the core #60 rule:

  • guests receive only final resolved config through StartInput.config
  • config identity for authoritative mods must include the final effective authoritative config
  • unsupported/unknown schema-backed keys are rejected before runtime start
  • no active config comes from mod.toml [config]

Questions to answer

  • Which layers exist in rc8/rc9 scope?
  • Which layers are authoritative and affect admission identity?
  • Which layers are client-local only?
  • Where should instance/server config files live in DevKit instances?
  • Where should world-bound config live in save metadata?
  • How should stack layer config deep-merge with later local overrides?
  • How do locked/hidden/schema authority fields affect writable layers?

Non-goals

  • Do not implement live reload semantics here.
  • Do not build a GUI editor here.
  • Do not change guest callback APIs beyond the already established StartInput.config.

Acceptance criteria

  • A documented config precedence model exists.
  • Runtime resolution includes the selected new layer or layers.
  • Effective config remains deterministic.
  • Authoritative admission identity changes when authoritative effective config changes.
  • Docs explain where users/admins should edit config.
  • Tests cover precedence, deep merge behavior, unknown-key rejection, and authoritative identity drift.

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:mod-loadingMod discovery, resolution, manifests, negotiation, attach/load behavior.area:runtimeRuntime behavior, lifecycle, ticking, session behavior, execution flow.component:devkitDevkit-level / cross-repo work: manifests, integration glue, release shell, repo-wide coordination.future-foundationLong-term foundation, not necessarily blocking rc10.priority:p2Normal priority. Planned work, worthwhile but not urgent.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