That is a much harder target than a one-off demo.

The Minimum Product Bar​

A shippable PS1 editor workflow needs all of these pieces to cooperate:

• project creation and loading,
• asset import,
• stable GUID references,
• scene editing,
• component authoring,
• Level Builder mesh creation,
• Lua gameplay scripts,
• UI canvas authoring,
• build settings,
• validation,
• runtime selection (or compilation in a private source build),
• asset staging,
• disc packaging,
• emulator testing,
• hardware-oriented release guidance.

If any one of those is vague, the user ends up debugging engine internals instead of making a game.

Build Output Has to Be Inspectable​

Polygon Engine separates staged disc data from final package output:

Build/ps1/disc_root/
  SYSTEM.CNF
  POLYGON.EXE
  DATA/
    MANIFEST.JSN
    S/  scenes
    L/  Lua scripts
    M/  meshes
    R/  materials
    T/  textures
    A/  resident audio
    X/  XA music

Build/ps1/package/
  *.bin
  *.cue
  *.iso
  polygon.xml
  README_BURN_PS1.txt

This makes build failures easier to reason about. If the runtime says it cannot load a script, the staged DATA/L folder and manifest are visible. If packaging fails, the package folder and mkpsxiso log are visible.

Failure Modes the Editor Prevents​

The engine has already run into the kinds of problems a real user would hit:

• missing binary assets,
• scenes not included in the build,
• script load errors,
• runtime out-of-memory errors,
• input mapping confusion,
• colliders missing from visible meshes,
• near-plane face dropout,
• polygon overlap from large surfaces,
• performance drops from too much scene work,
• SPU/VRAM pressure from assets.

Those failures become validation, documentation, and safer defaults instead of project-specific knowledge.

Validation as a Product Feature​

The Problems panel is one of the most important parts of the editor. It turns runtime pain into editor feedback.

Good validation says:

This Level Builder mesh has no Collider and can be walked through.
This startup scene is not included in Scenes In Build.
This Lua heap exceeds the PS1 runtime cap.
This material is transparent and needs careful PS1 ordering.
This primitive cell size is too coarse for stable PS1 depth ordering.

That is more valuable than a generic build failure. The user can act on it.

Emulator Testing Is Necessary but Not Sufficient​

DuckStation is the right fast loop for day-to-day work. It catches:

• boot errors,
• missing files,
• script errors,
• input problems,
• performance regressions,
• obvious rendering artifacts.

But emulator success is not the same thing as a hardware claim. Real hardware remains the final confidence gate, especially for timing, disc behavior, audio, and edge-case rendering.

DuckStation is the fast test loop; real hardware is the release-quality check.

Supported Boundaries​

Polygon Engine keeps the supported path explicit. It does not claim to provide:

• arbitrary mesh boolean optimization,
• general-purpose world streaming,
• unlimited Lua,
• arbitrary simultaneous audio streaming beyond the single CD-XA music path,
• modern lighting,
• order-independent transparency,
• automatic perfect conversion for every primitive,
• hardware certification without real hardware testing.

Clear limits make the supported path stronger.

Production Checklist​

Before calling a project release-ready, the workflow should pass this checklist:

Why the Complete Path Matters​

PS1 homebrew tooling is still a small space. A visual editor, Lua scripting, binary asset pipeline, and PSn00bSDK runtime in one workflow is unusual enough that the technical details matter.

The editor does not replace the target architecture. It moves expensive conversion and descriptive validation to Windows, then sends compact, bounded data to the console.

That end-to-end contract is what turns an editor demonstration into a repeatable PS1 production workflow.

Continue Reading​

• A Practical Map of the Original PlayStation
• The CD-ROM Is Not Extra RAM
• Controller Polling and Memory Cards on PS1
• Build pipeline reference

Updated for Polygon Engine 0.1.0-ea.2.

A useful engine API hides the transaction details without hiding the facts that matter to the game.

Buttons Arrive as Device State​

The digital pad reports a bit field in which a cleared bit means the button is pressed. The runtime converts that active-low hardware representation into the positive questions gameplay code expects:

Input.GetButton(Input.CROSS)
Input.GetButtonDown(Input.CROSS)
Input.GetButtonUp(Input.CROSS)

isHeld comes from the current sample. Pressed and released states require both the current and previous samples:

pressed  = current down and previous up
released = current up and previous down

This edge detection belongs in the engine. Reimplementing it in every script creates inconsistent behavior at frame boundaries.

Not Every Pad Has the Same Capabilities​

The PlayStation family includes digital pads, Analog Joystick/Dual Analog modes, and DualShock-style analog mode. A game cannot assume that two sticks are available because a controller is connected.

Polygon Engine exposes capability checks:

