scene.shared.saver

Luau-side scene saver. Writes scene.json v6 — authored intent only. No captured runtime state.

Public surface

local saver = require("@builtin::assetTypes.scene.shared.saver")

saver.save(name, opts?)
  -- name: logical scene name ("main") OR full VFS path
  -- opts.layer: layer name to read from (default layers.active.name or "main")
  -- Returns: the absolute VFS path written.

What is captured

Field	Source	Notes
format, version	constants	Always "scene" + 6.
entities	entity.findAll() walk	Excludes temporary entities + the spawner-managed Player + primary Camera.
entities[].transform	local position / rotation / scale	NOT world transform — local only.
entities[].components	component.list + component.get	Strips _-prefixed runtime fields.
entities[].attributes	attribute.list + attribute.get	The entity's key/value bag, written as a { [key] = value } map; omitted for an entity that holds none. Holds the authored keys — a _-prefixed key is the engine's own session bookkeeping.
lighting	lights.snapshot(), filtered	Scene-level clear_color + sky only. Directional / ambient / point lights persist as Light entities in entities[].
player	sceneProxy.player_config	Carried forward from load-time, authored only.
camera	sceneProxy.camera_config	Carried forward from load-time, authored only.

What is NOT captured

• Local player's position / rotation. Runtime drift; not authored intent.
• Primary camera's transform. Runtime; behavior-driven.
• Any entity flagged temporary = true. Debug helpers, runtime markers.
• Internal component fields prefixed with _ (e.g. _velocity on CharacterController).

The spawner-managed entities (Player + primary Camera) are excluded because they're created on load by player_spawner / camera_spawner from the scene's declarative player + camera blocks. Saving them would double them on the next load.

Parts

The module is a folder of parts, each a module of its own that init.luau requires:

• scene_saver.serialize: one live entity as the record a scene file carries.
• scene_saver.recordDiff: the comparisons the record diffs are built from.

When to use

layers.active:save(name) (Phase 6) routes through this module. Callers that want a state snapshot (save-game systems, undo stacks) should use world.debugSaveToDisk(...) instead — that captures runtime state by design.