Welcome to Remake Engine Documentation

Remake Engine is a configuration-first orchestration engine for repeatable game rebuild workflows. The active runtime is EngineNet, a .NET 10 application that powers CLI, TUI, and GUI experiences from one core execution pipeline.

This book is focused on two audiences:

  • Module authors who define and maintain operations, placeholders, and tools.
  • Engine contributors who need a reliable map of runtime flow and interface behavior.

What You Can Do Here

  • Learn how to build and run the engine locally.
  • Author module manifests with TOML-first examples.
  • Understand how operations are loaded, resolved, and dispatched.
  • Pick the right interface for your workflow: CLI, TUI, or GUI.
  • Find schema references used for editor validation.

Read in This Order

  1. Start with Getting Started.
  2. Continue with Module Authoring.
  3. Use Architecture and Interfaces to understand behavior and execution paths.
  4. Use Reference for placeholders and schema links.

Source of Truth Policy

When behavior in this book and source code disagree, treat source files and schemas as canonical. In practice, that means keeping these areas in sync with runtime updates:

  • schemas/operations.schema.json and schemas/operations.toml.md
  • schemas/config.schema.json
  • schemas/game.schema.json
  • schemas/tools.schema.json and schemas/tools.toml.md

Remake Engine does not ship copyrighted game assets. You must provide your own legally obtained data.

Contributing

Documentation updates are part of feature delivery. See Documentation Contributions for workflow and style rules.

Prerequisites

Before working with Remake Engine, install the following:

  • .NET SDK 10.0
  • Git
  • PowerShell 7+ (recommended for Windows command examples)

Platform Notes

  • Primary supported runtime target is Windows x64.
  • Windows variants and Linux targets are active goals.
  • macOS support is best-effort where toolchains allow it.

Clone the Repository

git clone https://github.com/yggdrasil-au/RemakeEngine.git
cd RemakeEngine

Documentation Location

  • Main documentation book source lives in RemakeEngineDocs/src.
  • Runtime schemas live in schemas/ and remain a canonical source for module formats.

Build and Test

Use the solution-level commands from repository root to validate engine changes.

Build

dotnet build RemakeEngine.slnx

Test

dotnet test RemakeEngine.slnx --nologo

Optional Coverage Collection

dotnet test RemakeEngine.slnx --collect "XPlat Code Coverage"

Build Documentation Locally

From repository root:

mdbook build RemakeEngineDocs

If mdbook is not installed globally, you can use the bundled executable in RemakeEngineDocs.

Run the Engine

EngineNet supports three user experiences: GUI, TUI, and direct CLI execution.

Default Entry Point

dotnet run -c Release --framework net10.0 --project EngineNet

When no specific mode flags are provided, the engine chooses its default startup behavior.

Launch GUI

dotnet run -c Release --framework net10.0 --project EngineNet -- --gui

Launch TUI

dotnet run -c Release --framework net10.0 --project EngineNet -- --tui

Execute a Direct CLI Operation

dotnet run -c Release --framework net10.0 --project EngineNet -- --game_module "EngineApps/Games/demo" --script_type lua --script "{{Game_Root}}/scripts/lua_feature_demo.lua"

Use direct CLI execution for automation and ad-hoc script runs.

Module Layout

A module lives under EngineApps/Games/ModuleName and is usually composed of:

  • operations.toml for operation definitions
  • config.toml for module-specific placeholders
  • game.toml for launch metadata
  • Tools.toml for tool dependencies
  • scripts/ and operations/ for runtime scripts
  • TMP/ for temporary generated data

Minimal Module Skeleton

EngineApps/Games/MyModule/
  operations.toml
  config.toml
  game.toml
  Tools.toml
  scripts/
  operations/
  TMP/

Authoring Priorities

  1. Define stable operation IDs and names first.
  2. Keep prompts focused and explicit.
  3. Move machine-specific values into config.toml placeholders.
  4. Declare tools in Tools.toml instead of hardcoding binary paths.

Operations Manifest

operations.toml is the main workflow definition for a module. Operations are declared using TOML array-of-table syntax.

Basic Structure

[[operation]]
id = 10
Name = "Extract Assets"
script_type = "lua"
script = "{{Game_Root}}/operations/extract.lua"
args = ["--out", "{{Game_Root}}/Extracted"]
run-all = true
init = false
depends-on = [1]

Common Fields

  • id: unique integer per operation
  • Name: display text used in UI and TUI
  • script_type: runtime type such as lua, js, python, bms, or engine
  • script: path or operation token interpreted by script_type
  • args: argument list with placeholder support
  • run-all: include in run-all execution flow
  • init: run during initialization and hide from normal menu lists
  • depends-on: operation IDs that must succeed first
  • prompts: interactive prompt definitions
  • onsuccess: child operations executed only after success

Execution Notes

  • Placeholder values are resolved recursively before execution.
  • onsuccess operations are resolved at child execution time, using current context.
  • dependency graphs are validated by engine runtime before run-all execution.

Canonical Specification