• Input.IsConnected()
• Input.HasAnalog()
• Input.GetPadType()
• Input.GetAxis(stickOrAction), returning normalized X and Y in -1..1
• Input.L3 and Input.R3 when the pad exposes stick-click buttons

The hardware axis bytes use 0-255, centered near 128; the public Lua API returns normalized numbers, centered at 0. For a digital pad, the engine maps the D-pad onto the left-stick result so movement code can share one path. The right stick remains centered. A dual-stick camera checks Input.HasAnalog() and asks the player to enable analog mode rather than silently reassigning shoulder or trigger buttons.

Editor Play Mode feeds keyboard, mouse, SDL controllers, and generic joysticks into the public Input API. DuckStation still needs the correct emulated device selected: Digital Controller for digital-only projects or Analog Controller/DualShock with analog mode enabled for dual-stick and L3/R3 input.

The editor is an iteration environment, not proof of a particular controller, emulator mapping, or console revision. Validate the packaged build on each intended target configuration.

A Memory Card Save Is a File Format​

Memory-card persistence needs more than writing gameplay bytes. A standard save file includes platform-facing metadata and an engine payload.

Polygon Engine writes one 8,192-byte block containing:

standard memory-card header
  -> display title
  -> 16-color icon palette and icon data
versioned Polygon Engine payload
  -> key/value entries
  -> checksum

The project defines a unique save-file ID and display title. This prevents two Polygon Engine games from silently targeting the same card file and gives the save a recognizable name in a memory-card browser.

The runtime supports 32 entries. Keys are limited to 31 characters plus a terminator; values are limited to 63 characters plus a terminator. The fixed layout keeps memory ownership and file size predictable.

Writes Can Fail​

Gameplay code must treat saving as an operation with a result:

if not SaveData.Write("checkpoint", "hub") then
    Log.Print(SaveData.GetLastError())
    return
end

if not SaveData.Flush() then
    Log.Print(SaveData.GetLastError())
end

SaveData.Write() changes the in-memory document. SaveData.Flush() persists the complete document by writing and verifying the inactive journal generation inside the existing block.

Useful failure states include:

• no card or no save file,
• invalid or oversized key/value,
• entry capacity reached,
• file creation failure,
• incomplete write,
• corrupt checksum or payload,
• unsupported save version.

The game should surface those outcomes. A silent save icon is not enough if the card was removed or the write failed.

Versioning and Migration​

The current format is versioned and checksummed. On load, the runtime distinguishes an empty card from corrupted data and from a newer unsupported version.

Polygon Engine can also read its supported older payload. The data is kept in memory and rewritten in the standard format after the next successful flush. Migration happens at the format boundary rather than inside gameplay scripts.

This is a small system, but it has the properties a shipping save path needs:

• a platform-recognizable header,
• per-project identity,
• bounded payload,
• corruption detection,
• explicit error reporting,
• backward migration for the supported older format.

The Engine Lesson​

Input and saving are often presented as single function calls. The hardware view is more useful:

controller: poll -> identify -> normalize -> derive transitions
memory card: encode -> create/write -> verify status -> report to gameplay

Polygon Engine keeps those device concerns in the runtime and exposes a small Lua surface. Scripts receive stable game concepts while retaining enough status information to handle the real device correctly.

Continue Reading​

• Lua Gameplay on a Fixed-Memory PS1 Runtime
• What It Takes to Ship a PS1 Project from an Editor
• Input reference
• SaveData reference

Test the player experience​

Use View > Save Data Simulator to test missing, full, and unreadable saves while developing. Check the return value of each save or load operation, show a clear message, and provide a retry option. Repeat the flow in DuckStation and on your target console with a test Memory Card.

See Persistence for examples and the key/value limits.

Updated for Polygon Engine 0.1.0-ea.2.

Polygon Engine treats asset import and runtime budgets as the same problem. If something can be authored in the editor, it has to be countable before the build.

The Memory Picture​

The original PlayStation gives the engine very little room:

This is why the editor has to show budgets. A project can be visually tiny and still fail if it uses too many textures, clips, scripts, or UI elements.

Textures​

Textures are imported into PS1-oriented .tex data. The runtime validates the texture header, data size, format, dimensions, and VRAM placement before uploading.

The current runtime limits include:

• 64 texture assets,
• 20 texture page slots,
• 1 MB total VRAM shared with framebuffers.

Texture import supports indexed and direct formats, but content still needs discipline. A single large texture can be more expensive than several small, reusable ones. UI images also use texture memory, so menus and HUD art must be budgeted with the world.

Materials​

Materials are intentionally simple:

• base color,
• optional main texture,
• render mode,
• double-sided flag,
• vertex color multiply,
• dithering.

