Epok Engine
Documentation/Release notes

Epok Engine v0.6.0

START WITH THE BIG PICTURE

What does this part of Epok do?

Version 0.6.0 is about 2D games: a complete 2D world on the console, a pixel-accurate 2D editor with tile painting, and a playable Platformer 2D template, plus HUD check boxes, sliders, colour tags and string tables.

  1. 01Review compatibility and the editor version
  2. 02Create a Platformer 2D project
  3. 03Paint tiles and add 2D nodes

What is happening under the hood?

  • Authoring contracts are unchanged; Actor2D nodes, TileSets and string tables are additive.
  • A project descriptor must declare editor_version 0.6.0; upgrade through the Hub.
  • The 2D runtime is opt-in by content: a project without 2D nodes compiles none of it.
  • The 2D world has not been validated on physical PlayStation hardware.

Field note: Play the template before reading the reference: every node it uses is explained by its own Inspector.

Epok v0.6.0 is about 2D games. A complete 2D world now runs natively on the console:

  • sprites with frame animation and tile maps painted from TileSets;
  • parallax and canvas layers;
  • paths and moving platforms, lines, polygons, particles and 2D audio;
  • cut-out skeletons with IK and pathfinding;
  • rigid bodies and joints;
  • render-to-VRAM pictures and split screen.

The editor authors all of it in a pixel-accurate 2D Scene view. New Project > Platformer 2D starts from a playable, layered side-scroller in C++, Blueprint or Lua. The HUD gains check boxes, sliders, colour tags and string tables with switchable languages.

The 2D runtime is opt-in by content: a project without 2D nodes compiles none of it. See 2D worlds.

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 data is additive:

  • Actor2D actors with 2D components;
  • two new authored assets, TileSet (format 1) and the project string table assets/Localization/Strings.epokasset (format 1);
  • keyed texts and focusable toggles and sliders on HUD elements.

A map without them loads as before.

The editor version advances, so a project descriptor must read editor_version: 0.6.0. A project authored with v0.5.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; generated build output changes in three ways:

  • VRAM reservation. The framebuffer reservation now follows the display width instead of always taking 640 columns. A 320-pixel-wide game gains 327,680 bytes of texture space, and textures may be placed differently. Authored fonts keep their placement at every resolution.
  • Built-in font. A space no longer emits a glyph primitive: one primitive fewer per space, and no stray texels.
  • Static RAM. HUD actor data grows by 8 bytes per actor slot for focus events and slider steps. The sample game's static RAM goes from 973.7 KiB to 976.0 KiB, and a project without 2D content adds nothing else.

The HUD preview protocol between the editor and its preview runner moves from 5 to 6, which concerns no project file.

2D worlds

  • Nodes. Actor2D actors with a pixel-based, Y-down transform carry Sprite2D, TileMapLayer, Collider2D, CharacterBody2D, Camera2D, Parallax2D, Path2D, PathFollow2D, Line2D, Polygon2D, Particles2D, AudioPlayer2D, VisibleOnScreenNotifier2D, RemoteTransform2D, Skeleton2D, NavigationRegion2D, NavigationAgent2D, RigidBody2D, Joint2D, SubViewport2D, SplitScreen2D, CanvasLayer2D and CanvasModulate2D components, beside any C++, Blueprint or Lua component.
  • Sprites and cameras. Texture regions, sprite-sheet cells, flips, modulate, the console blend modes, z-index and y-sort, and named frame animations with events. Camera2D follows with drag margins, limits, smoothing, zoom, rotation and shake. A sprite that is neither rotated, scaled nor flipped is drawn as a hardware rectangle with exact texels.
  • Collision and movement. Box and circle colliders with layers and masks in solid, trigger and one-way modes. move_and_slide detects floor, wall and ceiling, with floor snapping. Overlaps reach the actor's overlap_2d event, and gameplay gets raycast_2d and overlap_box_2d queries.
  • Tile worlds.
    • TileSets carry collision, one-way tiles, animation, terrains and custom data.
    • TileMapLayer cooks only the 16 × 16-cell chunks that hold tiles, draws only the cells on screen and can be edited at runtime.
    • Parallax2D scrolls and repeats; canvas layers draw in screen pixels or world space.
  • Content.
    • Curved paths with followers that carry a body standing on them, so moving platforms work.
    • Line2D and Polygon2D shapes, and CPU Particles2D emitters.
    • AudioPlayer2D with distance attenuation and stereo pan.
    • On-screen notifiers and remote transforms.
  • Cut-out skeletons. Skeleton2D animates attached parts as bones with pose keys. It allows up to 24 bones, 16 animations of up to 64 keys and two two-bone IK chains. A Skeleton2D component takes 224 bytes on the console.
  • Navigation. NavigationRegion2D is a grid built from a tile layer and static bodies, or a navmesh outline. NavigationAgent2D finds a path to a target node or position and walks its node itself, with no script. A grid costs one bit per cell.
  • Rigid bodies and joints. RigidBody2D boxes and circles collide like move_and_slide (no tunnelling). Characters push pushable bodies, and bodies can sleep and be frozen. Joint2D ties bodies with rods, ropes and springs, and a Line2D that follows nodes draws the rope.
  • Pictures and split screen.
    • SubViewport2D draws a camera's view, or one canvas layer, into a 15-bit VRAM picture every few frames, and any Sprite2D can show it: minimaps, monitors, group transparency.
    • SplitScreen2D shows two cameras side by side or stacked, with the HUD drawn once over both.