Use schemas/operations.toml.md and schemas/operations.schema.json as the canonical format references when adding new fields.

Prompt Authoring

Prompts collect user input before an operation is executed. Prompts are defined under each operation.

Supported Prompt Types

  • confirm: yes or no value
  • text: single text value
  • checkbox: multi-select values

Confirm Example

[[operation.prompts]]
type = "confirm"
Name = "verbose"
message = "Enable verbose output?"
default = false
cli_arg = "--verbose"

When true, cli_arg is appended to command arguments.

Text Example

[[operation.prompts]]
type = "text"
Name = "source"
message = "Source directory path:"
Required = true
cli_arg_prefix = "--source"

The result is appended as two tokens: cli_arg_prefix and input value.

Checkbox Example

[[operation.prompts]]
type = "checkbox"
Name = "formats"
message = "Select export formats"
choices = ["glb", "fbx", "obj"]
default = ["glb"]
cli_prefix = "--export"

Each selected value is appended after cli_prefix.

Prompt Rules

  • Name values must be unique inside one operation.
  • condition values refer to another prompt Name.
  • Keep defaults type-consistent with prompt type.
  • Prefer clear user messages over short internal abbreviations.

Config Placeholders

config.toml provides module-specific placeholder values used during operation resolution.

Structure

The schema expects a placeholders array of maps.

[[placeholders]]
Region = "US"
SourcePath = "{{Project_Root}}/Data/Source"
UseLosslessAudio = true

Behavior

  • Each placeholders table contributes key-value pairs to runtime context.
  • Later tables override earlier key definitions.
  • Values can be string, boolean, integer, or number.
  • Put machine-independent defaults in config.toml.
  • Keep user-specific secrets and paths outside committed module files when possible.
  • Reference placeholder keys from operations.toml using {{KeyName}} syntax.

Canonical Reference

Use schemas/config.schema.json for field validation and editor IntelliSense.

Game Manifest

game.toml declares how a built module launches its runtime target.

Requirement

A game manifest must define exactly one launch target family:

  • exe or executable
  • lua, lua_script, or script
  • godot, godot_project, or project

Example: Executable

title = "My Remake"
exe = "{{Game_Root}}/bin/MyGame.exe"

Example: Lua Entry

title = "My Remake"
lua = "{{Game_Root}}/scripts/entry.lua"

Example: Godot Project

title = "My Remake"
godot = "{{Game_Root}}/project.godot"

Notes

  • Paths can include placeholders such as {{Game_Root}} and {{Project_Root}}.
  • Keep title user-facing and descriptive.
  • Validate manifest shape against schemas/game.schema.json.

Tools Manifest

Tools.toml declares module tool dependencies. The engine installs tools into shared project-level locations and reuses them across modules.

Minimal Example

title = "Module Tools"

[[tool]]
name = "QuickBMS"
version = "0.12.0"
unpack = true

[[tool]]
name = "ffmpeg"
version = "8.0"
unpack = true

Runtime Policy

  • Tool archives are cached under EngineApps/Tools/_archives.
  • Installed tools are placed under EngineApps/Tools.
  • Install folders are namespaced by tool, version, and platform.

Example folder naming:

  • QuickBMS-0.12.0-win-x64
  • Blender-4.5.4-win-arm64

Compatibility Notes

Legacy fields destination and unpack_destination are accepted for compatibility but ignored by current runtime placement logic.

Canonical Reference

Use schemas/tools.toml.md and schemas/tools.schema.json as the source of truth for supported fields.

Core Runtime

EngineNet.Core is the runtime layer behind all interfaces. It provides loading, context assembly, placeholder resolution, and operation execution.

Core Responsibilities

  • Track runtime state shared by CLI, TUI, and GUI.
  • Discover modules from registries and game directories.
  • Load operation manifests from operations.toml or operations.json.
  • Collect prompt answers and combine with defaults.
  • Build execution context from engine config, module metadata, and config.toml placeholders.
  • Resolve placeholders recursively in operation payloads.
  • Dispatch operations to built-in handlers and script engines.

Runtime Area Map

  • Engine/: operation execution entry points
  • Services/: operation loading, command execution, launcher, and registry services
  • Data/: runtime models
  • Utils/: execution context and placeholder resolvers
  • Serialization/: TOML, JSON, and YAML parsing helpers
  • ExternalTools/: tool acquisition and resolution support

Interface Boundary

Interfaces call into core through a narrowed contract exposed by Interface.Main. This protects UI layers from direct deep coupling to runtime internals.

Execution Flow

The operation pipeline is centered on manifest loading, context preparation, and dispatch.

High-Level Sequence

  1. Parse operations from operations.toml or operations.json.
  2. Normalize operation metadata and IDs.
  3. Collect user prompt answers from active interface.
  4. Build runtime execution context from engine and module data.
  5. Resolve placeholders recursively in script paths and arguments.
  6. Execute selected operation or run-all flow.
  7. Dispatch to built-in handlers or script runtimes.
  8. Execute onsuccess child operations when parent succeeds.