That simplicity is part of the PS1 design. The runtime is not trying to emulate a modern material graph. It is trying to emit predictable GPU primitives.

The editor warns when a material choice is likely to be risky:

• double-sided materials increase draw cost and can make ordering less stable,
• transparent materials need careful placement and should stay small or isolated,
• missing texture assets should fail validation before runtime.

Audio​

Audio starts from imported WAV files, then follows one of two PS1 paths.

Resident clips are converted to VAG ADPCM, loaded into SPU RAM, and played through Audio Source components or the AudioSource Lua API. Streaming music is encoded as CD-XA data and played from the disc through the Music Lua API.

Short effects and latency-sensitive loops belong in the resident path. Long music belongs in XA streaming. Marking a long track as a resident Audio Source can still exhaust SPU RAM even when the source WAV looks modest on disk.

The import workflow is:

1. import WAV,
2. choose resident VAG or Streaming Music (CD-XA),
3. choose a target sample rate for resident audio,
4. assign VAG clips to Audio Source or address XA tracks by name,
5. validate SPU use and streaming-track count,
6. trigger playback through Play On Start, AudioSource, or Music.

The runtime suspends XA playback while it performs a scene load and restarts the suspended track from its beginning afterward. This keeps scene reads and music streaming from competing for incompatible CD access.

Lighting​

Lighting is GTE-oriented and deliberately limited. The runtime supports a small number of directional lights plus ambient contribution. The current runtime cap is 3 scene directional lights.

That fits the hardware. Directional lighting gives low-poly scenes shape and readability without pretending the renderer has:

• per-pixel lights,
• dynamic shadows,
• normal maps,
• physically based materials.

Lua can still create gameplay moments by enabling/disabling Light GameObjects or sequencing scene states. The important part is that the lighting model stays understandable and cheap.

UI and Particles​

Authored UI has a fixed scene element budget of 32. Particles are also capped. These limits are not glamour features, but they keep frame time and memory predictable.

For UI, the production rule is:

• use authored UI for shipping menus and HUD,
• keep element count small,
• use UI.DrawText() for temporary/debug text only,
• avoid texture-heavy UI unless it is part of the art budget.

The Budget Dashboard​

The PS1 Budget dashboard is a bridge between content and runtime. It summarizes:

• GameObject count,
• UI count,
• unique meshes,
• materials,
• textures,
• texture page placement,
• audio clips,
• Lua heap,
• packet buffer estimate,
• scene triangles,
• warnings and hard issues.

This is essential for a user-facing engine. The user should not need to know C constants to understand that a scene is drifting out of bounds.

What Makes This Project Interesting​

Most modern engine workflows assume the target is forgiving. Polygon Engine is interesting because the target is not forgiving at all.

The asset pipeline is therefore not just "import files." It is a system that turns friendly editor content into something a 1994 console can actually load, sort, light, play, and keep in memory.

Continue Reading​

• VRAM Is a Layout, Not a Texture Folder
• The CD-ROM Is Not Extra RAM
• Lua Gameplay on a Fixed-Memory PS1 Runtime

The current RAM model includes actual scene-object storage and separate load peaks for the old scene plus BSN read and the new scene plus asset/script staging. Live diagnostics expose allocation requests and nested subsystem times; they do not measure the largest free heap block. PS1 Ready is a static budget result. See the Budget Dashboard before using it as release evidence.

Updated for Polygon Engine 0.1.0-ea.2.

Polygon Engine's scripting model is built around that tension: scripts should be easy to attach, inspect, and test, while the runtime keeps memory, script count, and API surface bounded.

What Lua Owns​

In Polygon Engine, Lua is responsible for gameplay behavior:

• responding to triggers and collisions,
• driving pickups, gates, terminals, and stations,
• updating UI text and focus,
• calling scene loads,
• playing audio sources,
• toggling GameObjects,
• reading and writing small save data values.

Lua does not own the renderer, asset loader, SPU upload path, mesh format, or build pipeline. Those stay in C/C++.

That split is deliberate. The PS1 runtime should expose a small set of stable APIs instead of letting scripts reach into every subsystem.

GameObject-Attached Scripts​

Scripts are attached to scene GameObjects through a Lua Behaviour component. The runtime invokes lifecycle functions when they exist:

function Start(gameObjectId)
    Log.Print(GameObject.GetName(gameObjectId) .. " ready")
end

function Update(gameObjectId, deltaTime)
    Transform.RotateY(gameObjectId, 45 * deltaTime)
end

function OnTriggerEnter(gameObjectId, otherGameObjectId)
    Log.Print("triggered by " .. tostring(otherGameObjectId))
end

The engine also supports script-to-script style calls through GameObject.Invoke and UI Button callback targets. Build/editor validation can detect missing callback functions before the runtime is launched.

