Build and Runtime Troubleshooting

Use this page when the editor validates incorrectly, the PS1 build fails, or the runtime reports a load error.

Fast Triage

1. Run Build > Validate Project.
2. Open Problems and fix hard errors first.
3. Open Build > Show PS1 Budget and inspect hard limits.
4. Check Build/ps1/logs/ after a failed build.
5. Inspect Build/ps1/disc_root/DATA/MANIFEST.JSN when a runtime asset cannot load.
6. Test the generated .cue from Build/ps1/package/.

Common Build Issues

Symptom	Likely cause	Fix
Missing runtime compiler tools	Private/source build selected without its toolchain	Use the installed binary runtime or open Build > Tool Paths...
Missing Ninja path	Private/source runtime build selected without its build runner	Configure Ninja for that source build; binary releases use the bundled runtime
Missing mkpsxiso path	Tool path not configured	Set mkpsxiso executable path
Build & Run fails	DuckStation path missing or invalid	Configure DuckStation path
Controller works in menus but not in 3D scene	DuckStation pad is mapped as digital, analog mode is off, or the emulator has no Port 1 mapping	Configure Port 1 as Analog Controller / DualShock and enable Automatically Enable Analog Mode, or press the mapped Analog/Guide button
Startup scene missing	Build Settings points to a missing scene	Open Build > Build Settings...
Scene load fails at runtime	Scene not included in Scenes In Build	Add the scene to Build Settings
Package Disc Only fails	No available runtime or stale staged files	Run full Build PS1 (Release)

Runtime Load Errors

failed to load MANIFEST.JSN

Check:

• Build/ps1/disc_root/DATA/MANIFEST.JSN exists,
• packaging completed successfully,
• the .cue points to the expected .bin,
• the runtime is launched from the latest build output.

Missing script or script load error

Check:

• the Lua Behaviour Script field points to an existing .lua file,
• the script is under the project and staged into compact runtime folder DATA/L,
• the script does not exceed the configured size limit,
• the target callback function exists if a UI button or Interactable calls it.

Missing mesh, texture, material, or audio

Check:

• the asset exists in Library/asset_db.json,
• the source asset still exists under Assets/,
• the imported output exists under Library/,
• the staged file exists under the compact Build/ps1/disc_root/DATA runtime folders (S, L, M, R, T, A, or X),
• Validate Project does not report missing GUIDs or files.

Streaming music does not play

Check:

• the source WAV has Streaming Music (CD-XA) enabled,
• no more than 8 streaming tracks are enabled,
• Build/ps1/disc_root/DATA/X/ contains the encoded track,
• the name passed to Music.Play() matches the WAV filename stem; comparison is case-insensitive,
• the script checks the boolean returned by Music.Play().

Gameplay Issues

Symptom	Check
Player walks through an object	Object has Collider, Collider is not trigger, Level Builder placement created collider
Trigger does not fire	Collider exists, Is Trigger is enabled, and the Lua Behaviour defines OnTriggerEnter
Interact does nothing	Player has Interaction Ray, target has Interactable, and the configured function name matches exactly
UI button does nothing	Button On Click target GameObject/function is set and the Lua Behaviour defines that function
SceneManager.LoadScene() does nothing	Target scene path is correct and included in Build Settings
Audio does not play	GameObject has Audio Source, clip GUID exists, and the resident clip fits the SPU budget
Music does not play	Streaming flag is enabled, track is staged in DATA/X, and Music.Play() uses the source filename stem
Save/load does not persist	Use PlayerPrefs.Save() for typed preferences or SaveData.Flush() for raw values; use SaveData.Reload() before expecting fresh device data
Game uses the wrong refresh rate	Select NTSC or PAL under Project Settings, save, then run a full Release build instead of Package Disc Only
Progress Bar does not change	Resolve it with UI.Find(), then check the boolean returned by ProgressBar.SetValue()
Navigation destination returns false	GameObject has an enabled root NavMesh Agent, referenced surface exists, preview bake has a connected path on that surface, and the complete route fits within 32 points
Agent crosses a dynamic obstacle	Runtime navigation has no dynamic avoidance; use authored colliders in the bake or stop/replan from script
Portal room disappears	Renderer Room assignment, camera inside expected Room, Portal enabled/open and direction/two-sided state, non-zero opening size, and valid Portal transform
Timeline.Play() returns false	Clip name matches exactly and the clip exists in the active scene
Native player still moves in a cutscene	Enable Disable Player Controls on the clip; custom Lua movement must be gated separately
Rumble is unavailable	Use Rumble.IsSupported(); verify an analog/DualShock pad, DuckStation vibration mapping, and that the active BIOS handler supports the fail-closed optional output patch

Rendering and Performance Issues

Symptom	Check
Wall disappears very close to camera	Near-plane clipping, collider placement, oversized wall primitive
Polygons overlap incorrectly	Large surfaces, far distance above safe range, transparent/double-sided materials
Scene is slow	Triangle count, packet estimate, texture count, audio clips, active scripts
UI draws over world unexpectedly	UI element sort/order and foreground OT reservation
Transparent object sorts badly	Keep transparent surfaces small and isolated
VRAM packing conflict	Open VRAM Inspector, select the red region, reveal the texture, then change format/size and reimport
Mesh colors are missing	Imported mesh contains vertex colors and Mesh Renderer uses Mesh Vertex Colors
GTE lighting is flat	Mesh contains usable normals, scene lighting is active, and Mesh Renderer uses GTE Vertex Lighting
Distance fog band looks coarse	Increase geometry subdivision where a large triangle spans much of the fog range; PS1 fog is interpolated from per-vertex factors, not evaluated per pixel

For live runtime measurements, hold L1 + R1 and tap Select to toggle the hidden overlay. A frame value above 1, an increasing slow-frame count, packet drops, or Lua errors indicates a runtime issue worth investigating. Test both gameplay and scene transitions; loading frames are part of the observed session.

What to Save When Reporting a Bug

Include:

• project name and active scene,
• exact build command,
• Problems panel output,
• Console build/runtime logs,
• Build/ps1/logs/ps1_budget_current_scene.json,
• Build/ps1/logs/build_summary.json,
• relevant script file,
• screenshot or short video of the runtime issue,
• whether the issue happens in editor Play Mode, DuckStation, or hardware.

Script, memory, and loading problems

Symptom	What to try
Lua instruction or memory limit exceeded	Shorten callbacks, avoid creating strings and tables every frame, and review the Lua budgets in Project Settings. Use a Debug build for source line information.
RAM budget exceeded after an update	Build again to refresh the report, then reduce scene or asset size using the Budget Dashboard. Check scene transitions as well as individual scenes.
Music restarts after loading	XA playback resumes from the beginning of the track. Plan transitions with that behavior in mind.
Diagnostic text disappears	Check packet-drop counters in the runtime overlay and reduce geometry or UI load.
Saving or loading fails	Open Save Data Simulator, check the selected failure mode, and inspect SaveData.GetLastError(). Show a failure message and a retry option in your game.