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.
- 01Identify the file type
- 02Edit it with its owning tool
- 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/.