Runtime Scripting Limits​

The current scripting limits are intentionally visible:

The default project can choose smaller settings, but it cannot exceed the runtime cap. The build validates those caps.

Script Properties​

Script properties are one of the most useful workflow features. They let the same Lua file behave differently per GameObject.

For example, a station script can expose:

stationId = 3
promptText = "Activate"
targetGameObjectId = -1

The editor reads defaults, lets the user override values in the Inspector, and stages those values with the scene. The runtime passes them to the script component.

This is the kind of feature that makes a PS1 editor practical: fewer duplicated scripts, more data-driven GameObject behavior.

Instruction Budget​

Runaway scripts are especially harmful on a fixed runtime. A bad loop can steal the entire frame and make the game look like a renderer problem.

Polygon Engine exposes an instruction budget setting. When enabled, Lua calls are guarded so runaway scripts can be stopped instead of silently destroying frame time.

The build also warns when the instruction hook interval is larger than the per-call budget, because that configuration lets scripts overshoot before being interrupted.

Authored UI, Not Just Debug Text​

The runtime supports up to eight named UI canvases with independent reference sizes, visibility, and sort order. The fixed scene-wide element budget covers:

• Panel,
• Text,
• Image,
• Button,
• ProgressBar.

Lua can find UI elements, change text, progress, position, size, and color, toggle element or canvas visibility, change canvas order, and set or read focus:

local progressText = -1
local hudCanvas = -1

function Start(gameObjectId)
    hudCanvas = Canvas.Find("HUD")
    Canvas.SetEnabled(hudCanvas, true)
    progressText = UI.Find("Progress Text")
    Text.SetText(progressText, "Stations 0/5")
end

function Update(gameObjectId, deltaTime)
    if Input.GetButtonDown(Input.CROSS) then
        Text.SetText(progressText, "Activated")
    end
end

This is different from drawing temporary debug text. The authored UI is part of the scene data and is staged for the runtime.

Save Data​

The SaveData API is a bounded key-value layer backed by one 8,192-byte memory-card block:

if SaveData.Write("checkpoint", "hub") and
   SaveData.Write("station_03_complete", "1") then
    if not SaveData.Flush() then
        Log.Print(SaveData.GetLastError())
    end
end

local checkpoint = SaveData.Read("checkpoint")

The runtime supports 32 entries, with 31-character keys and 63-character values. The file includes a standard memory-card header, project-defined title, 16-color icon, versioned payload, and checksum.

The API reports card absence, capacity errors, invalid values, incomplete writes, corrupt payloads, and unsupported versions. Gameplay code can therefore show a real save result instead of assuming that flush() succeeded.

Supported older save payloads are decoded and rewritten in the current format after the next successful flush. Migration stays inside the persistence layer; gameplay scripts continue to read the same keys.

The system is intentionally small. It covers checkpoints, settings, progress flags, and compact player state without turning the memory card into a general database.

Why This Approach Fits PS1​

The PS1 does not have room for an unbounded scripting environment. The engine has to make Lua feel friendly while keeping it measurable.

The rule is:

Lua owns game rules.
C runtime owns hardware.
Editor owns validation.
Build owns packaging.

That separation is what makes Lua practical for PS1 homebrew instead of just impressive in a screenshot.

Continue Reading​

• Controller Polling and Memory Cards on PS1
• From Editor JSON to PS1 Runtime Data
• SaveData reference

Saving and testing your game​

Use PlayerPrefs for typed progress and settings. Call PlayerPrefs.Save() to persist changes and SaveData.Reload() to load the last save. Check each result before displaying a success message. Keep keys short: PlayerPrefs allows 28 bytes per key and 61 bytes per string value.

Test save, load, reset, and retry with View > Save Data Simulator, then repeat those flows in your packaged game. See the Persistence reference and Two-Room Relay tutorial.

For script errors, Debug builds retain source line information. Keep Lua memory and instruction limits in mind and measure gameplay performance; see the Runtime Reference.

Updated for Polygon Engine 0.1.0-ea.2.

The CD-ROM is capacity, not working memory.

Sector-Based Storage​

Data files are read in sectors. A common data-sector payload is 2,048 bytes, so runtime reads naturally operate in sector-sized units even when a file is not an exact multiple of that size.

This has practical consequences:

• small files still require directory lookup and sector access,
• unrelated files placed far apart can increase seeking,
• loading directly inside a frame update can create visible stalls,
• buffers need room for aligned reads and decoded output,
• filenames must match the disc filesystem and toolchain rules.

Polygon Engine uses short, deterministic disc names and an ISO-friendly directory layout. Human-readable source paths remain in the project; staged runtime paths are compact.

