Polygon Engine Documentation

Polygon Engine is a Windows editor, asset pipeline, Lua gameplay layer, and PlayStation 1 runtime for building PS1 games with a visual workflow. The editor uses familiar concepts such as GameObjects, Components, Prefabs, a Hierarchy, an Inspector, and a Canvas, while the runtime and build pipeline remain designed around the limits of the original PlayStation.

The documentation is organized as a product manual: start with the editor workflow, then move into assets, components, scripting, build output, and PS1 production rules.

Engine Layers

Editor (Windows, C++ / ImGui)
  -> scene editing, components, UI canvas, Level Builder, validation

Asset Pipeline
  -> source assets in Assets/
  -> imported runtime assets in Library/
  -> resident VAG audio or streamed CD-XA music
  -> GUID-based references through Library/asset_db.json

Build Pipeline
  -> validates scenes, scripts, budgets, and tool paths
  -> stages DATA/ assets and manifest files
  -> selects the bundled PS1 runtime (compiles only in a private source build)
  -> packages disc output under Build/ps1/package

PS1 Runtime (C + PSn00bSDK)
  -> loads DATA/MANIFEST.JSN and the startup scene
  -> renders through GTE/GPU ordering-table paths
  -> runs Lua scripts, authored UI, audio, collision, and save data

What the Engine Currently Supports

Polygon Engine currently focuses on these workflows:

• visual scene authoring with GameObjects, Components, Prefabs, and multi-selection editing,
• imported models, textures, materials, audio, and Lua scripts,
• Level Builder mesh assets saved into the project and reused in scenes,
• multiple named authored UI canvases with panels, text, images, buttons, and scriptable visibility/order,
• bitmap-font UI and runtime ProgressBars,
• configurable loading displays, distance fog, mesh vertex colors, and GTE vertex lighting,
• recursive Room/Portal connectivity and height-aware baked grid navigation,
• concurrent standalone Animation clips for GameObjects, UI, rumble, and skeletal events,
• compact cutscene timelines with Game View preview, events, UI/fog tracks, and optional player-control blocking,
• hard-skinned FBX animation with bounded PS1 geometry and matrix budgets,
• an interactive VRAM layout inspector for framebuffers, texture pages, footprints, and CLUTs,
• Lua Behaviours with a strict PascalCase API, editor diagnostics, hot reload, generated language-server definitions, and PS1 bytecode validation,
• native player, interaction, camera, collider, light, audio, animator, and save systems,
• PS1 validation, budget reporting, asset staging, and disc packaging.

Documentation Map

Section	Use it for
Quick Start	Open a project, validate it, and produce the first PS1 build
Project Structure	Understand Assets, Library, Scenes, and Build
First Person Tour	Learn the basic bundled reference project and smoke-test flow
Advanced Feature Lab	Validate skeletal animation, timelines, portals, navigation, multiple canvases, SaveData and rumble
First Project Tutorial	Build a two-room first-person game with Lua, UI, audio, a trigger, and memory-card saving
Project Hub	Create, register, search, reopen, and repair local project listings
Editor Manual	Learn the main panels and recommended workflow
Level Builder	Create reusable mesh assets inside the editor
UV Editor	Unwrap, pack, inspect, and adjust mesh UVs for PS1 textures
Advanced Scene Authoring	Configure rendering, loading/UI, rooms/navigation, cutscenes, and standalone animations
VRAM Inspector	Inspect the current scene's planned physical VRAM layout
Scene Management	Configure build scenes, transitions, loading, and persistent data
Visibility and Culling	Understand the conservative runtime visibility path and its authoring rules
Rooms, Portals, and Navigation	Author room connectivity and baked runtime paths
Cutscenes and Timelines	Author and trigger compact in-engine sequences
Standalone Animations	Author concurrent GameObject, UI, rumble, and skeletal-event clips
Components	Understand the GameObject and Component model
Asset Pipeline	Import static models, skeletal animation, textures, materials, and audio
Lua Scripting	Implement gameplay behavior with the current runtime API
Lua Authoring Workflow	Configure tooling, expose Inspector properties, diagnose scripts, and preserve PS1 parity
Cookbook	Copy common gameplay patterns such as pickups, gates, UI buttons, and save/load
Build Pipeline	Validate, stage, select the runtime, and package PS1 output
Troubleshooting	Diagnose common build and runtime failures
PS1 Architecture	Understand the hardware model behind the engine's constraints
PS1 Production Reference	Stay within PlayStation memory and rendering limits

Documentation Contract

This manual documents the current public workflow and API. Names shown in the Lua reference are exact and case-sensitive; undeclared aliases are not part of the runtime contract. When a feature supports only a narrow PS1-safe path, the documentation states that scope directly.

Keep project backups and run Production Acceptance after opening an older project. Polygon Engine upgrades supported project, scene, and Prefab documents transactionally before saving them. Documents created by a newer unsupported format are rejected instead of being rewritten. Platform, controller, emulator, and hardware boundaries are listed in Supported Platforms and Limitations.

Finding your way around

The Lua API calls scene objects GameObject. In the editor, create them from Scene > Create Entity. A UI Button's Target Entity field selects the GameObject that receives its callback.

After updating the editor, regenerate your project's Lua workspace so your code editor shows the available functions and arguments. Use the Lua API Reference alongside the scripting examples.