Epok Engine v0.2.0

Epok v0.2.0 adds a complete Lua gameplay pipeline for the original PlayStation, expands skeletal animation with two target playback formats, and improves Blueprint inheritance, Actor authoring, mesh selection and lighting feedback throughout the editor.

Compatibility

Projects created with v0.1.1 remain on map version 6, Blueprint version 5, and reflection schema 9; this release does not require another project recreation or document migration. Continue to distribute the matching editor and epok-header-tool together.

Lua is introduced in this release under the versioned, statically checked epok-lua v1 profile. Lua classes use code declarations such as local Guard = epok.Actor3D:extend(); the experimental epok.class { ... } metadata-table syntax from development builds is deliberately rejected with a migration diagnostic. The editor stores stable Lua class identities in ProjectSettings/LuaClasses.epoksettings, so normal source renames do not orphan placed instances.

Projects select exactly one Lua execution mode. Native C++ lowers scripts ahead of time and links no interpreter. Lua VM — bytecode and Lua VM — source link the pinned psxlua/Lua 5.2-derived runtime and therefore require preservation of its MIT notice. Existing C++ and Blueprint classes continue to use the shared reflection and runtime contracts.

Lua gameplay scripting

• Author classes under assets/scripts/*.lua by extending any eligible reflected C++, Blueprint or Lua parent. Plain assignments declare Inspector properties, Lua Language Server annotations declare callable signatures, lifecycle methods override reflected events, and qualified .super calls invoke parent behavior explicitly.
• Publish Lua classes into the same reflected registry used by C++ and Blueprints. They participate in parent selection, defaults, attachment, spawning and Blueprint inheritance instead of living in a provider-specific object model.
• Choose Native C++, Lua VM — bytecode, or Lua VM — source in Project Settings > Scripting > Lua Execution. Play, Build and standalone export honor the saved project mode, invalidate stale artifacts when it changes, and never fall back silently after a compile or dependency failure.
• Compile all three modes from one typed intermediate representation and route engine operations through the same epok::bp API used by Blueprint nodes. This keeps fixed-point arithmetic, widening, short-circuit evaluation and runtime calls consistent across backends.
• Access spatial state directly through self.position, self.rotation and self.scale, or UI layout through self.rect_position and self.rect_size. Builtins cover input, scene changes, object checks/casts, spawning, ownership, audio, textures and component sequence/effect playback.
• Reflect Actor and ActorComponent operations directly, including activation, destruction, tick state, hierarchy/identity readers and component ownership. C++, Blueprint and Lua authors inherit the same members without handwritten bridge classes.
• Generate .epok/lua/epok.d.lua from the live registry and create .luarc.json when absent, giving external editors definitions for native, Blueprint and Lua inheritance, properties, callables, events, records, enums, transforms and builtins.

Lua target runtime and tooling

• Build host-side Lua bytecode with a 32-bit ABI dumper and verify its header byte-for-byte against the target runtime. Bytecode builds link a no-parser archive; source builds package normalized text and link the parser archive.
• Use fixed VM arenas rather than an unbounded target heap: 96 KiB for bytecode and 128 KiB for source by default. The measured source-mode peak is about 21 KiB, and projects can override the generated arena setting when needed.
• Keep 64-bit asset/class identities and playback handles outside the VM's 32-bit integer boundary through typed adapters.
• Fix VM/runtime edge cases uncovered by conformance work, including statement-bearing short-circuit operands, result evaluation before dispatch packing, typed-reference assignment widening, grow-in-place arena accounting and collection between chunk loads.
• Add feasibility, ABI, conformance, execution-mode and editor-tooling integration suites, plus documented sample classes for native inheritance, properties, spawning, movement and event handling.

Skeletal animation on PSX

• Add a per-model PSX animation choice during FBX import and reimport. Rigid bones (fastest) remains the default; Baked vertex frames trades executable/archive space for less runtime pose work without changing scene authoring or clip identities.
• Group rigid vertices into per-bone ranges and submit them directly through the GTE after conservative animation-envelope culling. Dynamically lit materials retain the compatible CPU path where posed normals are required.
• Compile baked clips as independent compressed 30 Hz vertex frames, using compact bind-pose deltas with bounded absolute-coordinate fallbacks and shared payloads. Visible characters decode into the existing 512-vertex scratch buffer.
• Store conservative bounds across the bind pose and every imported animation sample, so fully off-screen characters skip both bone evaluation and baked-frame decoding.
• Enforce the existing 512 KiB per-model target animation budget and extend the integration verifier to build and execute both formats in PCSX-Redux.

Blueprint and editor workflow

• Create lifecycle event overrides disconnected and visibly inherited by default. Wiring an event implements it; disconnecting restores parent behavior. Event context menus can add an explicitly named parent call at the intended point in the graph.
• Require descriptive reflected parameter names, inherit pin names from base declarations and preserve saved pin identities when SDK parameter labels improve.
• Filter Add Component and C++/Blueprint component creation by the selected Actor's domain and compatibility rules. Project C++ classes open at their real declaration, while engine classes remain read-only.
• Let the Mesh Filter switch an instance between the engine cube, editable project meshes and skeletal meshes without modifying shared assets or changing the Actor identity. OBJ import can bring external source dependencies into project-owned assets while enforcing source-folder boundaries.
• Keep the last valid baked lighting preview visible while editing, mark stale or missing caches with an amber warning, and expose Build Lighting in the top-level Build menu. Cached colors follow Actor identities rather than hierarchy order.
• Clarify viewport camera-wheel movement and streamline Inspector controls for Actor active/static state and names.

Validation

• Rust formatting and the default serialized Rust test suite are run by the required release-policy check for this pull request after building epok-header-tool.
• Development validation covered all three Lua modes with identical probes in PCSX-Redux, the host/target bytecode ABI, the Lua feasibility harness, Lua Language Server diagnostics, MIPS Lua builds and standalone export paths.
• Skeletal integration coverage imports the sample FBX, builds both Rigid GTE and Baked Vertices representations, executes both in PCSX-Redux and compares decoded baked positions with the editor pose.
• Lua and the new skeletal playback formats have not been validated on physical PlayStation hardware. GPU/emulator scenarios outside their dedicated integration suites and cross-platform distribution testing remain separate from the required Windows release check.

Full comparison: v0.1.1...v0.2.0