Frame Engine

A simulation engine written in Rust, with a companion 3D editor.

Frame Engine advances a world state forward in fixed, deterministic time steps. It is a simulation engine, not a renderer. The simulation runs headless with no window required, and rendering is a separate, swappable layer on top. That separation lets the engine run on servers and be reused across different games and tools.

Forking and contributing

Frame Engine is built in the open and meant to be learned from. If it looks useful, fork it, clone it, and bend it to whatever you are making. The Mozilla Public License 2.0 means you can use it freely, for any purpose, including in closed commercial games, with no permission asked. The one thing it asks is that if you change the engine's own files and share the result, you share those changes under the same licence.

A few things worth knowing before you dig in:

• It is hand-rolled on purpose. The engine's world, systems, and clock are written by hand rather than pulled from an ECS crate, so the code is meant to be read and understood top to bottom rather than treated as a black box. Reading DESIGN.md first is the fastest way in: it explains not just what each piece does but why it is shaped that way.
• The engine stays graphics-free. crates/frame-engine depends on serde and ron for scenes and rapier3d for physics, and on nothing else. All windowing, GPU, and UI code lives in crates/frame-editor. If you extend the engine, keeping that line clean is the one constraint worth respecting, because it is what lets the simulation run headless on a server.
• Dependencies point one way. The editor depends on the engine, never the reverse. The engine knows nothing about the editor or any application built on it.
• main is the working branch. It is where features land and can be unstable. Fork from main if you want to hack on the latest; depend on a tagged release if you want something steady (see below).

If you build something the engine is missing, a system, a component, a piece of the editor, and you think it fits, get in touch. Open an issue to talk it through, or a pull request if you have already built it. Nothing is guaranteed to land, but good work that fits the project's direction is genuinely welcome, and if it suits the engine it may well make it into the main public build.

Built something with it, or forked it into your own thing? Tag me on X at @OuterFrameInter, I would love to see it, and that is also the easiest way to reach me if GitHub is not your preferred route.

There is also a Discord server for bug reports, showing off what you have built, and following development: https://discord.gg/ufXDNJnzgf

Frame Engine is a learning project as much as a tool: I am still growing my own Rust as I build the engine and editor in the open, which is part of why the code is written to be read rather than to show off. Considered feedback, on the engine, the editor, or the overall approach, is always welcome.

Releases and stability

main is the working branch, where in-progress features land. It is under constant change and can be incomplete or unstable at any moment.

For a stable build, download a tagged release rather than cloning main. Releases are cut at points where the project is known to build and run, so a release is your dependable copy. Tagged releases are on the project's Releases page.

This repo restarted fresh with no tagged releases yet (see SECURITY.md for why). Cargo.toml currently sits at 0.0.0, a placeholder for this pre-release baseline. The first tagged release will be 0.1.0, planned for Friday 30 October 2026 at 10pm UK time. It will be a source release (a tag, release notes and build instructions), so you build it yourself with Cargo. The capabilities listed below reflect current main.

Releases come at most once a week. A crash, data loss or security bug gets a patch release (0.1.1 and so on) as soon as it is fixed, without waiting. What has been tested, the known bugs and how to report a security issue are in SECURITY.md.

Status

Early development, past the toy stage, with a working engine and a usable editor shell.

Engine