Run-All Behavior

Run-all mode includes operations marked with run-all or run_all and validates dependency order before dispatch.

Placeholder Timing

For onsuccess child operations, placeholders are evaluated at child execution time, not frozen at parent start.

Operational Impact

This flow lets module authors keep operations declarative while the runtime handles ordering, prompt input, and environment-specific value resolution.

Script Engines

The ScriptEngines layer maps operation script types to executable actions.

Runtime Families

  • Embedded runtimes execute inside the engine process, such as lua, js, and python.
  • External runtime wrappers launch tooling processes, such as bms workflows.

Dispatch Model

ScriptActionDispatcher selects an IAction implementation based on script_type. Each action provides a consistent execution contract so runtime orchestration remains uniform.

Lua API Definition Files

When new Lua globals are exposed by engine code, keep API definition files updated for editor tooling and documentation:

  • EngineApps/api_definitions/api_definitions.lua
  • EngineApps/api_definitions/api_definitions.d.ts
  • EngineApps/api_definitions/api_definitions.pyi

Also update the demo Lua feature script when introducing new Lua-facing behavior.

CLI

The CLI is designed for ad-hoc execution and automation. It can build an operation at runtime without requiring an existing operations.toml entry.

Typical Use Cases

  • CI automation
  • One-off maintenance scripts
  • Rapid testing of scripts before manifest integration

Example Direct Invocation

dotnet run -c Debug --project EngineNet --framework net10.0 -- --game_module "./EngineApps/Games/demo" --script_type lua --script "{{Game_Root}}/scripts/lua_feature_demo.lua" --args '["--module", "{{Game_Root}}"]'

Notes

  • The CLI can bypass menu-driven operation selection.
  • You can still list file-defined operations when needed.
  • Favor direct CLI for repeatable automation entrypoints.

TUI

The TUI is a menu-driven terminal interface that executes workflows defined in operation manifests.

Behavior

  1. Discover available modules.
  2. Load operations from module manifests.
  3. Present selectable operations.
  4. Collect prompt input interactively.
  5. Stream output as operations run.

Best For

  • Interactive development sessions
  • Quick validation of module operation design
  • Running workflows without GUI dependencies

Constraint

The TUI is file-driven. A script must exist in the operation manifest to be executed through this interface.

GUI

The GUI provides a visual, user-focused way to run module workflows and launch games.

Behavior

  • Loads operation manifests for selected modules.
  • Renders operation metadata as visual controls.
  • Presents prompt input through UI dialogs.
  • Supports run-all and game launch entrypoints.

Best For

  • End-user operation execution
  • Module workflows that benefit from visual prompt handling
  • Operator-friendly launch flows

Constraint

Like the TUI, the GUI is file-driven and depends on operation metadata defined by the module author.

Placeholders

Placeholders are string tokens in the form {{KeyName}} resolved by runtime context before operation execution.

Common Built-In Placeholders

  • {{Game_Root}}: absolute module root path
  • {{Project_Root}}: absolute repository root path

Module Placeholders

Module-specific placeholder keys come from config.toml placeholders tables.

Resolution Scope

Placeholder expansion applies to operation script paths, arguments, and nested operation payload values.

Resolution Timing

  • Parent operation values are resolved before parent execution.
  • onsuccess child operations resolve using latest runtime context at child execution time.

Good Practices

  • Use descriptive placeholder names.
  • Keep placeholders stable across operation revisions.
  • Avoid hardcoding machine-specific absolute paths in operation files.

Schemas

Use schemas for editor validation, completion, and consistent module authoring.

Core Schema Files

  • schemas/operations.schema.json: operation format validation
  • schemas/config.schema.json: module placeholder structure
  • schemas/game.schema.json: launch target manifest structure
  • schemas/tools.schema.json: tool dependency manifest validation

Companion Markdown Specifications

  • schemas/operations.toml.md: operations authoring guide and prompt behavior
  • schemas/tools.toml.md: tools manifest behavior and runtime policy

Sync Policy

When runtime parsing behavior changes in engine code, update matching schema and documentation files in the same change set.

This policy keeps IDE validation accurate and avoids drift between module author documentation and runtime behavior.

Contributing to Remake Engine Docs

The documentation lives in RemakeEngineDocs/ and is published via mdBook. Contributions that align the docs with EngineNet or improve module author guidance are welcome.

Workflow

  1. Follow the main project guidelines in CONTRIBUTING.md.
  2. Edit the Markdown sources inside RemakeEngineDocs/src/.
  3. Update SUMMARY.md if you add, remove, or rename pages.
  4. Build locally with mdbook build RemakeEngineDocs (optional) to preview changes.
  5. Submit a pull request referencing the documentation updates alongside any code/spec changes.

Style

  • Use concise headings and plain ASCII text.
  • Prefer TOML examples for new manifests; include JSON equivalents only when necessary.
  • Link to specs or source files when describing engine behaviour.
  • Keep the tone instructional and module-focused.

Thank you for keeping the docs accurate!