The Staged Disc​

The build output is organized around a small runtime manifest:

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

SYSTEM.CNF identifies the executable and boot settings. MANIFEST.JSN maps scene names and asset GUIDs to their final disc paths.

The manifest prevents the runtime from reproducing editor logic. It does not scan Assets/, parse import metadata, or guess which file belongs to a GUID. The Windows build resolves those relationships and fails before packaging when a required reference is missing.

Loading Is a Runtime State​

Reading a scene is not a normal pointer lookup. The runtime has to:

1. find the manifest entry,
2. locate the disc file,
3. read it into a bounded buffer,
4. validate its header and size,
5. rebuild runtime tables,
6. upload textures or audio to their dedicated memory,
7. resume gameplay only when the state is coherent.

Polygon Engine uses an explicit loading screen during scene transitions. This makes the stall visible and gives the CD subsystem room to complete work without pretending that arbitrary asset access is instantaneous.

The current binary scene read buffer is 160 KB; the manifest text buffer is 16 KB. Those limits are shared by build validation and runtime code.

Resident VAG vs Streamed XA​

The PS1 offers two different audio paths that solve different problems.

Resident effects are imported from WAV, converted to VAG ADPCM, copied into SPU RAM, and played through SPU voices. They have low playback latency but compete for the 512 KB sound buffer.

Streaming music is encoded as CD-XA data and read from the disc while it plays. It avoids storing an entire music track in SPU RAM, but it occupies the CD data path.

Polygon Engine exposes both paths:

The current runtime supports up to 16 resident audio clips and 8 XA music tracks. These are bounded engine tables.

During a scene load, Polygon Engine suspends XA playback, performs the disc work, and then restarts the suspended track from its beginning. That policy avoids making the CD-ROM serve two incompatible access patterns at the same moment.

Packaging Is Part of Correctness​

The staged files still need a valid disc image. Polygon Engine uses mkpsxiso to generate the package artifacts, including .bin, .cue, and .iso outputs.

The .cue describes the track layout used with the binary image. It is the primary artifact for emulator testing and physical-disc workflows. The standalone .iso is useful for inspection and compatible tools, but it does not replace every track-layout use case.

The package also includes burn guidance because file generation and hardware use are separate concerns. A build that boots in DuckStation proves that the executable and disc structure are coherent. Real hardware remains the final check for media, timing, and drive behavior.

The Engine Lesson​

Disc architecture reaches far into the editor:

• stable GUIDs make renaming source files safe,
• import metadata records the compiled artifact,
• build validation catches missing references,
• the manifest keeps runtime lookup small,
• loading screens acknowledge physical latency,
• XA streaming and scene loading coordinate access to the same device.

On PS1, the asset database is not only an editor convenience. It is the front end of a storage system that ends at an optical drive.

Continue Reading​

• From Editor JSON to PS1 Runtime Data
• Assets, Audio, Lighting, and the Budgets Behind Them
• What It Takes to Ship a PS1 Project from an Editor

Updated for Polygon Engine 0.1.0-ea.2.

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:

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:

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:

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.

This is why level authoring in Polygon Engine is split into two related paths: scene primitives and reusable Level Builder mesh assets.

Scene Primitives vs Mesh Assets​

The editor supports built-in scene primitives such as Plane, Cube, and Capsule. They are useful for fast blockouts and simple level structure.

The Level Builder creates editable mesh assets. Those are saved as project-owned source meshes and compiled into runtime mesh files.

That distinction matters:

All of them can end up as runtime mesh data, but they have different editing and validation rules.

The Bake Path​

The PS1 build pipeline can process compatible static built-in Plane and Cube geometry. The goal is to avoid shipping huge raw primitives to a renderer that has no z-buffer.

The bake path uses constants that are deliberately conservative:

The exact grouping and runtime cell size are implementation details and can change independently as the visibility path is tuned. Do not build gameplay logic around a fixed sector dimension. The stable authoring rule is that large primitives should become smaller runtime surfaces when that is safer for the ordering table and visibility workload.

Covered Faces and Conservative Removal​

Adjacent boxes often contain faces the player never sees: wall-to-wall contact faces, floor/wall overlaps, or hidden backsides inside modular construction. Removing some covered faces helps performance and reduces ordering conflicts.

Polygon Engine's removal is intentionally conservative. It should never behave like a full constructive-solid-geometry system. It does not solve arbitrary mesh boolean operations, and it does not claim to optimize every imported model.

The useful target is narrower:

• remove obvious covered faces for compatible static primitive layouts,
• preserve material assignment,
• preserve world placement,
• avoid deleting faces when the decision is ambiguous.

For a PS1 editor, a safe partial optimization is better than a broad optimization that silently breaks levels.

