Skip to main content

Scene Management

Polygon Engine projects can contain multiple scenes, but the PS1 runtime loads one authored scene at a time. Build Settings defines which scenes are staged, their deterministic order, and which scene starts when the generated game boots.

Configure Scenes in Build​

Open Build > Build Settings and verify:

  1. Every scene that can be loaded at runtime appears in Scenes In Build.
  2. The intended boot scene is selected as the startup scene.
  3. Scene paths remain inside the project's configured Scenes directory.
  4. Production Acceptance does not report a missing or duplicate build entry.

The build collects dependencies from every included scene and writes the scene mapping to the staged manifest. A scene file existing under Scenes/ is not enough by itself; it must be included in Build Settings.

Load a Scene from Lua​

Use SceneManager.LoadScene() with a staged scene name or path:

function openHub(gameObjectId)
    SceneManager.LoadScene("hub")
end

The request is deferred until the runtime reaches its safe scene-transition point. The current scene is not replaced in the middle of the Lua callback. See the Scene Lua API for accepted names and path rules.

Loading Behavior​

Scene loading is an explicit CD-ROM operation. During boot and scene changes, the runtime presents its built-in loading display and pumps progress while it reads staged data. Long CD-XA music is suspended around scene data loading and can be restarted by the audio system after the transition. Resume currently starts the track from its beginning.

The packaged runtime spreads scene reads, asset decode, texture/SPU uploads, and final component initialization across bounded units of work. Scene-local sequential bundles reduce physical seeks; if a valid bundle is unavailable, the same logical files can be read from their loose staged paths. This is an implementation optimization, not a second authoring mode.

The loader preserves the previous scene while checking the destination size and reading its bounded BSN data. A failed size query does not allocate a maximum-size fallback buffer. After the destination header passes validation, the in-place path can release the previous scene to make room for decoding. A failure after that point clears partial state, leaves a valid empty scene, and reports an error. Cancellation and supersession also clean up staging. This is bounded, staged loading; it does not guarantee rollback to the previous playable scene after every failure.

Only one scene transition owns the CD path at a time. A newer request cancels and finishes the current request before starting its replacement. Do not issue SceneManager.LoadScene() every frame; gate transitions in project state and submit one deliberate request.

Do not design a transition around instantaneous access. Keep startup and transition scenes within the reported loader and binary-scene budgets, and test from the generated CUE so the test uses the packaged disc layout.

Configure the authored display in Advanced Scene Authoring > Loading & UI. Each scene stores label, colors, optional image texture, bitmap font, progress and percentage visibility, minimum display time, and fade-out duration. The layout remains deliberately fixed and PS1-safe; these settings style its content rather than creating an arbitrary transition Canvas.

The build also copies a compact form of each scene's loading configuration into its staged manifest entry. A transition can therefore select the destination scene's presentation before opening that scene's .BSN, so its colors, label, image/font references, progress policy, and timing apply from the first loading frame rather than appearing after the target scene has already loaded.

See Advanced Scene Authoring for every field.

State Across Scenes​

Authored GameObjects, UI elements, component state, and scene-local Lua instances belong to the loaded scene. Use SaveData for values that must survive a scene transition:

SaveData.Write("checkpoint", "hub_terminal")
SceneManager.LoadScene("hub")

SaveData.Write() updates the in-memory key-value store. Call SaveData.Flush() only when the value must be committed to the memory card at that point. See SaveData for failure handling and format limits.

Validation Checklist​

  • Every SceneManager.LoadScene() target is in Build Settings.
  • The startup scene has an enabled playable camera.
  • Scene-local scripts do not assume that GameObject IDs from another scene remain valid.
  • Required save keys have sensible defaults when no memory-card data exists.
  • The build stays below the manifest scene cap and per-scene binary limits.
  • Transitions are tested repeatedly from the packaged CUE in DuckStation.
  • Loading progress advances without presenting partially initialized gameplay.
  • A failed destination produces an actionable runtime error and never leaves a partially populated scene active.

For staging and output details, see Build Pipeline.