From Editor JSON to PS1 Runtime Data
The editor and the PS1 runtime should not consume the same data. That is one of the most important architectural decisions in Polygon Engine.
The editor wants readable project files, flexible authoring state, stable GUIDs, import metadata, screenshots, logs, and panels. The PS1 runtime wants compact data, fixed limits, predictable memory, and short disc paths.
Why Not Load Editor Data Directly?
Loading editor JSON directly on PS1 sounds convenient until you count the costs:
- parsing text consumes CPU and memory,
- large documents need larger buffers,
- strings and flexible fields complicate memory ownership,
- missing references fail late,
- runtime error messages become less actionable,
- the format becomes hard to change without breaking old projects.
Polygon Engine keeps editor data friendly for humans, then converts it during build into runtime data.
Source of Truth
The project has several data layers:
| Layer | Example path | Purpose |
|---|---|---|
| Project config | polygon.project.json | Budgets, scripting limits, build settings, PS1 target settings |
| Source assets | Assets/ | Models, textures, audio, scripts, materials, Level Builder meshes |
| Scenes | Scenes/*.json | Editable scene objects, UI canvas, components |
| Imported assets | Library/ | Runtime-ready meshes, textures, audio, asset database |
| Build output | Build/ps1/ | Staged disc root, package files, logs |
Only the build output is intended for the PS1 runtime.
Runtime Limits Are Part of the Format
The runtime uses fixed-size arrays and conservative buffers. Some important limits are shared between editor validation and runtime code:
| Runtime limit | Value |
|---|---|
| GameObjects per scene | 160 |
| Texture assets | 64 |
| Texture page slots | 20 |
| Mesh assets | 192 |
| Material assets | 64 |
| Audio clips | 16 |
| Script components | 32 |
| Script source cache | 32 |
| UI elements | 32 |
| Manifest assets | 256 |
| Manifest scripts | 64 |
| Manifest scenes | 32 |
| Manifest size | 16 KB |
| Binary scene size | 160 KB |
These are not arbitrary documentation numbers. They come from the runtime and shared project type limits. The editor validates against them because finding this problem after boot is too late.
What the Build Stages
A successful PS1 build produces a staged disc root like this:
Build/ps1/disc_root/
SYSTEM.CNF
POLYGON.EXE
DATA/
MANIFEST.JSN
S/ binary scenes
L/ Lua scripts
M/ meshes
R/ materials
T/ textures
A/ resident audio
X/ XA music
The user-facing output lives under:
Build/ps1/package/
That package folder contains the generated disc image artifacts and burn guidance. The internal disc_root exists so the pipeline and manifest are inspectable.
Manifest-Driven Runtime Loading
The runtime starts by reading:
DATA/MANIFEST.JSN
The manifest maps staged scene, script, and asset references to disc paths. This avoids forcing the runtime to guess where a GUID lives. It also means the build can fail early if a scene references a missing mesh, texture, material, audio clip, or script.
The runtime still has error handling for missing files, bad mesh headers, truncated textures, and script load failures, but the goal is for those errors to be rare in normal editor-built projects.
Build Tool Requirements
The PS1 build depends on external tools:
| Tool | Role |
|---|---|
| Bundled Polygon runtime | Used by standard binary releases |
| PSn00bSDK | Compiles and links the runtime only in private source builds |
| CMake and Ninja | Generate and run private source runtime builds |
| mkpsxiso | Builds the disc image output |
| DuckStation | Optional Build & Run testing loop |
The editor can validate tool paths and report missing or invalid tools. DuckStation is optional unless the user wants one-click testing.
Why This Matters for Users
A user should not have to understand the internal runtime to make a working build. They should see:
- which scenes are included,
- which scene starts first,
- which assets are missing,
- which budgets are over limit,
- which scripts exceed runtime constraints,
- which colliders or materials are risky.
That is why the Problems panel and PS1 Budget dashboard are part of the pipeline. The build system is not just a compiler wrapper. It is the place where editor freedom becomes PS1-compatible runtime data.
The Design Tradeoff
This approach adds work to the build pipeline. It has to convert, validate, stage, and package. But it keeps the runtime simpler and more predictable.
On PS1, that tradeoff is worth it. Complexity belongs in the Windows editor whenever possible. The console runtime should spend its limited memory and CPU budget on the game.
Continue Reading
- A Practical Map of the Original PlayStation
- The CD-ROM Is Not Extra RAM
- What It Takes to Ship a PS1 Project from an Editor
Updated for Polygon Engine 0.1.0-ea.2.