Level Builder Mesh Assets​

Level Builder is the in-editor path for authoring reusable mesh pieces. The workflow is:

Create Primitive / Load Mesh Asset
  -> edit in Object, Vertex, Edge, or Face mode
  -> validate mesh
  -> save source .pmsh under Assets/Meshes/
  -> export runtime .msh under Library/meshes/
  -> register GUID in Library/asset_db.json
  -> place mesh in scene

The compiled mesh runtime format uses the PGMSH1 magic. The runtime validates the header, vertex count, index count, index range, and data size before using the mesh.

Topology Editing Is a Product Feature​

Moving a face should not accidentally detach it from the model. Pulling an edge should not move only one triangle unless the tool is explicitly separating or extruding geometry.

That sounds obvious, but it is one of the most important pieces of a trustworthy level editor. If a non-engine-programmer user can create broken topology without realizing it, the engine is not production-ready.

Level Builder therefore needs clear tool behavior:

• selection modes must be explicit,
• gizmo drags must transform the selected geometry, not the camera,
• shared vertices and edges should remain shared by default,
• destructive operations such as Delete, Duplicate, Extrude, Inset, Merge, and Subdivide should be intentional,
• validation should surface degenerate faces, long edges, and non-manifold risk.

The modeling tool does not need to compete with Blender. It needs to produce reliable PS1 gameplay geometry.

Colliders Are Not Optional​

Visual geometry and collision geometry are separate concepts. A mesh can render correctly and still let the player walk through it if the scene has no Collider component.

When a Level Builder mesh is placed into a scene, Polygon Engine creates a GameObject with:

• Mesh Renderer referencing the saved mesh asset,
• an AABB Collider based on the mesh bounds.

That collider can be edited in the main Inspector. The build validation also warns when a Level Builder mesh reaches the PS1 runtime path without a Collider, because that object can be walked through.

This is a good example of product-oriented validation. The warning explains the gameplay consequence, not only the data problem.

Authoring Rules That Matter​

For PS1-facing levels, good content is usually:

• modular,
• low-poly,
• chunked into rooms, corridors, and thresholds,
• built from simple opaque materials,
• explicit about collision,
• validated before packaging.

Bad content is usually:

• giant coplanar surfaces,
• thin overlapping shells,
• dense rounded primitives used everywhere,
• transparent surfaces placed across the main view,
• imported art with no collider or budget review.

Polygon Engine's authoring workflow exists to move users from the second list to the first without asking them to understand every PS1 hardware detail.

Continue Reading​

• Rendering for a Console Without a Z-Buffer
• From Editor JSON to PS1 Runtime Data
• Level Builder reference

Updated for Polygon Engine 0.1.0-ea.2.

The editor can show a clean 3D scene. The PS1 runtime has to turn that scene into ordered GPU primitives with no z-buffer, fixed-point transforms, small memory pools, and a very unforgiving camera near plane.

The Core Constraint​

Modern engines usually rely on a z-buffer. If two triangles overlap on screen, the GPU can compare depth per pixel and keep the closest fragment. The PS1 GPU does not do that.

The PS1 pipeline is closer to this:

model vertices
  -> GTE transform and projection
  -> depth estimate
  -> ordering table bucket
  -> GPU primitive packet
  -> draw in ordered submission

That means visibility is approximate. A triangle is not resolved per pixel against every other triangle. The engine picks an ordering bucket, inserts a primitive, and the GPU draws it when that bucket is processed.

Polygon Engine's runtime uses an ordering table length of 2048, with the first 64 buckets reserved for UI and foreground work. That gives a useful depth range, but it does not make arbitrary overlapping geometry safe.

Why Editor Geometry Lies​

An editor viewport can make bad PS1 content look fine:

• giant floors look stable because the preview can sort or rasterize more forgivingly,
• overlapping walls look acceptable because the desktop path can hide depth ambiguity,
• thin coplanar details look crisp until the PS1 ordering table flips them,
• very close walls look fine until they cross the near plane,
• transparent materials look correct until draw order becomes content-dependent.

The practical lesson is that PS1 scenes need authoring rules. The renderer alone cannot make every scene correct.

Ordering Table Policy in Polygon Engine​

The runtime estimates depth and clamps primitives into ordering table buckets. It also computes GTE ordering scale values from the configured far distance, because a very large far plane spreads limited depth precision across too much space.

That is why the editor warns when PS1 far distance goes above roughly 32 world units. A larger range can be useful, but it reduces ordering precision and makes polygon overlap more visible.

The runtime currently combines several strategies:

This is not a full visibility solver. It is a PS1-appropriate compromise.

Near-Plane Clipping​