Native PC Play draws the same 2D frame as the console. See 2D worlds.

2D editor

  • 2D Scene view.
    • Select, move, rotate, scale and pan tools with grid and rotation snapping, pixel rulers, and real texture and animation previews.
    • Collider, camera, joint, bone and navigation overlays.
    • Drag-and-drop sprite creation, a sprite region editor and a sprite-sheet slicer.
  • Tile painting. Paint, line, rectangle, fill, picker, eraser and selection tools, with random scatter, flips and quarter turns. Patterns and terrains, and a TileSet editor with its own undo.
  • Shapes and skeletons. Paths, lines, polygons and navmesh outlines are edited on the canvas. Skeletons have a pose timeline in the Inspector, rest poses, a Play preview and Reach target for IK.
  • Finding and fixing nodes.
    • Add 2D Node and Add Component search by name, group or purpose, best match first, with the project's recent nodes on top.
    • Node and texture pickers with many choices open with a search field.
    • A node that cannot work as set up shows a warning sign in the Hierarchy and the reasons in its Inspector. One-click fixes add a collider fitted to the sprite, show a picture on the HUD, or add a navigation region over the ground.
  • HUD Interact preview. The preview no longer fails to build on a new project.

Platformer 2D template

New Project > Platformer 2D creates a playable 320 × 240 side-scroller:

  • an animated player that runs, jumps and pushes a crate;
  • a following camera with level limits;
  • a tile map with one-way platforms and a lift on a path;
  • layered parallax scenery with a sky, sun, hills, clouds, treeline and foreground;
  • a cut-out guide whose arm follows the player through IK, and a glowing wisp that navigates round the solid tiles;
  • a garland of light bulbs on rope joints, drifting petals and fireflies, coins and a HUD.

The scene is grouped by purpose so a game can start by deleting what it does not need. Its gameplay is written in C++, Blueprint or Lua, and every flavor behaves identically. The template opens without a single configuration warning.

HUD

  • Check boxes and sliders. Focusable elements can be toggles (Cross flips them) or buttons, and a focused progress bar with a step moves by it on Left/Right. Gameplay reads pressed, changed and cancelled events once each.
  • Colour tags. [color=#rrggbb] recolours part of a text, and the tags take no room.
  • Localization. Window > Strings edits a table of keys and languages, with CSV export and import. Texts pick a key, and LocalizationLibrary::set_language rewrites every keyed text at once and keeps the choice across scene changes.

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

Generated reference and parity coverage

  • The API reference is re-extracted: 113 Epok headers with 1,967 callables, and 53 PsyQo headers with 944 (unchanged).
  • The gameplay parity inventory grows from 3,826 to 4,733 rows: 907 are added and none are removed, with no disposition changes on existing rows.
  • 24 of the added rows are public gameplay API: the 2D queries and their hit sample, the overlap_2d event, toggle and press events on focusable elements, slider steps, keyed texts and the localization library.
  • The other 883 are internal, almost all in the 2D modules.

Validation

  • The Rust suite passes on macOS: 959 passed, 71 ignored. It includes six editor usability scenarios that drive the real 2D view toolbar, Hierarchy and Inspector with simulated input:

    • a pushable crate, 6 interactions;
    • a lamp on a rope fixed from its warning, 9;
    • a picture on the HUD, 4;
    • an enemy chasing the player, 6;
    • physics on an existing sprite, 7;
    • a split screen, 10.

    Each finishes without a script and without warnings.

  • The host runtime tests (world2d.cpp, world2d_service.cpp, hud_layout.cpp) cover projection, colliders, movement, one-way platforms, triggers, tiles, content nodes, skeletons, navigation, rigid bodies, joints, views and the HUD widgets.

  • The Platformer 2D template builds for the PlayStation in C++, Lua and Blueprint and is played in PCSX-Redux over MCP. Further emulator tests check a SubViewport2D minimap and a SplitScreen2D, and the HUD check boxes, sliders and language switch.

  • Emulator runs are evidence for their fixed setups and are not physical-console timing. The 2D world and the new HUD widgets have not been validated on physical PlayStation hardware.

Known boundaries

  • Boxes ignore rotation for collision, and rigid boxes slide and stack without tumbling: the solver is axis-aligned, and circles roll.
  • There are no polygon colliders, and tile collision shapes are rectangles, so there are no slopes yet.
  • Tile layers use their node's position but not its rotation or scale, and they do not y-sort with sprites. A TileSet uses one atlas texture.
  • Navigation regions are cooked where they are placed and do not change at runtime. Paths do not cross from one region into another, and the map plans at most one path per step.
  • Skeleton parts are rigid: there is no mesh deformation or skinning.
  • Joints are not drawn at runtime; draw them with a Line2D that follows the same nodes.
  • SubViewport2D pictures are at most 256 × 256 pixels, at 2 bytes per pixel of VRAM.
  • On Native PC Play, 2D audio keeps the volume it started with and is not panned.
  • HUD scroll containers, tabs and themes, interactive XA music, 2D timeline tracks and 2D scene import are not part of this release.

Full comparison: v0.5.0...v0.6.0

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