scene.assetType
- README.md31.1 KB
- about.yaml524 B
- behavior.luau133 KB
- inspector.luau2.5 KB
- shared.module
- template
- type.yaml4.9 KB
This package holds more than this page lists. See all of its files in its world.
README.md
Scene (asset type)
A scene is a saved, loadable snapshot of an entity scenegraph inside a
world: the entity hierarchy, transforms, components, lighting, and a
declared player intent, plus an auto-discovered startup script. A scene
is the unit of "level" or "screen" — a title screen, a lobby, a gameplay
area, and an end-of-game summary each get their own scene.
Scenes load as layers. One root scene is active at a time; additional scenes can load additively as overlays on top of it. Each scene owns its own multiplayer relay room. Switching scenes is a local call: the client that makes it leaves the old scene's room and joins the new scene's room.
When to use one
- You want a savable, re-loadable snapshot of an entity scenegraph plus its lighting and player setup.
- You want a runnable starting state for a level or screen.
- You want a scenes-as-data flow:
layers.load("lobby"), edit live, thenlayers.active:save()to flush the scene’s recorded edits.
For a reusable entity assembly (a prop, a vehicle, a UI panel) that many
scenes spawn into themselves, use a .bundle. A scene is a whole-world
snapshot; a bundle is one prefab that lives inside scenes.
Folder shape
A scene asset is a folder ending in .scene. Its identity is the folder
name with the suffix stripped (Lobby.scene → Lobby).
scene.json— the scenegraph:entities[], lighting, and the top-levelplayerintent. Required. Written by the engine — a build, a save, a human dragging something in. Not hand-edited.build.luau— what the scene is made of, written as code. Runs while you author; saving bakes its result intoscene.json(see Building a scene).authoring/— durable intents, the accepted generated baseline, and revision metadata for persistent v7 world scenes.entrypoint.luau: the startup script. Required. Auto-discovered as a sibling ofscene.json; define lifecycle callbacks here (see The entrypoint).<name>.<type>/— an asset the build makes, authored here bybuild.asset(see The assets a build makes), alongside.build.assets, which records whichbuild.luauproduced each of them.prefabs/— optional subfolder for scene-local bundles.scripts/— optional subfolder for scene-local Luau helpers, required fromentrypoint.luau.README.md: notes about THIS scene: what it shows or plays and what it is for. Required. The general scene model lives here, inguides { path: "types/scene" }..metadata: Required.
scene.json is version 7. It carries "format": "scene",
"version": 7, an entities[] array, and a top-level "player" string
intent.
A newly scaffolded scene carries its template baseline in authoring.initialGenerated
inside the initial artifact. Its first authoring transaction consumes that baseline,
writes the accepted state, and replaces the initialization metadata with the accepted
revision. This lets the first build distinguish template output from authored edits.
The player intent
Every scene declares how it handles players with a top-level player
field in scene.json:
"spawns"— the scene carries an authored player setup, and the engine spawns a player for each connecting user from it. This is the default for a freshly created scene."none"— the scene spawns no player and authors no camera. Author your own Camera entity for the view (menus, UI-only screens, cinematics).
How "spawns" works
A "spawns" scene authors two things in scene.json:
- A PlayerPrototype — an entity carrying the
PlayerPrototypecomponent, whosebodyfield names a child entity (the body). The body carries an avatar (anAssetpointing at an avatar, e.g.@builtin::avatars.humanoid). ACameraRigchild carries aCamerawith a camera behavior (e.g.orbital_follow). The prototype root is authoredPrototypeOnlyso it exists as a clonable template. - A PlayerSpawn — an entity carrying the
PlayerSpawncomponent, whoseprototypefield names the PlayerPrototype to instantiate and whose transform is where players appear.
The scaffolded scene groups these under two organizing entities,
PlayerSetups (holding the prototype) and Spawns (holding the spawn),
so the authoring tree stays legible.
On each user join — entering play, and each subsequent connect — the engine runs the spawn for that user:
- It clones the PlayerPrototype subtree.
- The clone root becomes the user's internal identity — a registry-only
entity named
usercarrying theUserIdentitycomponent. The identity is the anchor for who the player is; it has no world presence. - The body named by
PlayerPrototype.bodyis adopted as the user's avatar — their visible presence in the world — and placed at the PlayerSpawn's world transform. Move the PlayerSpawn (or drag it in the editor) to set where players appear. - The
CameraRig's Camera follows the bound avatar.
The player prototype is live in edit mode so you can see and adjust it. In play mode it is deactivated and marked internal — it stays a clonable source while each user gets their own clone.
Reaching the live player
The player surface lives on the root scene's registry,
layers.active.players:
players.localPlayer— this client's player, a curated handle.players.localReady—trueonce the local player's avatar is bound (or the scene opted its avatar out).players:list()/players:count()— the players connected in this scene's room.players:get(userId)— a connected player by account id.players:ownerOf(avatar)— the player whose body is a given avatar.
A player handle is a data record about who the player is, plus a link to their body:
player.avatar— the body's entity ref. Act on the body through it (player.avatar.position, raycasts, rig access).player.isLocal— whether this client owns the player.player.ready— whether a live avatar is bound.player.userId/player.identity/player.displayName— the player's account identity.player.avatar = ref— bind a live body entity as the player's body (assign nil to clear). To use a.bundle/.avatarasset, spawn it into the world first, then bind the resulting entity.
The player's identity entity is the internal anchor; the handle exposes the
body (player.avatar) and the player's data, and reaching for
.entity / .id / .component raises with a redirect to player.avatar.
Authored edits and source changes
Persistent v7 world scenes compose a generated build baseline with durable authored edits. Edits made by people, agents and tools in edit mode are recorded automatically. The Scene panel and sceneRef:authoringStatus() expose persistence state, authored-edit counts, build conflicts and migration uncertainty. Scene saves flush this state; version-control commits and publishing are separate operations.
The authoring folder holds the accepted baseline and intent records. scene.json holds the composed result and its revision. An unedited field follows the build. An edited field retains its authored value; if the build changes that field differently, the conflict records both values. Structural conflicts retain the last accepted scene.
Packages can bind a source argument with modules.sourceEditing.bind, stating its semantic id, scope, known output identities and whether that scope is complete. A declaration in a loop can affect several placements; a single-placement replacement uses a placement-specific input.
sceneRef:prepareSourceChange(sourcePlan, selections) evaluates a checked build.luau candidate. sourcePlan comes from SourceEditing.prepareTarget; each selection supplies an entity id, its intent revision, and exact normalized field paths such as {{"name"}}. The candidate must reproduce each selected override. Preparation returns a reviewable transaction; assetTypes.scene.shared.coordinator.commit(plan) commits the source change, generated baseline, selected intent retirement and artifact together. Other overrides remain. A stale source or intent revision requires a new preparation.
Building a scene
build.luau declares what the scene holds. It is ordinary engine code —
entity.spawn, component.add, transform writes, for loops, a require
of a module that computes a layout — and what it creates is what ends up in
the scene.
function content()
for i = 0, 4 do
local crate = entity.spawn("crate")
build.key(crate, "crate:" .. tostring(i))
crate.localPosition = { i * 2, 0.5, 0 }
crate.component.add("Model", { model = asset.resolve("cube", "mesh") })
end
end
The build runs while you author, in edit mode. In persistent v7 world scenes,
its candidate is composed with authored edits and committed before reconciliation.
The entities remain selectable and inspectable, and the composed artifact loads
when the world opens. Play mode loads the accepted scene.json.
Editing the file rebuilds the scene in place. Writing build.luau is the
signal; there is nothing to reload, and the rebuild saves. An entity keeps the
id it had, so a reference to it — a spawn naming a prototype, another entity's
component naming this one — survives every rebuild. Add a crate to the loop and
the other four do not move.
A write through write_file, edit_file or the engine's bash answers once
the rebuild it started has finished, so what the rebuild landed and kept comes
back on that answer as a notice, whose message is the report's summary line:
[info] a write to build.luau rebuilt the scene { content="6", scene="scenes.main",
editorOnly="1", kept="1", message="build.luau against the scene: kept 1 value on
1 entity (crate_3); ..." }
A rebuild still running when the write's wait ends is named under the answer's
startedWork, and its notice arrives on a later call.
An edit saved while a rebuild is still running is an edit to code that rebuild has already read, so it gets a rebuild of its own once that one finishes, and says which it was:
[info] a write to build.luau arrived during a rebuild and was rebuilt after it
{ content="7", scene="scenes.main", editorOnly="1" }
Several edits saved during the same rebuild get the one run after it, which reads the file as it stands then.
A scene that declares a build also runs it when it loads in edit, so the
scene shows what the code says now, including an edit made while the world was
closed. A load whose .build.state records the current script reads
scene.json and runs nothing. When a persistent v7 world scene runs a build,
pending authored edits are recorded first and participate in the candidate
composition. A refused candidate leaves the accepted artifact in place.
A library scene (one under /libs/, the @builtin library included) is read
by its load: the build lands in the live scene and its files stay as the
library states them. Play reads scene.json, so it comes up without that build
until :build() saves it.
The two surfaces
content()— the scene's own entities. Present in play.editorOnly()— entities present while authoring and absent in play. They carry theEditorOnlyparticipation the runtime deactivates and hides when play begins, and they are baked too, so a collaborator opening the world sees the same ones. Anything an author needs to see and a player does not goes here — an alignment guide, a spacing marker, a debug volume.
Both are optional. A scene with neither has no build.
What a rebuild touches
Only the entities the build itself placed. Anything a human dragged in, or a
tool placed directly, is invisible to a rebuild and never moved or removed.
For persistent v7 world scenes, the generated result is composed with authored
intent before reconciliation. A build always applies. Authored intent that
names an entity, parent, reference or component the build no longer produces is
retired: it leaves the composed scene, the build report lists it under
retired with the entity's name, the field path and the value it held, and
sceneAuthoring.reviewRecorded keeps listing it. sceneAuthoring.reapplyRetired
moves a retired entity's field edits onto another entity, and
sceneAuthoring.discardRecorded removes saved edits or forgets retired ones.
A part of the scene build.luau itself states that is broken (a parent or an
entity or component reference the scene does not hold, a parent cycle, a record
that cannot be restored) is skipped and the rest is placed: the build report
lists each skip under skipped with the entity, the path and what was wrong,
one warning names the first, and sceneAuthoring.reviewRecorded lists them
under skipped until the build no longer states them.
A plain rebuild keeps a hand edit to an entity the build placed: a value
build.luau states the way the last build stated it is left as the scene holds
it, so a move, a rename, an attribute, the active flag, the lifecycle mode, the
replication scope or a component field changed since survives the rebuild, the
one a write starts included. To see every such edit,
ask the build for its report:
local report = layers.active.asset:build({ save = false })
print(report.message) -- opens with one line counting all four lists
On a scene already holding what the build states it leaves nothing to save,
and it answers kept (hand edits to entities the build placed), driven
(fields another component writes at runtime, such as a sky orienting the sun),
handAdded (components and attributes added by hand to built entities) and
handPlaced (entities no build placed). An entity's render layer and its
hide() switch are runtime state no build sets, so the lists leave them out;
the answer states what the scene holds on both for the entities a build
placed instead, in renderLayers ({ entity, name, layer }) and hidden
({ entity, name }), and its message counts them ("render layer set on 3
(...); hidden by hide() 0"). It also names the scene it compared: client is
the client of the world it ran in (user, or a sub-client's id), since every
client holds its own live scene, and unsaved lists the edits that scene held
beyond the saved scene.json (the entries sceneAuthoring.changes lists), so
an empty unsaved makes the report a statement about scene.json. To land
build.luau's values over the kept ones:
layers.active.asset:build({ restate = true })
A restate writes exactly the values kept names, so the scene's diff after one
is the report. To bring a handPlaced entity into the build, delete the
hand-made one and save the scene, then write it into build.luau: the write
rebuilds at once in every client and the writing client saves its rebuild, so
a delete left unsaved in another client can come back. A hand-made entity
still standing under a name the build now places is reported with
builtTwin, a second copy beside the build's, and the message names the
calls that settle it. The message also compares the report against
scene.json as saved: it names each unsaved edit and what it changed, and any
entity whose live state differs from the scene's files with no unsaved edit
behind it (a write this client has not taken), with the calls that take that
client back to scene.json before anything saves from it.
guides { path: "core/scenes-as-code" }, "What a rebuild touches", gives the
shape of every entry and how driven and restate meet.
The build writes its own name and each entity's place in the hierarchy onto the
entity, and scene.json records that pair beside the entity's name and
transform — which is why a rebuild after a reload, in a later session, lands on
exactly the entities it placed the first time without anything having been
remembered.
When the file did not change
:build() runs the build against what it resolves right now — for the case
where something the builder reads changed and the file did not: a module it
requires, an asset it resolves. After a write it is unnecessary; the write has
already run it.
layers.active.asset:build() -- rebuild and save
layers.active.asset:build({ save = false })
It answers with how many entities each surface placed —
{ content = 6, editorOnly = 1 } — and with nil for a scene that has no
build.luau. Called while a build for that scene is already running, it returns
at once with { inFlight = true, scene, trigger, startedBy, message } naming
that build instead of starting a second one; inFlight is what tells the two
answers apart.
An operation the bake cannot hold is refused rather than applied. A build accepts what its records carry: entity lifecycle, transforms, hierarchy, names, visibility, active state, participation mode, network scope, attributes, and components with their public data. Anything else raises while the build runs, naming the operation and the build it answered to, instead of leaving the scene depending on something no reload brings back. When that happens the previous build stays exactly as it was. A runtime resource a build needs — a mesh it generates, a texture it writes — is made as an asset instead, below. Everything else a refusal names goes outside the builder, or into a component the builder attaches, which runs at play.
The assets a build makes
build.asset(type, name, produce) makes an asset the build's content names — a
mesh a lathe produces, a texture a pattern writes. produce takes nothing and
returns the creation parameters asset.create takes for that type; the call
returns the asset's AssetRef, which is what a component field holds.
function content()
local tower = build.asset("mesh", "tower", function()
local positions, indices = lathe(profile, 16)
return { positions = positions, indices = indices }
end)
entity.spawn("tower").component.add("Model", { model = tower })
end
The asset is authored inside the scene's own folder — Lobby.scene/tower.mesh
— and the scene records which build.luau produced it in .build.assets. So
produce runs when the build script changed and never otherwise: a reload
re-runs the build and reuses the asset, while editing the profile re-authors
tower.mesh in place, keeping its path and its guid. That is what holds the
reference — scene.json names assets by guid.
For a part of a scene that several scenes place — or that one scene places many
times with different settings — see guides { path: "types/sceneModule" },
which is the same idea with declared inputs a placement sets.
guides { path: "core/scenes-as-code" } covers both.
The entrypoint
entrypoint.luau is the scene's runtime — what happens while the game is
being played. What the scene is comes from build.luau above; nothing here
has to construct it.
entrypoint.luau is auto-discovered as a sibling of scene.json. The
loader runs it in a fresh environment and folds its top-level
function name(...) declarations into the matching scene lifecycle event.
Define the callbacks the scene needs — the recognised set:
onLoad()— the scene loaded in play mode. Gameplay-start hook, runs on every connected client.onHostLoad()— the scene loaded in play mode, on the client that owns the scene's synced content (the relay room creator; offline and single-player count as host). Fires once. Entities spawned here — and anywhere downstream — become synced automatically, so this is where shared world content is spawned: it runs on exactly one peer, and every other peer receives the entities from the relay snapshot.onEditLoad()— the scene loaded in edit mode. Custom per-scene authoring tools. Writing this file while the scene is loaded in edit mode reloads its layer, so the newonEditLoadruns after the previous load'sonUnload.onUnload()— before the scene's entities are torn down. Extra cleanup; engine-managed teardown (entity despawn, resource release) runs separately.update(dt)— per frame in play mode, while the gameplay clock runs.editorUpdate(dt)— per frame in edit mode, running or paused. Play-paused ticks neither hook. The scene loader partitions these strictly on mode; a component's hooks of the same name readengine.pausedinstead, so the two rules differ —man componentshas that table.localPlayerReady(player)— once the local player's avatar is ready. Gameplay wiring for the local player: attach state, bind UI, swap the avatar. The avatar is already placed at the PlayerSpawn, so this is for behavior, not positioning.playerJoined(player)— a remote player joined this scene's room. Use for per-player UI (nameplates, greetings). The local player arrives throughlocalPlayerReady.playerLeft(eid)— a remote player left this scene's room. Receives the departed entity's id (the entity is already despawned).
Each scene's entrypoint runs in its own environment, so two scenes can
declare the same top-level names without clashing. Keep each callback
short; push per-scene logic into scripts/ modules and require them.
Layers
Scenes load through the layers namespace.
layers.load(ref, opts?)— load a scene.refis a scene AssetRef or identity string. Withoutopts.additive, this is a root load: it replaces the current root scene.opts:additive— load as an overlay alongside the current root instead of replacing it.persistent— keep an additive overlay mounted across mode flips and root swaps.origin— a{x, y, z}world offset for the overlay's entities.deferred— spread the entity spawn across frames (for thousand-entity scenes); the load signals complete only once the scene has settled.
layers.active— the current root scene proxy (nil before any load).layers.list()— every loaded layer (root + additive overlays).layers.find(ref)/layers.is_loaded(ref)— look up a loaded layer by ref.layers.onLoad(cb)/layers.onUnload(cb)/layers.onBeforeLoad(cb)— subscribe to every scene load / unload (distinct from a scene proxy's own:on_load/:on_unload, which fire only for that scene).
A root scene carries the players, camera, and settings surfaces;
additive overlays inherit the root's players and lighting and do not carry
their own.
The scene proxy
layers.active (and layers.find / layers.list entries) returns a
scene proxy:
- Fields:
.guid(canonical identity),.name,.path,.asset,.additive,.visible,.state("loading"→"loaded"→"ready"→"unloading"),.ready,.players,.camera,.settings,.entrypoint. .camera— a proxy over the scene's primary camera entity; read and write the live Camera component through it, and.camera.behaviors._list()enumerates the available camera behaviors.:save(opts?)— publish the live scenegraph to canonicalscene.json(see Saving). A convenience that forwards to the scene ASSET'ssave(self.asset:save(opts)): the proxy is the runtime view and owns nothing on disk, so persistence lives on the asset.:reload(): unload and reload the same scene (a runtime respawn). A scene with abuild.luauruns its build again and saves the scene, soscene.jsonholds what the reload built and the next play loads it; a library scene's rebuild lands in the live scene alone.:clearDirty()— discard unsaved edits and respawn from canonical. Forwards to the scene asset'sdiscard(self.asset:discard(opts)).:sceneAsset()— the durableAssetRef<scene>this live layer maps to.:promoteDirty()/:writeDirty()/:hasDirty()— manage the dirty overlay directly.:unload()— despawn the layer and free its slot.:onReady(cb)— fire once the scene reachesready(latched: a late subscriber fires immediately).
Multiplayer & relay rooms
Every scene has its own relay room, keyed by the world guid, the boot
profile, the mode, and the scene guid. Switching scenes with
layers.load runs a room transition — leave the old room, tear down,
join the destination scene's room — all on the client that made the call.
Teardown of the old scene never leaks to peers in the new one.
In play mode connected to a relay, the scene's entities are
host-authoritative: only the room creator instantiates them (marked
synced), and every joiner receives them from the relay snapshot rather
than spawning their own. This is why shared world content belongs in
onHostLoad — spawning it in onLoad would run on every peer and
duplicate it. Each player's own avatar spawns per-user from the
PlayerSpawn on every client.
Edit mode and offline boots spawn locally and never auto-sync.
Loading and saving
Loading — layers.load(ref) for a root scene:
- Despawns the current root scene's non-persistent entities.
- Instantiates the entities from
scene.json(including the player prototype and spawn for a"spawns"scene). - Applies lighting and sky.
- Runs
entrypoint.luauand fires lifecycle callbacks as their events occur.
Saving — persistence lives on the scene ASSET. sceneRef:save()
writes the scene's current state back to canonical scene.json; when the
scene is loaded it captures the live scenegraph, and when it is not loaded
it promotes the pending dirty overlay. layers.active:save() is the
convenience form — it forwards to the active layer's mapped asset
(layers.active.asset:save()). Writing canonical is the only path that
does so: edit ↔ play cycles never save, so hitting play to test never
overwrites the scene. Between saves, live edits accumulate in a per-scene
dirty overlay that the loader merges on top of canonical.
sceneRef:discard() throws the overlay away and restores the saved state
— deleting the overlay, and respawning the live layer when the scene is
loaded. It works whether or not the scene is loaded, because the overlay
belongs to the asset, not the runtime layer. layers.active:clearDirty()
forwards here. Saves capture entity data, not the entrypoint script —
edits to entrypoint.luau and scripts/ are always preserved.
opts.to on save/discard targets a different scene ("save as"),
taking either a bare name ("level_2") or a full VFS path.
What a record states. A component's record in scene.json holds the
fields that instance's configuration states: the keys of the table it was
added with (a build.luau call's own init table, or the record it was
loaded from) and every field written since, through code, a tool or the
inspector. A field nothing set stays out of the record and takes the
component's declared default each time the scene loads, so changing that
default reaches every entity that left the field to it. To have an entity
follow the default again, remove the field from its record. A field set on a
live entity after its record was made is a change the scene review names
(sceneAuthoring.changes lists it as + Type.field = value), and accepting it
writes the field into the record. A stored
value cannot be told apart from one an author chose, so a stored value
loads and saves as it is, and a hot reload that changes a default one of
them shadows names it. A stored field the component no longer declares is named by a
[component.add] warning when the record loads and left out of the next
save.
Lighting
Lights are ordinary entities: a directional light, an ambient light, and
a sky are entities carrying Light / ProceduralSky components in
scene.json. Author, move, and tune them like any other entity. If a
scene is missing any of {directional light, ambient light, sky}, the
loader adds a temporary default for the absent one so a scene never loads
dark or skyless; the defaults are never saved into the scene.
Scene-level lighting state that is not an entity — clear color and sky
descriptor — lives under layers.active.settings.lighting (clear_color,
sky); writing those fields updates the engine live.
Modes
Scenes load in both edit and play mode (see man modes). The mode
governs behavior:
- An entrypoint's
update(dt)runs in play while the gameplay clock runs, and itseditorUpdate(dt)runs in edit. A component's hooks of the same name follow the clock rather than the mode —man componentshas the four states that produces. - Player prototypes are live in edit and deactivated + internal in play,
where each user instead gets a clone.
EditorOnlyentities follow the same edit-live / play-internal toggle. onLoad/onHostLoadfire on a play-mode load;onEditLoadfires on an edit-mode load.
How to create one
asset.create("scene", "<Name>")
-- Creates /zero/source/<Name>.scene/ with:
-- build.luau where this scene's content is written. A new one starts
-- with the sun / ambient / sky lighting and the "spawns"
-- player setup, commented for editing — everything else the
-- scene comes to hold is written here too.
-- scene.json what that code produces, baked.
-- entrypoint.luau commented lifecycle-callback stubs.
A freshly created scene has a player with a following camera on the first press
of play. It carries no ground, so the first thing to author is what the player
stands on — a content() line away in build.luau.
Discovery
asset.list("scene")— every registered scene.asset.inspect("<name>")— entity count, lighting summary, source path, and this type README.
Authoring conventions
- Keep static layout in
scene.json— geometry, lights, props, the player prototype and spawn. - Keep dynamic setup in
entrypoint.luaulifecycle callbacks — event listeners, gameplay state, services attached to spawned entities. - Spawn shared, synced world content from
onHostLoad; spawn each player's own gameplay wiring fromlocalPlayerReady. - Set the world's startup scene in
/.world_settings— that is the scene the world boots into. - Y is up; -Z is forward.
- Renaming the folder changes the scene's identity. References to the scene are recorded against the scene itself, so renaming or moving it does not break them.
Related types
.bundle— reusable entity hierarchies that scenes spawn into themselves..service: a declarative content generator a scene can draw on..world_settings— picks the startup scene and world-level renderer / physics options.
In the Inspector
Selecting a scene opens its Scene section, read from scene.json without loading the scene: how many entities it holds, how many of them are roots (and their names), how players join and the file's format version when it states them, and whether the scene has edits not yet saved.