Epok Engine
Documentation/Release notes

Epok Engine v0.5.0

START WITH THE BIG PICTURE

What does this part of Epok do?

Version 0.5.0 is about large worlds: geometry streamed from disc in checked pages, camera visibility tracks, prepared packet order for static scenery, textures cooked to their real size, worlds beyond ±128 units and a HUD authored in the editor.

  1. 01Review compatibility and the editor version
  2. 02Pick the optimization techniques your world needs
  3. 03Measure with the memory and performance tools

What is happening under the hood?

  • Every technique is opt-in with a stated cost; a project that enables none builds as before.
  • A project descriptor must declare editor_version 0.5.0; upgrade through the Hub.
  • Rebuild after upgrading: texture placement and baked face formats change generated output.

Field note: Read World optimization first: it says what each technique does, when to use it and what it measured.

Epok v0.5.0 is about large worlds on the PlayStation. Geometry streams from disc in checked pages. A guided camera can carry a baked visibility track that names exactly what each point of its route sees. Static scenery can be drawn from prepared, already-sorted packet lists. The editor now authors that whole workflow: draw the camera's route, bake what it sees on the GPU, and build. Around it, textures cook to their real 4- or 8-bit size, native TIM sources import losslessly, worlds are no longer bounded to ±128 units, and a camera can draw a sky, horizon and ground background. The HUD becomes authorable in the editor, with layout containers, focus navigation, rotation and imported TrueType/OpenType fonts.

Every technique is an opt-in setting with a stated cost. A project that enables none of them builds and renders as it did. World optimization techniques catalogues what each one does, when to use it, and what it measured.

Compatibility

The authoring contracts are unchanged: project descriptor format 1, map format 6, Blueprint format 5, Epok Lua Gameplay profile 2 and timeline schema 3. New scene data is additive and optional: a visibility track and its camera path, a prepared packet order program, and a camera's sky gradient. A map without them loads and saves byte-for-byte as before.

The editor version advances, so a project descriptor must read editor_version: 0.5.0. A project authored with v0.4.0 moves forward through the Hub's confirmed upgrade, which backs the descriptor up into .epok/migrations. Headless open paths reject a mismatched revision rather than migrating silently. The shipped examples/sample-game and both examples/gameplay-api-parity projects are updated.

Rebuild after upgrading. Texture VRAM placement changes because textures are now packed by size rather than in fixed shelves, and baked scenery uses baked face format 3. Neither changes authored data; both change generated build output. The HUD preview protocol between the editor and its preview runner moves from 2 to 5, which concerns no project file.

Windows setup now pins PCSX-Redux 26877.20261008.9, built from the same commit as the macOS pin, so both hosts run the same emulator. The previously pinned nightly is no longer served by its host, which made a fresh Windows setup fail. An existing Windows install reports a checksum mismatch on the old .tools/redux.zip: move it aside, then run tools/setup.ps1 -Repair to replace the emulator's files.

Large worlds: streaming and camera visibility tracks

  • Geometry streaming. EditableMesh chunks are packed into checksummed 64 KiB pages in GEOMETRY.BIN and loaded into a pool of 2 to 8 pages as they are needed. With geometry streaming, texture pixels can live in the same pages and be uploaded on bank activation.
  • Geometry Draw Distance. Chunks wholly beyond a camera-space distance (1 to 128, default 128) are rejected before their geometry is loaded.
  • Camera visibility tracks. For a guided camera, the build stores which faces each camera sample sees, as changes from the previous sample, and which pages that sample and the next one need. The streamer loads exactly those. The build measures the worst page transition and rejects a pool that is too small instead of dropping visible geometry. A route graph lets a player-driven target choose among recorded routes.
  • Static world. Optional for tracked scenery. Meshes are cooked in world space and drawn with the camera's matrix, so meshes of different actors meet without one-pixel seams. On the study scene, background pixels leaking through the ground at the start view fell from about 250 per frame to about 80.
  • No ±128 world limit. Actor translations and chunk origins are signed 32-bit Q12, chunk vertices are 16- or 32-bit as each chunk needs, and projection is camera-relative with exact re-anchoring. See World and camera coordinates.

See Geometry streaming.

Prepared packet order

For every camera sample, the build stores the exact list of polygons to draw, already in draw order, as delta-coded lists. At run time the renderer walks the list, projects each polygon with the GTE and emits its packet. It runs no visibility test, sort or per-polygon material setup. It covers static, unlit scenery.

Over the 401 camera views of a recorded demo, the prepared pass went from 1.24x to a median of 0.97x the reference renderer's time on the same polygon lists (p10 0.92x, p90 1.11x), and is faster on 241 of the 401 views. The contributions, each verified for identical output:

  • Baked faces carry their final GPU texture words, so the renderer copies them: 4.4% of the pass.
  • Few values live across the polygon loop: 13% combined.
  • GTE latency overlap (viewport test during RTPS, fourth-corner fetch during RTPT, depth average read late): 3.6%.
  • Projection blocks padded to 64 bytes: 1.2%.
  • Early rejection of faces wholly beside the screen: 0.8%.
  • The free packet-slot run held in registers: 0.7%.

Exact Near Clipping stays on by default. Turning it off draws faces at the camera as the GTE produces them, as the reference renderer does: 584k instead of 715k cycles at one static study view.

