Epok Engine
Documentation/Start here

Epok document formats

START WITH THE BIG PICTURE

What does this part of Epok do?

Epok projects contain authored documents, generated output and local preferences with distinct ownership.

  1. 01Identify the file type
  2. 02Edit it with its owning tool
  3. 03Rebuild derived data when required

What is happening under the hood?

  • Maps, project settings and source assets have different formats and owners.
  • The current Actor architecture rejects older Entity/Behaviour maps instead of silently converting them.
  • Generated build data and local preferences should not be mistaken for authored assets.

Field note: Keep older projects intact when recreating their content in the current format.

Epok uses type-specific extensions and YAML for editor-owned text documents. The PSX runtime consumes generated C++ and binary data; it does not parse YAML.

Document Extension / location
Project identity and settings Game.epokproject at the project root
Scene / map assets/scenes/Main.epokmap
Visual Blueprint assets/scripts/Enemy.epokbp
C++ gameplay source Annotated .hpp and .cpp files under assets/scripts/
Resource package Stone.epokasset (binary)
Additional map registry ProjectSettings/Maps.epoksettings
Lua class identity registry ProjectSettings/LuaClasses.epoksettings
Editor tool configuration Editor.epokconfig
Machine/project tool override Local.epokconfig
User preferences Editor.epokprefs, RecentProjects.epokprefs
Local project state UserSettings/SceneView.epokprefs, ImportState.epokprefs, Breakpoints.epokprefs
Reflection/import caches .epok/reflection/Reflection.epokcache, .epok/imported/<hash>/Import.epokcache
Extractor request .epok/reflection/Reflection.epokrequest
Exported script manifest Scripts.epokmanifest
Generated Blueprint debug map blueprints/<id>.epokdebug

For example:

format_version: 1
editor_version: 0.10.0
name: My Game
startup_scene: assets/scenes/Main.epokmap
auto_build: true

The document layer retains the existing versioned data schemas, UUIDs, numeric types, validation, and plain mappings/sequences. Writers produce deterministic YAML with stable field ordering and no language-specific enum tags. Unknown Blueprint fields are retained. Comments and hand-chosen formatting are not preserved when the editor saves a document. Duplicate keys and multiple YAML documents in one file are rejected. JSON syntax remains accepted as a subset for legacy fixtures, but ordinary Epok saves write YAML.

.epokasset packages use the eight-byte EPOKAS01 signature, followed by the existing metadata/source lengths and binary payload. Their embedded metadata remains JSON; the package is not a text document.

JSON remains intentional for MCP and extractor stdout, VS Code configuration, Clang's compile_commands.json, PCSX-Redux configuration, the dependency bootstrap manifest tools/dependencies.json, and explicitly JSON diagnostic reports. These do not acquire Epok extensions merely because they are in this checkout.

Scripts.epokmanifest v2 is generated provenance. files and native_sources are relative to the manifest directory (file_base: manifest); dependencies are relative to the authoring project (dependency_base: project). All use forward slashes. Dependencies describe the original inputs; standalone builds use the staged files and do not require those authoring paths. Regenerating a build/export replaces generated v1 host-path manifests with v2 without changing source files. Provider dependencies outside the project are rejected before writing artifacts.

Document versions

Current maps use scene document version 6 with one actors collection. Blueprint assets use version 5 and the generated reflection cache uses schema 9. Previous Entity/Behaviour maps, older Blueprint formats and .epokscript sidecars are rejected with a diagnostic; opening them does not rewrite or convert their files. See Recreating a project for the Actor architecture and Actors and components.

Dungeon generators

A map may carry a dungeons list, omitted when empty. Each entry holds the editor-only settings of one Dungeon Generator: its id, the root actor that places it, the seed, the layout source (Rooms or Recipe), the rooms layout settings, the 3D sizes and whether it has a ceiling, the optional spawn_actor, tile_set, style and recipe, and output — the actors and assets the last generation wrote, with a fingerprint of the settings and digests of the style and recipe that produced them. The cook reads only the generated actors and assets. A Collider3DComponent may hold a boxes list (minimum and maximum corners in the actor's local space) for a compound collider. A Dungeon Style is an authored .epokasset of kind DungeonStyle whose payload is a JSON document: a version, whether it is two_d, and its nodes (spots, and pieces naming their spot as parent). A Dungeon Recipe is an authored .epokasset of kind DungeonRecipe whose JSON payload is a version and an ordered steps list, each tagged by step (Lattice, MainPath, Branch, Items, KeyLock, OneWay, Caves, Rooms) with its settings; ranges are [smallest, largest] pairs and paths are named (main is the main path). See Dungeon Generator.

Blueprint assets

Current Blueprint assets use version 5 and participate in the reflected Actor class model. See Blueprints for authoring, inheritance and compatibility.

Migrating an existing game

There is no automatic migration of older Entity/Behaviour maps or Blueprint formats. Preserve the original project, create a current project and recreate its maps and gameplay. Descriptor-only migration does not convert game content. See Recreating a project for the Actor architecture.

Working copy

This refactor started from upstream main commit 811fcb4 (Replace Blueprint promo screenshot with cursor-free native capture). Epok is presented as an engine for the original PlayStation. The source repository is https://github.com/epokengine/epok-engine. The website is https://epokengine.github.io/.

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