Build Pipeline

The build pipeline turns an editor project into PS1 runtime data and disc package output. Public binary releases use a precompiled proprietary runtime; the pipeline validates the project, stages scenes and assets, and runs mkpsxiso to generate package files.

For the shortest path through the process, see Quick Start.

Build Commands

The Build menu contains the main actions below. The toolbar's Build and Run buttons are shortcuts to the first two commands; both use Release.

Command	What it does
Build Disc Image (.bin + .cue)	Validate, prepare content, and generate the disc image. Does not open an emulator.
Build & Run in DuckStation	Generate the same disc image, then open its .cue in DuckStation. Requires a configured DuckStation path.
Build Settings...	Choose Scenes In Build and the startup scene.
Validate Project	Check the project and show results in Problems without generating a disc.
Open Disc Image Folder	Open Build/ps1/package/, where the generated files are saved.

Less frequent operations are under Build > Tools & Diagnostics:

Command	When to use it
Tool Paths...	Configure packaging tools and DuckStation, and check toolchain readiness.
Show PS1 Budget	Review the current scene's estimated hardware usage.
Show VRAM Inspector	Inspect framebuffer, texture-page, and CLUT placement.
Export PS1 Budget Report	Write the current-scene report to Build/ps1/logs/ps1_budget_current_scene.json.
Open Build Report	Open the latest Build/ps1/logs/ps1_build_performance_report.json; build a disc first.
Build with Readiness Checks	Build in Release and require PS1 Ready. Budget warnings can fail this stricter check; it does not replace gameplay testing.
Repackage Disc (Reuse Runtime)	Prepare content and regenerate the disc using an available Release runtime. Use a full build after changing the engine or build configuration.

For a CD-R, keep the generated .bin and .cue together and select the .cue in your disc-burning software's image-writing mode. The BIN contains the disc data; the CUE describes its tracks and references the BIN. This is the same pair used by DuckStation. Build the image with Build Disc Image (.bin + .cue) when you only need the files; no emulator is required.

Pipeline Stages

Validate Project
  -> check tool paths, scene list, startup scene, scripts, assets, stale imports, budgets

Select Runtime
  -> use the precompiled Debug or Release Polygon Engine runtime
  -> private source checkouts may compile it with PSn00bSDK and Ninja

Stage disc_root
  -> write SYSTEM.CNF, POLYGON.EXE, DATA/MANIFEST.JSN
  -> reimport stale textures/audio when source or import settings changed
  -> stage scenes, scripts, meshes, materials, textures, and audio
  -> validate and stage referenced hard-skinned animation assets
  -> encode enabled streaming-music WAV files as CD-XA
  -> bake PS1-safe primitive geometry into runtime mesh chunks
  -> bake enabled navigation surfaces into deterministic height-aware node/link graphs
  -> reject overlong runtime strings before writing .BSN data
  -> write bounded BSN data plus sized scene-feature chunks
  -> write one sector-aligned sequential dependency bundle per built scene
  -> write post-bake PS1 budget and performance reports

Package
  -> write mkpsxiso XML
  -> generate .bin, .cue, and .iso under Build/ps1/package
  -> write logs and burn guidance

Output Folders

Path	Description
Build/ps1/disc_root/	Internal staged disc contents
Build/ps1/package/	User-facing package output
Build/ps1/logs/	Build summary, authoring budgets, post-bake runtime budgets, performance report, build log, and packaging log
Library/build_history.json	Last 20 local build summaries

The package folder is the one most users should inspect after a successful build.

Completion Summary

The completion dialog shows the result, duration, disc path, and generated file sizes. Open Disc Image Folder opens the output folder. Repackage & Run prepares the disc again using the last build options and an available runtime, then opens DuckStation. Copy Summary copies a compact summary for support.

Build/ps1/logs/build_summary.json stores the latest result, including the failure step and message when a build stops. Library/build_history.json retains the last 20 summaries. These files support local diagnosis; the package and authoritative post-bake reports remain the release evidence.

Staged Runtime Data

The PS1 runtime expects a compact staged layout. A typical build includes:

Build/ps1/disc_root/
  SYSTEM.CNF
  POLYGON.EXE
  DATA/
    MANIFEST.JSN
    S/  scenes
    L/  Lua scripts
    M/  meshes
    K/  hard-skinned animation assets
    R/  materials
    T/  textures
    A/  resident VAG audio
    X/  streaming CD-XA music (when present)
    B/  scene-local sequential bundles

DATA/MANIFEST.JSN maps runtime GUIDs and scene names to these compact staged disc paths. The editor still shows friendly project categories such as Scenes, Scripts, Meshes, Materials, Textures, and Audio; the short folder names exist only to reduce manifest text and CD path overhead on PS1.

Each built scene also receives a scene-local .PGB bundle containing its binary scene and ordered dependencies. The manifest maps the scene to that bundle, allowing the runtime to perform sequential CD reads with fewer seeks. Loose staged assets remain available as a bounded fallback and as the canonical manifest paths; authors do not reference .PGB files directly.

Each manifest scene entry also carries the destination scene's compact loading screen configuration. The runtime can select that presentation before reading the destination .BSN, which makes the correct loading screen available from the transition's first frame. The LOAD BSN chunk remains the scene-resident copy of the same authored settings.

Post-Bake Budget Reports

The build pipeline validates both authoring data and final PS1 runtime data. The authoring estimate catches missing references early. The post-bake report is the source of truth because it is generated after primitives are converted into mesh chunks and after scenes are written as binary .BSN files.

