Independent game projects
START WITH THE BIG PICTURE
What does this part of Epok do?
A project is your game folder, not a secret database inside the editor. You can back it up, move it and build it without mixing it with another game.
- 01Pick or create a folder
- 02Open its .epokproject descriptor
- 03Edit, build and export inside that root
What is happening under the hood?
- Canonical paths and a lock prevent two editors from writing the same project.
- The descriptor records startup, Play and transition choices in YAML.
- Legacy manifests migrate explicitly and keep recovery data.
Field note: Keep source projects in version control; keep generated `.epok/`, exports and user layout data out of commits.
Epok starts in Projects. Create a project with a template, a gameplay flavor, a name and a parent folder, or open an existing project folder. Recent projects are shortcuts to their folders; Remove from list forgets a shortcut without deleting the game. Basic contains a camera, an empty world and an inert GameRoot class in the chosen language; Sample is a ground plane, two cubes and one Spinner behaviour. The default location is Documents/Epok Projects, outside the editor installation.
Use File > Projects... (New / Open / Close) to return to the selector. Unsaved scenes offer Save and close, Discard changes and Cancel. Closing a project stops its owned build/emulator before releasing its lock. A failed open stays in the selector and displays the error; it never substitutes a sample scene or overwrites a damaged project.
The dark Hub opens on a searchable project list. Search matches names and paths; the sort button switches between recently opened and alphabetical order. Each row shows its folder, PlayStation target and compatible editor version. Click a row to open it, or use its ... menu to open or remove the shortcut. Unavailable projects remain visible so their errors can be inspected. New project opens the template browser and Dependencies opens the tool paths, one tab per target platform; both are panes of the same window, not dialogs over it. Open project accepts a folder path or the native folder browser. The Hub has its own typography and palette, preserved when returning from the editor.
New project
The New Project view is a template browser, not a wizard. Cards on the left carry a thumbnail, a title and a one-line summary, and the whole card selects; the panel on the right shows a large 16:9 preview of the selected template, a paragraph about it and what it includes. A preview that cannot be decoded falls back to a plain tile and never stops the editor from starting.
Project defaults below the preview holds the two decisions a new project makes, as two lists:
- Gameplay — C++, Blueprint or Lua. It chooses which starter implementation the template writes, and nothing else.
- Target — PlayStation, the only target Epok builds today.
Project location and project name stay at the bottom with the resolved destination folder. Create project is unavailable while the name or the location is unusable and the reason is shown next to them; Enter in the name field creates when the fields are valid. Cancel returns to the project list with the selections untouched.
Gameplay flavors
The flavor is a generation choice. A Lua project can gain C++ classes and Blueprints afterwards, a C++ project can gain Lua scripts, and a scene can bind all three at once. All six templates record their installation choice and semantic class references in ProjectSettings/Template.epoksettings; the descriptor continues to own project settings. See starter classes and roles for generated files and inheritance.
| Flavor | What the template writes | Console build |
|---|---|---|
| C++ | Project-owned sources under assets/scripts |
Compiled with the rest of the project |
| Blueprint | A project-owned graph under assets/Blueprints |
The backend generates native code; the source you edit stays visual |
| Lua | Project-owned .lua under assets/scripts |
Built with the project's Lua execution setting, which starts on the ahead-of-time native mode |
All six templates accept every authoring flavor and share the same actors, transforms, colliders and resources. Basic writes an editable, inert GameRoot Actor class. Dungeon Complete writes game policies and ordinary editable HUD/modal widget classes in the selected language, alongside shared native mechanisms and its Pocket Lua game. Lua template rules use Native C++ AOT: edit the Lua source; generated C++ belongs to build output. The required template acceptance matrix has 18 combinations. The engine retains separate VM bytecode/source functionality and regression coverage.
Dungeon Complete