• A deterministic fixed-timestep clock (in core/) with spiral-of-death protection, used by both the engine binary and the editor.
• A hand-rolled ECS world with a growing set of component types (position, velocity, colour, a per-axis scale, a full yaw/pitch/roll rotation, an emissive material strength, health, a Mesh (a primitive, an imported model, or none), plus opt-in Light, Sound, Camera, Parent, UiText, UiImage and RigidBody components and the Controlled, Static and Gravity markers) and runtime spawn and despawn, both reachable from a script as well as the editor. Spawn reuses freed slots, so entity ids stay stable and despawned slots are reclaimed.
• A Light component (Directional, a fixed no-falloff direction like a sun, or Point, at the entity's own position with a linear falloff to a set range, plus an intensity multiplier and a colour) and a Sound component (a file name and a one-shot play request flag, the same request-and-clear pattern spawn/despawn already use from scripts). Both are just data the engine carries and serializes; drawing a light and actually playing a sound are the editor's job.
• Runtime component registration: World can hold component types it wasn't compiled knowing about, through a generic, string-keyed insert_dynamic/get_dynamic API. f64 values survive a save and reload; a value of any other type still resets on reload. Scripts can reach these too, through custom_<name> variables.
• A Substance schema (melting point, durability, conductivity, and more) and a name-keyed registry for it on World, the shape for a wood, a stone, or a metal, with Substance::blend mixing two into a new one, freeform, any ratio, no fixed recipes. No actual substances are defined; that stays game content.
• A generic ComponentStorage<T> type, wired into the world. It implements Default, and World derives Default, so a fresh world is built in one place and adding a component type is cheap and uniform. A small query API (query, join, with, without) lets systems ask for "every entity with these components" without index loops.
• A movement system that advances entities each tick, and an input system that drives Controlled entities from held WASD keys.
• Per-entity colour and scale, stored as component data and serialized with the scene.
• A per-entity Mesh primitive (cube, sphere, or plane), stored as component data and serialized with the scene; defaults to cube, so older scenes load unchanged. Mesh::Empty is an entity with no shape, for something that is only a point in the world (a spawn marker, a sound source, a holder for settings): it is not drawn, has no collision box and gets no physics body.
• A hand rolled OBJ importer: an assets module parses Wavefront OBJ text (Blender's export works with default settings), reads texture coordinates, normalises models to unit size, and reports their half extents so collision fits their real shape. Imported models are a Mesh::Custom(name) on an entity.
• AABB collision, detection and response: a collision system records which entity boxes overlap each run, along with the contact point where they overlap (feeding the hit/hit_id/hit_point script variables and the editor's red tint), and a resolve_collisions system pushes overlapping entities apart along their least-overlapping axis after movement. A Static marker keeps an entity immovable, so others rest against it. Boxes are axis-aligned scale-boxes derived from a shared ENTITY_SIZE (1 m: a world unit is a metre), the world-space size the editor also renders and picks against. A box is expanded conservatively to bound an entity's rotation, yaw, pitch and roll (not true oriented-box precision), and entities that opt into physics skip this hand-rolled path.
• Rigid-body physics through rapier3d, the one dependency the engine crate takes beyond serde and ron, bought rather than hand-rolled: a RigidBody marker opts an entity in, with Static giving a fixed body and Gravity a dynamic one. A Controlled plus RigidBody entity is a physics character, swept through the world by a kinematic character controller: it stops at walls, slides along them, falls, lands, jumps on Space when standing on something, and turns to face the way it moves. Give it a CharacterBody and it becomes a person-sized capsule built from that body's numbers (height, radius, eye height, walk, run and crouch speeds, jump height, step height, steepest slope, mass, air control): it walks where it looks, runs and crouches, steps up small ledges, keeps its speed through a jump and stays crouched under a low ceiling. A Look holds where it is looking, and a Camera on it, or attached to it, sees from its eyes. The body is plain data, so a game can grow or change it over a character's life. Physics state is runtime-only; the scene saves only which entities opt in.
• Parenting, cameras, prefabs and UI: Parent attaches one entity to another with a local offset that turns with the parent, Camera marks the entity Play looks through, and a prefab captures an entity and its whole parented subtree as an unlinked, stamp-and-forget template saved as its own RON file. UiText and UiImage are screen-space UI components (normalised position, display-only for now).
• Per-entity scripting: an entity can carry a Script that names a shared library script (source held once on the world, in a name-to-source map), with a ScriptRuntime trait and a run_scripts system forming the seam. The engine stores script source as data and runs nothing itself; the interpreter lives in the editor, the same way rendering does.
• A graphics-free input abstraction (which buttons are held), fed by the editor and read by systems, so input can drive the simulation without the engine knowing about windowing.
• Scene serialization to and from a human-readable RON file (serde and RON), with backward compatibility for scenes saved before newer fields like colour and scale existed.
• Version checks: scenes and prefabs carry a save format number and projects record the editor version that last saved them, so an older editor warns about, and won't save over, something from a newer one. Multiplayer clients and servers check versions on connect, and plugins can name the engine version they need.
• A read-only ASCII debug renderer that draws the world as a grid.
• A library and binary split, so the engine is importable by other crates.
• A first slice of multiplayer, in net/: an authoritative Server that accepts clients, applies their uploaded input, and broadcasts every entity's position, and a receiving Client that applies whatever arrives and uploads its own held input back, learning which entity is its own from a one-time Welcome message. Positions and input only, no interest management, and a disconnected client's entity is despawned but can't yet reconnect to it, all deliberately left for later. This replaces an earlier lockstep plan, a better fit for a small closed session than a persistent, always-joinable world; see DESIGN.md for why. Runnable now through the engine binary's own server/client modes.

frame-editor (companion editor; links to the engine, runs the sim in a window)

• Opens a native window (winit) and renders the world on the GPU through wgpu.
• Draws entities as instanced, shaded primitives (cube, sphere, or plane) in real 3D, each in its own colour, size, optional glow (an emissive material strength), and full yaw, pitch and roll rotation, with a perspective camera and a depth buffer for correct occlusion. Overlapping entities are tinted red, a live view of the engine's collision detection.
• Multi-light shading: up to four active Light entities are summed per fragment (not per vertex, so falloff reads correctly across a face) on top of a flat ambient base. A Light beyond the cap is simply not drawn, a real, named limit rather than an unbounded cost. Lights are edited from the Inspector: pick Directional or Point, set direction or range, and set intensity and, for a point light, colour. With more lights than the cap, directional lights win, then the point lights nearest the camera. The first directional light also casts shadows: a 2048 shadow map follows the part of the world in front of the camera (out to a Shadow distance you set), with soft (filtered) edges that don't shimmer as the camera moves. Shadows and the distance are in Edit > Editor settings…. Point lights do not cast shadows yet.
• Sound playback through kira: a Sound section in the Inspector picks a file from a dropdown of the project's audio (found by name anywhere under assets/, so it can be moved between folders) and a "Play now" button fires it for a quick manual test. Each tick, any entity with a pending Sound.play request gets it turned into a real play call, the file decoded once into a small cache and reused (cheaply cloned, not re-read) on every later play. No audio device or no project open both just mean the request is quietly dropped.
• An orbit, pan, and zoom camera (middle-drag orbit, Shift+middle-drag pan, scroll zoom). Left-click only ever selects.
• Textured models: a model's Material panel in the Assets tab picks a base-colour PNG and roughness and metalness sliders, shared by every entity that uses that model. Roughness and metalness are an honest approximation, not a physically based specular highlight.
• Click-to-pick selection: click an entity to select it. The selected entity is brightened rather than recoloured, so its own colour stays visible while you edit it.
• Live entity editing: nudge the selection with the arrow keys and Page Up/Down, spawn with N, despawn with Delete, and drive a Controlled entity with WASD while the sim is playing.
• A project launcher: the editor opens on a launcher to create a named project, open one by folder, or reopen a recent one from a list of cards (name, description, last-edited date, version, and Edit / Play / Settings actions). A project is a folder holding project.ron (name, start scene, description, version), its scenes in scenes/, its scripts as .rhai files in scripts/, and what every scene shares (materials, plugin settings, globals) in project-data.ron; Settings edits the manifest. A project from before scenes (one scene file at the top) is converted the first time it opens, with a .backup copy of the old file kept beside it.
• Scenes: a project holds any number of scenes. The Scenes tab in the console lists them, marks the open one and the start scene, and creates, opens, duplicates, renames and deletes them (two steps to delete; the open scene and the last scene can't be). Play scene in the menu bar plays the scene that is open, as it is now; the launcher's Play and a game build start on the start scene. A script changes scene with load_scene("name"), and keeps numbers across the change with set_global and get_global. Script files edited outside the editor (another text editor, or git) are picked up when the editor window gets focus back.
• Scene save and load: opening a project loads its scene, Ctrl+S (or F5) saves it and F9 reloads it, and the File menu also opens or saves a scene to any path through a native file dialog.
• Unsaved-changes protection: the window title shows a * while the scene has edits that aren't saved, and quitting, closing the window, closing the project, reloading, or opening another scene asks first (Save, Don't save, or Cancel). Only authoring edits count; the running simulation moving things does not.
• Editor preferences, remembered across runs in editor.ron: the flythrough speed (scrolling while you fly changes it too), mouse look and orbit sensitivity, inverted look on either axis, how long to hold a Scene row before it drags, and whether the controls overlay shows. Edit them under Edit > Editor settings…, which also holds the plugin switches and a Credits section.
• A Script Editor: a dockable tab where the shared script library is written, a sidebar of script names beside a single code editor with a line-number gutter and live checks: a status line flags parse errors (line and column) in red, and unknown variables (names that aren't part of the script API or a local let) in amber, catching the typos Rhai would otherwise fail on silently at run time. Scripts can be renamed as well as deleted; renaming rewrites every entity's reference to the old name, so it doesn't orphan anything. Scripts see structured values (pos.x, vel, color.r, with vector arithmetic) alongside the older flat names, plus their own id, whether they carry the Controlled/Static/Gravity marker, which movement keys are held, and, on collision, which entity was hit and where. Scripts can also request a new entity be spawned or an existing one despawned, and read or write runtime-registered dynamic component values through custom_<name> variables. All of it runs live through a Rhai backend and is assigned to entities from the Inspector. See SCRIPTING.md for how to write them.
• A translate gizmo: selecting an entity draws three axis arms in the viewport (X red, Y green, Z blue); drag an arm to move the entity along that axis, at any camera angle, as a single undo step.
• A Prefabs tab: lists the project's prefabs/ folder with a Spawn button for each, dropping a fresh instance at the camera focus. The Inspector's Save as Prefab field writes a new one from the selected entity and its parented children.
• A Source Control tab: a read-only view of the open project's git state, branch, upstream with ahead/behind counts, and changed files (amber unstaged, green staged). No network, no credentials; commits and pushes stay in your terminal or git client.
• A plugin loader with enable/disable support: a project's plugins/ folder (created automatically if missing) is scanned the same way its assets are, and each enabled plugin's Rhai scripts merge into the project's own script library under a name-spaced prefix, so they show up in the ordinary Inspector script picker like any hand-written script. Edit > Editor settings… lists every installed plugin with a checkbox, off by default for anything newly found; a Plugins tab next to Help shows what's currently switched on, along with a button for each action a plugin declares. Compiled Rust plugins are deliberately not supported (Rust has no stable ABI, making that genuinely fragile); Rhai keeps every plugin inside the same sandboxed interpreter every other script already runs in. A plugin can also declare custom Inspector fields (a slider or drag box tied to one of its own dynamic values), menu actions (running one of its scripts once, or toggling a value), and panels (a titled, global section in the Plugins panel, not tied to any entity), all purely declarative: a plugin describes what it wants, the editor is the only thing that ever draws or runs anything. See PLUGINS.md if you want to build one.
• Model import and an Assets tab: File > Import model brings a Blender OBJ export into the project, renders it, lists it in the mesh picker, and fits collision to it. The Assets tab in the bottom console shows the project's assets as tiles with rendered previews, with folders and a move flow to organise them. File > Import audio brings in WAV, OGG, MP3 or FLAC files, checking each one decodes first, into whichever assets folder is open. Dropping model or audio files on the editor window imports them too (Windows, macOS and X11; not yet on Wayland).
• A dockable panel layout built with egui and egui_dock. The Viewport, Scene, Inspector, and Script Editor are tabs you can drag, tab together, and split apart; the Viewport is a transparent tab so the 3D shows through. Scene, Inspector, Script Editor and Source Control can also be popped out into their own windows (right-click the tab). Alongside them:
  • a top toolbar showing the editor's logo and working File/Edit/View/Help menus, each item mirroring a keyboard shortcut (open/save/reload scene, close project, quit; spawn, despawn, clear selection; play/pause, step, controls overlay),
  • a Scene tab (entities as a parent/child tree, click to select, drag one onto another to reparent) and an Inspector tab (edit the selected entity's transform, colour, emissive strength and mesh, toggle its Controlled, Static, Gravity and physics markers, add or edit its light, sound, camera, parent and screen-space UI components, preview a camera's view live, save it as a prefab, and assign a library script through a searchable picker, all written straight back into the world),
  • a fixed bottom console dock with an Output tab showing a live log and a Terminal placeholder.
• A custom editor theme, Outerface V1: neutral dark panels with a restrained green accent and a wood-brown secondary accent, and a thin wood-to-green strip across the top of the window. It is set in one apply_editor_theme function, applied to the main window and to every popped-out panel window. The Play window is left alone, since it shows the game rather than the editor. The dock's tab bar is styled to match (the active tab sits on the panel colour with a wood outline), and the Inspector's section headings and checkboxes are drawn by two small helpers (section_label and outerface_checkbox) so they look the same everywhere.
• Three embedded fonts: Manrope for body text, Fraunces for headings, and JetBrains Mono for the console and other monospace text. They are compiled into the editor, so nothing is loaded from the network or the system. See Fonts below for their licence.
• Runs the simulation live on the engine's fixed-timestep clock, so the sim ticks at a true 30 per second independent of the window's repaint rate, with play, pause, and step controls.
• Undo and redo (Ctrl+Z / Ctrl+Y), built on full-world snapshots. Spawning, despawning, nudging, and Inspector edits are undoable; a drag or a held key is a single step.
• A flythrough camera: hold the right mouse button to look around with the mouse and fly with WASD (cursor grabbed), seeded from the current view. Scroll changes the fly speed. Left-click picks the entity at screen-centre and makes it the orbit pivot; release the button to return to orbit.

Play a project in a separate, clean game window: its own window and GPU surface running the world with no editor chrome, the simulation live and WASD driving Controlled entities. A program built on the editor library can also start straight into a project's game with no editor at all (frame_editor::run_player, or run_player_with_menu to open on the game's own menu first), from the project folder or from one compressed pack file holding the whole project (frame_engine::pack). Such a program can also turn on File > Build Game (frame_editor::set_game_builder), which compiles the game, packs the project and zips a folder ready to send to players.

Currently at the frontier: finishing the Outerface V1 theme pass (selected Scene rows, sliders, Inspector spacing); a fuller material model (real view-dependent specular), and shadows from point lights; collision and physics refinements (true oriented boxes, a broad phase, joints); interest management and reconnect support for multiplayer; and wiring net::Server/net::Client into the editor's own Play window. Rotation, script rename support, the script API's original "what a script can reach" list, rigid-body physics and characters, prefabs, parenting and cameras, textured models, client input upload, a plugin loader with enable/disable support, the full editor-extension surface for plugins (custom Inspector fields, menu actions, and panels), multi-light shading, and basic sound playback are done for now.

Principles

• Simulation is separate from rendering. The simulation knows nothing about how it is drawn. The editor reads the world and draws it across a crate boundary, and never owns the state. The engine crate pulls in no graphics libraries, and no script interpreter: it holds script source as data and leaves running it to the host, just as it leaves drawing to the host.
• Headless by default. Runs with no window. Rendering is optional and added on top.
• Deterministic, fixed-timestep. One tick is always the same slice of simulated time, so behaviour is identical across machines. The editor honours this with the engine's own clock rather than ticking once per rendered frame.
• Reusable. The engine is its own library crate, so it can power more than one game or tool. Dependencies point inward: tools depend on the engine, never the reverse.
• Hand-roll the heart, buy the rest. The engine is built by hand to be understood deeply. Solved problems that are not the heart (windowing, the GPU API, linear algebra, UI, file dialogs, config paths, dates, git, audio, scripting, physics) use existing libraries: winit, wgpu, glam, egui and egui_dock, rfd, dirs, chrono, git2, kira, rhai, rapier3d (the one such library the engine itself depends on), and serde with ron for scenes and the project manifest.
• No premature abstraction. Machinery is built when the pain is real, not before. The fixed-timestep clock stayed duplicated inline until a second consumer made the duplication real, then moved into core/.

Workspace structure

This repository is a Cargo workspace holding multiple crates:

crates/
├── frame-engine/       the simulation engine (library and binary)
│   └── src/
│       ├── core/       fixed-timestep clock (clock.rs)
│       ├── world/      simulation state (entities, components, storage)
│       ├── systems/    logic that runs each tick
│       ├── input/      graphics-free input abstraction (held buttons)
│       ├── net/        multiplayer: an authoritative Server and a Client
│       ├── assets/     hand-rolled OBJ parser
│       ├── physics.rs  rapier3d rigid bodies and characters
│       ├── render/     read-only ASCII debug view
│       ├── lib.rs      library root, exposes the engine to other crates
│       └── main.rs     binary runner, drives the tick loop
└── frame-editor/       editor; depends on frame-engine
    ├── assets/
    │   ├── frame-editor.png   the editor's logo
    │   └── fonts/             Manrope, Fraunces and JetBrains Mono, embedded
    └── src/
        ├── main.rs     windowed 3D editor: app state, camera, picking,
        │               entity editing, the egui panel layout, and the
        │               wgpu render pipeline
        ├── script.rs   the Rhai script runtime (the editor's ScriptRuntime)
        ├── shader.wgsl entity shader (instanced, shaded primitives)
        ├── text.wgsl   screen-space overlay shader (controls legend)
        └── font.rs     hand-rolled bitmap font for the overlay

The engine and editor live in one repo so they evolve together, but build as separate targets.

Building

Requires Rust.

Run the engine (headless tick loop and ASCII debug view):

cargo run -p frame-engine

Run the editor (opens the project launcher; pick or create a project to enter the 3D editor):

cargo run -p frame-editor

Editor controls:

• P play or pause, . step one tick while paused
• WASD drive a Controlled entity (while playing), Space jump (a physics character with Gravity, standing on something), Shift run and C crouch (a character with a CharacterBody). In the Play window, click to take the mouse and it turns a character's view; Esc frees the mouse and Esc again closes the window; F3 shows the game's numbers (frame rate, memory, where you are, and each module's own); F1 opens the game's own panels, when a module has one (EditorModule::play_panel), freeing the mouse while they are open; with the mouse taken, the left and right mouse buttons are the two actions (Button::Use and Button::UseAlt) E is Button::Interact and Q is Button::Swap, which the game decides what to do with, and a dot in the middle of the screen shows where you are looking; Ctrl crouches too. In water a game says is deep (World.liquids) a character swims: Space swims up and Ctrl or C dives
• Left-click select an entity, Esc clear selection
• Arrow keys move selection on X and Y, Page Up / Page Down move on Z
• N spawn an entity, Delete despawn the selection
• Ctrl+Z undo, Ctrl+Y (or Ctrl+Shift+Z) redo
• Ctrl+S (or F5) save scene, F9 reload scene (asks first if there are unsaved changes)
• Middle-drag orbit, Shift+Middle-drag pan, Scroll zoom
• Drag a gizmo arm move the selected entity along that axis
• Hold right mouse flythrough camera: mouse looks, WASD flies, Scroll sets fly speed, left-click picks the centred entity as the orbit pivot
• H toggle the controls overlay

License

Frame Engine is licensed under the Mozilla Public License 2.0 (MPL-2.0). In plain terms:

• You can use it, modify it and ship games or tools built on it, including closed-source and commercial ones.
• Your own game code, scripts, assets and separate crates stay yours, under whatever licence you choose.
• If you modify files that are part of Frame Engine and distribute the result, those modified files must be shared under the MPL-2.0 too.
• The names "Frame Engine" and "Outer Frame Interactive" are not covered by the licence. See TRADEMARKS.md.

Versions published before the licence changed to MPL-2.0 remain available under the MIT licence they were released with. The embedded fonts below are the exception to all of this, each under its own licence.

Fonts

The editor embeds three fonts from crates/frame-editor/assets/fonts/: Manrope, Fraunces, and JetBrains Mono. All three are released under the SIL Open Font License 1.1, which allows use, modification, and redistribution, including inside software, as long as the licence travels with the fonts. The licence texts, with each font's copyright notice, sit next to the fonts: Manrope, Fraunces and JetBrains Mono. They are not covered by this repository's MPL-2.0 licence.

Manrope-Regular.ttf is the regular weight cut from the Manrope variable font. egui reads a variable font at its lightest weight, which looked far too thin, so a fixed weight is used instead.

Design notes

See DESIGN.md for architecture decisions and reasoning, SCRIPTING.md for the guide to writing entity scripts, and PLUGINS.md for the guide to building a plugin.