One of the most obvious PS1 rendering failures is a wall face disappearing when the player gets close. This happens when a primitive crosses the camera near plane and the renderer either rejects it too aggressively or projects invalid coordinates.

Polygon Engine's runtime handles this with conservative near-plane policy:

• keep mesh chunks alive when their bounds touch the near plane,
• let per-triangle clipping decide what survives,
• clip triangles and quads against the complete visible frustum,
• use safe projected coordinates when vertices get too close,
• prevent lateral grazing from collapsing extreme coordinates into the GPU's signed screen-coordinate range,
• avoid relying on a coarse object cull for close camera geometry.

That work was necessary for first-person scenes. In a first-person game, the camera constantly touches walls, terminals, pickups, and doors. Near-plane clipping is not an edge case; it is part of normal play.

Large Triangles Are a Content Bug​

The PS1 can draw large polygons, but large polygons are harder to order. A single wall quad that spans a whole corridor can overlap many objects and still produce one approximate depth value. The larger the primitive, the more likely the order is wrong for part of the screen.

Polygon Engine pushes against that in two places:

1. Authoring guidance: use smaller modular pieces for floors, walls, and thresholds.
2. Build processing: compatible static Plane and Cube geometry can be baked into smaller staged mesh chunks.

The runtime also has a triangle sorting cap for mesh-local sorting. That cap keeps sorting useful without letting sorting itself become the frame-time problem.

The Supported Boundary​

Polygon Engine does not claim to provide:

• it does not add a z-buffer to PS1,
• it does not make arbitrary interpenetrating geometry correct,
• it does not turn every imported model into a PS1-safe layout,
• it does not make transparency order-independent,
• it does not remove the need for content budgets.

The design goal is narrower and more useful: provide a visual editor while keeping final geometry inside a PS1-shaped envelope.

A Better Mental Model​

Think of PS1 rendering as a contract between the editor, build pipeline, and runtime:

Editor:
  make risky geometry visible and editable

Build:
  bake, chunk, validate, and stage runtime data

Runtime:
  transform, clip, sort, and draw with predictable limits

User:
  keep content modular, simple, and target-aware

That is the approach behind Polygon Engine. The PS1 is not a platform where the renderer can clean up every content mistake at the end. The tool has to guide the author before the runtime gets involved.

Continue Reading​

• A Practical Map of the Original PlayStation
• VRAM Is a Layout, Not a Texture Folder
• Building PS1-Safe Levels from Editor Geometry

Every rendering decision changes that layout. Resolution, color depth, double buffering, texture format, and palette placement all consume the same address space.

Start with the Display Buffers​

Polygon Engine targets a 320 x 240 frame. In 15-bit display mode, one frame occupies approximately:

320 x 240 x 2 bytes = 153,600 bytes

Double buffering needs two display areas, so about 307,200 bytes are committed before textures enter the picture. Alignment, drawing regions, and the chosen VRAM arrangement matter in addition to the raw byte count.

The two buffers solve a different problem from a z-buffer. One is displayed while the GPU draws the next frame into the other. Swapping them prevents the viewer from seeing a partially rendered frame. Neither buffer stores per-pixel depth.

Texture Pages​

The GPU addresses texture data through texture-page state plus per-vertex u, v coordinates. A texture page represents a 256 x 256 texel coordinate space, but its width in VRAM words depends on pixel format:

Indexed textures trade palette restrictions for density. A 4-bit texture stores four texels in the same VRAM width used by one direct-color texel. That can be a major saving when the art works with a small palette.

The page is not a standalone texture object. Several imported images can occupy regions within a page, provided their coordinates, format, and CLUT references remain valid.

CLUTs Are Real VRAM Data​

A CLUT is a row of 16-bit colors stored in VRAM. Four-bit textures select among 16 entries; eight-bit textures select among 256.

This creates useful art techniques:

• reuse one indexed image with different palettes,
• keep UI icons compact,
• reserve direct color for gradients or assets that cannot share a palette.

It also creates failure cases. A texture can fit while its palette rows do not. Two images can overlap because their texel dimensions were converted to VRAM words incorrectly. A CLUT placed inside a display area can be overwritten by rendering.

VRAM validation has to understand placement, not only file size.

Why Textures Warp​

The GPU interpolates texture coordinates affinely in screen space. It does not perform perspective-correct interpolation. A large polygon viewed at an angle therefore shows the familiar PS1 texture swim or warp.

More texture resolution does not fix the interpolation model. The practical controls are geometric:

• keep walls and floors modular,
• avoid one polygon spanning a large depth range,
• subdivide surfaces where the artifact is unacceptable,
• keep UV seams and T-junctions under control,
• use the visual character intentionally instead of expecting modern stability.

Subdivision improves local interpolation but increases transformed vertices, primitives, packet memory, and ordering work. It is always a budget trade.

