Epok Engine v0.7.0
START WITH THE BIG PICTURE
What does this part of Epok do?
Version 0.7.0 adds the Dungeon Generator: seeded dungeons in 3D and 2D with designed routes, keys and locked doors, stairs, handmade rooms, gameplay queries, a minimap, a seed bench and volumes, plus a Dungeon template.
- 01Review compatibility and the editor version
- 02Create a Dungeon project or add a generator to a map
- 03Shape it with recipes, styles, rooms and volumes
What is happening under the hood?
- Every authoring contract from v0.6.0 is unchanged; maps without a generator load as before.
- A project descriptor must declare editor_version 0.7.0; upgrade through the Hub, which backs up the descriptor first.
- Lua == and Blueprint Equal now compare object references by identity, as C++ already did.
- The sample game's static RAM goes from 976.0 KiB to 981.0 KiB.
- Dungeon content has not been validated on physical PlayStation hardware.
Field note: Start with Your first dungeon: the template shows every new feature working together before you build your own.
Epok v0.7.0 is about dungeons. A Dungeon Generator placed in a map lays out rooms, corridors and doors from a seed and bakes them into ordinary content, in 3D and in 2D:
- rooms and corridors scattered on a grid, or a designed route grown from a Dungeon Recipe: a main path, branches, loops, caves, items, keys and the doors they open, one-way shortcuts, floors joined by stairs and rooms built by hand;
- a Dungeon Style that decides what every spot becomes, with a built-in sci-fi look drawn for the console;
- keys and locked doors that work in game in C++, Blueprint and Lua;
- gameplay queries, a minimap with fog of war, a seed bench and generation volumes.
New Project > Dungeon starts from a playable dungeon with the Third Person character, in C++, Blueprint or Lua. See Dungeon Generator and Dungeon template.
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:
- Dungeon Generators stored in maps, with their settings and what they generated;
- three new authored assets, Dungeon Style, Dungeon Recipe and Dungeon Room (format 1 each).
A map without a generator loads as before, and generated content is ordinary actors, meshes and tile layers that build without the generator.
The editor version advances, so a project descriptor must read editor_version: 0.7.0.
A project authored with v0.6.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.
Two behaviours change:
- Reference equality in Lua and Blueprint. Lua
==and~=, and Blueprint Equal and Not equal, compare two object, actor or component references by identity, as C++ already did. A reference is one ObjectId on the console, so the runtime does not change. - The Third Person controller walks down steps. New projects' controllers, in all three flavors, probe the ground when they leave it without jumping and move onto it, so stairs are walked down rather than fallen down. Existing projects keep the controller they have.
Rebuild after upgrading. A map without a dungeon cooks empty dungeon tables, and the minimap renderer compiles out unless a map uses it. Static RAM grows a little for every project: collision gains compound colliders (about 2.4 KB of code and tables, and 8 bytes per actor slot) and the dungeon tables take about 200 bytes. The sample game's static RAM goes from 976.0 KiB to 981.0 KiB.
Dungeon Generator
- Generators. GameObject > Dungeon Generator adds one to a 3D or 2D map. Its band in the Inspector edits the seed, layout and look, previews the layout in the Scene view, shows warnings with fixes and the PSX budget the map will use (actors, quads, collision boxes, navigation nodes or tiles). Each generation is one undo step and the same seed and settings always give the same dungeon.
- Rooms and corridors. Rooms scattered with a minimum spacing, joined by a spanning tree of their nearest neighbours plus loops by chance, with corridors routed around other rooms.
- 3D bake. A few EditableMesh sections, one compound collider (many boxes on one actor), up to twelve navigation volumes and spawn and goal actors, under the generator. Defaults are sized to the Third Person character (cells of 3, walls of 6, doors of 3.6), a ceiling closes the dungeon, and the band fits the sizes to any character's collider.
- 2D bake. One TileMapLayer solved with Floor and Wall terrains of a TileSet, with the built-in dungeon tiles when the project has none.
- Automation. MCP
dungeon_generate,--generate-dungeon,--dungeon-seedand--dungeon-settingsgenerate headlessly;--template dungeoncreates the template.
Dungeon Styles
A Dungeon Style maps the generator's spots (floor, wall, door, doorway, solid, corner, column, ceiling, room, spawn, goal, key, lock, item, one-way door) to ordered pieces: blockout geometry, EditableMeshes merged into the sections, actors of any class, baked point lights, Key and Door pieces, and 2D terrains and tiles. Each piece has a chance (once per spot or once per room, for room-wide variants), an area, a limit, a transform, whether it stops the pieces after it and the paths it keeps to. The node editor adds pieces from a searchable menu or by dragging from a spot, keeps its own undo, autosaves and regenerates the map's dungeons as it changes. The built-in look gives each room one of three floors and walls, columns along the walls and a ceiling, with textures drawn for the console.
Dungeon Recipes
A Dungeon Recipe grows a room graph from ordered steps and lays it out on the grid:
| Step | What it does |
|---|---|
| Lattice, Main path, Branch | Room slots, the route from spawn to goal, dead ends and loops back |
| Items | Named items by depth along paths, anywhere, at a room's centre or against a wall |
| Key and lock | A key on some paths, the locked door it opens on others |
| One-way doors | Shortcuts back towards the spawn that open from the far side |
| Caves | Rooms of some paths grown by a cellular automaton |
| Levels | Rooms on up to five floor levels, joined by flights of stairs in their corridors |
| Handmade rooms | Rooms of some paths made from Dungeon Rooms, turned to fit, up to a number |
| Rooms | Room fill, cut corners, corridor width |
Every key and lock is checked by walking from the spawn and picking up keys, and corridors stay apart so a locked door cannot be walked around. The editor lists the steps with tooltips and previews the room graph for any seed, with levels and handmade rooms marked.
Keys and doors that work in game
Key and Door pieces place a key that is picked up on touch and a locked door that
disappears when its key is taken, in 3D and 2D. Their DungeonKey and DungeonDoor
classes are installed into the project in its flavor (C++, Blueprint or Lua) and never
overwritten once edited; unedited earlier copies are replaced. A key is picked up only by
the generator's Player, and the band offers Use Player when keys have none.
Levels and stairs
With a Levels step rooms stand on different floors: a level is 1.6 units, climbed in four steps of 0.4 inside one straight corridor cell, so rooms stay flat and doors open onto level floor. Walls, ceilings, every style piece and navigation follow the floor, and collision is solid but for the air over each walkable cell. The recipe editor shows each room's level and the band counts levels and flights.
Handmade rooms
A Dungeon Room is a room built once in any map and saved with GameObject > Save Selection as Dungeon Room...; empties named Door on its edge become its doors. The room editor shows its floor plan, where doors, spots for keys and items and cells left out of the floor are clicked on and off. A recipe's Handmade rooms step places rooms in quarter turns at their doors: plain meshes, cubes and solid colliders merge into the dungeon's geometry and collision, and lights and actors with behaviour are copied with stable identities. The Dungeon template builds a Reactor room in a workbench map.
Gameplay queries
Each generation bakes what game code may ask about the dungeon, and the map cooks it as
constant tables: the room count, the room at a point or under an actor, the spawn and
goal rooms, each room's bounds, level, path, depth and links, the next room on the way
between two rooms and their distance, keys, items, locked doors, up to eight free spots
per room, the seed and a seed-bound random stream. Gameplay API > Dungeon in
Blueprint, epok.dungeon in Lua and epok::DungeonLibrary in C++. The band lists the
rooms as game code numbers them and picks one out in the Scene view.
Minimap
The band's Minimap settings put a map of the dungeon in a corner of the console's screen, drawn under the HUD. It fills in as the player explores: a room once entered, with dim stubs of the corridors leaving it, a corridor once walked. Keys show until they are picked up, locked doors until they open, and the goal once its room is explored. The box fits the dungeon or follows the player at a fixed scale. Game code shows and hides it, opens a full-screen map and reveals or forgets rooms. It costs about 9 KB of RAM for the template's dungeon, shown in the band.
Seed bench
Test seeds... lays out many seeds of a generator without touching the map and
measures each against the console's budget, with histograms of recipe attempts, quads
and actors, a table of the seeds that do or do not fit with Use, and CSV export of
those that fit to the project's exports/ folder. --dungeon-seed-bench runs it
headless.
Volumes
Generation volumes are rectangles of the generator's grid, drawn by dragging in a Volumes window: Keep out, Only here, Room here and Mirror left-right or front-back. Rooms-and-corridors layouts follow all of them; recipes close the lattice slots a Keep out or Only here volume touches and keep their whole grid so volumes stay put whatever the seed.
Dungeon template
New Project > Dungeon creates the Third Person character and orbit camera in a recipe dungeon: cave branches with treasure, a loop, one-way shortcuts, rooms on three floors joined by stairs, a key and its locked door, and one handmade Reactor room, in the built-in sci-fi look with baked lighting. Its gameplay is C++ (recommended), Blueprint or Lua, and every flavor plays alike. It uses about 1.9 MiB of the console's 2 MiB of RAM.
Editor
- The Hub's template list scrolls.
- In 3D the Dungeon Room editor, the Volumes window and the minimap put +Z at the top, as the Scene view from above does.
--open-dungeon-recipe,--open-dungeon-style,--open-dungeon-room,--open-dungeon-seeds,--open-dungeon-volumes,--open-map,--dungeon-query-roomand--frame-dungeonopen dungeon views for screenshots.
Generated reference and parity coverage
- The API reference is re-extracted: 116 Epok headers with 2,016 callables, and 53 PsyQo headers with 944 (unchanged). The new headers are the dungeon random stream, the dungeon map and the minimap renderer; the collision header gains compound colliders. The extraction now reports no diagnostics: the ordered renderer, a fragment that only compiles inside the runtime's main file, is no longer parsed on its own, and the palette renderer is parsed with the empty texture table of the documented configuration.
- The gameplay parity inventory grows from 4,733 to 4,878 rows: 145 are added and none are removed, with no disposition changes on existing rows. 44 of the added rows are public gameplay API (the Dungeon library, its room and point records, and the minimap functions); the other 101 are internal.
Validation
- The Rust suite passes on macOS: 1,029 passed, 74 ignored. It covers layouts (reachability, spacing, loops, levels meeting across every open edge, handmade footprints, volumes), recipes (reproducible graphs, solvability with several keys, locks that cannot be walked around), the bake into real projects (cook, navigation, regeneration, stairs, merged handmade rooms, 2D), the queries' cook, the minimap's rectangles, the seed bench and the template in every flavor.
- The host runtime tests cover compound colliders, the dungeon random stream's golden values, the Dungeon library's queries and the minimap's exploring.
- The Dungeon template builds for the PlayStation in C++, Lua and Blueprint with at least 64 KB of RAM left free, and is played in PCSX-Redux: keys and doors in every flavor, climbing and descending stairs, the Reactor room, the queries from C++ and Lua, and the minimap filling in, in full screen and following the player, in 3D and 2D.
- The Windows serial tests run one at a time with longer deadlines, so they no longer fail on loaded runners.
- Emulator runs are evidence for their fixed setups and are not physical-console timing. The dungeon content has not been validated on physical PlayStation hardware.
Known boundaries
- Levels, handmade rooms and the Room here and Mirror volumes belong to 3D layouts or rooms-and-corridors layouts as documented: a 2D dungeon keeps one plane and draws handmade rooms as generated rooms of their shape.
- A dungeon must stay within 254 units across, and its generator may be moved but not rotated or scaled.
- Every quad of a map reserves render memory on the console, so a detailed handmade room costs RAM even where it replaces a generated room; the seed bench measures the band's budget, not RAM.
- Hairline cracks can show near the camera on dungeon floors and walls.
- Baked lights of a handmade room are copied as actors.
- The minimap reveals rooms on entering; there is no line-of-sight reveal, and exploration is kept per map load unless game code restores it.
Full comparison: v0.6.0...v0.7.0