Guided camera tools in the editor

  • Build > Camera Path. Draws the route a guided camera follows.
    • Fly the Scene view to a shot and press Add key. Each key stores the pose, the horizontal field of view, the time, and whether it travels from the previous key or cuts to it.
    • The timeline shows keys as draggable diamonds, with cut markers, a playhead and zoom. The Scene view draws the path as numbered cameras that can be picked.
    • Play previews the path through the view.
    • Update samples turns the path into the track's samples.
    • Imported tracks convert to keys within a tolerance. On the study scene, 1,650 samples became 420 keys within 0.66 world units and 0.25 degrees.
  • Build > Bake Visibility. Computes each sample's visible faces on the GPU and writes them into the track, in the background with progress and an estimate of the time left. Presets trade specks against draw cost; draw distance is set in world units. The bake can also generate the prepared packet order. The study scene's 1,649 samples baked in 297 s.
  • Camera recordings. Play options > Record camera for visibility bake records the camera the game really renders during Native PC Play, and the bake adds what those cameras saw.
    • Lists baked from a recorded demo's cameras, with a 10% margin, draw at 1.01x the imported lists' cost in the prepared pass (p10 0.96x, p90 1.12x).
    • Lists baked from two thirds of those cameras lacked 0.4 display pixels per view for the remaining third.

Camera background

A camera's Background is a flat sky color, as before, or a sky gradient: the sky color overhead, a horizon color and a ground color below the horizon. Gaps and pits below the horizon then read as ground instead of sky. The runtime splits the screen along the true horizon, for any pitch or roll, and draws each side as at most three dithered Gouraud triangles in place of the flat clear. Along a 90-second guided path the frame rate was 56.18 fps with and without it. See Sky gradient background.

Textures and VRAM

  • Real texel size. Textures cook to 4 bits per texel when every index fits, and stay 8-bit otherwise, with no resampling or quantization.
  • Packing. Pixel rectangles and CLUT rows are packed offline with deterministic MaxRects orderings, so a scene has no count-based texture limit; an unfittable bank fails explicitly.
  • Fonts share the packer. Authored HUD fonts are placed first, from the font set alone, so every scene bank packs its textures around the same fonts.
  • Native TIM import. Indexed .tim sources import through the same Texture workflow and keep every index and all 16 bits of each palette entry.

See PSX texture cooking.

HUD authoring

  • The UI creation menu returns, with anchor presets and eight resize handles.
  • Layout containers. Horizontal, Vertical, Grid, Margin and Center, with per-element fill, expand and shrink flags, minimum size and stretch. The editor and the console run the same measure-and-arrange code, and a subtree without a container resolves exactly as before.
  • Focus navigation. Explicit neighbours and a highlight tint, moved by the D-pad on console, in the preview's Interact mode and in Native Play.
  • Styling and rotation. Tiled panel images and nine-slice borders in the Inspector. Rect rotation about the pivot is inherited by children, and zero rotation emits exactly the previous primitives.
  • Imported fonts. .ttf and .otf sources become 4bpp glyph atlases with a chosen character set, pixel height, antialiasing, padding and monospace override. Text keeps UTF-8 as written and draws with per-glyph advance and Left, Center or Right alignment.

Every new capability is reflected and reaches C++, Blueprint and every Lua execution mode. See HUD and 2D entities.

Editor and tools

  • Scene loading. Maps open through a background loader that reports its stages and keeps the previous map until handoff. Decoded inputs are cached by content hash. See Scene loading.

  • Scene View. Texture arrays grow in banks, so the Scene view has no artificial 32-texture limit. Baked visibility and streaming can be simulated in the view, opt-in. See Scene View resources and camera.

  • MCP. Twenty-six tools. New:

    • camera_path: create, convert, set keys, add a key from the view, select, update samples and preview.
    • visibility_bake: start and poll the bake.

    Actor patches can now set camera fields, and editor_state reports emulator and Native PC frames separately. See Integrations / MCP.

Generated reference and parity coverage

  • The API reference is re-extracted: 104 Epok headers with 1,565 callables, and 53 PsyQo headers with 944.
  • The gameplay parity inventory grows to 3,826 rows. The 529 public gameplay rows are unchanged, with no disposition changes on existing rows.
  • 433 rows are added, all internal renderer, streaming and camera machinery; the new renderer headers are classified as internal by name.
  • Three internal rows are gone with the declarations they described: the old texture initializer, a padding field and a union member.

Validation

  • The Rust suite passes on macOS: 900 passed, 71 ignored, including GPU readbacks run explicitly for the sky gradient, native STP, texture banks and game projection.
  • Renderer changes were checked against diagnostic sweep builds:
    • identical packet counts and counters for every camera sample, in both near-clipping modes;
    • byte-identical VRAM at the deterministic start view;
    • a GTE validation build that checks every projected vertex against an independent model.
  • End to end in the editor on a study scene:
    • a camera path was converted, sampled, baked on the GPU and built;
    • the world renders along the path in the emulator;
    • after merging the HUD work, an imported TTF label and the built-in font render correctly.
  • Emulator measurements are evidence for their fixed setups and are not physical-console timing. Streaming, visibility tracks, the prepared packet order, the sky gradient and the HUD work have not been validated on physical PlayStation hardware.

Known boundaries

  • A face touching the camera can leave a one-pixel edge artifact at the screen border in the baked renderers.
  • Player-driven route graphs are imported, not authored in the editor; Camera Path edits time-driven routes.
  • The prepared packet order covers static, unlit, untinted, non-scrolling scenery without fog or backface culling.
  • The editor writes the flat sky color without sRGB conversion, and the gradient matches it so switching modes does not shift the sky.

Full comparison: v0.4.0...v0.5.0

Documentation for v0.5.0 · View technical source · 6d01853