Important generated files:

File	Purpose
ps1_budget_current_scene.json	Current scene budget; overwritten with post-bake data during build
ps1_runtime_budget_<scene>_<hash>.json	One authoritative post-bake budget per built scene
ps1_build_performance_report.json	Build-level manifest, runtime memory, global asset, and scene summary

The build-level report also records the selected video region and target refresh rate. Acceptance checks that the project, report and staged MANIFEST.JSN agree.

Warnings appear when a scene approaches fixed PS1 limits such as GameObject count, mesh cache, manifest cache, packet buffer, binary scene load size, or runtime RAM headroom. .BSN scene data is treated as loader transient memory; the runtime report separates that peak from persistent mesh and Lua memory. Hard issues stop the build before packaging.

The build-level report now carries one canonical readiness field: PS1 Ready, Needs optimization, or Build blocker. Production acceptance requires PS1 Ready across the build, not merely a successful ISO/BIN/CUE.

The current production targets for official templates are:

Budget	Production target
Runtime RAM	At least 160 KB free inside the PS1-safe runtime budget
Manifest text	At or below 70% of the 16 KB manifest buffer
Binary scene read size	At or below 65% of the 160 KB scene load buffer
Packet estimate	At or below 80% of the 96 KB packet buffer

Release and acceptance builds require a real runtime memory report. Package-only flows may reuse staged content, but they are not considered authoritative if the runtime memory data is missing.

Binary Scene Data

Current builds write bounded .BSN scene data. The core GameObject and UI payload is followed by tagged, byte-sized feature chunks:

Chunk	Data
RNDR	Distance fog and per-Mesh Renderer color/fog/Room policy
LOAD	Loading-screen presentation and timing
UIEX	Bitmap fonts and extended UI/ProgressBar fields
UICV	Named canvas definitions and element-to-canvas bindings
INTR	Interactable button, cooldown, repeatability, and prompt-canvas fields
WRLD	Rooms and Portals
NAVG	Navigation components plus baked nodes and links
TIME	Cutscene clips, tracks, and keyframes
ANIM	Standalone Animation clips, tracks, and keyframes
SKEL	Scene Animator bindings

Sized unknown chunks can be skipped safely, while malformed or truncated known chunks fail with an explicit scene-load error. Rebuild projects after upgrading so the current writer and validation rules check every supported feature.

Validation Coverage

Validation is part of the product, not an optional debug step. It catches issues such as:

• missing required runtime or packaging tools (SDK/CMake/Ninja only for source builds; DuckStation only for Run),
• startup scene not included in Scenes In Build,
• scenes referenced by build settings that do not exist,
• missing mesh, texture, material, audio, or script assets,
• stale texture or audio imports when source files or settings changed,
• XA encoding failures or more than 8 streaming-music tracks,
• scene-bundle dependency, path, or package-generation failures,
• UI callbacks that reference missing Lua functions,
• Lua heap, script size, and script count limits,
• Level Builder meshes without Colliders,
• bitmap font scales outside the integer 1..4 range, imported atlases whose actual dimensions cannot contain the declared glyph grid, or invalid ProgressBar values,
• broken Room/Portal, renderer-room, NavMesh Surface, or NavMesh Agent references,
• navigation bake capacity errors,
• invalid cutscene targets, times, interpolation, events, or fixed capacities,
• invalid standalone Animation tracks, targets, times, completion-safe capacities, or unsupported cutscene-only track types,
• invalid skeletal assets, clips, bindings, hard-skin geometry, material count, or scene geometry/matrix/scratch budgets,
• overlong .BSN strings such as GameObject names, spawn IDs, prompts, Lua callback names, Input Action names, Animator states, or UI text,
• risky PS1 geometry such as large unsegmented built-in primitives,
• transparent or double-sided materials that may need careful ordering,
• post-bake binary scene, manifest, mesh, script, audio, animation, and runtime memory limits.

Hard errors should be fixed before building. Warnings should be treated as production risks.

Disc Images

The package step can generate .bin, .cue, and .iso artifacts. For real PS1 disc burning, use the .cue file because it describes the raw BIN image layout expected by PS1 tools.

DuckStation testing normally uses the generated package output.

Troubleshooting Checklist

Symptom	First places to check
Runtime cannot load a scene	Build Settings, startup scene, Scenes In Build, DATA/MANIFEST.JSN
Runtime cannot load a script	Script component path, staged DATA/L, build validation
Missing texture or material	Asset database entry, material GUID, staged DATA/T and DATA/R
Texture or audio changed but build looks old	Reimport status in Project Browser, source hash/settings hash warnings
Streaming music does not play	Streaming Music flag, track filename stem, staged DATA/X, Music.Play() return value
Object can be walked through	Collider component, Level Builder placement, Collider trigger flag
Build fails at packaging	mkpsxiso path, package logs, locked files in Build/ps1/package
Build & Run is disabled or fails	DuckStation path and generated .cue

For practical menu usage, see Workflow: Build & Export.

For common failures and runtime load errors, see Troubleshooting.

Testing the package

Rebuild after updating the editor or changing assets. The Build menu and command-line export use Release. Reproduce script errors in Play Mode to inspect source-line diagnostics, then test the rebuilt Release disc. A successful build is followed by gameplay testing: check controls, UI, frame rate, scene transitions, audio, and saving in the packaged game.

See Budget Dashboard for the meaning of PS1 Ready and the next testing steps.