Dungeon Complete is the finished Reactor Station action game: pooled enemies, a boss, camera-relative controls, inventory, healing items, upgrades, persistent trading and the Asteroid Catcher PocketStation minigame. It includes only the level's referenced assets, selected authoring sources and shared native mechanisms, with editable import sources and asset notices. Its SoundFont keeps the three MIDI presets used by the song, preserving their samples and settings.
New projects start in the embedded PSX emulator with PC-on-demand geometry, 320x240 output and the game's bounded render pools. No serial adapter settings, memory cards, captures, build outputs or personal editor layout are copied. The separate Dungeon starter remains available.
Opening a project shows a centered, borderless 640 × 400 splash with abstract retro artwork, the original Epok logo, the project name and live loading stage. Its activity bar does not invent a percentage. Once loading finishes, the window restores the Hub/editor size, position and maximized state. A failed open restores the Hub and displays the error. Startup does not add an artificial splash delay. The artwork is embedded, so it works outside the installation's working directory.
Ownership and format
Third Person adds an optimized editable arena, static blue cubes and an animated player with camera-relative movement, jumping, collision and an orbit camera. It intentionally excludes combat, NPCs and audio. See Third Person template for controls, hierarchy and rendering details. The command-line template name is third-person.
My Game/
My Game.epokproject # Versioned project identity and settings
assets/scenes/Main.epokmap # Original scenes
assets/scripts/ # Project-owned C++ and Lua classes
assets/Blueprints/ # Editable Blueprint classes
ProjectSettings/Template.epoksettings # Template installation and class roles
assets/Audio/*.epokasset # Imported assets with UUIDs and source snapshots
.gitignore
.epok/ # Regenerable build/emulator data; ignored
UserSettings/ # Local editor layout; ignored
exports/ # Standalone C++ exports; ignored
The root-level .epokproject descriptor contains format_version, editor_version, name, startup_scene, auto_build and rendering. It is the single writable owner of these settings; it is not an archive and does not contain assets. Open Edit > Project Settings to edit it. Rendering defaults to 640 x 480 interlaced NTSC when omitted. The startup scene is a relative path within assets/scenes; there is no fixed SampleScene path. Format/version mismatches are rejected. Existing ProjectSettings/project.json projects remain readable and migrate only through --migrate-project <folder>; reading never rewrites them. Projects with both active formats, or multiple root descriptors, are rejected until recovered.
Track the root .epokproject descriptor, assets/, ProjectSettings/ and .gitignore in the game's own repository. Moving or copying this content preserves the game; .epok/ can be removed while closed and regenerated on the next build. Preserve .epok/migrations/ backups separately before deleting that cache if needed for recovery. Creation requires a new destination and never merges with existing files, and it is transactional: a creation that fails part way removes the folder it claimed, so a half-written project is never offered as a real one.
The editor executable embeds its runtime source snapshot, templates, fonts and emulator adapter. Only generated C++ builds and exports receive runtime copies. Projects do not need editor Rust sources, runtime/, resources/, third_party/ or .tools/.
Tool configuration belongs to the editor installation: Editor.epokconfig, optionally replaced by Local.epokconfig. Installation discovery uses EPOK_EDITOR_HOME, then executable ancestors with Editor.epokconfig, then the development checkout recorded at compilation. It does not use the working directory. Relative tool paths resolve against that installation. An optional, untracked project Local.epokconfig replaces the machine configuration and resolves its paths against the project. A legacy Auto compile preference does not schedule automatic game builds; Build and Play validate or compile explicitly.
The Hub stores recent folders in %LOCALAPPDATA%/Epok/RecentProjects.epokprefs, separate from both the editor repository and shared game files. Layout belongs to UserSettings/editor-layout-v2.ini. An OS-backed .epok/project.lock prevents simultaneous editing/building through Epok; a crash releases the lock automatically, so a leftover file is harmless.
Command line
cargo run --locked
cargo run --locked -- --create-project "D:/Games/My Game" --template basic
cargo run --locked -- --create-project "D:/Games/My Demo" --template sample --name "My Demo"
cargo run --locked -- --create-project "D:/Games/My Hero" --template third-person --gameplay lua
cargo run --locked -- --create-project "D:/Games/My Complete Game" --template dungeon-complete
cargo run --locked -- --project "D:/Games/My Game"
cargo run --locked -- --project "D:/Games/My Game/My Game.epokproject"
cargo run --locked -- --project "D:/Games/My Game" --build-psx
cargo run --locked -- --project examples/sample-game --play-psx --stop-after 10
--gameplay takes cpp, blueprint or lua and defaults to cpp, so an existing command line keeps generating exactly what it did before. There is no target option while PlayStation is the only target.
Creation is a headless operation; open the resulting folder to edit. Build, Play, lighting bake and profiling require --project. Running from an arbitrary working directory works with the executable's absolute path. Game paths with spaces are tested; the upstream SDK/tool installation still needs a path without spaces.
The old repository-root sample lives in examples/sample-game/. It is an ordinary project and also supplies the embedded Sample game template. Rebuild the editor after changing embedded runtime/template sources.
Runtime and asset contract
Epok ships one matched PsyQo runtime; editor_version pins that contract. Dependency resolution, package installation and multi-editor upgrades remain future work.
Maps use one Actor collection in scene document version 6. Previous Entity/Behaviour maps and older Blueprint formats are rejected without being silently converted. Create a current project and recreate the content; see Recreating a project for the Actor architecture. The current project may propose a Default Scene Blueprint Parent for maps without a scene Blueprint.
Imported AudioClips use UUID references and portable .epokasset packages with embedded source snapshots. Their index and conversions are disposable; moves are reconciled on opening and while running. See Assets and audio. Native script bindings use class/member identities; see C++ scripting for the current Actor workflow.
Migration and recovery
The following descriptor migration only concerns a compatible legacy project manifest; it does not convert old Entity/Behaviour maps or Blueprint formats. Opening never rewrites a legacy manifest. Close the project, then run epok-editor --migrate-project <folder>. Migration validates settings/startup scene, takes the canonical-root lock, publishes the descriptor exclusively, and preserves legacy bytes in a uniquely named .epok/migrations/*.backup file.
If interrupted, both formats may remain active. Choose deliberately: epok-editor --recover-project <folder> --prefer legacy or --prefer descriptor. The selected format must validate; the other is preserved as a backup. Multiple descriptors are never arbitrarily selected: move unwanted descriptors outside the root before opening. No automatic merge is performed.
The Hub's Open project accepts a path and offers separate File... and Folder... browsers. Folder, --project <descriptor>, and positional epok-editor "My Game.epokproject" launches use the same root, settings, lock, and recent entry.
Optional Windows file association
After installing both host executables and the dependency distribution, run tools/register-project.ps1 -EditorPath "C:/Epok/epok-editor.exe" to register the quoted open command and application icon for the current user. tools/setup.ps1 -RegisterProjectFiles -EditorPath <exe> provides the same optional setup step. Existing non-Epok defaults are respected; choose Epok in Windows Default Apps if necessary.
Use the same command with -Unregister before removing that installation. It removes only registrations owned by that executable and leaves other applications' associations intact. -WhatIf previews registration/removal. Portable builds need no registration and never register themselves on launch. Double-clicking the descriptor opens the folder-based project, not a scene or archive.