Skip to content

[Architecture] Add persistent runtime state for block and structure simulations #58

@yunnwi

Description

@yunnwi

Summary

Add a generic way for mods to persist runtime state attached to blocks, regions, structures, or mod-defined simulation objects.

Problem / Motivation

Many systems need state that should not be represented only by changing block type.

Examples:

  • tree age, health, species, growth stage
  • machine energy, inventory, progress
  • gas mixture, pressure, density
  • territory ownership
  • crop growth
  • decay/infection progress

Session-local state is useful, but simulation state often needs to survive world save/load.

Current state

Runtime-loaded mods can keep state during a session, but there is no clearly documented generic world-persistent state model for mod-defined block/structure simulations.

Proposed direction

Provide mod-owned persistent state storage keyed by:

  • world position
  • region/chunk
  • structure id
  • mod-defined object id

The engine should not understand the meaning of the state. It should provide:

  • serialization
  • save/load lifecycle
  • ownership isolation by mod
  • versioning/migration hooks
  • query/update access
  • budget/size diagnostics

Alternatives considered

Encoding all state into block variants is simple but does not scale.
Keeping state only in memory loses simulation state on reload.
Using ad hoc files per mod risks inconsistent lifecycle and compatibility.

Ownership / boundary impact

  • engine/platform owns persistence lifecycle and isolation
  • mods own schema and semantics
  • vanilla can use the same primitive for first-party gameplay

Non-goals

  • Hardcoding tree/gas/machine state into engine core
  • Replacing block IDs or normal world storage
  • Defining one universal gameplay state schema

Open questions

  • Should state be position-keyed, object-keyed, or both?
  • How should migrations work across mod versions?
  • What limits should apply to per-mod persistent state?

Expected follow-up work

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    status:triageNew / untriaged. Needs initial review and classification.type:architectureLong-term structural / contract / system design work, not just isolated implementation.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions