Skip to content

worlds-and-saves.md

Latest commit

 

History

History
157 lines (105 loc) · 4.24 KB

worlds-and-saves.md

File metadata and controls

157 lines (105 loc) · 4.24 KB

Worlds And Saves

Status: baseline shell contract for the graybox client.

Purpose

The Bevy client now has a minimal product shell around the simulation:

  • a start page
  • persistent worlds
  • manual saves
  • autosaves
  • scenario previews for iteration/debugging

This is intentionally narrow. A world is a saved scenario instance, not a campaign map or procedural overworld.

Start Page

Default cargo run -p app_bevy behavior now opens a start page with:

  • Continue
  • New World
  • Load World
  • Scenario Browser

Keyboard behavior:

  • Up/Down or W/S: move selection
  • Enter or Space: confirm
  • Esc: leave sub-pages and return to the main start page

Page behavior:

  • Continue: loads the most recently used world from profile settings, or the newest world if no explicit last-world id is stored
  • New World: chooses a scenario and creates a persistent world instance immediately
  • Load World: chooses an existing world by metadata
  • Scenario Browser: browses scenario goals/prompts and can either preview them or create a persistent world from them

Persistent Worlds

Persistent play should happen inside named world instances.

Current model:

  • one world = one saved WorldState plus metadata
  • a world is always rooted in one scenario id
  • loading a world restores the latest autosave if present, otherwise the manual state.json

The current graybox does not yet support:

  • renaming worlds
  • deleting worlds
  • multiple user profiles
  • save thumbnails
  • cloud sync

Preview Sessions

Passing a scenario id still bypasses the start page:

cargo run -p app_bevy -- --scenario first_slice

That creates a transient preview session rather than a persistent world. Preview sessions exist to keep iteration/debugging fast and preserve the old direct-boot workflow.

Preview-only behavior:

  • F5 writes /tmp/three_d_systems_debug_save.json
  • F8 reloads the scenario template
  • F9 loads that preview save
  • F6/F7 cycle preview scenarios

Persistent worlds use a different save path and do not use those debug shortcuts for primary persistence.

Save Controls

Persistent-world controls:

  • F5: manual save to state.json and autosave.json
  • F8: reload the current world from disk
  • Esc: autosave and return to the start page

Autosave policy:

  • after successful build/configuration actions
  • after returning to the start page
  • periodically during simulation ticks

Preview controls:

  • F5: save debug snapshot
  • F8: reset preview to scenario baseline
  • F9: load preview debug snapshot

File Layout

Default app-data root:

  • macOS: ~/Library/Application Support/three_d_systems_game/
  • Linux/XDG fallback: $XDG_DATA_HOME/three_d_systems_game/ or ~/.local/share/three_d_systems_game/

Current layout:

profiles/default/settings.json
worlds/<world_id>/meta.json
worlds/<world_id>/state.json
worlds/<world_id>/autosave.json

settings.json currently stores:

  • last_world_id

meta.json currently stores:

  • world_id
  • display_name
  • scenario_id
  • scenario_display_name
  • created_unix_seconds
  • updated_unix_seconds
  • tick
  • victory_state
  • objective_summary

The save payload for state.json and autosave.json is the same validated WorldState snapshot already used by the debug/headless path.

Environment Override

For testing or portable runs, override the app-data root with:

THREE_D_SYSTEMS_APPDATA=/custom/path cargo run -p app_bevy

This is useful when:

  • you want predictable test output outside the normal user data directory
  • you want to inspect world files directly during debugging
  • you are running from an environment where the default app-data location is awkward

Design Notes

Why keep worlds shared/global instead of adding a player bag or multiple modal inventory screens?

  • the current game already has a sim-owned global build inventory through the Fabricator loop
  • moving to per-avatar inventory would add management noise without improving the machine-topology fantasy
  • the prototype is strongest when state stays visible in one continuous build view instead of fragmenting across many screens

So the current shell direction remains:

  • shared build inventory
  • one continuous build scene
  • contextual side panels
  • a minimal menu only for world/session management