Polygon Engine's Import Contract​

Polygon Engine converts source images into PS1-oriented .tex data. Import metadata records the format, dimensions, palette requirements, and estimated VRAM use. The build then performs deterministic page and CLUT packing.

The current runtime supports:

• up to 64 texture assets,
• 20 texture-page slots in the allocator,
• project-visible VRAM placement and budget validation.

Those are engine limits, not claims about the theoretical maximum of the hardware. They keep runtime tables and the build allocator bounded.

If packing fails, the useful question is not only "Are my textures too large?" It is also:

• Are too many assets using direct color?
• Can several images share a palette?
• Are UI textures consuming world-texture space?
• Is an image reserving a large rectangular region with little useful content?
• Does the chosen display layout leave the expected free region?

Dithering and the Final Image​

The GPU performs color calculations with more precision than the 15-bit display result and can apply dithering when reducing the output. Polygon Engine exposes dithering because it helps gradients and lighting survive the final color quantization.

Dithering does not create more VRAM or remove banding in every case. It changes the spatial pattern of the error, which often reads better on low-resolution output.

VRAM is one of the clearest examples of PS1 development as systems work. Texture import, screen setup, material design, UI art, and runtime rendering all meet in the same 1 MB map.

Continue Reading​

• A Practical Map of the Original PlayStation
• Rendering for a Console Without a Z-Buffer
• Assets, Audio, Lighting, and the Budgets Behind Them

Understanding those boundaries explains most PS1 engine decisions. The machine is fast when work is prepared for the right unit and expensive when the CPU has to compensate for a poor data layout.

The Hardware at a Glance​

The CPU also has a 4 KB instruction cache and a 1 KB scratchpad. Those numbers are small enough that code structure and data locality are part of performance work.

One Frame Crosses Several Systems​

A typical 3D frame is not sent to a single graphics API. It moves through a chain:

gameplay and scene traversal on the CPU
  -> world/view matrices
  -> GTE transform, lighting, and perspective projection
  -> screen-space triangles and quads
  -> depth buckets in an ordering table
  -> GPU command packets in main RAM
  -> DMA submission to the GPU
  -> rasterization into VRAM
  -> video output from the current display area

The GTE does not draw pixels. The GPU does not transform 3D vertices. The ordering table is a CPU-side structure that decides packet submission order. Each unit solves a specific part of the frame.

This separation is why a PS1 renderer needs more than a triangle loop. It needs bounded packet memory, numeric conversion, clipping, culling, ordering policy, double buffering, and a VRAM layout that remains valid for the entire frame.

Memory Is Split by Purpose​

The PS1 has no unified memory pool.

• Main RAM holds executable code and live game data.
• VRAM holds display areas, texture pixels, and CLUT data.
• SPU RAM holds resident ADPCM samples.
• CD-ROM holds the complete game but behaves as storage, not working memory.

Moving data between these domains is an operation. Textures are uploaded to VRAM. VAG samples are transferred to SPU RAM. Scene and asset files are read from disc into bounded main-memory buffers.

An engine therefore needs several budgets at once. A scene can fit in main RAM and still fail because its textures do not pack into VRAM. It can fit both and still exhaust SPU RAM with resident audio.

Fixed Point Is Part of the Architecture​

The console does not include the usual floating-point coprocessor. A compiler can provide software floating point, but it is a poor default for frame-critical work. PS1 graphics code instead relies heavily on integer and fixed-point representations.

Fixed point is not merely a performance trick. It changes the failure modes:

• values have explicit scale and range,
• multiplication needs wider intermediates or careful shifts,
• projection can saturate,
• world coordinates can overflow the range expected by the GTE,
• vertices snap to the integer screen grid.

Polygon Engine keeps editor transforms convenient on Windows, then converts and validates them for the runtime. Geometry that approaches unsafe projection ranges uses a guarded clipping/projection path instead of trusting saturated GTE output.

Why Polygon Engine Does More Work Before Boot​

The Windows editor has memory, file-system access, descriptive errors, and enough CPU time for conversion. The console should receive compact data that already respects runtime limits.

Polygon Engine uses that asymmetry deliberately:

Windows editor  -> import, author, inspect
Build pipeline  -> validate, quantize, bake, stage, package
PS1 runtime     -> load bounded data and execute the game

This is the central architectural rule of the engine. Flexible source data stays on the development machine. Predictable binary data goes to the console.

The result is not an attempt to hide the PlayStation. It is a workflow that exposes the constraints early enough to act on them.

Continue Reading​

• VRAM Is a Layout, Not a Texture Folder
• Rendering for a Console Without a Z-Buffer
• From Editor JSON to PS1 Runtime Data