Welcome!

Hello there! Thank you for checking out Kerosene.

Note

AI Generated content disclosure: Most of these docs were made by AI. If you want to improve them, please do! All help to kerosene is greatly appreciated :>

Warning

Kerosene is 1.0.0 alpha. It works end to end, but its API may still change between alphas, and a finished game still needs things it does not have yet: see Missing features.

Hello! Welcome to the Kerosene documentation.

Have you ever used the Source engine? Have you wished it was open source and you could make a game with the same tools? With Kerosene, we’ve tried our best!

Kerosene is a Rust game crate for brush-built 3D games. You add kerosene to a Cargo project, implement one trait, and you have a game, with the editor and every compiler along with it. Everything builds from source on your own machine, so the same game builds on Linux, Windows and macOS. It is PURELY open source: GPL 3.0 with an exception that lets your game stay yours, so long as it says it is built with Kerosene.

cargo install kerosene --features tools
kerosene-tools new mygame
cd mygame
cargo play

Kerosene has, among other things:

Tip

This list is incomplete, please read the rest of the docs to get a full view of this engine’s capabilites.

• A Source-style movement solver, air-strafing and all
• Brush-based world geometry, compiled to a BSP tree with baked visibility, lighting and acoustics
• Physics props on Box3D
• Entity I/O, Rhai map scripting and a game UI
• Skeletal animation
• Saved games and level changes
• Steam: achievements, stats, leaderboards, cloud saves and the Workshop
• Chisel, a level editor, and a compiler for every kind of content
• And more!

Making a game? Start with Getting started, then Making a game, and read Publishing before you hand anything to anyone.

Working on Kerosene itself? The Documentation and the Devnotes are how it works inside.

Getting started

Kerosene is a crate. A game is a Cargo package that depends on it, and everything — the engine, the editor, the compilers, your game — builds from source on your own machine. There is no installer, no launcher and no account. What runs on Linux runs on Windows and macOS, because it is the same code compiled there.

What you need

• Rust 1.94 or later, from rustup.
• On Linux, the ALSA headers for sound: libasound2-dev on Debian and Ubuntu, alsa-lib-devel on Fedora. Without them, a game still builds with --no-default-features, just silently.
• A GPU with Vulkan, Metal or DirectX 12. The editor’s 3D view is drawn in software and needs none.

Five minutes to a running game

cargo install kerosene --features tools
kerosene-tools new orbital-drift --name "Orbital Drift"
cd orbital-drift
cargo play

The toolset can also come straight from the repository, cargo install --git https://github.com/t342guy/kerosene kerosene-tools, and a game made by that toolset depends on the matching release tag, so it builds the same Kerosene the toolset is. kerosene-tools doctor checks the machine first: Rust, the Linux sound headers, the GPU.

new makes this:

orbital-drift/
  Cargo.toml              the package: kerosene, and two binaries
  .cargo/config.toml      cargo play, cargo tools, cargo ship
  orbital-drift.kproj  the project: its name, content, start map, game
  README.md               the commands, and what is where
  .gitignore              the build's outputs, and the player's own files
  .gitattributes          art and sound are binary
  .github/workflows/ci.yml  test and play it on Linux, Windows and macOS
  src/
    main.rs               the game binary: launch(game, options)
    game.rs               the game: a Game, a class of its own, and a test
    tools.rs              the game's own editor and compilers
  content/
    maps/orbital_drift_start.kmap
    art/ materials/ models/ sound/ scripts/ textures/

It is also a git repository, unless it was made inside one already or with --no-git.

The first cargo play builds the engine and its tools, which takes a few minutes. Then it compiles the starter map and opens the game on it. Walk up to the orange plinth: the gem on it is an item_pickup, a class the game defines in src/game.rs, and the console (`) says so when you take it. F5 saves, F9 loads.

Every cargo play after that rebuilds only what changed. With nothing changed, the game starts at once.

The loop

cargo play skimps the maps’ visibility and lighting, because a layout you are still moving walls around in does not need them. cargo ship always does them properly.

Where things go

Your code is src/game.rs and whatever modules you add. A game is one type implementing Game; every method has a default, so you add the ones you need. Making a game goes through each.

Your content is content/. Maps are drawn in Chisel. Textures go in art/ as PNGs; models in art/ as OBJ or glTF; sounds in sound/ as WAV, FLAC or MP3. cargo play compiles each into what the engine reads, beside its source.

The engine’s base content is under all of it. Kerosene carries the developer textures, the stock props, sounds and UI, and a plain room, compiled into the engine, so a game has something to show before it has anything of its own. Put a file at the same path in content/ and yours is used instead: content/ui/hud.kui replaces the stock HUD.

Another platform

Build on it. Clone your game on the Windows or macOS machine and run the same three commands; nothing in a Kerosene game is specific to where it was started. cargo ship there makes that platform’s dist/.

kiln --ship dist --target <triple> cross-compiles, for a developer who has set up that target’s linker and libraries. That setup is Rust’s rather than Kerosene’s, and building on each platform is the supported way.

Staying up to date

Kerosene follows Semantic Versioning on the kerosene crate’s API. Your Cargo.toml names a version; cargo update takes fixes and additions without breaking your game, and a new major version is one you move to on purpose, with the changelog saying what to change.

Next

• Making a game: the Game trait, classes, the schema and your game’s tools.
• Saving and level changes.
• Publishing, before you hand anything to anyone.

Making a game

This section is for people who want to build something on Kerosene, as opposed to people working on Kerosene itself. The rest of the book describes the engine from the inside; these pages describe it from where a game developer stands: what a project is, what it looks like on disk, how it gets built, and what has to be true before you hand it to somebody.

Warning

Kerosene is 1.0.0 alpha. Everything described here works, but the list of things a finished game needs and the engine does not yet have is long — see Publishing and Missing features before you commit to it.

New here? Getting started has you playing a game of your own in five minutes; this page is what is going on underneath.

Two shapes of project

A Kerosene project is a directory with a .kproj file at the top and a content tree beside it. There are two kinds, and the difference is one key.

A game crate. Your own Rust binary, depending on kerosene, with your own entity classes and rules: what kerosene-tools new makes. The engine is a dependency, never a fork: your crate implements one trait, Game, and hands it to launch; nothing in the engine’s source is edited to add a mechanic. A game crate below is the whole of it, and the stock kerosene runtime is the same thing with the stock game: apps/kerosene/src/main.rs is five lines.

A content-only project, or a mod, in Source’s sense: maps, materials, models, sounds and scripts, and nothing compiled. The game binary is the stock kerosene runtime, unmodified, and all of the behaviour comes from entity I/O wired in Chisel and from Rhai scripts (see Scripting), using the entity classes that ship in kerosene-game. No Rust and no build of the engine — but also nothing the stock classes cannot do, because Rhai is deliberately sandboxed and cannot allocate an entity, touch the renderer or open a file. kerosene-tools new --content-only makes one.

The key that turns one into the other is game.

The project file

project
{
    "name"     "My Game"
    "content"  "content"
    "startmap" "mg_intro"
    "game"     "my-game"
}

content is relative so the project can be cloned or moved and still be right. Every tool and the engine find the project the same way, with the same code, so there is one answer to “where is the content” and each program says which answer it took. The full account is in crates/kerosene-vfs/src/project.rs.

The content tree

content/
  engine.kcfg      renderer, window size, vsync — written on first run
  art/                source textures (.png) and meshes (.obj)
  textures/           texture *sets*: colour, normal, roughness… per folder
  materials/          .kmat — hand-written KeyValues (built into .kmat_c)
  models/             .kmdl, compiled by Forge from art/
  maps/               .kmap (yours) and .kbsp (compiled)
  sound/              .wav / .flac / .mp3 sources and compiled .kaud
  scripts/            .kscr (Rhai) and the .ksnd sound table
  <name>.vault        the archive Kiln packs everything into

Sources and build outputs sit side by side on purpose: every .obj under art/ becomes a .kmdl at the matching path under models/, and every .kmap under maps/ becomes a .kbsp. There is no list to keep up to date. Commit the sources; the compiled files are outputs and reproducible.

engine.kcfg always exists once anything has run — the first program to look for it and not find it writes the defaults. See Configuration.

The loop

flowchart LR
    C[Chisel<br/>edit the map] -->|F9| K[Kiln<br/>textures · models · sounds · maps · pack]
    K --> R[kerosene<br/>play it]
    R -->|what's wrong| C
    K -->|"--ship dist"| D[dist/<br/>hand it to someone]

Day to day, in a game crate:

cargo play                            # build what changed, then play
cargo tools chisel content/maps/mg_intro.kmap
cargo ship                            # build it all properly, into dist/

and in a content-only project, the same with the toolset itself: kerosene-tools play, kerosene-tools chisel …, kerosene-tools kiln --ship dist.

Chisel’s F9 compiles the current map and launches the engine on it, and builds any textures added since the editor opened. kiln --only maps --fast skips the visibility and lighting passes while a layout is still moving; an unvised, unlit map loads and plays, it just draws everything and looks flat.

Everything Kiln does is also a subcommand you can run by hand or from a build server — cleave, umbra, resonance, radiance, alchemy, forge, timbre, vault — and Tools is the reference for each.

When the game is ready for other people, the last stage is kiln --ship <dir>, and Publishing is about what that does and what it cannot do for you.

A game crate

The engine is one crate, kerosene, and a game is a crate that depends on it. Nothing else of the engine is named; the engine’s public parts are modules of it (kerosene::engine, kerosene::entity, kerosene::math, …), and so are the third-party crates your own signatures mention — kerosene::egui, kerosene::glam, kerosene::rhai — so the versions can never disagree. Its version follows SemVer on exactly that API; see Versioning for what is covered, and what, under kerosene::internals, is not.

You need Rust 1.94 or later (the workspace is edition 2024). On Linux the default audio feature wants the ALSA headers (libasound2-dev); --no-default-features builds without a sound device.

kerosene-tools new writes all of the following; this is what it means.

[package]
name = "mygame"
version = "0.1.0"
edition = "2024"

[dependencies]
kerosene = { version = "1.0.0-a4", default-features = false }

[features]
default = ["audio"]
audio = ["kerosene/audio"]
tools = ["kerosene/tools"]
steam = ["kerosene/steam"]

[[bin]]
name = "mygame"
path = "src/main.rs"

[[bin]]
name = "mygame-tools"
path = "src/tools.rs"
required-features = ["tools"]

# The engine optimised even in a debug build.
[profile.dev.package."*"]
opt-level = 2

The engine’s default features are off and passed through as the game’s own, so cargo build --no-default-features reaches the engine’s audio switch. required-features is what keeps the toolset — egui, the compilers, the audio decoders Timbre uses — out of a plain cargo build of the game. Features are per package, not per binary, so without it the game binary would link everything the tools do.

The game

A game is a type that implements Game. Every method has a do-nothing default, so a game that only adds a class implements one method. This one adds an item_pickup class, an inventory, an additem command and a HUD line:

#![allow(unused)]
fn main() {
// src/game.rs
use kerosene::prelude::*;

pub const SCHEMA: &str = include_str!("mygame.kdef");

#[derive(Default)]
pub struct MyGame {
    inventory: Vec<String>,
}

// Class handlers get the entity world and nothing else, exactly as the
// stock ones do, so they can be tested without an engine. When one needs
// the rest of the game it leaves a request with a kind of the game's own;
// `entity_request` below picks it up at the end of the tick.
fn input_pickup(world: &mut EntityWorld, id: EntityId, ev: &kerosene::entity::InputEvent) -> bool {
    let what = world
        .get(id)
        .and_then(|e| e.fields.text("item").map(|t| t.into_owned()))
        .unwrap_or_else(|| "thing".into());
    world.request("mygame.pickup", what, id, ev.activator);
    world.fire_output(id, "OnPickup", ev.activator, None);
    world.remove(id);
    true
}

impl Game for MyGame {
    fn classes(&self, registry: &mut ClassRegistry) {
        kerosene::game::register(registry); // doors, triggers, lights: the stock set
        registry.register(
            ClassDef::new("item_pickup")
                .input("Pickup", input_pickup)
                .output("OnPickup"),
        );
    }

    fn schema(&self) -> &'static str {
        SCHEMA
    }

    // The console is up, nothing has run yet: register commands here and
    // they work from autoexec.cfg and the command line.
    fn setup(&mut self, engine: &mut Engine) {
        engine.console.register_command("additem", ConVarFlags::NONE, "Put an item in the inventory.", |con, args| {
            con.request("mygame.additem", args.get(1).unwrap_or("thing"));
        });
    }

    fn entity_request(&mut self, engine: &mut Engine, req: &HostRequest) -> bool {
        if req.kind == "mygame.pickup" {
            self.inventory.push(req.payload.clone());
            engine.console.print(format!("picked up {}", req.payload));
            return true;
        }
        false
    }

    fn console_request(&mut self, _: &mut Engine, kind: &str, payload: &str) -> bool {
        if kind == "mygame.additem" {
            self.inventory.push(payload.to_string());
            return true;
        }
        false
    }

    // Every tick, after the player has moved and entities have thought,
    // before physics steps. `engine` is the whole engine.
    fn tick(&mut self, engine: &mut Engine, _input: &InputState, _dt: f32) {
        if engine.player.health <= 0.0 {
            self.inventory.clear();
        }
    }

    fn wants_ui(&self) -> bool {
        true
    }

    fn ui(&mut self, _: &mut Engine, ctx: &egui::Context) {
        egui::Area::new("hud".into()).show(ctx, |ui| {
            ui.label(format!("inventory: {}", self.inventory.join(", ")));
        });
    }
}
}

// src/main.rs
mod game;

// Counts allocations for the `mem` console command.
#[global_allocator]
static ALLOCATOR: kerosene::lifecycle::TrackingAllocator =
    kerosene::lifecycle::TrackingAllocator::new();

fn main() -> kerosene::anyhow::Result<()> {
    kerosene::launch(
        game::MyGame::default(),
        kerosene::LaunchOptions::new("My Game", env!("CARGO_PKG_VERSION")),
    )
}

launch is everything the stock binary does: the logger, --content, --vault, --headless, +command arguments, finding the project file and its start map, the saved engine settings, every .vault in the tree, and then a window or a headless run. mygame --headless 600 +map mg_intro is your dedicated server. The name is the window’s title and the desktop’s name for the game (.app_id(..) to choose another), and the version — yours, not Kerosene’s — is what version in the console and the log print beside Kerosene’s own.

The hooks, in the order the engine calls them: classes (once, at construction), setup, map_loaded and player_spawned, then per tick pre_tick (before the player moves — change movement convars here), tick (after entities have thought), with entity_request and console_request answering anything the engine did not understand; each frame frame (paused or not, with the real time elapsed) and ui while wants_ui says so. map_unloading comes before a map is replaced and shutdown as the engine exits. save and load keep the game’s own state in saved games and carry it across level changes, and can_save can refuse one; see Saving and level changes. player_damaged decides how much a hit takes, and player_died can take a death over – a death screen, reloading the last save – instead of the instant respawn: return true and the player stays down until engine.respawn_player(). One rule: a hook must not make the engine call another hook on the same game, so tick uses engine.request_map(..) rather than load_map (the inner hook would be skipped and logged, not run). Everything else on &mut Engine is yours: the fields console, entities, player, ui, audio, platform and input, and methods such as vfs(), time(), map_name(), run_script(..) and quit().

What a game most often reaches for:

A class of the game’s own with a model is drawn and collided with when it says how: ClassDef::new("npc_guard").model(ModelRole::Animated).

A class can react to the player walking into it, and to being damaged, without any wiring: ClassDef::new("item_ammo").on_touch(give_ammo) runs give_ammo(world, id, player) on the tick the player’s box meets it (its brush, or for a point entity a cube touch_size across), and .on_damage(f) runs f(world, id, amount, attacker) whenever engine.damage_entity hits it. The stock weapons call damage_entity on what they shoot, which is how breakable glass breaks.

Input reaches a game the way it reaches the engine: as console commands, bound to keys. A game’s own held action needs no command of its own: bind a key to +zoom and read engine.input.action_held("zoom") in tick. For a one-shot, register a command in setup and bind it in cfg/autoexec.cfg. engine.input is also what a rebinding screen changes: bind, unbind and keys_for("+jump").

The schema

Chisel shows what a .kdef says. Yours describes your classes and can inherit the engine’s bases:

// src/mygame.kdef
class {
    "name" "item_pickup" "base" "Entity" "base" "Point"
    "help" "Something the player can pick up."
    key    { "name" "item" "label" "Item" "type" "string" "default" "thing" "help" "What it is." }
    input  { "name" "Pickup" "help" "Take it." }
    output { "name" "OnPickup" "help" "Fired when taken." }
}

Entity carries the inputs every entity answers (Kill, AddOutput, the FireUsers); Point carries origin and angles. The registry and the schema are checked against each other by the same function the stock game uses for its own, so a class you register and forget to describe — or an input you describe and forget to handle — is a failing test and not a designer wiring up nothing:

#![allow(unused)]
fn main() {
// tests/schema.rs
#[path = "../src/game.rs"]
mod game;
use kerosene::prelude::*;

#[test]
fn the_schema_describes_the_game() {
    let mut registry = ClassRegistry::new();
    game::MyGame::default().classes(&mut registry);
    let mut schema = kerosene::entity::Schema::parse(kerosene::game::schema::BUILTIN).unwrap();
    schema.merge(kerosene::entity::Schema::parse_after(game::SCHEMA, Some(&schema)).unwrap());
    let problems = kerosene::entity::schema::check(&registry, &schema);
    assert!(problems.is_empty(), "{problems:#?}");
}
}

The tools

The toolset is a library behind the tools feature. Your mygame-tools is the whole of it — Chisel, the compilers, Kiln, Vault — with your schema in the editor and F9 building and launching your binary:

// src/tools.rs
mod game;

fn main() -> kerosene::anyhow::Result<()> {
    kerosene::tools::main_with(
        kerosene::tools::Options::new("mygame-tools", env!("CARGO_PKG_VERSION"))
            .schema(&[game::SCHEMA])
            .game("mygame"),
    )
}

cargo run --features tools --bin mygame-tools -- chisel content/maps/mg_intro.kmap

which .cargo/config.toml shortens to cargo tools chisel …; cargo play is mygame-tools play, and cargo ship is mygame-tools kiln --ship dist.

F9 runs cargo build -p mygame (a debug build, for the edit-compile-play loop) and launches target/debug/mygame on the compiled map, with cargo’s output in the editor’s output panel. kiln --ship builds it in release. The stock kerosene-tools does the same for any project whose file names a game package, without your schema in the editor — drop the .kdef into the content tree for that. A package whose binary is not named after it says so with "bin" in the project file.

Where to read next

• Formats — every file above, byte by byte.
• Scripting — the whole Rhai surface on one page.
• Audio — the .ksnd table and how sounds are placed.
• Positioning — what the engine is shaped to be good at, which is the honest way to decide whether to use it.

Saving and level changes

Kerosene saves the whole game between two ticks and puts it back exactly: the same entities with the same handles, the same inputs still on their way, the player where they stood and moving as they were. A saved game played on for two hundred ticks ends in the same world as the game that was saved played on for two hundred ticks; a test holds it to that.

Most games need no code for any of it. A game crate adds two methods if it keeps state of its own.

For players

Saves are files, save/<name>.ksav, in the player’s own directory: the same place cfg/config.cfg goes.

<game> is the game’s app id, from its name (orbital-drift). Not beside the executable, which a game installed in Program Files or a Steam library cannot write to. --portable keeps them in the first content directory instead, which is where saves from before 1.0.0-a3 are, and those are still found and loaded either way. They are JSON, so a bug report can include one and anyone can read it.

A game cannot be saved with no map loaded, or while the player is dead.

For mappers

Three entities:

Landmarks. Put an info_landmark with the same name at the same spot, relative to the geometry either side of the seam, in both maps, and name it in the trigger_changelevel’s landmark. The player arrives exactly where they stood relative to it, moving and facing as they were, so a corridor that crosses the seam is walked straight through. Without one, they start at the next map’s info_player_start.

With sv_autosave 1, the default, every level change saves as auto on arrival.

From the console or a script: changelevel <map> [landmark].

What a save keeps

Everything in an entity’s fields, wires and I/O queue, which is everything the stock classes know:

• a door half open stays half open, and finishes opening
• a math_counter keeps its count
• a wire that fires once, and has, stays spent
• a logic_auto does not fire again
• an output fired with a delay still arrives on time

It also keeps:

• the player, with their velocity and view
• each physics prop’s velocity
• the placed decals
• the UI store and the layers that were showing
• the map script’s variables, meaning every top-level variable that holds plain data: numbers, text, booleans, arrays and maps

A variable holding a function or an engine object is not saved. It comes back as whatever the script’s top level sets it to.

A save of a map that has since been recompiled still loads, with a warning, because the entities it holds may no longer match the geometry.

For game code

The engine owns the level. Your Game owns everything else, and saves it with two methods:

#![allow(unused)]
fn main() {
impl Game for MyGame {
    fn save(&mut self, _: &mut Engine) -> kerosene::serde_json::Value {
        kerosene::serde_json::json!({ "inventory": self.inventory })
    }

    fn load(&mut self, engine: &mut Engine, data: &kerosene::serde_json::Value) {
        self.inventory = data["inventory"]
            .as_array()
            .into_iter()
            .flatten()
            .filter_map(|v| v.as_str().map(String::from))
            .collect();
    }
}
}

• save is called for every saved game and every level change.
• load is called after the map has loaded and after map_loaded, so it overrides whatever a fresh map set up. It is not called when save returned null.

The stock game saves its weapons this way: rounds, the weapon in hand and the dash cooldown.

From code:

A class whose state lives outside its fields registers on_restore. It runs instead of the spawn handler when a save puts the entity back. ambient_generic uses it to ask for its looping sound again:

#![allow(unused)]
fn main() {
ClassDef::new("ambient_generic").on_spawn(spawn).on_restore(restore)
}

The UI hears game_saved, game_loaded and level_changed as events, and the name of the last save is in save.last.

Cloud saves

When the store has a cloud, as Steam does, every save is also written there. On load, whichever copy is newer wins, the local file or the cloud’s, so a save follows the player to another machine. A local file that is missing is fetched from the cloud. Off Steam there is no cloud, and saves are only local.

Steam Auto-Cloud works as well: point it at the save/ directory.

Publishing

What has to be true before a game built on Kerosene goes to other people: what the licences require, what you may do, what you may not, and what you technically can do today but will pay for. The legal reasoning lives in Licensing and the technical gaps in Missing features; this page is the two of them condensed to the questions a release actually raises.

Note

None of this is legal advice. It is an accurate account of what the licences in this repository say and what the code does, so that you or an actual lawyer can move quickly.

Requirements

Kerosene is licensed GPL-3.0-or-later with the Kerosene Exception. The exception is what lets a closed-source game link the engine at all: it is an additional permission under GPL §7, granted on conditions, and shipping a game means meeting them. A distribution must carry:

1. The licence texts. LICENSE (the GPL) and LICENSE-EXCEPTION (the Kerosene Exception), in full, beside the game.
2. A notice that the program is built with Kerosene, what licence the engine is under, and that it comes with no warranty.
3. A pointer to the corresponding engine source. The obligation travels with the copy, so it has to be in the copy: a URL, or an offer, in the README.txt.
4. An attribution screen. Each time the game starts, before or together with its first interactive screen, it shows that it is built with Kerosene. Brief and dismissable is fine; disabled, hidden or illegible is not. A game with no graphical interface prints the line instead.
5. Third-party notices for what travels inside the binary. Two things do: smartstring (MPL-2.0, pulled in by the script engine) and the typefaces egui embeds (SIL OFL 1.1 and Ubuntu Font Licence 1.0). Both are satisfied by preserving their notices.
6. If you changed Kerosene’s own files: the whole modified engine stays under the GPL with the exception; it says “modified from Kerosene”, the version or commit it diverged from, and where Kerosene’s source is — in its notice, in the game’s README.txt and on the attribution screen; and its complete source is published where anyone can obtain it free of charge. See Forks and derived engines.

kiln --ship writes 1, 2 and 5 for you and leaves a labelled space for 3 and for the modified-engine line in 6. Item 4 is drawn by your game — the engine does not draw it for you yet (Missing features) — and the rest of 6 is yours alone; no tool can know whether the engine you built against is the one in the repository.

You can

You cannot

You can, but…

Everything here works, or can be made to work, and each has a cost the engine does not yet hide. These are the gaps a release runs into, in roughly the order you will hit them; the fuller list is Missing features.

Forks and derived engines

There are three ways to change the engine, and they are not equal.

A pull request. The cheapest by far, and the one the project asks for first. Send the change upstream, build on the updated engine, and the fix exists once — reviewed, tested, and maintained by someone other than you. Every other option below means you carry it.

A private fork. You changed something and you ship it inside your own game. A modified Kerosene is a modified Kerosene wherever the changed files live, so what you owe is what the exception says of one:

• the whole modified engine stays under the GPL with the exception (§1(a));
• if the game is closed — that is, if you are using the linking permission — the complete source of the modified engine is published where anyone can obtain it free of charge, not only offered to your players (§1(c));
• it says “modified from Kerosene” (or “built from Kerosene”), the version or commit it diverged from, and where Kerosene’s source is — in the engine’s own notice, in the game’s README.txt, and on the game’s attribution screen (§2(b), §2(e));
• it is not presented as the original or as endorsed by this project.

Decline the exception and you are under the plain GPL: the entire game is then a covered work, and only then is publication not required — recipients get the source instead.

A derived engine. The Source lineage has a precedent for this: Respawn took Source, rewrote large parts of it, and shipped Titanfall on the result — a branch that was recognisably Source and recognisably not. Kerosene would like to be forked that way. If you rewrite the renderer, or the physics, or half of everything, and other people are going to build games on what you made, that is a derived engine, and you are welcome to name it after this one so its lineage is plain: Kerosene: Ultimate, Kerosene NG, whatever fits. Everything a private fork owes, a derived engine owes too; the attribution-screen requirement is inherited, so every game built on the fork shows “built with Kerosene NG, modified from Kerosene”.

The naming policy

The licence grants no right to the name. §2(d) of the exception grants it, on conditions: call your engine something a reasonable person would take for a Kerosene branch — a name that contains “Kerosene” or is plainly derived from it — and you accept these:

1. Publish the whole modified engine as source, under the GPL with the exception — the engine, not only the files you changed — where anyone can obtain it free of charge. A Kerosene-named engine is open the way Kerosene is open, whether or not a closed game ever ships on it.
2. Attribute Kerosene as §2(b) asks: “modified from Kerosene”, the version or commit you diverged from, and a link to Kerosene’s source, in your engine’s notice and in the notice and attribution screen of every game built on it.
3. Say it is a derivative. Do not present it as the official Kerosene or as endorsed by this project; a line in the README saying it is an independent fork is enough.

Use a name that is not Kerosene’s and only §2(b) and the linking conditions apply. The project would rather see a well-named derivative than a closed one with a different label.

What stays the same whichever way you go: the two licence texts ship, the notices ship, kiln --ship still writes them, and no Valve or id mark becomes part of anybody’s branding.

How kiln --ship helps

kerosene-tools kiln --ship dist

builds the content if it is stale, builds the game package if the project names one, and assembles:

dist/
  my_game            the game, or the engine runtime when the project names none
  my_game.kproj   content = "content", so the game finds its own archive
  content/
    my_game.vault
  LICENSE            the GNU General Public License, version 3, full text
  LICENSE-EXCEPTION  the Kerosene Exception, full text
  README.txt         what this is, and the notices the licence asks for

Three properties are worth knowing:

• It copies a named list, not a directory. Nothing from target/ sweeps in by accident, and in particular no tool does.
• It refuses rather than warns. A missing archive, or one older than any file in the content tree, stops the ship stage. Run kiln again first.
• The licence texts are compiled into kiln, so shipping works from an installed toolset that is nowhere near a checkout.
• --steam adds Valve’s library and nothing else. It builds with the steam feature, puts libsteam_api beside the game with an rpath to find it, and writes SteamPipe scripts next to dist/ rather than inside it. See Steam. On Windows, every ship links the C runtime statically, so players need no Visual C++ redistributable.

What it leaves for you: the README.txt has an Engine source section that says the source must be available and asks you to say where — and, if your engine is modified, which version it diverged from and where the whole modified source is published. Fill it in. That, the attribution screen the game draws itself, and testing the result on a machine that is not yours — see the Shipping checklist.

Platforms & distribution

Where a Kerosene game can run today, where it can be sold, and what each choice costs. The short version: Linux is the only platform anyone has tested; everything else is untested rather than known broken, and no storefront has any integration yet.

Operating systems

CI (.github/workflows/ci.yml) runs the tests on Linux, and makes a game with kerosene-tools new there and plays it headless. On Windows and macOS it only compiles, so “compiles” is known there and nothing more: if you ship on either you are the first to find out whether it runs.

Build each platform’s copy on that platform: clone the game there and run cargo ship. kiln --ship dist --target <triple> cross-compiles for a developer who has that target’s linker and libraries set up; that setup is Rust’s to document, and building natively is the supported way. scripts/build-content.sh is a Linux shell script, but it is only a wrapper: kerosene-tools kiln is what it calls and that is a program, on every platform.

Storefronts

Nothing in the licence stops you selling on any of these. Steam is the one the engine integrates with; see Steam.

The Workshop is worth a sentence because it is the store feature the engine is built for. The formats are open and each map is one .vault, so a subscribed map mounts as one more VFS layer with no format work at all. The engine does exactly that at startup, and kerosene-tools workshop upload puts a .vault up.

Dedicated servers

kerosene --headless <ticks> runs the simulation with no window, and it is what a dedicated server is, not a test mode — but there is no network stack for it to serve. Until there is, a server is a single-player game with no screen.

Packaging

kiln --ship produces a folder, and a folder is the distribution: no installer, no auto-updater, no code signing. Zip it. On Linux the executable bit is preserved through the copy; on other platforms the archive format has to preserve it for you.

The game finds its content by climbing from the executable, and the shipped .kproj says content = "content", so the folder works from wherever it is unpacked and does not care about the working directory.

What the player needs

• A GPU and driver wgpu can talk to: Vulkan on Linux, and presumably DX12 or Metal elsewhere.
• Write access to the content folder on first run, for engine.kcfg (see Publishing).
• Nothing else. There is no runtime, no redistributable, no shared library: the game is one static binary and one archive.

Steam

Kerosene talks to Steam through Valve’s Steamworks SDK. It covers:

• achievements, stats and leaderboards
• rich presence
• cloud files
• DLC checks
• the overlay
• the Workshop

The same map, script and game code works off Steam too. Without Steam, the store is a stand-in that keeps achievements and stats for the session and answers every request the way Steam would. Nothing needs an if steam branch.

Turning it on

Steam is an opt-in Cargo feature. A default build of Kerosene links nothing that is not free software, and the Steamworks SDK is not. So a Steam build is one you ask for:

# your game's Cargo.toml
[dependencies]
kerosene = { ..., features = ["steam"] }        # always Steam

# or, better, as a feature of your own that kiln can turn on:
[features]
steam = ["kerosene/steam"]

The stock runtime has the same switch:

cargo run -p kerosene-runtime --features steam

The SDK comes from the steamworks crate, whose Rust bindings are MIT/Apache and which carries Valve’s headers and redistributable libraries. You need no C++ toolchain, no bindgen and no separate SDK download.

The project file

Everything Steam needs to know goes in the .kproj:

project
{
    "name"        "My Game"
    "startmap"    "mg_intro"

    "steam_appid" "480"          // your app id; 480 is Valve's test app, Spacewar
    "steam_depot" "481"          // optional; the app id plus one by default

    "achievements"
    {
        "ACH_FIRST_DOOR"  "Open the first door"
        "ACH_TEN_DOORS"   "Open ten doors"
    }
    "stats"
    {
        "doors_opened"    "int"
        "distance"        "float"
    }
    "dlc"
    {
        "1234560"         "Soundtrack"
    }
}

Achievements and stats are declared. An id that is not listed here is refused, and the console says which id and why. Without that rule, a typo in a map would be an achievement nobody can ever get. Each id must also be set up under the same API name in the Steamworks partner site.

Running it

Shift+Tab opens the overlay, and the game pauses under it by opening the pause menu. The menu stays open after the overlay closes, so the player returns to a menu rather than straight into play.

From a map: entity I/O

Results fire on every entity of the class that names the same thing, not only on the one that asked. For example, an achievement a script awards still fires the logic_achievement for it. A leaderboard’s answer arrives a moment later from Valve’s servers and lands on the entity for that board.

A logic_stat with a threshold and an achievement does the usual thing for “open ten doors”. It shows Steam’s progress toast on the way (3/10, 4/10, …) and awards the achievement when the stat reaches the threshold.

Kerosene Demo has one example: typing the code into the keypad in kero_start fires ach_keypad’s Unlock, and the HUD toasts “Code breaker”. Its kerosene-demo.kproj declares ACH_KEYPAD.

From a script: platform (or steam)

Map scripts and UI scripts have the same object:

platform.unlock("ACH_FIRST_DOOR");
steam.add_stat("doors_opened", 1);          // `steam` is the same object
platform.progress("ACH_TEN_DOORS", 3, 10);
platform.submit_score("atrium_time", 5230, true);   // true: lower is better
platform.presence("status", "In the atrium");
if platform.owns_dlc(1234560) { ... }
platform.open_overlay("achievements");

print(platform.user);                       // the Steam name, or the OS user
if platform.available { ... }               // a store is connected
if platform.is_unlocked("ACH_FIRST_DOOR") { ... }
let doors = platform.stat("doors_opened");

The object works inside functions as well as at the top of a file. What comes back arrives as an event:

• Map scripts: fn on_platform_event(name, data).
• UI layouts: on:achievement_unlocked="..." or on_event.

UI bindings read the same state from the store:

• platform.available, platform.name, platform.user and platform.overlay
• platform.achievements.<id>, platform.stats.<name> and platform.dlc.<appid>
• platform.names.<id>, the display names from the project

The stock HUD’s achievement toast is built from these.

From game code

#![allow(unused)]
fn main() {
use kerosene::platform::PlatformAction;

if let Err(why) = engine.platform_apply(&PlatformAction::AddStat { name: "kills".into(), delta: 1.0 }) {
    log::warn!("{why}"); // e.g. the stat is not declared in the .kproj
}
let user = engine.platform().user();
}

Game::platform_event hears every event after the entities and the map script. engine.platform_mut().cloud_write(name, bytes) and cloud_read use Steam Cloud’s file API.

Cloud saves

There are two ways to do it:

• Steam Auto-Cloud. Configure it in Steamworks to sync a folder, and no code is needed at all.
• The cloud API. cloud_write / cloud_read store named files in the game’s cloud quota.

Off Steam, the stand-in keeps “cloud” files in memory. Saved games use these calls on their own: every save is mirrored to the cloud, and the newer copy wins on load. See Saving and level changes.

The Workshop

A subscribed Workshop item is a folder. At startup, the engine mounts every .vault in every subscribed, installed item as one more layer of its file system. A map from the Workshop is found like any other map, and nothing about the format changes.

To upload one:

cargo build -p kerosene-tools --features steam
kerosene-tools workshop upload content/my_map.vault --title "My Map" --preview shot.png
kerosene-tools workshop upload content/my_map.vault --item 3141592653 --note "Fixed the leak"

The first form makes a new item and prints its id. Pass that id next time to update the item rather than make another. You need the Steam client running and signed in to an account that owns the game.

Shipping: kiln --ship --steam

kerosene-tools kiln --ship dist --steam                 # a build to upload
kerosene-tools kiln --ship dist --steam --steam-dev     # plus steam_appid.txt, to test outside Steam
kerosene-tools kiln --ship dist --steam-upload myacct   # build, then upload with steamcmd

On top of an ordinary ship, --steam does five things:

1. Builds with the steam feature, into target/ship so the everyday build is left alone. A project with no game package gets the stock runtime, built from the engine checkout.
2. Installs Valve’s redistributable (libsteam_api.so, steam_api64.dll or libsteam_api.dylib) beside the game. The copy comes from the build that linked it, so the versions always match.
3. Makes it findable. On Linux the binary gets an rpath of $ORIGIN, and on macOS of @executable_path. Windows looks beside the executable on its own. The shipped game starts from any working directory.
4. Writes the SteamPipe scripts, steam_build/app_build_<appid>.vdf and depot_build_<depot>.vdf, beside dist/ rather than in it. It then prints the steamcmd line that uploads them. The depot script excludes steam_appid.txt and *.pdb, so a test file can never reach players.
5. Says so in README.txt: the library is Valve’s, redistributed under the Steamworks SDK Access Agreement, and not part of Kerosene.

Kiln never handles credentials. With --steam-upload, steamcmd asks for the password and Steam Guard code itself.

On Windows, every ship links the C runtime statically, Steam or not. So a player needs no Visual C++ redistributable either, and the only redistributable a Kerosene game carries is Valve’s.

Licensing

The Kerosene Exception lets a game combine the engine with Independent Modules, and the Steamworks SDK is one. A Steam build of your game is a Combined Work like any other. The engine part stays GPL with its source available, and the SDK stays Valve’s under Valve’s terms.

The Kerosene source tree carries none of the SDK. It arrives through Cargo only when a game turns the feature on.

What is not here yet

• Steam Input, and gamepads in general. Under Steam, Steam Input’s virtual pads appear as ordinary controllers, so they come with gamepad support.
• Lobbies, matchmaking and networking.
• Inventory and microtransactions.
• Downloading or reading leaderboard entries. Posting works; showing a table does not yet.
• Workshop browsing from inside the game. The Steam client’s Workshop page does the subscribing.

Shipping checklist

In the order you will do them. Each item links to the page that explains it.

Before the build

• startmap in .kproj names the map New Game starts on.
• The main menu, splash and loading screen are the game’s own, or the base ones are what you want: ship ui/menus/main.kui, splash.kui, loading.kui to replace them.
• game in .kproj names your Cargo package — or is deliberately absent, because you are shipping a content-only project on the stock runtime. (Making a game)
• kerosene-tools kiln --dry-run lists every stage you expect and no map you have forgotten.
• kerosene-tools kiln runs clean: no leaks reported at the end, no missing texture or model. A leaking map compiles anyway, so read the summary.
• You have played every map from the compiled .vault, not from loose files — loose files shadow the archive, and a file you forgot to add will look fine on your machine and be missing on the player’s.

The build

• kerosene-tools kiln --ship dist succeeds. If it refuses, it says why: a stale archive means run kiln again first. (Publishing)
• dist/ holds the game binary, <name>.kproj, content/<name>.vault, LICENSE, LICENSE-EXCEPTION and README.txt — and no kerosene-tools binary.
• README.txt, “Engine source”: replaced the instruction with the URL or offer where the Kerosene source you built against can be obtained. Nothing does this for you.
• The game shows an attribution screen when it starts — “Built with Kerosene”, before or with the first interactive screen — that a player cannot switch off. The engine does not draw one for you yet; a few lines in Game::ui do it. (Publishing)
• If you changed any Kerosene file: the whole modified engine is published where anyone can get it, and the README.txt and the attribution screen say “modified from Kerosene” with the version or commit you diverged from and where the modified source is. Better: the change is a pull request upstream. (Publishing)
• If the engine you built on carries a Kerosene-derived name: the same, plus its source is published whether or not your game is closed. (Publishing)
• The engine commit you built against is tagged or written down, so the source pointer means something in a year.

If it ships on Steam

• steam_appid in .kproj is your app id, not 480.
• Every achievement and stat the game awards is declared in the .kproj and set up under the same API name in Steamworks. achievement_list in the console shows what the game declares. (Steam)
• kerosene-tools kiln --ship dist --steam succeeds, and dist/ holds Valve’s libsteam_api.so / steam_api64.dll / libsteam_api.dylib beside the game.
• No steam_appid.txt is in what you upload. --steam-dev writes one for testing, and the depot script excludes it anyway.
• Started from Steam, platform_status says steam (connected), and Shift+Tab pauses the game.

Before it goes out

• Run dist/<name> from a different working directory. It must find its own content.
• Run it on a machine that is not yours, ideally one that has never had a Rust toolchain or a Kerosene checkout on it.
• Run it once from a read-only location and confirm it still starts — engine.kcfg cannot be written there and the defaults must do.
• If the target is Windows or macOS: CI builds it; you are still the first to run it. Test there before announcing it. (Platforms)
• Your store page says the things the engine cannot do yet and your game therefore does not: no gamepad, unless you built it. (Publishing)

FAQ

Short answers. Each links to the page with the long one.

Can I sell a game made with Kerosene? Yes. The licence does not restrict commercial use. (Publishing)

Do I have to open-source my game? No. The Kerosene Exception lets you link the engine into a closed game. Your code, levels, assets and scripts are yours; the engine part stays GPL with its source available. (Licensing)

Isn’t the GPL viral? How can my game be closed? On its own it would be. The exception is an additional permission under GPL §7 that says a game linking Kerosene is not a covered work, on conditions: engine source, the built-with notice, an attribution screen, and — if you changed the engine — the whole modified engine published. (Licensing)

What do I have to ship alongside the game? Both texts (LICENSE, LICENSE-EXCEPTION) and a README.txt with the notices. kiln --ship writes all of it; you fill in where the engine source can be obtained. And the game itself shows an attribution screen at start. (Shipping checklist)

What is the attribution screen? “Built with Kerosene”, shown each time the game starts, before or with the first interactive screen. It can be brief and dismissable; it cannot be switched off. Draw it in Game::ui for now — the engine will draw it for you eventually. A game on a modified engine shows “built with Fork, modified from Kerosene”. (Publishing)

Can I remove the “Built with Kerosene” notice? No. It is a condition of the linking permission and a notice §7(b) of the GPL lets the project require. Remove it and the permission goes with it, which makes the whole game GPL. (Publishing)

Can I ship Chisel or the compilers with my game, for modders? Not inside the distribution kiln --ship makes, and not without also distributing their source: the tools are GPL binaries in their own right. Point modders at the Kerosene repository instead, or build your own mygame-tools on kerosene::tools, which ships like the game. (Publishing)

I changed the engine. What do I owe? The whole modified engine stays GPL with the exception; it says “modified from Kerosene” with the version you diverged from and a link back — in its notice, the game’s README.txt and the attribution screen; and if your game is closed, the modified engine’s complete source is published where anyone can get it. The project would rather have a pull request. (Publishing)

Can I make my own engine out of Kerosene and call it “Kerosene: Ultimate”? Yes, and the project would like that — the way Titanfall’s engine was a rewritten branch of Source. The name costs what a modified engine already owes plus publishing its whole source whether or not a closed game ships on it, and saying plainly it is a derivative rather than the official one. (Publishing)

Do I owe anything for Symphonia (the MP3/FLAC decoder)? No. Only Timbre, a build tool, links it, and kiln --ship never puts a tool in a distribution. The one MPL-2.0 dependency a game does carry is smartstring, and its notice is written for you. (Licensing)

Can I use Source or Hammer assets, or open a .vmf? No, on both counts. Kerosene’s formats are its own and deliberately cannot read theirs, and the project ships no Valve or id content. Bring your own. (Licensing)

Is it game-ready? Not yet. It is 1.0.0 alpha. Everything works end to end — make a game with kerosene-tools new, draw a level, compile it, walk around it, save and load — but main menus, gamepads, combat, networking and crash reporting do not exist yet. (Publishing)

How do I start? cargo install kerosene --features tools, kerosene-tools new mygame, cargo play. (Getting started)

Will an update break my game? Not without saying so. Kerosene’s version follows Semantic Versioning on the kerosene crate’s API: cargo update takes fixes and additions, and a breaking change waits for a major version, with the changelog saying what to change. The 1.0.0 alphas are the exception. (Versioning)

Does it run on Windows or macOS? CI runs every test on both, and makes and plays a new game on each. Nobody has played one there by hand yet. (Platforms)

Can players mod a shipped game? Yes, trivially: a loose file under content/ shadows the same path in the .vault. That is also why there is no tamper protection. (Publishing)

Can I make a game without writing Rust? Yes — a content-only project: maps, entity I/O and Rhai scripts on the stock runtime. The moment you need something the stock entity classes cannot do, you need a game crate. (Making a game)

Architecture

How the pieces fit, and why they are arranged this way.

The shape of the thing

---
config:
  layout: elk
---
flowchart LR
    n1["Source content"] --> n2(["Build-time tools"])
    n2 --> n3["Runtime"]
    n4(["art/.png"]) --> n7@{ label: "<span style=\"color:\">alchemy</span>" }
    n7 --> n8(["materials/*.ktex &amp; *.kmat_c"])
    n8 --> n9["Kerosene"]
    n5(["art/.obj"]) --> n10["forge"]
    n10 --> n11(["models/*.kmdl"])
    n11 --> n9
    n6(["maps/.kmap"]) --> n12["cleave"]
    n12 --> n13(["maps/*.kbsp"]) & n15(["`*.kprt`"])
    n13 --> n14["umbra"]
    n15 --> n14
    n14 --> n16["+vis"] & n17["radiance"] & n20["resonance"]
    n16 --> n9
    n17 --> n18["+light"]
    n20 --> n21["+sound"]
    n21 --> n16
    n18 <--> n16 & n19["chisel"]
    n19 --> n6

    n1@{ shape: rect}
    n3@{ shape: rect}
    n7@{ shape: rounded}
    n9@{ shape: rect}
    n10@{ shape: rounded}
    n12@{ shape: rounded}
    n14@{ shape: rounded}
    n16@{ shape: rect}
    n17@{ shape: rounded}
    n18@{ shape: rect}
    n19@{ shape: rounded}
    style n1 stroke:#2962FF,color:#2962FF
    style n2 stroke:#FF6D00,color:#FF6D00
    style n3 stroke:#AA00FF,color:#AA00FF
    style n4 stroke:#2962FF,color:#2962FF
    style n7 stroke:#FF6D00
    style n8 color:#D50000,stroke:#D50000
    style n9 color:#AA00FF,stroke:#AA00FF
    style n5 stroke:#2962FF,color:#2962FF
    style n10 stroke:#FF6D00
    style n11 color:#D50000,stroke:#D50000
    style n6 stroke:#2962FF,color:#2962FF
    style n12 stroke:#FF6D00
    style n13 color:#D50000,stroke:#D50000
    style n15 stroke:#D50000,color:#D50000
    style n14 stroke:#FF6D00
    style n17 stroke:#FF6D00
    style n19 stroke:#FF6D00

Everything above the line happens once, on a developer’s machine or a build server. Everything below happens sixty-four times a second on a player’s.

That division is the single most important thing about a BSP engine, and it is why the tools are not part of the engine. Visibility takes minutes to compute and microseconds to query. Lighting takes minutes to bake and nothing at all to sample. Neither belongs in the engine.

Crate dependencies

---
config:
  layout: elk
  theme: default
  look: neo
  fontFamily: '''Source Code Pro Variable'', monospace'
---
flowchart TB
    n1["Kerosene-math"] --> n2["Kerosene-kv"] & n4(["cleave"]) & n8["Kerosene-physics"] & n9["Kerosene rigid"] & n11["kerosene-entity"] & n13["Kerosene-vfs"] & n14["kerosene-asset"] & n15["kerosene-render"] & n17["Kerosene (runtime)"]
    n2 --> n3["kerosene-map"] & n5["kerosene-bsp"]
    n3 --> n5 & n4
    n4 --> n5
    n6(["umbra"]) --> n5
    n7(["radiance"]) --> n6
    n20(["resonance"]) --> n6 & n14
    n5 --> n8
    n10(["Box3d-rust"]) --> n9
    n12["kerosene-game"] --> n11
    n14 --> n13 & n15
    n15 --> n16["kerosene-engine"]
    n16 --> n18["kerosene"]
    n12 --> n18
    n18 --> n17

    n1@{ shape: rounded}
    n2@{ shape: rounded}
    n8@{ shape: rounded}
    n9@{ shape: rounded}
    n11@{ shape: rounded}
    n13@{ shape: rounded}
    n14@{ shape: rounded}
    n15@{ shape: rounded}
    n17@{ shape: rounded}
    n3@{ shape: rounded}
    n5@{ shape: rounded}
    n12@{ shape: rounded}
    n16@{ shape: rounded}

Nothing points upward. kerosene-math knows about nothing; kerosene-engine knows about everything except the game. The tools sit off to the side, depending on the format crates but never on the engine.

kerosene is the top of it all, and the product: the game crate. It re-exports the engine’s stable crates as modules and the rest under kerosene::internals, wraps the stock game as kerosene::game::Stock, and provides launch. It is the one crate a game names, its API is what Kerosene’s version number follows (Versioning), and the runtime binary is a call into it.

Underneath everything is the engine’s base content, crates/kerosene-engine/base/base.vault: the developer textures, the stock props, sounds and UI, and a plain room, kerosene_room, compiled into the engine and mounted as the last layer of the file system. A game with no content of its own still has something to show, and a game’s own file at the same path always wins.

The game seam

The engine has no game of its own. kerosene-engine defines a Game trait – classes, schema, setup, map_loaded, player_spawned, pre_tick, tick, frame, entity_request, console_request, wants_ui, ui, ui_event, save, load, can_save, player_damaged, player_died, platform_event, map_unloading and shutdown, every one with a default – and runs whatever implements it, with &mut Engine in every hook. kerosene-game is the stock implementation’s classes and knows nothing of the engine; the engine tests against it as a dev-dependency and kerosene::game::Stock is the type that joins the two.

What used to be game code the engine called by name – what a trigger does to the player, the everywhere flag on a sound – is now an engine convention (kerosene_engine::triggers, audio::SF_EVERYWHERE) that any game’s classes get by following the field names. The game is held outside the engine while a hook runs, which is what lets a hook take &mut Engine; the cost is that a hook cannot cause another hook, so a game changes maps with request_map.

kerosene-config is not on the diagram because it sits to the side of all of it: a small crate on top of kerosene-kv that reads engine.kcfg, the settings every program shares (which renderer, how big the window). The game, Chisel, and the tool windows all ask it the same question, so the renderer is chosen once in a file rather than once per program.

kerosene-rigid is the newcomer beside kerosene-physics. Player movement stays in kerosene-physics (it is Source’s gamemovement, and that is the feel); kerosene-rigid wraps box3d-rust, Erin Catto’s 3D engine ported to pure Rust, for everything the player is not – physics props, the rigid bodies that tumble and roll. It speaks Kerosene units natively: Box3D’s length-unit scale is set to inches once at startup, and no coordinate conversion happens anywhere.

In the engine, a PhysicsProps owns one PhysicsWorld: at map load every static world brush (and every detail) becomes a convex hull, moving brush entities become static bodies that follow their entity’s pose, and each prop_physics entity becomes a dynamic box (shaped from its model’s bounds, loaded through kerosene-asset). Once a tick the simulation is stepped and its poses written back to the entities. The renderer draws those props as .kmdl models at their simulated pose, and phys_debug turns the collision boxes into a wireframe overlay. The player’s movement traces against the prop boxes too (through PlayerCollision), and the use key doubles as a pick-up tool: grab a prop, carry it, press use again to launch it. prop_dynamic_spawner is the game-side spawner that creates the props in the first place.

Two edges in that picture are there for a reason worth stating. chisel depends on alchemy, because the editor builds the content tree’s textures itself rather than re-invoking the toolset for it. And everything – the editor, the compilers, the runtime – finds the content tree through kerosene_vfs::root, one function they all call, and finds the runtime and the toolset’s subcommands through kerosene_vfs::toolchain, likewise. Each of them working either out separately is not a hypothetical: they did, they disagreed, and a tool looking in the wrong directory is indistinguishable from a tool that is broken. A shared answer that explains itself is the whole of the fix.

kiln sits above the compilers rather than beside them: it is the one tool that runs the others, and it does so by re-invoking the same executable with the compiler’s name as a subcommand, so nothing about the pipeline being one program leaks into the compilers being separate stages.

The map pipeline in detail

Cleave: .kmap → .kbsp

1. Brushes. Each .kmap solid becomes a set of interned half-space planes. Plane interning matters more than it sounds: two faces meant to be coplanar must end up sharing one plane index, or the tree splits along a hair’s width between them and the compile explodes.

2. CSG. Every face is cut against every brush that could bury it, and the buried parts are dropped. On a real map this removes about a third of all faces before anything else runs. The subtle case is coplanar faces: two brushes flush side by side keep exactly one shared face (lower index wins, deterministically); two brushes back to back drop it entirely.

3. The tree. Built top-down from the brushes’ own planes, choosing at each step the plane that scores best on Quake’s heuristic — coplanar faces are worth a great deal, splits cost the same amount, axial planes get a bonus. Detail brushes are held out of this entirely, which is the single biggest lever a designer has over compile time.

4. Portals and flood fill. Portals are the polygons where two leaves touch. Flooding outward from every entity through passable portals answers three questions at once: is the map sealed, which leaves are inside it, and what is the connectivity graph the visibility compile needs.

5. Outside removal. Leaves the flood never reached become solid. This deletes the entire outer shell of the level — the backs of every wall, the underside of the floor — and it is why a sealed map is so much cheaper than an open one.

6. Emission. Faces are filed down the tree into the leaves that can see them, vertices are welded so adjacent faces share records (or their seams crack open under rounding), and edges are shared through the surfedge indirection.

Umbra: visibility

For every cluster, which other clusters can be seen from anywhere inside it.

Base vis is cheap and generous — two portals might see each other if each pokes out on the far side of the other, flooded transitively. The full portal flow then narrows a shrinking sight cone with separating planes: the planes touching one edge of the source and one vertex of each portal passed through. When the cone closes to nothing, everything beyond is invisible.

The result is a bit per cluster pair, run-length encoded. At runtime the renderer decompresses one row and skips every leaf not in it.

Resonance: acoustics

Every leaf is listened to from inside: a few hundred rays go out and bounce until they have nothing left, and each surface they strike gives up how much it soaks up per band, from its material. The averages — how far a ray goes between surfaces, how much it loses at each — are what Eyring’s formula for reverberation time wants, measured in the room’s actual shape rather than assumed for a box.

Leaves that touch and sound alike are then gathered into rooms by union-find over the portal graph, widest portals first, merging only while the merged average still sounds like both halves. A hall the tree cut into twenty leaves is one hall again; a doorway is a boundary because the two sides disagree. One record per room goes in the map, and a leaf-to-room table beside it.

Radiance: lighting

Every lit face carries a grid of luxels. For each, find where it sits in the world and ask every light whether it can see it, then bounce.

Two details do most of the work of making it look right. Grid points near the edge of an angled face fall inside neighbouring geometry — left alone they bake black and produce a dark rim around every surface, so they are pulled toward the face centre until they clear. And shadow rays start slightly off the surface, because starting exactly on it means the first thing every ray hits is the face it came from.

Runtime

The tick

Fixed at 64 Hz, decoupled from rendering. A 240 Hz display draws 240 smooth frames of a 64 Hz simulation, not 240 simulations. The catch-up accumulator is capped so that a stall — a breakpoint, a window drag — does not produce a burst of hundreds of ticks that looks like the world fast-forwarding.

Each tick:

1. Categorise the player’s position: are they standing on something?
2. Friction, then acceleration, then the move itself. That order matters: running friction after acceleration makes ground movement mushy and breaks air strafing entirely.
3. Update triggers from the player’s box.
4. Run the entity queue: deliver due events, run thinks, reclaim removals.

Collision

Traces work against brushes, not triangles. A brush is a handful of planes, so testing one is a handful of dot products regardless of how detailed its surface is, and the BSP narrows the search to the brushes actually along the path.

Brush entities — doors, platforms — are separate models kept out of the world tree so they can move without re-splitting it. They are traced separately and the nearest hit taken. Forgetting that is how you walk through every door in the game.

Rendering

What to draw is decided long before the GPU is involved:

1. Find the viewer’s cluster.
2. Take its PVS row — the clusters that can possibly be seen.
3. Frustum-cull the leaves in those clusters, then their surfaces.
4. Draw what is left, batched by material.

The PVS and the frustum do different jobs and neither subsumes the other: the PVS removes rooms you cannot see through any opening, the frustum removes what is behind you.

Brush entities are a second pass, and have to be. A door, a lift, anything tied to a class is compiled as its own model with its own leaves, and those leaves are not in the world’s PVS. A leaf walk therefore finds the world and nothing else — which is exactly what happened: every brush entity in every map was built into the mesh and never drawn, and the sample map’s door was simply not there. They are drawn after the world, one model at a time, culled against the frustum by their bounds rather than by the PVS. There are a handful of them, they are the things the player walks up to, and culling one wrongly costs far more than drawing it.

Each carries a displacement — where its entity has moved to — applied in the vertex shader through a uniform with a dynamic offset. That displacement comes from the same fields the collision code traces against, so what you see and what you walk into are the same thing by construction.

Lightmaps pack into one atlas per section, so a section draws in as many calls as it has materials rather than one per face.

Streamed sections

A map can be more than one machine wants resident at once. Chisel lets the designer mark a visgroup as streamed; Cleave numbers those visgroups as sections after the always-loaded world (section 0) and tags every world face and brush with its section. At runtime kerosene_engine::streaming decides, once a tick, which sections should be resident:

• the world, always;
• any section with a face in a cluster the player’s cluster can hear — the PAS, which is the PVS flooded one doorway further. A room therefore starts loading a doorway before it can be seen, and that doorway is the margin that hides the build;
• any section an awake physics prop is inside, so a crate thrown into the next room does not fall through a floor that has since gone.

A section that stops being wanted lingers sv_stream_linger seconds before it is dropped, so pacing over a threshold does not thrash. With no vis data, with the player outside the world, or with sv_stream 0, everything is wanted.

What streams is the expensive part and only that: each section’s render mesh and lightmap atlas, built on a worker thread from the shared BSP and uploaded on the main thread, and its rigid-body hulls. The BSP tree, the entity list, the player’s traces and entity I/O are whole whatever is loaded — the tree is small, the traces have to work everywhere, and a logic_relay in an unloaded room still fires. Brush entities are never streamed: a door is drawn and collided with wherever it has moved to. This is sections of one map, not an open world: everything is still one .kbsp, compiled and lit as one.

r_stream_debug 1 draws each section’s bounds in the colour of its state. content/maps/two_rooms.kmap in Kerosene Demo is a small map with two streamed rooms.

Entities

Entities are a bag of named fields rather than typed structs, because the meaningful fields belong to the game, not the engine. Classes are registered handlers — the same split Source draws between its engine and its game DLL. kerosene-entity knows how to route an input; the game – kerosene-game for the stock classes, yours through the Game trait – decides what Open means.

Outputs become queued events even at zero delay, so an entity firing at itself cannot recurse into the stack, and ordering does not change when a delay is added. Handles carry a generation, so an event naming an entity that died before it fired resolves to nothing rather than to whoever took its slot.

Testing

Where a subsystem can be tested without a GPU or a window, it is:

• Movement runs against a hand-built box world — a floor, a step, a wall — rather than a compiled map, so a failing test is a movement bug rather than a map bug.
• Shaders are validated through naga, the same compiler wgpu uses, so a typo fails in CI rather than at pipeline creation on a machine with a display.
• The whole pipeline is exercised by tests that build a .kmap in memory, compile it through Cleave, load the result and play it. Every crate can pass its own tests and still not add up to a level you can walk around; that suite is where the seams show.

Sound

Six layers, separable on purpose.

Sound has a compiled form as well as a source one. timbre turns .wav into .kaud, which is a quarter the size, carries loop points and a peak, and records whether the sound may be positioned at all. The engine prefers it and falls back to the .wav when there is no compiled form — so a designer who has just dropped a file in hears it without running a build first, and a shipped game carries only the small one. See tools.md.

The split is the whole design. Everything that decides how a sound sounds — falloff, panning, resampling, voice limits — is arithmetic on buffers with no hardware in it, so a sound that pans the wrong way is a numeric fact rather than something to notice by ear on the third playthrough.

The mixer runs whether or not a sound card does. If audio only existed when a device opened, then everything about a game’s behaviour that touches sound — how many voices a trigger starts, whether a looping ambience got stopped — would differ between a machine with sound and one without, and only one of those would ever be tested. A missing device costs the last hop to the speakers and nothing else.

Playing something

play ui/click            # at the console
stopsound                # everything, now
snd_restart              # reopen the device, forget every decoded sound
volume 0.5               # master, archived
snd_reverb_preset hall   # hear a hall everywhere; empty to hear the map's rooms
snd_acoustics_debug 1    # say which room you are in as you move; 2 draws them

From a level: an ambient_generic entity, or a script.

play_sound("ui/click");                                  // heard flat
play_sound("door/move", Vector(256.0, 256.0, 64.0));     // from a place
play_sound("door/move", find_by_name("gate").origin, 0.5);
stop_sounds();

.ksnd — sound scripts

A level fires door/move, and what that is lives in a script rather than on the entity. The same indirection materials have, for the same reason: making every door in a game quieter should be one edit, not a hunt through a map.

sound
{
    "name"        "door/move"
    "file"        "sound/door/move.wav"
    "volume"      "0.9"
    "pitch"       "1.0"
    "loop"        "0"
    "distance"    "128"     // full volume within this radius
    "attenuation" "1.0"     // how fast it falls off past it; 0 never does
    "max"         "2048"    // not heard at all past this
}

Every .ksnd under scripts/ loads at startup, later files overriding earlier ones so a mod can change one sound without copying a file. A name nothing defines is taken as a path under sound/, so play ui/click.wav works before anyone has written a script.

How a sound is heard

• Inside distance it is at full volume. Without that radius a sound at the listener’s own position divides by zero, and one a step away is much quieter than one underfoot — neither of which is how hearing works.
• Past it, inverse-distance falloff scaled by attenuation. Zero carries forever, which is what music and a level-wide ambience want.
• The last quarter of the range fades out, so a sound does not audibly switch off as you step past its limit.
• Panning is constant-power: the two gains square-sum to one, so a sound crossing in front keeps the same loudness instead of dipping in the middle.
• Gains ramp rather than jumping. A discontinuity in a waveform is a click, and a sound moving past the listener changes gain every block.
• 64 voices at once, and the quietest gives way. A trigger firing every tick would otherwise stack thousands of copies of the same sound, which is both deafening and slow.

How a room sounds

A sound in a level is heard through the level: an empty concrete hall rings, a carpeted office is dead, a shout across a courtyard loses its consonants, and a door between you and a radio turns it into a murmur. None of that is placed. Resonance measures it from the map’s shape and materials at compile time, and the engine reads it back every tick.

The room. The map carries one record per room — a set of leaves that sound alike — saying how long sound lingers there in each of four bands, how soon the first echo returns, how open to the sky it is, and how loud the room is next to the sound itself. The mixer has one reverb, a feedback delay network with eight lines and a per-band loss in each loop, and every tick the engine hands it the record for the room the listener’s ears are in. Only the listener’s room: a sound in the next room over is heard through this room, which is how it works in a building. Near a doorway the two rooms’ figures are blended by distance, so stepping through one is a slide rather than a switch, and the reverb slides its own parameters over a fifth of a second on top, so nothing clicks.

Air. Every positioned sound is low-passed by its distance — 2 kHz at 4096 units, an octave lower for every 1233 beyond — because air really does eat the highs, and a shout across a field should not arrive with every consonant intact.

Walls. For every positioned sound the engine asks two questions. Is the sound’s cluster in the listener’s potentially audible set — the PVS grown by one room, which Umbra writes and this is the first thing to read? If not, no path exists and the sound is silent. Otherwise, how many of three lines from the ear to the sound — one straight, one to either side — are blocked? A wall blocks all three and the sound comes through 12 dB down with nothing above 800 Hz; a doorway lets one or two through and the sound comes round it thinned rather than cut. Being in the same room halves the effect: a pillar between two people in a hall is not a wall. Up to 24 sounds are re-traced each tick, the rest keeping last tick’s answer until their turn.

What the compiler looked at. Every surface’s absorption per band comes from its material — from $surfaceprop, or from an explicit $acoustics key (see formats.md). A designer who wants a room to sound a particular way regardless places an env_acoustic_override in it.

Everything above is arithmetic on buffers with no device in it, like the rest of the mixer. The reverb’s decay times are checked in a test by measuring them off its own impulse response; the compiler’s are checked against Eyring’s formula for a concrete cube. A room that rings wrong is a number, not a feeling.

ambient_generic

The entity every level uses more than any other sound mechanism.

Inputs: PlaySound, StopSound, Toggle, Volume. Output: OnPlay.

Formats

16-bit PCM WAV is the common case and what the sample content ships. Also read: 8-bit (unsigned, centred on 128), 24-bit, 32-bit PCM, and 32-bit float, mono or stereo, at any sample rate — anything not matching the device’s rate is resampled. WAVE_FORMAT_EXTENSIBLE headers are read through to the real format, which is what a modern recorder writes.

The decoder is written out rather than pulled in, because a decoder is somewhere an unexpected file should produce an error rather than a panic: a chunk claiming more bytes than the file holds is normal, not an attack, and takes what is there.

Building without audio

cpal needs ALSA headers on Linux (libasound2-dev). If that is not available:

cargo build --no-default-features -p kerosene-runtime

Everything except the last hop to the speakers still builds, and the whole mixer test suite still runs.

The console

The developer console opens with the key left of 1 (`, ~). It runs commands and sets convars the way Source’s does, and so does everything else that runs text: a key binding, autoexec.cfg, a +command on the command line, a layout’s command(), a map’s script.

• name prints a convar and its help; name value sets it.
• ; separates commands, // starts a comment, quotes keep a phrase together.
• Tab completes a command’s name, and then its argument where that is a map, a save, a sound, a class or a convar. Pressing Tab again cycles.
• Up and down walk history, which is kept between sessions in cfg/console_history.txt beside config.cfg.
• find <text> searches names and help; help <name> explains one.

Cheats

A command or convar marked cheat works only with sv_cheats 1. Turning sv_cheats off puts every cheat convar back to its default, so a noclip left on does not outlive the permission for it. toggle, incrementvar and revert respect the flag like typing does.

Developer commands

Video

r_fullscreen is 0 for a window, 1 for borderless fullscreen and 2 for exclusive fullscreen at the monitor’s own mode. It is saved like the other options, and the options menu has a switch for it. cl_fov takes 50 to 130.

The command line

game +map arena +sv_cheats 1     # any +command runs after config.cfg
game -w 1280 -h 720              # the window's size, over engine.kcfg's
game -fullscreen                 # or -windowed, over the saved r_fullscreen
game --headless 600 +map arena   # simulate without a window, then report
game --portable                  # keep saves and settings beside the content

--help (or -h on its own) lists the rest.

Where things are written

Everything the console writes – config.cfg, the history, screenshots, condump – goes into the player’s own directory (~/.local/share/<game>, %APPDATA%\<game>, ~/Library/Application Support/<game>), or with --portable into the content tree. Paths are virtual: nothing a command is given can reach outside that directory.

Configuration

The engine has settings that belong to no single map and no single project: which renderer to use, how big the window is, whether it syncs to the display. They live in one file at the top of the content tree:

engine.kcfg

The file always exists. The first program to look for it and not find it writes one with the defaults in it, so a fresh clone runs before anyone has edited anything, and a hand-edited file is read back on the next run.

The file

KeyValues, like everything else a person is expected to edit:

engineconf
{
    "renderer" "vulkan"
    "width"    "1280"
    "height"   "720"
    "vsync"    "1"
}

Every key is optional. A key that is absent falls back to its default, and a key that is wrong (a renderer nobody has heard of, a width that is not a number) logs a warning and falls back rather than refusing to start. A config must not be the reason the engine will not boot.

The renderer

The renderer defaults to Vulkan. The engine asks wgpu for the Vulkan backend first, and only falls back to whatever else the machine has when Vulkan is not there — with a log line saying it fell back, so the choice is never silent.

auto means “whatever wgpu would have picked”, which on Linux is usually Vulkan and elsewhere is Metal or DirectX 12. metal and dx12 exist for the reverse case: a machine with several backends where someone wants to pin one for a reason of their own.

Every program that draws a window reads the same setting — the game, Chisel, and the tool windows — so the renderer choice is made once, in the file, not per program.

File formats

Text where a person edits or reviews it; binary where the engine loads it. The runtime reads no source format: a .kmat becomes a .kmat_c in the build, as a .png becomes a .ktex.

Every coordinate in every one of them is in kerosene units – one kerosene unit is one inch, a player is 72 of them tall. Angles are degrees, times are seconds, and Z is up.

KeyValues

The text format .kmap, .kmat, .kdef and the compiled entity lump all use.

world
{
    "classname" "worldspawn"
    "skyname"   "sky_kero"
    solid
    {
        "id" "1"
        // faces follow
    }
}

Two properties drive the implementation. Keys repeat — a world holds many solid blocks — so entries are an ordered list, never a map; a HashMap would silently eat brushes. And order is meaningful, so round-tripping a map through the editor does not reshuffle it and produce a noisy diff.

Backslashes are literal, so materials\dev\grid survives intact. Only the escapes the writer emits (\", \\, \n, \t) are resolved on read.

.kmap — editable maps

versioninfo { "formatversion" "1" }
world
{
    "id" "1"
    "classname" "worldspawn"
    solid
    {
        "id" "2"
        side
        {
            "id" "3"
            "plane"    "(0 0 0) (0 64 0) (64 64 0)"
            "material" "dev/grid"
            "uaxis"    "[1 0 0 0] 0.25"
            "vaxis"    "[0 -1 0 0] 0.25"
        }
    }
}
entity { "id" "9" "classname" "info_player_start" "origin" "0 0 32" }

Brushes are planes, not vertices. A solid is the intersection of its faces’ half-spaces. That makes convexity structural — you cannot author a brush with a hole in it — and it is what makes CSG possible. The cost is that a solid’s actual polygons only exist once something computes them.

Each plane is written as three points, listed clockwise as seen from the front of the face, so the normal is (p0 - p1) × (p2 - p1). That looks like the wrong cross product and is not: every brush face ever written to a .map-lineage file depends on exactly this ordering.

Faces carry no UVs. They carry two texture axes — world vectors a point is projected onto — which is what makes texturing feel the way it does in a brush editor: drag a brush and the texture stays locked to world space.

Any object can carry any key. An entity is a bag of "key" "value" pairs and always was; a solid and a side are too. The keys the format defines (plane, material, the axes, and so on) become typed fields; every other pair round-trips untouched, so a key the game or a compiler pass invents later, or one a person types into Chisel’s key-value editor, is never silently dropped. Cleave reads two on a solid: "detail" "1" compiles the brush as detail without tying it to detail, and "section" "name" puts it in a streamed section by name. Brush and face keys never reach the compiled map; a brush that should mean something to the game is tied to an entity, as in Source.

The editor’s own blocks. What Chisel needs to remember that the game does not is kept out of the properties so it can never leak into the compiled entity lump. Every solid and entity may carry an editor block, and the root may carry visgroups, any number of group blocks, and a cordon:

visgroups
{
    visgroup
    {
        "name"    "Cave"
        "id"      "40"
        "color"   "90 200 120"
        "visible" "0"
        "stream"  "1"
        visgroup { "name" "Pool" "id" "41" "color" "120 170 255" }
    }
}
solid
{
    "id" "2"
    side { ... }
    editor { "visgroupid" "41" "groupid" "50" "color" "220 30 30" "comments" "back stairs" }
}
group  { "id" "50" }
cordon { "mins" "-512 -512 0" "maxs" "512 512 256" "active" "1" }

VisGroups nest, and hiding a parent hides its children. A visgroup with "stream" "1" is also a section: Cleave tags its brushes with it and the engine streams the section’s geometry in and out around the player (see .kbsp below). Groups are flat: objects that share a groupid select together. "visible" "0" in an object’s editor block is quick-hide. Every one of these blocks is omitted when it would say nothing, so a map that uses none of them is byte-for-byte the map it was before they existed, and a reader that predates them skips them. Visgroup and group ids share the map’s one id space with entities, solids and sides.

Meshes. Beside its solids, the world may hold polygon meshes – Source 2 Hammer’s kind of geometry: points and the faces between them, any shape, open or closed, concave if it likes.

mesh
{
    "id" "40"
    vertices
    {
        "v" "0 0 0"
        "v" "0 64 0"
        "v" "64 64 16"
        "v" "64 0 16"
    }
    face
    {
        "id" "41"
        "v" "0 1 2 3"
        "material" "dev/grid"
        "uaxis" "[1 0 0 0] 0.25"
        "vaxis" "[0 -1 0 0] 0.25"
        "lightmapscale" "16"
    }
    editor { "visgroupid" "41" }
}

One vertex a line, so moving one is a one-line diff. A face lists vertex indices clockwise seen from the front, the same winding a brush face’s plane points and a compiled face use. Axes and lightmap scale default the way a brush face’s do. A face that is not flat and convex is cut into triangles when it compiles. Meshes are detail: Cleave draws, lights and collides with them – each face backed by an invisible 8-unit collision slab, so every trace in the engine sees it – but never lets them split the tree, seal the map or block visibility. Block a space out in brushes; dress it in meshes. Only the world’s meshes compile for now; a brush entity carrying one is warned about and left out.

.kbsp — compiled maps

A header (KROS, a version, a 24-slot lump directory) followed by flat arrays of #[repr(C)] records. Every record is padding-free, so loading a lump is a bounds check and a cast rather than a parse.

The surfedge indirection. A face’s vertices are reached through a run of surfedges, each a signed index into the edge lump — negative meaning “walk this edge backwards”. Two faces meeting at an edge therefore share one edge record and one pair of vertex positions, which is what keeps their seam watertight no matter how the arithmetic rounds.

Plane pairs. Planes always live at indices 2k and 2k+1, so flipping one is index ^ 1. A node stores one plane index and its two children implicitly use the plane and its inverse.

Lightmap samples are ColorRgbExp32: three bytes and a shared exponent. That is what lets a baked lightmap carry values well above 1.0 — a bright sky, a lamp against a wall — in four bytes instead of twelve, and it is why the lighting can be tone-mapped at runtime rather than clipped at bake time.

Rooms. The two acoustics lumps took the directory’s two spare slots, so adding them moved no version. The first is an ACST header — the four band frequencies, then how many rooms and paths follow — and an 80-byte record per room: decay time per band, the absorption it was derived from, mean free path, pre-delay, openness, wet level, diffusion, a bounding sphere, volume, flags and a leaf count. The second is one u16 per leaf naming its room, 0xFFFF for a leaf in none. An empty acoustics lump is a map Resonance has not run on, the same way an empty visibility lump is a map without vis; the engine plays it dry and says so.

Sections. Version 2 added four slots for the streamed sections and kept one spare. A section is a visgroup the designer marked as streamed; Cleave numbers them in tree order after the world and tags every world face and brush with its number. The engine keeps the tree, the entities and the traces whole and streams each section’s render mesh, lightmap atlas and rigid-body hulls as the player moves. A compile always writes the lumps – one section, every face in it, for a map with no streamed groups – and a version 1 file is refused with a message to recompile.

Cubemaps. The last spare slot, so adding it moved no version either: a file from before it has the lump empty and reads as a map without probes. A KCUB header – version, face size, probe count – then each probe’s origin, then every probe’s six faces of RGB9E5 texels (three 9-bit mantissas and a shared 5-bit exponent: linear HDR in four bytes, on the same scale as the lightmap, 1.0 being a white surface lit to full). Radiance writes it from the env_cubemap entities, after baking the lightmaps the probes photograph. The face order and orientation are kerosene_bsp::cubemaps::face_basis – Kerosene’s own, since the renderer picks faces itself rather than using a hardware cube map. The next lump needs a version bump.

Every index in the file is validated at load. A dangling one becomes an out-of-bounds read deep inside the renderer, where the cause is invisible.

.kprt — the portal graph

Written by Cleave, read by Umbra.

VPRT1
<cluster count>
<portal count>
<points> <cluster a> <cluster b> (x y z) (x y z) ...

The winding’s own plane normal points toward the first cluster listed. Only portals between two non-solid leaves appear: sight does not travel through rock, so a portal with a solid side is not a portal.

.kwalk — the NPC walkmap

Written by Cleave, read by whatever drives NPC navigation. It is the answer to “where can NPCs go”, precomputed once at build time the same way the PVS precomputes visibility: the runtime asks a cheap question – is this point on a walkable face, and what is that face’s rule – instead of re-deriving it from the BSP.

A little-endian binary: a KRWL magic, a version, a face count, then one record per face holding its rule, its polygon and its normal. Cleave builds it from the world’s flat walkable faces – a face whose normal points up and wears ordinary geometry – and folds in each face’s walkmap rule chosen in Chisel:

• allow – walkable if flat. The default; a floor that says nothing is one.
• deny – never part of the walkmap, however flat.
• avoid – walkable, but flagged for NPCs to route around.
• always – part of the walkmap even if the face is not flat, for ramps.

Brush entities are absent on purpose: a door moves, and a static walkmap that said a closed door was open would send an NPC through it.

Navigation is built on top of the faces: kerosene-walk’s NavGraph links faces that share an edge and A*-searches them into a list of waypoints, with avoid faces given a movement-cost penalty so paths bend around them when a detour is not much longer. The runtime asks for a path the way it asks whether a point is walkable — cheaply, against data the compiler already produced.

The resource container

Compiled materials, textures and models share one layout, KRES, from the kerosene-resource crate. The rest (.kaud, .kbsp, .kwalk) still have a header of their own each, and move into it one at a time. A .ktex or .kmdl from before the container still loads: its old layout is exactly what the container’s DATA block now holds.

Then the blocks, each on a 16-byte boundary. Three tags mean the same in every kind: DATA is the payload; REFS lists, as virtual paths, the other resources this one needs, which a packager follows; EDIT records the compiler, its arguments, and each input with its hash, so a tool can tell a stale file. A reader skips tags it does not know. All integers are little-endian. alchemy info prints a compiled material’s header and blocks.

.ktex — textures

The resource container, kind KTEX. Its DATA block is a 48-byte header (dimensions, format, flags, average colour) then the mip chain, largest first. Uncompressed RGBA8, RGB8 or R8.

Mipmaps, the average colour Radiance needs for bounce lighting, and sampling intent are all resolved at build time. Doing them at load costs startup on every run, and doing them well is not something to redo per launch.

.kmat — materials

lit
{
    "$basetexture"   "dev/grid"
    "$bumpmap"       "dev/grid_normal"
    "$roughness"     "dev/grid_rough"
    "$selfillummask" "dev/grid_emissive"
    "$ao"            "dev/grid_ao"
    "$metalnessmap"  "dev/grid_metal"
    "$surfaceprop"   "concrete"
}

That is the source. Alchemy compiles each one to a .kmat_c beside it (kind KMAT): the shader is resolved and the text parsed at build time, and the textures it names go in the REFS block. The engine loads the .kmat_c. A project whose content predates compiled materials still runs from its .kmat files, with a warning for each, until its next build.

The block name is the shader — lit, unlit, sky, water, ui. A small closed set, because every one is a real code path; an open-ended string would just be a way to fail at draw time instead of load time.

Geometry references materials, never textures, so retexturing a level or making every metal surface reflective is one file change. Unknown parameters round-trip rather than being dropped: a game will invent keys the engine has never heard of.

The six texture parameters above are the ones the renderer samples. Every one but $basetexture is optional and absent by default, and a material that names none of them renders exactly as it would have before they existed — the shader branches on a per-material word saying which are real, so there is one pipeline rather than a variant per combination.

Two scalars go with the maps, the way glTF’s factors do: each multiplies its map, and with no map it is the whole answer.

Shading is GGX with height-correlated Smith and Schlick Fresnel – the model Source 2 and every other current engine settled on. A lightmapped surface reflects its nearest visible env_cubemap, blurred by roughness; one with no probe reflects an even glow the brightness of its own lightmap.

$surfaceprop is the physical type the surface is made of — concrete, metal, wood, and so on. It has two consumers. At runtime a trace that stops against a face reports the face’s material, and the engine reads that material’s $surfaceprop to choose a footstep sound (footstep/<type>/n). At compile time Resonance reads it for how much sound the surface soaks up, per band, from a table of the published figures for each type: carpet eats the highs, concrete eats almost nothing, snow eats almost everything. Unknown types parse to other rather than failing, so a game’s own surface names still work without the engine shipping them.

$acoustics overrides that, for the texture that looks like concrete and is meant to be acoustic tile: either four absorption coefficients for 125, 500, 2000 and 8000 Hz — "0.02 0.14 0.60 0.65" — or the name of a surface type to borrow them from, "carpet", leaving the footsteps as they were.

.kmdl — models

The resource container, kind KMDL, whose REFS block names every material the model draws with. Its DATA block is a 64-byte header, then vertices, indices, meshes, bones and a string table.

One model holds several meshes, each with its own material, because a single object routinely uses more than one. Splitting by material at compile time means one draw call per mesh instead of sorting at runtime.

Vertices carry four bone influences whether or not the model is skinned. Eight wasted bytes per vertex on a static prop buys one vertex layout, one shader path and no branch in the hot loop.

Bones are listed parents-first, so a single forward pass can build world transforms with no recursion and no sorting. A bone’s rest transform is its bind pose – the pose the mesh was skinned in – which is what the renderer inverts to move the mesh with the bones.

Animations (version 2). After the string table: one 16-byte record per clip – name, frame count, frames per second, a loop flag – then every clip’s keys, frame after frame, one 28-byte BoneKey (translation, rotation quaternion, both relative to the parent) per bone per frame. Clips are resampled at a fixed rate by Forge, so playing one is two lookups and an interpolation per bone. A version 1 file – every static prop compiled before animations existed – still loads, as a model with none.

Triangles are wound counter-clockwise as seen from the front – the convention the GPU renderer culls by, and the opposite of .kmap faces, which are clockwise. Forge takes an OBJ’s winding as-is (the axis remap preserves handedness), so the OBJ must already be counter-clockwise: a face wound the other way compiles and collides fine but renders inside out.

texture.kcfg — texture sets

A single PNG is not a surface. A surface is a colour, the bumps in it, how rough it is, what it glows with and where it self-shadows — five images that belong together and are useless apart. So a texture can also be a folder, under content/textures/:

content/textures/Walltextures/variant1/
    basecolor.png
    normal.png
    roughness.png
    emissive.png
    ao.png
    texture.kcfg      (optional)

It names itself from where it sits: Walltextures/variant1 compiles to Walltextures_variant1, and each map takes a suffix — _normal, _rough, _emissive, _ao. The path is already unique and already describes the thing, so restating it in a file would only be a second answer that can disagree with the first. Alchemy writes the matching .kmat wiring up whichever maps are there, once, and never overwrites one afterwards.

Filenames are matched generously (albedo, diffuse, col; nrm, bump; rough; glow, selfillum; occlusion) because those names come out of whatever tool baked them, and rejecting albedo.png because the engine wanted basecolor.png would be a rule that exists only to be tripped over. A folder with no base colour is not a set: the other maps modulate a colour, and with nothing to modulate they would compile into a material that draws the missing-texture checkerboard.

texture.kcfg is how you overrule any of that. Every key is optional — the point of the folder convention is that the common case needs no file at all:

texture
{
    "name"        "brick_red"     // instead of the folder-derived name
    "normal"      "weird_bumps.png"  // an image discovery would not find
    "shader"      "lit"
    "surfaceprop" "brick"
    "clamp"       "0"
    "point"       "0"
    "translucent" "0"
}

A key naming a file that is not there costs that one map, not the texture; a config that does not parse costs the config, not the folder. Losing a whole surface to a stray brace would be a poor trade.

To make one without editing anything by hand:

kerosene-tools alchemy new-texture Walls/brick     --basecolor brick.png --normal brick_n.png --surfaceprop brick

The images are copied in under their canonical stems, so the artist’s originals stay where they are and the content tree stays self-contained.

The loose art/*.png tree is unchanged and still compiles one image to one texture — right for a tool texture or a skybox, which have nothing to be a set with.

The developer texture set

Not a format, but content worth knowing the provenance of: alchemy dev-textures writes content/art/dev/ and content/art/tools/ along with their materials. The PNGs and .kmat files it writes are committed; only the compiled .ktex is not, because that is a build artefact.

dev/ are 256x256 checkerboards. At the default texture scale of 0.25 world units per texel that covers 64 ku, so the 4x4 grid on them reads as 16 ku cells – the size most brushwork is done at – with a fainter 4 ku subdivision over it. The checker is what makes a stretched texture obvious: a square that is not square is visible from across a room, where a stretched grid line is not. Only dev/measure carries numbers, because a world-aligned projection mirrors on opposite walls and text in a tiling texture therefore reads backwards on half of them.

tools/ are 128x128, flat, hatched, and labelled with their own name. A colour alone does not tell clip from playerclip at a glance.

They are generated because they are defined by numbers – this grid is 16 units, that colour means “blocks players” – and a definition that lives only in a PNG is one nobody can read or review. They are committed anyway, because a fresh clone with no textures in it is a fresh clone that looks broken: having a generator is a reason to keep one, not a reason to leave its output out of the repository. The generator reports what it changed and what was already correct, so re-running it on an unchanged tree is a no-op and a diff against it is meaningful.

Chisel runs the generator, and the batch compile after it, before it finishes loading. So a clone with the .ktex files missing – which is every clone, since they are build artefacts – still opens an editor with textures in it.

A test checks the set against the compiler’s tool-material table in both directions: offering a tool material the compiler treats as world geometry would silently wall off a doorway.

.kproj — the project file

Where a project says, rather than implies, where its content is.

project
{
    "name"     "My Mod"
    "content"  "content"
    "startmap" "mm_intro"
}

content is relative to the file, so a project can be cloned or moved anywhere and still be right. Every key is optional – an empty project { } block still marks a directory as a project, with content defaulting to a content/ directory beside it and then to the directory the file is in, which is the shape of a shipped game where the project file sits in the folder it describes. startmap is what kerosene loads when nothing else says which; a project that is a library of maps simply omits it rather than having one invented.

It exists because everything else about locating content is inference. The tools climb the directory tree looking for something shaped like a content root, which works, and is why a fresh clone needs no setup, and is still a guess – one nobody could overrule short of passing --content to every tool every time. A project file is the answer that wins.

Within any one place searched, a project file beats an inferred root even one found closer down: a stated answer that loses to a guess is not an answer. Between places, nearness still decides. The full order is in tools.md.

The content tree is created, not required

The directories under content/ — maps, materials, art, textures, models, sound, scripts — are made on first run by whatever starts first, the engine or the toolset, and any that are missing are filled in. A tree with one of them absent does not announce itself; it looks like whichever tool went looking for it being broken, which is the same class of problem the content-root search was written to end.

kerosene-tools init [dir] does it deliberately, writing a .kproj and the tree beside it. It is safe to run on an existing project: the project file is left exactly as it is, and only missing directories are created.

A project that wants a different layout says so, with repeated dir keys, and is believed — the same bargain as content:

project
{
    "content" "content"
    "dir"     "maps"
    "dir"     "materials"
    "dir"     "levels"
}

A project with no dir key gets the standard set, which is every project written so far. A dir naming a path outside the tree is ignored with a warning: the list is text somebody typed, and it does not get to create directories beside the project.

.kdef — entity class definitions

What an editor needs to know about the game’s entities: for each class, the keys it reads, the inputs it answers to and the outputs it fires. The engine never reads this — an entity there is a bag of whatever keys the map carries, and that is deliberate. The file exists so that a person placing a door is shown that speed and lip are things, instead of an empty panel.

It is the FGD relationship, and it is what keeps Chisel a separate program from the game: the editor reads the game’s file rather than linking its code.

base
{
    "name" "Entity"
    key   { "name" "targetname" "label" "Name" "type" "target_source"
            "help" "What other entities call this one." }
    input { "name" "Kill" "help" "Remove this entity from the map." }
}

class
{
    "name" "door"
    "kind" "brush"
    "base" "Entity"
    "help" "A brush that slides open and shut."
    key {
        "name" "spawnflags" "label" "Flags" "type" "flags" "default" "0"
        choice { "value" "1" "label" "Starts open" }
    }
    key    { "name" "speed" "type" "float" "default" "100" "help" "Units per second." }
    input  { "name" "SetSpeed" "parameter" "units per second" }
    output { "name" "OnFullyOpen" }
}

kind is point, brush or any, and decides which menu a class appears in. A class may name several base blocks; their keys, inputs and outputs come first, and a key the class redefines wins. Key types are string, int, float, bool, vec3, angles, color, target_source, target_destination, material, model, choices and flags — the set is closed, so an unrecognised type is an error at load rather than a text box at edit time.

A class may also declare helpers: what the editor draws for it beyond its marker – the FGD’s studio(), lightcone() and sphere(). They change nothing in the game.

class
{
    "name" "light_spot"
    "base" "Entity" "base" "Point" "base" "Angles"
    helper { "type" "lightcone" }
    helper { "type" "lightradius" }
}
class
{
    "name" "ambient_generic"
    helper { "type" "sphere" "radius" "radius" "color" "120 230 220" }
}

A numeric parameter is a number or the name of a key: "radius" "radius" reads the entity’s own radius, "radius" "256" is always 256. Helpers are inherited from bases like keys, and a class’s own helper of a type replaces an inherited one. Two need no declaring: a class with a model-typed model key is drawn as its model, and every target_destination key draws a line to what it names. An unknown helper type is an error at load, naming the class.

Files are merged in sorted path order and a later definition of a class replaces an earlier one, so a mod can drop its own file beside the game’s.

A default is what the game assumes when a key is absent. Chisel shows it greyed rather than writing it into the map, so a .kmap only carries the keys someone chose — which is what makes a diff between two saves readable.

content/kerosene.kdef describes the sample game, and a test in kerosene-game checks it against the class registry in both directions: an input the game handles and the file does not offer is a build failure, and so is an input the file offers that nothing handles.

.kscr — level scripts

A map’s script, loaded automatically when the level starts if it is named after the map. The language is Rhai; the API, the hooks and the limits are in scripting.md.

fn on_map_start() {
    for door in find_by_class("door") {
        print(`${door} at ${door.origin}`);
    }
}

Nothing about the format is special — it is source text the engine hands to a VM. It is listed here because it is content the engine loads by name and packs into a .vault with everything else.

.ksnd — sound scripts

What a sound name means: which file, how loud, how far it carries. The format and the model behind it are in audio.md.

.vault — content archives

[ header 40 bytes ][ directory, sorted by path ][ data blob ]

Each directory record is path_len:u16, path, crc32:u32, offset:u64, size:u64. Paths are stored already normalised, so a lookup is a binary search with no per-query allocation.

Reads are checked against the stored CRC. A corrupt archive — a truncated download, a bad copy — is far better caught at the read than as a garbled texture three subsystems later.

Output is byte-for-byte reproducible: insertion order does not leak into the file, which matters for patching and for diffing releases.

Virtual paths

Asset paths arrive in every spelling — Materials\Dev\Grid, materials/dev/grid, ./materials//dev/grid — and all resolve to one key: lowercase, forward slashes, no redundant parts.

Paths that climb above the search root are refused, not clamped. Map and material files are untrusted content that ships between users, and ../../../../etc/passwd in a $basetexture must not resolve to anything.

Search paths are consulted in the order they were added, first hit wins, and loose files shadow packed ones — so during development you drop a file next to a shipped archive and it takes effect immediately, with no repack.

Licensing

Kerosene is licensed under the GNU General Public License, version 3 or later, with the Kerosene Exception — additional terms under the GPL’s section 7. Both texts ship in the repository, LICENSE and LICENSE-EXCEPTION; Cargo.toml declares license = "GPL-3.0-or-later WITH AdditionRef-Kerosene-Exception-1.0", and every source file carries the matching SPDX-License-Identifier line.

AdditionRef- is SPDX’s prefix (from version 2.3) for an addition to a licence that is not on SPDX’s own list of exceptions, which the Kerosene Exception is not. It is what makes the expression one that tools can read: Cargo, cargo-deny and anything else that audits a dependency tree see the GPL and the Exception — including its permission to link Kerosene statically — rather than refusing the line or reading it as the GPL alone. Earlier versions spelled it LicenseRef-Kerosene-Exception-1.0, which SPDX does not allow after WITH; the terms are the same.

NOTICE states what that means on one page; this document explains the reasoning, walks the exception clause by clause, and then does the dependency audit.

I am not a lawyer and none of this is legal advice. It is an accurate inventory plus the reasoning behind the choice, so that you or an actual lawyer can move quickly.

What the licence means here

The GPL on its own would make any program that links Kerosene a covered work: a game built on it would have to be GPL too. The exception changes that, and only that.

A game built on Kerosene is yours. The exception’s section 1 is an additional permission: link Kerosene, statically or dynamically, into a game and convey the game under terms of your choice — closed, commercial, whatever you like. Your code, levels, scripts and assets are yours. The conditions:

• the engine part of the game — Kerosene, plus any change you made to it — stays under the GPL with the exception, with its source available as the GPL requires;
• the game carries a notice that it is built with Kerosene and says where the engine source is (kiln --ship writes it);
• the game shows an attribution screen when it starts — “Built with Kerosene”, before or together with its first interactive screen. Brief and dismissable is fine; disabled or hidden is not. A program with no graphical interface prints the same line instead;
• if the engine is modified, the whole modified engine is published as source where anyone can obtain it free of charge, not only offered to the people who receive the game.

A modified engine is a modified Kerosene, whatever it is called and wherever the changed files are put — a copy of movement.rs inside your game crate is still the engine. Convey one, alone or inside a game, and section 2 of the exception asks that it say plainly that it is “modified from Kerosene” or “built from Kerosene”, name the version or commit it diverged from, and link to Kerosene’s source — in its own notice, in the notice of every game built on it, and on the attribution screen of every game built on it. It must not present itself as the original or as endorsed by this project, and it must carry the attribution-screen requirement forward so that games on the fork still show where they came from.

The Kerosene name is not granted by the licence. A fork may call itself Kerosene-something only if it does the above and publishes its complete source, as one engine rather than as changed files, under the same terms. Any other name owes only what the GPL and the exception say.

The tools — Chisel, the compilers, Kiln — are under the same terms. The linking permission covers them too, so a game’s own mygame-tools binary built on kerosene::tools ships the same way the game does. An unmodified tool distributed on its own is a plain GPL binary: ship it with its source.

Why the GPL with an exception, and not the LGPL or the MPL

Kerosene began under LGPL-3.0-or-later, then offered MPL-2.0 as an alternative arm. Each had the flaw the other fixed:

• The LGPL’s mechanism is relinking. It assumes a user can swap the library inside a program for their own build, and Rust’s default static linking makes that a chore for anyone shipping a closed game — C-ABI plumbing, or an object-file distribution step cargo does not do. None of it bites at development time; the moment a binary leaves the door it demands work.
• The MPL’s unit is the file. It has no linking stage, so it asks nothing of a closed game — but it also asks nothing of a modified engine beyond the files that changed, and nothing at all of a fork that presents itself as something new. The derivative-engine policy had to live outside the licence, as a condition on using the name.

GPL §7 gives a licensor the two levers that fix both at once. An additional permission may be granted on any conditions the licensor likes, because a recipient who declines the conditions simply has no permission and the plain GPL applies. That is the linking exception: it does what the LGPL does for a game — keep your code, keep the engine open — without the relinking clause, and its conditions carry the policy the MPL could not. And §7 (b)–(f) allow a short list of additional requirements — preserved notices, marking of modified versions, no misrepresentation, limits on the licensor’s name — that cover the rest of the policy and that a recipient cannot strip.

Nothing in the exception is a “further restriction” in §7’s sense. Every requirement is one the section names, and every condition sits on the permission rather than on the GPL.

The exception, clause by clause

A recipient may remove the §1 permission from their copy, as §7 allows, and be left with the plain GPL plus §2. Nobody can remove §2.

The engine does not yet draw the attribution screen for you: a game adds one through Game::ui today, and an engine-drawn one that satisfies §2(e) by default is a listed gap in Missing features. The obligation is on the shipped program either way.

Third-party dependencies

325 distinct crates in the workspace dependency graph (normal edges, all targets). Two facts matter more than any list:

• Every licence in the tree is GPL-3.0-compatible. Apache-2.0 is compatible with GPL version 3 (not 2, which is one reason the project is 3-or-later), and MPL-2.0 lets its files be combined into a GPL work through its own §3.3. A copyleft dependency is ordinary here rather than something to quarantine.
• No GPL crate appears at any depth, and no LGPL or AGPL crate either. Kerosene is the only whole-work copyleft in a game built on it, and the exception is what decides what that asks of the game. Nothing in the tree adds an obligation of its own beyond a notice.

The only copyleft-licensed dependencies are MPL-2.0:

(Counts are per dependency edge, so a crate pulled in by several others is counted more than once. Regenerate them with the command below; the table is a snapshot and the command is the truth.)

Regenerate with:

cargo tree --workspace --edges normal --prefix none --format '{p}|{l}'

The MPL-2.0 rows above are smartstring and Symphonia’s six crates.

box3d-rust (MIT) sits in the plain-MIT bucket and backs kerosene-physics’s PhysicsWorld, the rigid-body simulation. It is a pure-Rust port of Erin Catto’s Box3D with no dependencies of its own and no build script, chosen over a Jolt FFI wrapper specifically so the tree never has to vendor a C++ physics library, carry bindgen output, or require a C++ toolchain to link it.

Steamworks, which only a Steam build links

The steamworks crate (MIT OR Apache-2.0) and the steamworks-sys crate under it are behind the opt-in steam feature of kerosene-platform, which is off in every default build. What they bind, and carry, is Valve’s Steamworks SDK: its headers and its redistributable steam_api libraries. The SDK is not free software, and is distributed under the Steamworks SDK Access Agreement.

That is why it is a feature and not a dependency. The Kerosene tree vendors none of the SDK, and nothing in the default build links it. The table above describes the default build, so the SDK is not in it.

A game that turns the feature on is a Combined Work under the Exception, with the SDK as an Independent Module, which §1 permits. The engine part stays GPL with its source available; the SDK stays under Valve’s terms. The GPL alone would not allow the combination, and this is one of the things the Exception is for. kiln --ship --steam writes a notice saying all of this into the shipped README.txt.

The two MPL-2.0 dependencies

What MPL-2.0 asks: file-level copyleft. A shipped, unmodified binary carrying MPL-2.0 code owes a notice — the licence text and a statement of where the MPL source lives. Modified MPL files must be released as source under MPL-2.0. It reaches nothing else.

smartstring, which the engine does link

smartstring 1.0.1 (MPL-2.0+)
└── rhai
    └── kerosene-script → kerosene-engine

Scripting pulls it in, so it is inside kerosene and inside every game built on it. A shipped game therefore carries MPL-2.0 code, and the obligation that travels with it is the notice — the same shape as the OFL and Ubuntu font obligations that egui brings, and satisfied the same way. kiln --ship writes that notice into the distribution’s README.txt, so a build made with it is compliant without anyone remembering to be.

glTF, which only a build tool links

gltf  gltf-json  gltf-derive  serde  serde_derive  serde_json

MIT or Apache-2.0, all reached only by forge, which reads .gltf and .glb sources. The engine reads the .kmdl Forge writes and never links these, for the same reason as Symphonia below: a tool is never shipped.

Symphonia, which only a build tool links

symphonia  symphonia-core  symphonia-common
symphonia-metadata  symphonia-bundle-flac  symphonia-bundle-mp3

All MPL-2.0, all reached only by timbre, which reads FLAC and MP3 sources. kerosene-audio decodes what a player’s machine loads and is hand-written for that reason; Timbre is a compiler that runs on the machine making the content, and kiln --ship refuses to put a tool in a distribution at all. So no game ever ships these, and no game developer inherits anything from them. Alchemy made the same call first, pulling in image for PNG and JPEG while the engine reads only .ktex.

Admitting them was a choice with poor alternatives. There is no maintained, permissively licensed, pure-Rust MP3 decoder: the options were Symphonia, a C library through bindings — which would put a C++ toolchain in the build and wreck the cross-compilation story kiln --ship depends on — or writing an MP3 decoder by hand, which is several thousand lines of solved problem. FLAC alone could have used claxon (Apache-2.0); MP3 forced it.

The four that actually matter

Apache-2.0-only crates.

winit  cpal  ab_glyph  ab_glyph_rasterizer
owned_ttf_parser  spirv  codespan-reporting  gethostname

Apache-2.0 decided the GPL version: it cannot be bundled under GPL-2.0, but it can under GPL-3.0, and Kerosene is 3-or-later. The list is kept here because it is the set of crates whose “Apache-2.0 only” status is worth knowing if anyone ever forks with different terms in mind.

Bundled fonts — epaint_default_fonts and egui-phosphor. egui ships default typefaces under the SIL Open Font Licence 1.1 and the Ubuntu Font Licence 1.0, and egui-phosphor (MIT OR Apache-2.0) embeds the Phosphor icon font, itself MIT. Those travel inside any binary linking egui, which here means the toolset and the engine’s debug overlay. Both licences permit redistribution; both require their notices to be preserved, and OFL forbids selling the fonts on their own and imposes a Reserved Font Name rule if you modify a font. Shipping them unmodified inside an application is exactly the intended case. If you publish binaries, ship the font licences alongside them.

hexf-parse is CC0-1.0. A public-domain dedication, so it imposes nothing — but some corporate policies flag CC0 because it explicitly does not grant patent rights. Irrelevant for a hobby or open-source release; worth knowing if this ever goes near a company’s legal review.

dpi is Apache-2.0 AND MIT — conjunctive, not a choice. Both sets of terms apply. Both are permissive, so this changes nothing practical.

Content in this repository

Everything under content/ was made for this project:

• content/art/**.png — flat-colour and procedural developer textures (256x256 and 128x128), authored here. No metadata, no third-party source.
• content/art/props/crate.obj — hand-written vertex list.
• content/maps/kerosene_room.kmap — emitted by crates/kerosene-map/examples/starter_room.rs from kerosene_map::starter, i.e. generated by code in this repository.
• The demo level, which used to be here, is in its own repository, kerosene-demo, made the same way.
• content/materials/**.kmat — hand-written KeyValues.

Nothing was extracted from, decompiled from, or converted out of any game. Every compiled artefact (.kbsp, .ktex, .kmdl, .kprt, .vault) is a build output, reproducible with scripts/build-content.sh, and is not committed.

Provenance of the algorithms

This is the part worth being honest about, because it is the only place the question has any teeth.

Kerosene implements techniques that are decades of published graphics research: BSP trees for solid geometry and draw order (Fuchs/Kedem/Naylor 1980; Naylor/Amanatides/Thibault 1990), portal-based PVS precomputation (Teller’s 1992 dissertation), radiosity lightmapping (Goral et al. 1984), Sutherland–Hodgman clipping (1974), Gribb–Hartmann frustum extraction. None of that is anyone’s property.

id Software’s Quake tools are a famous implementation of several of them, released under GPL-2.0, and Valve’s Source engine descends from that lineage. Some modules here follow that implementation’s structure closely enough that a reader would recognise it:

All of it was written from scratch in Rust, against descriptions of the algorithms rather than by transcription; the naming, types, error handling, data layout and tests are this project’s own. US copyright does not extend to “any idea, procedure, process, system, method of operation” regardless of how it is described in a work (17 U.S.C. §102(b)), and the constants that are copied — an epsilon of 0.1, an air-speed cap of 30, a table of six axis vectors — are facts about a behaviour being deliberately matched, not creative expression.

That is the reasoning. It is not a guarantee, and the honest framing is: following the structure of GPL-2.0 source is lower risk than copying it and higher risk than never having read it. Every place it happens is named in a source comment and in the table above, so nothing is hidden.

The choice of licence does not change this, and it is worth being explicit about why, since picking a licence might look like an answer to it. It isn’t. A licence governs what this project grants downstream; it cannot clear anything upstream. Being GPL-licensed ourselves is about combining code going forward, not about taking code out of a GPL-2.0 work — GPL-2.0 code could not be moved under GPL-3.0-or-later with an exception in any case, because the GPL does not permit relicensing its code without the author’s permission. What actually lowers the risk is what the project already does: ship no Valve or id content, define formats theirs cannot read, and state provenance plainly.

Names and trademarks

“Valve”, “Source”, “Hammer”, “Quake” and the rest appear throughout the docs and comments. That use is nominative — naming someone else’s product in order to say what a thing here is analogous to. It is the same use as “works like Photoshop”. It is not branding: nothing in this project is named after a Valve product, no Valve mark appears in a binary’s name, icon or UI chrome, and NOTICE disclaims affiliation explicitly.

The file formats were renamed for exactly this reason. .vmap, .vmat, .vmdl and .vtex — the extensions this project originally used — are Source 2’s real extensions, and .lin is the leak pointfile Hammer loads. They are now .kmap, .kmat, .kmdl, .ktex and .kleak, and the two binary magics that named Valve formats (VTEX, VMDL) are now KRTX and KRMD.

The engine’s own name changed once too, for a plainer reason: it was VoidEngine until August 2026, and an unrelated engine built on id Tech 6 already had that name. Nothing was shared with it and nothing needed clearing; the collision was simply a collision. The extensions moved with the name — .voidmap became .kmap, and the magics VOID, VOTX, VOMD and VOAU became KROS, KRTX, KRMD and KRAU — so a file written by either version says which it came from.

Consequences of the choice, in one place

For contributors. Patches to Kerosene’s own files are offered under the same terms — GPL-3.0-or-later WITH the Kerosene Exception. That matters more than it would for a plain GPL project: the exception is an additional permission, and a contribution offered under the GPL alone would carry no such permission, so the file it touched could no longer be linked into a closed game. There is no CLA; the SPDX line in every file records the terms, and sending a pull request is accepting them.

For someone forking the engine. The whole modified engine is under the GPL with the exception. It says “modified from Kerosene”, names the version or commit it diverged from, and links to Kerosene’s source — in its notice, in the notice of every game built on it, and on their attribution screens. Ship a closed game on it and the fork’s whole source is published where anyone can get it. Call it Kerosene-something and the same publication is the price of the name. The project’s preference, every time: contribute the change back as a pull request and use the updated engine, so the fix exists once rather than once per fork. Forks and derived engines has the three cases side by side.

For someone shipping a game. Your game is yours. You owe the licence texts, the notice with a source pointer, and an attribution screen at start; kiln --ship writes the first two and the Shipping checklist has the third. There is no relinking clause and nothing resembling one.

For someone shipping the tools. Chisel and the compilers are under the same terms. A game’s own tools binary is a combined work like the game and ships the same way. A tool on its own is a GPL binary: distribute the source with it.

Fonts, again, because it catches people. Any binary linking egui — the toolset, and the engine’s debug overlay — carries OFL-1.1 and Ubuntu-Font-1.0 typefaces inside it, and the toolset carries the MIT Phosphor icon font too. All three licences are satisfied by shipping their notices alongside the binary. None conflicts with the GPL, because the fonts are data travelling with the program rather than part of it.

And smartstring, for the same reason. It is MPL-2.0 and it is inside the engine, so a shipped game carries it and owes its notice. kiln --ship writes that too.

What the licence does not do. It does not make the provenance question above go away, in either direction. Copyleft is a statement about what you grant downstream; it is not a clearance of anything upstream. What actually keeps this project clean is what it already does: ship no Valve or id content, define formats theirs cannot read, and name every module that follows the structure of published work.

Missing features

An inventory of what Kerosene does not have yet, in four parts: what the code reveals that the docs did not admit, what the docs already admit, what is absent by subsystem, and what the mainstream engines have that is worth borrowing – and what is not. Read it as a candidate roadmap, not a bug list: several of these are deliberate design choices (a flat entity list, a closed shader set) and several are simply unstarted. The last section puts an order on it.

For which of these absences actually matter – and which genres the engine is shaped to serve – see positioning.md. Everything here is weighed against that document’s answer: a movement shooter or an immersive sim first, geometry-heavy and animation-light.

1. What the code says that the docs did not

These were found by reading the tree rather than the README, and each is either a correctness gap or a thing whose absence undercuts a claim made elsewhere in these docs.

• The view is not interpolated between ticks. Fixed: the host reads Engine::interpolation_alpha() and takes the view angles from the latest input rather than the last tick.
• No continuous integration. Fixed: .github/workflows/ci.yml runs fmt --check, clippy -D warnings and the tests on Linux, and builds on Windows and macOS.
• No panic hook, no crash log. Fixed: kerosene_console::install_crash_handler writes crash.log beside the binary with the panic, a backtrace and the last 64 log lines.
• No demo recording. The most conspicuous Source feature not here, and the one the architecture most obviously supports: the tick is fixed, the simulation runs headless, and input arrives as an InputState per tick. Recording those is nearly free and buys replays, ghosts for the time-trial genre, bug reports that reproduce, and a regression harness for the movement solver. The determinism claim in positioning.md is unproven until something replays.
• No game-state serialization at all. Fixed: saved games are JSON through serde, level changes carry state across, and saves mirror to the store’s cloud. See Saving and level changes.
• volume is the only sound convar an options screen could set. There is no separate music or effects volume.
• kerosene-ui is not a UI toolkit. Fixed: the tools’ egui host is now kerosene-toolui, and kerosene-ui is the game UI (section 8).
• Chisel is a fifth of the codebase in one crate. About twenty-eight thousand lines now that the GPU viewport has landed in it (as gpu/); the renderer, the geometry (brush_edit, shapes, faces) and the egui layer would split cleanly.

2. Already acknowledged

These come straight from the README’s known-limits section and are kept here for completeness.

• Networking. The simulation runs headless (the hard part is done), but there is no client/server wire protocol, no snapshot, no prediction, and no replication.
• Skeletal animation. Playback exists: Forge imports skinned glTF with its clips, the renderer skins on the GPU, and prop_dynamic plays, switches and crossfades clips. See section 5 for what is not there.
• Chisel 3D view. Software-rasterised. It renders on the GPU now, with props drawn as their models and entity helpers (section 19). Still no lighting or shadow preview: the view is flat-shaded.
• Texture block compression. .ktex is uncompressed; no BCn. The README’s reason – a bad encoder is worse than none – no longer holds: intel_tex_2 and texpresso are pure-Rust BC7 encoders that are good enough.
• Mipmaps at runtime. Fixed: the whole chain is uploaded.
• Texture dimensions in the BSP. Fixed: Cleave reads each material’s compiled texture (from the project found next to the map, or --content) and writes its real size, warning by name for any it cannot find. Maps compiled before this carry the old 512 and want a recompile.
• Audio. Stereo only. Falloff, panning, occlusion, air absorption and a per-room reverb the compiler measures exist; doppler does not.

3. Rendering and visuals

• Dynamic/real-time lighting and shadows. light_dynamic (point or spot, switchable, movable) and a flashlight are drawn live on top of the bake, with clustered shading for up to 32 lights and shadow maps for the nearest shadow casters. What is left: no dynamic sun or cascaded shadows (the sun is baked whole), no light cookies or IES profiles, no volumetrics, and the 512² shadow maps are fixed-size rather than a convar.
• Post-processing. The scene is HDR (Rgba16Float) and tone-mapped once per frame (mat_tonemap: ACES by default, Reinhard, or none) with a live mat_exposure. Still no bloom, SSAO, color grading, auto-exposure or motion blur; the HDR target is what each of those needs first.
• Anti-aliasing. Fixed: r_msaa (4x by default) on the HDR target, resolved before tone-mapping. No TAA or FXAA.
• PBR material model. Materials are a small closed set (lit/unlit/sky/water/ui). They carry colour, normal, roughness, emissive, occlusion and metalness maps, plus $metalness and $roughnessfactor scalars, shaded with GGX / Smith / Schlick. What is left: no parallax, no per-material shader customization, and diffuse lighting is still direction-free, so normal maps on the world are lit by a fixed notional direction rather than the real one – radiosity normal mapping in Radiance is the fix.
• Level of detail. No LOD for models or geometry.
• Decals / projected textures. Mesh decals: cut from the world’s triangles when placed, lit by the lightmap under them and by dynamic lights, from infodecal, the decal command, scripts and the stock weapons (see Game UI). Not on moving brushes or props, and a section streamed in after a decal was placed does not get it.
• Particles / VFX. None. Muzzle flash, sparks, dust.
• Reflections. env_cubemap probes, baked by Radiance and reflected by every smooth or metal surface (nearest visible probe, blurred by roughness). No parallax correction, no SSR, no planar reflections.
• Dynamic sky / weather / time-of-day. Sky is a static skybox; sun and sky lighting are baked.
• GPU instancing. Fixed: prop_static models draw instanced, one call per model mesh however many copies there are. (They were not drawn at all before, and did not collide; now they do both.)
• Debug labels. Fixed: labelled passes and pipelines, and debug groups around the world, brush models, props and debug lines.

4. Physics and simulation

• Rigid-body dynamics. kerosene-physics is the player movement solver plus PhysicsWorld, which wraps Box3D (via box3d-rust) and is wired into the engine: world brushes become static hulls, detail joins them, and moving brush entities (doors, shutters) become static bodies that follow their entity’s pose, so a closed door blocks a thrown prop. prop_physics entities get dynamic box bodies (from their model bounds) whose object properties – mass, friction, elasticity, pickable – decide how heavy, grippy, bouncy and grabbable each one is, and a prop_dynamic_spawner drops them on demand (inheriting those properties). The player is in the simulation too, as a kinematic body, so props bounce off them rather than through them, and walking into one shoves it: how far is a contest between a fixed phys_player_push_force and the prop’s own mass, so a crate slides and a safe does not. The use key is a pick-up tool: aim at a prop and press use to carry it, press use again to set it down, or attack to throw it at phys_launch_speed plus whatever the player was already doing. A carried prop is steered toward the hold point rather than placed at it – driven by impulses under ceilings on speed, acceleration and turn (phys_hold_speed, phys_hold_accel, phys_hold_spin, phys_hold_spin_accel), braking early enough to arrive rather than overshoot – so it stays an ordinary body in the simulation: it turns to face the player as they turn, shoves what it can move, and hangs back short of the hold point when it meets what it cannot, rather than being driven through it. .kmdl models render at their simulated pose, and phys_debug draws the collision boxes. What is not there: convex-hull props (see the callout below – the solver does hulls, props do not use them), joints, per-surface-material friction, a launch-beams gravity gun, turning a prop while carrying it (Source’s use-plus-mouselook), and any sound or effect when a prop hits something.
• Ragdoll / skeletal physics. None. Box3D has joints, but no skeleton attachment.
• Vehicles / wheeled physics. None. Box3D has wheel joints, but no vehicle controller.
• Cloth / soft body / fluid simulation. Water is a volume flag, not simulated. Props fall through water rather than floating.
• Projectiles / ballistics. No projectile physics. The stock weapons are hitscan: they trace, mark walls and shove props.
• Generalized physics queries. Mostly fixed: Engine::trace, trace_ray and trace_view sweep a ray or a box against the world, the moving brushes and every prop’s body, and say which entity they hit (TraceHit::entity). Still missing: overlap and radius queries (“what is within 200 units”), and traces against a turned prop’s real box rather than the world box around it.
• Determinism is asserted, not audited. rayon is on the compile side today, but nothing guards the simulation path against it, or against a HashMap iteration order reaching gameplay. The demo replay in section 1 is the test that would catch it.

5. Animation and characters

• Skeletal animation playback. Fixed for prop_dynamic: clips play, loop or hold, and crossfade on change. Still missing: a viewmodel – the weapon in front of the camera, the first thing a shooter needs from this – and animation events (a footstep sound on frame 12).
• Animation state machines (the Animator equivalent). None: two-clip crossfades only.
• Morph targets / blend shapes. None.
• Inverse kinematics (foot placement, look-at). None.
• Animation retargeting. None.
• Third-person character. Only a first-person controller, which is otherwise solid: walk/run/jump/air-strafe, duck, swim, ladders, noclip, step-up, health/fall-damage/respawn.

6. AI and navigation

• NPC entities. No npc_* classes; tools/npcclip exists as a material but nothing is an NPC.
• Pathfinding. NavGraph links walkable faces that share a stretch of edge (T-junctions included, which a compiled floor is full of) and A*-searches it for waypoints. The engine loads each map’s .kwalk with it, and Engine::find_path and Engine::nav are how a game asks. There is still no smoothing into a funnel, no flow fields, and no NPC entity to steer along the result.
• Behavior trees / state machines / perception. No AI decision-making and no sight or hearing queries.
• Crowd / group movement. None.
• Dynamic navigation. The static walkmap cannot reflect a door that is currently open or closed.

7. Audio

• Occlusion / reverb Fixed: Resonance measures every room at compile time and the mixer has a reverb that reads it; walls muffle, and a sound with no way through is silent. See audio.md.
• Doppler. A sound moving past you does not bend in pitch.
• 3D spatialization. No HRTF, no surround.
• Audio effects / mixing buses. The mixer is voices into a stereo buffer with one reverb bus. No EQ, compression, ducking, or effects graph – and no volume convars for an options screen to drive.
• Streaming audio. Sounds are decoded whole; no streaming for long ambience or music.
• Footstep/impact effects. $surfaceprop now parses into a SurfaceProperty, and the engine traces to resolve it and emits stride-timed footstep sounds (footstep/<surface>/n) named off it. Impact effects are still not emitted – neither the player’s own landings nor a physics prop striking a wall makes a sound, though the solver reports every one of those collisions – and no footstep sound files ship, so a game without its own has silent steps (quietly: a game with no footsteps has made a choice).
• Procedural audio. None.

8. UI and HUD

• In-game HUD / menus. kerosene-ui: XML layouts, CSS styles and Rhai scripts, with bindings to published game state, hot reload, a stock HUD, damage overlay, pause menu with options, and world panels. See Game UI. Still missing: a main menu before any map is loaded, and dialogue boxes.
• The attribution screen. The licence exception requires every game to show “Built with Kerosene” when it starts. The engine should draw that itself, so a game meets the condition by default and a fork inherits it; today each game draws it in Game::ui.
• Gameplay UI toolkit. See above. What is left: scrolling containers, grid layout, and text shaping beyond kerning (no ligatures or right-to-left scripts).
• Localization. No string tables or translation. Cheap now, painful to retrofit.
• Runtime text/font rendering for gameplay: a glyph atlas over ab_glyph, with @font-face for a game’s own fonts.

9. Input

• Gamepad / joystick support. Keyboard and mouse only. gilrs is the pure-Rust answer; Steam Input replaces it on Steam and adds glyphs.
• Input actions. bind maps keys to commands, and a game’s own held +actions are per-tick state (engine.input.action_held("zoom")); the bindings are on Engine, with keys_for for a rebinding screen to show. There is still no layer that lets a gamepad and a keyboard both drive +attack, and no stock rebinding screen.
• Bindable keys. Fixed: arrows, the numpad, punctuation, the editing keys, mouse 4 and 5, and the wheel (mwheelup, mwheeldown), under Source’s names.
• Touch / mobile input. None.

10. Gameplay systems (beyond the FPS sandbox)

• Weapons and combat. A stub exists (kerosene_game::weapons): three hitscan weapons with ammo, reload, spread and recoil, and a dash on a cooldown. A shot marks walls and shoves props; nothing takes damage, and there are no projectiles, viewmodels or firing sounds.
• Damage model. Only player fall damage. No damage types, armor, enemy health, or hit reactions, and no OnDamaged output on entities.
• Inventory / items / pickups. None.
• Objectives / quests / missions. None.
• Dialogue system. None.
• Save/load. Fixed: save, load, F5 and F9, logic_autosave checkpoints. See Saving and level changes.
• Persistent game flow. Fixed: trigger_changelevel and changelevel carry the player’s health and the game’s own state (through Game::save and Game::load) into the next map, lined up by an info_landmark.
• Difficulty / game settings. None.
• Entity classes. The set is enough for the demo level and thin for a real one. Missing from Source’s glue, roughly in the order a mapper hits them: movelinear, tracktrain and path_track, logic_case, logic_compare, math_remap, filter_activator_name and _class, env_fade, env_shake, trigger_gravity, point_viewcontrol, env_sprite, game_ui. None of these are hard; each is a class in kerosene-game and a row in the schema – or in a game’s own crate, since a game registers classes through the Game trait without touching the engine. A game’s class with a model is drawn and collided with when it says how (ClassDef::model(ModelRole::Physics)); until this audit only the three stock prop_* names were.

11. Content and asset pipeline

• Prefabs / instances. Brushes are authored per map; there is no way to include one .kmap in another. This is not a scene-graph feature – Hammer had instances too – and past a handful of maps the brush workflow does not manage without it.
• Scene graph. Deliberately a flat entity list (a design choice, listed here for comparison with Unity/Unreal).
• Material editor. .kmat is hand-written KeyValues; no visual material graph.
• Shader graph / custom shaders. The shader set is closed.
• Animation import in Forge. glTF (skins and animations) is in. No FBX, no morph targets, no animated scale, and only a model’s first skin.
• Model LOD generation. None.
• Terrain tooling. Brushes only; no heightmap terrain or terrain editor.
• Level streaming / world partition. Sections: a visgroup marked as streamed is loaded and unloaded around the player by potential visibility (see architecture.md). Still one .kbsp per map, compiled and lit as one; not an open world.
• Visibility control for the mapper. tools/hint and tools/skip steer Cleave’s splits, but there is no areaportal and no occluder, so a door cannot close off what is behind it.
• Runtime asset hot-reload. Game UI reloads by itself (ui_hotreload), and scripts and sound tables on command (script_reload, snd_restart). Materials, textures, models and the map do not, nothing watches files for the scripts and sounds, and Chisel-to-engine iteration is F9, which is a full restart.
• Project templates. Fixed: kerosene-tools new makes a game crate (a Game with a class of its own, its toolset binary, cargo play, cargo tools and cargo ship, a project file and a starter map), or with --content-only a mod. The engine’s base content means either runs before it has any art of its own.
• Per-target build settings. .kproj names a content tree and a start map, and the window title comes from the game’s LaunchOptions. An icon, default convars and a start map per configuration belong there too, along with named ship targets (Godot’s export presets) for Kiln. kiln --ship --target <triple> builds for another platform, but there are no presets.

12. Networking and multiplayer

• Client/server protocol (acknowledged). No connection, snapshot, RPC, or entity replication.
• Prediction and interpolation. None between machines. On one machine the view is interpolated between ticks (section 1).
• Dedicated-server story. --headless exists, but there is no network stack to serve. If the engine goes Steam-first, Steam Datagram Relay is the pragmatic transport rather than a hand-written one.

13. Platform and distribution

• Windows/macOS support. CI compiles the workspace on Windows and macOS, but runs the tests and plays a new game only on Linux. Nobody has yet played one there by hand.
• Mobile / console. None.
• Crash reporting. A panic hook writes crash.log (section 1); there are no minidumps for native crashes and nothing that phones home. sentry covers both; Breakpad minidumps beside the log are the no-service option.
• Installer / auto-updater. None.
• build-content.sh is a shell script. For a game, cargo play and cargo ship are the build, and they run anywhere Cargo does. The script only builds this repository’s base content and the base vault.

14. Integrations

• Steamworks In, as the opt-in steam feature (see Steam). It covers:

  • init and the relaunch through Steam
  • the overlay, which pauses the game
  • achievements (with progress), stats and leaderboards
  • rich presence, DLC checks and the cloud file API
  • Workshop items mounted as VFS layers, with kerosene-tools workshop upload for putting a .vault up

  All of it is reachable from entity I/O (logic_achievement, logic_stat, logic_leaderboard, logic_richpresence, logic_platform), from Rhai (the platform object, alias steam) and from game code. kiln --ship --steam installs Valve’s redistributable with an rpath and writes the SteamPipe scripts.

  Still missing:

  • Steam Input
  • lobbies and Steam Datagram Relay
  • leaderboard downloads
  • Workshop browsing in-game
  • uploading from Chisel rather than the command line

• A platform trait kerosene-platform’s Backend: Steam is one implementation and the offline stand-in another, and no game code names either. GOG Galaxy and Epic Online Services are not written.

• Discord rich presence (discord-rich-presence). Trivial.

• Crash reporting (section 13).

• itch.io as a Kiln ship target, via butler.

15. Kerosene-specific tooling gaps (editor and compilers)

Chisel:

• 3D lighting preview (acknowledged). Baked lighting is not visible until compile and run.
• VisGroups. Fixed: a VisGroups tab with nested user groups and automatic ones, quick-hide, groups, and object colours.
• Autosave and recovery. Fixed: arena.kmap~ every minute, offered back when it is newer than the map.
• Recent files. None.
• Cordon. Fixed: a box that limits what is shown and what Cleave compiles, sealed by its own walls.
• Carve. Fixed, along with hollow and a clip tool.
• Instances / prefabs (section 11) and a prefab library in the browser.
• Entity report. Fixed: filterable, and it marks outputs aimed at nothing.
• Check for problems. Leak detection exists, the entity report finds dangling I/O, and “Check for problems” lists every problem in the output panel – broken wires included, by the same check the Outputs tab’s lights make. It does not yet look for a missing texture, and its lines do not lead to what they name.
• Undo history panel. Fixed: Edit → History....
• Vertex/edge editing. None. Brushes have it: the select tool’s vertex, edge and face modes, with drag in the flat views, extrude and merge, refusing any edit that would make a brush concave. Meshes still do not: Chisel draws, picks, moves, resizes, duplicates and deletes them, but a mesh is shaped by converting a brush, or by hand in the .kmap. No bevel yet, for either.
• Texture painting. No brush-based texture painting or blending.
• Walkmap visualization. The rule-tint view exists, but there is no in-editor preview of the compiled walkmap faces versus what Cleave will actually emit.
• Multi-entity editing. Fixed: the Object tab and the properties window edit every selected entity, brush or face together, with a key they disagree on marked and left alone until typed over.
• Play-in-editor. F9 launches the engine. Launching it as a child with a socket and syncing the camera back would be most of what Unity’s play button is worth.
• Automated level testing. No way to script or assert level logic in-editor beyond Rhai.

The compilers and Kiln:

• Incremental builds key on mtimes. Kiln now skips every stage’s current outputs (maps also record whether they were built fast or full), but by file time, which breaks on CI and after a git checkout; content hashes do not. A --watch mode and a build cache follow from having them.
• Independent stages run in sequence. Textures, models and sounds do not depend on each other.
• No lint. kerosene-tools lint: materials naming textures that do not exist, sounds a map fires that .ksnd does not define, outputs aimed at names no entity has. The editor’s “check for problems” and this should be one function.
• No map diff. The formats are text, which is the point; a semantic .kmap diff – this brush moved, that output was added – is something no mainstream engine can offer a team using git, and it is a small program.

The engine as a tool:

• No profiler. Nothing is instrumented. r_speeds reports counts; a frame timeline is what finds the hitch. puffin draws in egui and drops straight into the console overlay; tracy-client is the other answer.
• stat-style overlays. r_speeds and phys_stats exist; fps, memory, audio voices and physics bodies should be the same kind of thing.
• Hosted docs. docs.rs builds the published crate’s. Seven of the ten stable crates now refuse an undocumented public item (section 18).

16. Found in the September 2026 audit

A sweep of the runtime and the tools for what the sections above did not already list. Nothing in the tree is marked TODO, FIXME or todo!(); these are gaps found by reading.

Fixed in the same pass:

• Pausing did not pause. The pause menu, the console and the Steam overlay only showed a layer; the world ran underneath. sv_pause_on_menu (on by default) now stops the ticks, and a pause command does it whatever is open.
• No focus handling. Out of focus, the game pauses and snd_mute_losefocus silences it; minimised, it stops drawing.
• The window was always called “Kerosene”. The title and desktop app id are the game’s own, from LaunchOptions.
• A failed start said nothing. A native error box when the renderer cannot start, and when a windowed game crashes.

The runtime:

• Console. History is kept, Tab completes maps, saves, sounds, classes and convars, and there are maps, revert and host_writeconfig. config.cfg is still written only on a clean quit unless asked.
• Debug commands. god, buddha, notarget, give, kill, ent_fire, ent_create, ent_remove, ent_info, setpos, getpos, setang, restart and host_timescale are in; see the console. Still no r_wireframe, host_framerate, or ent_text drawn in the world (ent_info prints to the console).
• Video. Fullscreen, -w/-h/-fullscreen, a clamped cl_fov, screenshot are in. Still no render scale, texture-quality or anisotropy settings, and no UI text scale.
• Feel. Ducking snaps the view; no head bob, view roll, landing punch or step smoothing; crouch-jumping does not tuck the feet; no underwater tint, fog or muffling; no drowning, though WaterLevel::Eyes is there to drive it.
• Rendering. The worldspawn docs describe fog, and nothing implements it. The sky is one equirectangular texture: no cubemap or 3D skybox.
• Audio. No music system (playlists, crossfades), no env_soundscape, no subtitles or closed captions, no per-sound priority, and animated props make no sound. Doors and buttons do now: noise_move, noise_stop and noise_locked, door/move by default.
• Movers and entities. A door does not push, stop on or crush a blocking player and has no OnBlocked; a player on a moving platform is not carried; no parentname; no door_rotating, point_template/env_entity_maker, point_teleport, trigger_look/trigger_proximity, game_text or sky_camera.
• Scripting. No traces, spawning, or entity angles and velocity in the Rhai bindings. Random numbers are in: rand, rand_range, rand_int and pick, seeded per map.
• A map that fails to load leaves a blank world. Its reason is on the main menu.

The tools:

• Chisel. Cut, copy and paste work (in the editor, not through the system clipboard); go-to by id or name and nine camera bookmarks (not saved with the map) are in. No texture-lock toggle, though Solid::translate_world_locked exists; no find and replace. The layout, helper mode, shading and fly speed are remembered now (chisel.layout); the grid is not, and there is no Preferences dialog, keymap file, or light theme. Undo keeps a whole copy of the map per step.
• Validation. Nothing checks that a connection’s input exists on its target’s class. Fixed: every connection has a light, green, yellow or red, with the reason (section 19). There is no sound key type, so sound keys have no picker.
• The output panel cannot be searched, filtered or copied can now; its lines still do not lead to what they name.
• Other tools. Timbre, Alchemy and Loupe have no undo. Alchemy reads PNG, JPEG and TGA only: no EXR or HDR for skies. Radiance has no named quality presets. No kerosene-tools doctor: there is one now.
• The texture stage writes the developer textures into every project’s art/ and materials/, although the engine’s base content already has them, because the compilers read tool and sky materials from the project’s own tree. A new game’s .gitignore leaves them out; the fix is for the compilers to read the base content too.

18. Found in the second September 2026 audit

A second sweep, from the game’s side this time: what a game crate built on kerosene reaches for and does not find. Struck through is what was fixed in the same pass; the rest is open.

The game API:

• Traces never said what they hit. Engine::trace, trace_ray and trace_view return a TraceHit with the entity it hit – a door, a prop – as well as where and which way the surface faced.
• Only three class names could have a model. Drawing, animating and colliding a model were keyed to prop_static, prop_physics and prop_dynamic. A class now says so itself: ClassDef::model(ModelRole::Physics).
• No camera control. view_punch, screen_shake, set_fov_override, set_view_angles, and set_camera with a CameraOverride for a cutscene or a death camera. The stock weapons kick.
• A game could not read its own held actions. +zoom ran as a command once a frame; engine.input.action_held("zoom") is per-tick state now.
• The bindings belonged to the window. They are Engine::input, so a rebinding screen can read and change them, and bind works headless.
• Death was always an instant respawn. Game::player_damaged decides how much a hit takes and Game::player_died can take the death over, leaving the player dead until Engine::respawn_player. Maximum health is the game’s to set.
• Missing lifecycle hooks. frame (every frame, paused or not), player_spawned, can_save, map_unloading and shutdown.
• No debug drawing for a game. debug_line, debug_box and debug_point, for a number of seconds, under r_debugdraw. Still no text in the world.
• No seeded random numbers. Engine::rng, seeded by the map and kept in saves; rand, rand_range, rand_int and pick for scripts. The stock weapons’ spread still has a generator of its own.
• Spawning took a class name and nothing else. Engine::spawn_entity(class, &[(key, value)]) reads keyvalues the way the map loader does, then runs the spawn handler.
• The walkmap was never loaded. See section 6.
• Class handlers are bare fn pointers. They cannot capture settings or reach the game’s state; everything goes through a string-keyed HostRequest.
• No touch or damage callbacks on a class. ClassDef::on_touch and on_damage, with Engine::damage_entity. Still no use or collision callback.
• Triggers only notice the player. Spawnflag 8 adds physics props. An NPC, when there is one, is still to come.
• Error types differ by crate. platform and ui return Result<_, String>, the engine mixes that with anyhow, the rest use typed errors. Unifying them is a breaking change, so it wants doing before 1.0.0.

Rendering:

• $alphatest, $translucent and $nocull were parsed and ignored. On the world, an alpha-tested surface is cut out, a translucent one is blended back to front after everything solid, and $nocull draws both sides. On models the alpha test works, but a translucent model blends where it is drawn, among the solid ones and unsorted, and a two-sided model is still culled. Umbra and Radiance still treat a translucent brush as solid – it blocks visibility and casts a full shadow – unless it is detail.
• No sprites, billboards or beams. Particles need them first.
• No render-to-texture or second camera. Security monitors, mirrors, scopes and sky_camera all wait on it.
• No model attachments or hitboxes. No muzzle point, no held item, no headshot.
• No brightness or vsync at runtime. mat_gamma and r_vsync, both in the stock options menu and both applied at once.
• No loading screen. One is drawn for the frame before a load. The load itself still runs on the main thread, so a very long one still holds the window on that picture.

Audio:

• Pausing did not pause the sound. A paused game holds every sound in the world where it is; the interface’s clicks play on.
• No random variants or pitch in .ksnd. One file per sound; footsteps get variety by naming (footstep/<surface>/n).
• A playing voice cannot be changed. No volume, pitch or fade on a handle, so no crossfade and no door loop that fades out.
• No device choice or hot-plug. The default output always; a device that goes away needs snd_restart.

Platform and saves:

• Saves and settings went beside the executable. They go to the player’s own directory (~/.local/share/<game>, %APPDATA%\<game>, ~/Library/Application Support/<game>), and old saves in the content tree are still found. --portable keeps them in the content tree. crash.log is still written beside the executable.
• No local mods folder or -game flag. Workshop items mount; a folder of loose mods does not.
• No save migration. A newer save is refused and an older one loads as it is; nothing lets a game upgrade its own Game::save data. No save thumbnails.
• No save or load menu. The pause menu saves and loads, and the main menu loads.

Entities:

• Missing classes. breakable, wall_toggle, point_hurt, item_* pickups, game_end, player_speedmod are in, with point_teleport. Still missing: physbox, env_spark, env_explosion, and fog and water controllers.
• Thin common inputs. Kill, AddOutput and FireUser1 to 4 work on everything; SetParent does not, and Enable/Disable are each class’s own rather than universal.

The tools:

• cargo xtask bundle --out emptied whatever it was given. It clears only a directory it made.
• cargo xtask help failed. It exits 0.
• The published README’s links were broken. The bundle points them at GitHub.
• scripts/install-desktop.sh stopped on a missing icon, and bump-version.sh’s changelog step needed GNU sed. Both fixed; the bump also moves the changelog’s comparison links.
• No way to clean. kerosene-tools clean, kiln --clean.
• Mistakes on the command line were guessed at. An unknown command gets “did you mean”, and Chisel refuses a flag it does not know.
• new could make a game that depends on itself, and made no repository, CI or test. A game called Kerosene is kerosene-game; new runs git init and writes a CI workflow, .gitattributes, rust-version and a test of the pickup class.
• Four copies of “is this output up to date”. One, kerosene_vfs::up_to_date.
• “Check for problems” showed one. It lists them all in the output panel.
• Chisel and Kiln each build the compilers’ arguments. One list, kerosene_vfs::toolchain::MapStages.
• No shell completions. The top-level command line is hand-rolled, so clap cannot generate them.
• The generated game has no licence. Choosing one is the author’s, but new could ask.
• No --watch. kiln --watch and play --watch; the game reloads a rebuilt map under map_autoreload.

Code health:

• The stable crates’ public items were half undocumented. math, physics, script, vfs, game, console and platform are documented and warn on anything new that is not. entity (about 160 items), ui (about 280) and engine (about 150) are not yet, so the lint is off for them.
• Broken links in the crates’ own docs. Every crate’s rustdoc builds with warnings as errors.
• Big files. engine.rs’s console commands are in their own module now; kerosene-render/src/gpu.rs is still 3,200 lines.

19. The editor overhaul (September 2026)

Chisel was reworked towards Source 2’s Hammer: a GPU 3D view, a layout of toolbar, per-tool options bar, outliner and docked asset browser, hover cards, schema-declared entity helpers, a Hammer-style Outputs/Inputs pair with validation, and vertex/edge/face editing on brushes. See Tools. What doing it turned up:

• Handles move only in the flat views. A corner can be picked in 3D but not dragged there; the move gizmo still moves whole objects.
• No marquee for handles. Corners are picked one click at a time (with shift); dragging a box around several is not there yet.
• No bevel, no edge split, no face split. Extrude and merge are the only operations beyond moving; a face with a new edge across it needs the clip tool.
• Helpers are drawn, not edited. A spot light’s cone cannot be dragged wider, a sound’s sphere cannot be dragged bigger; the keys are typed.
• Models are static in the editor. An animated prop_dynamic shows its rest pose, and a model’s skin or body group is not previewed.
• infodecal and point_worldpanel draw an outline, not the decal’s material or the panel’s layout.
• The hover card has no material swatch, only the name.
• The software rasteriser is kept for tests and thumbnails. It no longer draws models or helpers, so a toolset without a GPU callback path shows less than one with it.

17. What the mainstream engines have, and whether it matters

positioning.md argues against chasing Unity, and this document agrees. But some of what they have is small and worth having, and it is worth being explicit about which is which.

Worth borrowing:

• Project templates and a new command: done, kerosene-tools new.
• Play-in-editor, in the child-process form above.
• Input action maps with a rebinding screen.
• Localization string tables.
• Build settings per platform, and named export presets.
• Prefabs, as Hammer instances rather than as a scene graph.
• A profiler in the editor.
• Unreal’s stat commands, as overlays.

Deliberately not:

• A scene graph, a shader graph, a material graph.
• Heightmap terrain.
• Open-world streaming. Sections of one map stream; a world of many maps does not.
• A garbage-collected scripting runtime. Rhai is small on purpose.
• Character tooling: animation state machines, IK, retargeting, until a game in a genre that needs them exists.

Three gaps worth calling out

1. The walkmap has a consumer now. The engine loads each map’s .kwalk, NavGraph links its faces (across T-junctions, which it used to miss, leaving a real floor with no links at all) and Engine::find_path answers with waypoints; Engine::debug_line can draw them. What is missing is the NPC that walks them.
2. The solver already does convex hulls; props do not use them. PhysicsWorld exposes add_dynamic_hull, and world brushes and detail go in as static hulls, so the hull path is real and running. But prop_physics bodies are built from the model’s bounding box (add_dynamic_box_material), so a barrel collides as a crate. Nothing calls add_dynamic_hull. Closing this is wiring a hull out of .kmdl geometry, not new physics.
3. $surfaceprop is driven at runtime. Traces now report the texinfo they hit, the engine resolves that to a material and its $surfaceprop, and footsteps emit from it. The remaining gap is the other side of the coin – impact effects – and the sound assets themselves, which are content rather than code.

An order

Weighed against positioning.md: the shortest path to a shipped movement shooter or immersive sim, cheapest first.

1. Interpolation, MSAA, runtime mipmaps, texdata dimensions. Done.
2. CI. Done: fmt, clippy, the layering check and the tests on Linux, a build on Windows and macOS, and a new game made and played.
3. Demo record and playback. Proves determinism, becomes the movement solver’s regression fixture, and is the ghost system for genre 3.
4. A game UI layer and save/load. Done, with a main menu, a loading screen and save and load pages.
5. Chisel: instances. VisGroups and autosave are in; this is what remains of making the second real map editable.
6. Weapons and damage. Hitscan, ammo, OnDamaged, decals for the holes.
7. Steam, Workshop first. Done, as the steam feature.
8. Impact sounds. The physics sandbox sounding like one; the room it happens in already rings.

Everything after that – animation, NPCs, networking – is in the sections above and is not smaller for being later.

Positioning

What this engine is good at, what it is not, and which games it is shaped to make. A companion to missing-features.md: that sheet says what is absent, this one says which of those absences actually matter.

Game titles here are named for one reason: to point at a shape of game, the same way the README names Valve and id tools to point at a shape of tool. None of their makers are affiliated with, endorse or sponsor Kerosene, and none of their code or content is in it. See NOTICE.

The comparison people reach for

The question that prompted this document was whether Kerosene could compete with Unity. The answer is no, and pursuing it would be the fastest way to kill the project.

Unity is roughly two decades and thousands of engineer-years. Matching it means a shader graph, an animation state machine, terrain, particles, LOD, five platform backends, an asset store, and console certification. That is not a roadmap; it is a company. Kerosene is around 125,000 lines across twenty engine crates and eleven tools.

But “compete with Unity” is the wrong frame, and the architecture already says so. The README’s thesis – the tools are separate from the engine and share open formats – is something Unity structurally cannot do, because its editor is the product and its runtime is downstream of it. Kerosene’s compilers are subcommands. You can script them, run them on a build server, replace one, or write your own. That is a real advantage and a permanent one, and it is worth more than feature parity in a race that cannot be won.

The useful question is not “how do we catch up” but “what is this shaped to be best at”.

A crate, not an editor you live inside

The other thing Unity structurally cannot be is a dependency. A Unity game is a folder the editor owns; the engine arrives as an installer, is upgraded by a hub, and runs your code inside its own. Kerosene inverts that. The game is a Cargo package, kerosene is a line in its Cargo.toml, and cargo play is the loop. The editor and the compilers are a library the game re-hosts as its own binary, so the tools a studio ships to its modders know its classes and launch its game.

That buys things a Rust developer already expects and a game engine rarely gives:

• The whole stack builds from source, on the developer’s machine, with nothing installed but Rust. There is no binary blob, no account, and no version of the engine that exists only on someone else’s server.
• Every platform is the same three commands. A game that builds on Linux builds on Windows and macOS, because it is the same code; CI makes and runs a new game on all three on every push.
• Versions mean something. The engine’s version is the game crate’s API under Semantic Versioning (Versioning), so upgrading is a cargo update that cannot break a game, or a major version with a changelog that says what to change — not a project-upgrade dialog.
• Nothing is hidden. A game can read the engine’s source in its editor, step into it in a debugger, and patch it with a [patch] section when it must, and it is all one cargo doc away.

The price is the Rust toolchain as a prerequisite, and the first build taking minutes rather than seconds. For the audience this is shaped for — people who would rather have the engine’s source than its installer — that is the right trade.

The Titanfall argument

The strongest case for this architecture is that it has already been made, by someone shipping a game on it.

Respawn built Titanfall on a branch of Source 2009. They did not take it for its renderer, most of which they replaced, or for its tools. They took it for two things: the movement solver and the brush pipeline.

Everything that makes that game feel the way it does – wallrunning, sliding, carried momentum – is built on top of the structure in kerosene-physics: accelerate, air_accelerate, clip_velocity, try_move, step_move. That is the Quake-to-Source lineage, and it is why air-strafing works at all. It is also five readable functions with unit tests, rather than a character controller written for someone else’s game.

The other half is the pipeline. Those levels are still convex solids compiled to a BSP tree with a precomputed PVS, because for a shooter that has to hold sixty frames a second, nothing beats the level telling you what you can see. That is Cleave, Umbra, Resonance and Radiance.

So: Kerosene is already good at the two things that mattered enough to build a studio’s flagship on. What it does not have is everything that was built on top of them with a large team.

Four things it is structurally good at

Movement feel. The solver is legible and tested. Tuning air acceleration is editing a function, not fighting an abstraction.

Entity I/O. kerosene-entity/src/io.rs has connections with delays, parameters and fire-once semantics. A designer wires an entire set-piece without writing code, and the result is a text file that diffs and reviews. This is an underrated design, and the mainstream engines’ answer – callbacks serialised into a scene blob – is worse.

Iteration speed. Brushes compile in seconds. That is a different design loop from sculpting in a DCC package and importing.

Determinism. A headless simulation, a unit scale that lands on powers of two, and no garbage collector. This is more valuable than it sounds; see the time-trial entry below.

Five games it is shaped to make

Each entry names the shape, what it leans on, and what it is still missing.

1. A movement shooter

Titanfall 2, Ultrakill, Neon White, Severed Steel.

These live or die on the solver, and Neon White in particular shows the market does not want photorealism – it wants frame-perfect movement and levels that read at a glance.

Leans on: the movement solver, fast compiles. Needs: weapons, and skeletal animation for viewmodels. Very little else. This is the shortest path from here to a shipped game.

2. An immersive sim or boomer shooter

Half-Life 2, Dishonored, Prey, Deathloop.

All brush-built, all I/O-driven. Physics props plus entity I/O plus Rhai hooks is most of the substrate for “the player solves this room however they like”.

Leans on: entity I/O, the physics sandbox, scripting. Needs: weapons, damage, and eventually NPCs. The best fit for what actually exists today, because it leans on the I/O system and the physics rather than on animation.

3. A time-trial or speedrunning game

Neon White, Clustertruck, the Trackmania design space.

Deterministic movement, fast level compiles, ghost replays. Determinism is the feature here rather than an implementation detail: fixed-timestep physics in the mainstream engines is not replay-stable across machines, and people build elaborate workarounds. Kerosene gets it as a consequence of how it is built.

Leans on: determinism, the solver, iteration speed. Needs: demo recording – which is also how the determinism claim gets proven, since nothing replays a session today – plus save/load for ghosts, and a HUD.

4. Competitive multiplayer with a mod scene

Counter-Strike, Team Fortress 2.

This is where the open-formats thesis pays off hardest, because a community that can write its own tools makes a game outlive its studio.

Leans on: replaceable compilers, open formats, the headless simulation. Needs: the whole of the networking section. Furthest out – but the headless split means the architecture is already pointed the right way.

The mod-scene half does not have to wait for the networking half. A map is a .vault, the VFS already mounts archives as layers, and Steam Workshop is an upload from Chisel and a subscription in-game. That is a weekend against the Steamworks SDK, not a networking stack, and it is the first place the open-formats thesis pays out where a player can see it.

5. Horror

Cry of Fear and the lo-fi space around it.

Baked radiosity in tight brush geometry is an aesthetic, not a compromise, and this genre has no appetite for physically-based shading.

Leans on: Radiance, the brush pipeline. Needs: audio occlusion and reverb – sound doing the work graphics does elsewhere.

The pattern, and what it rules out

Every one of those is geometry-heavy and animation-light. That is not a coincidence: it is exactly where the missing-features sheet is strongest and weakest.

The genres to stay away from are the ones the mainstream engines are actually good at – anything built on characters, dialogue, cutscenes, open worlds, or a large art budget. Not because they are impossible, but because they are a fight against every strength listed above.

What gates all of it

Three items on the sheet stand between “an impressive engine” and “somebody shipped a game with this”:

1. Skeletal animation. .kmdl stores bones and weights and nothing plays them. No characters means no NPCs and no enemies – a sandbox rather than a game. This is the single biggest blocker on the whole sheet.
2. Networking. The headless simulation is the hard architectural half, and it is done. Without a wire protocol, though, the comparison to Source stops being true in the way that mattered most to Source.
3. Windows. CI builds it there, and nothing has run it there. wgpu, winit and cpal all do Windows, so what is left is untested rather than broken – but most of the people who would want this cannot find out until somebody launches it.

One more is smaller than those and gates the feel rather than the possibility: there is no game UI layer, so there is no menu, no options screen and no HUD to put a game behind. It is on the order of days, and it is in the way of every genre above.

Everything else on that sheet – PBR, post-processing, decals, particles, LOD – makes games prettier. These make games possible.

The honest summary

Kerosene will not be a general-purpose Unity competitor. It could plausibly become the engine someone reaches for when they want to build a Half-Life 2-shaped game and find that nothing else lets them. That is a smaller market and a far more winnable one.

Scripting

Entity outputs wired to inputs compose further than they have any right to, and most of a level is built that way. But some things are not a graph. Counting, arithmetic, “pick one of these three at random”, “only if the player still has the crowbar” — expressing those as relays and counters is possible and miserable. This is the layer above.

It is deliberately not a second way to write the engine. A script cannot allocate an entity slot, walk the BSP tree, open a file, or touch the renderer. It reads a snapshot of the world and returns a list of things it would like done.

Running one

Three ways in, all equivalent underneath:

script find_by_name("gate").fire("Open")     # at the console (cheat-protected)
script_execute mymap                          # load scripts/mymap.kscr
script_reload                                 # forget everything and load it again

A map called atrium automatically loads scripts/atrium.kscr when it starts. That is where a level’s script belongs.

From inside a level, a logic_script entity is the seam: an output fires CallScriptFunction and a function in the script runs.

| Key | |
|---|---|
| `scriptfile` | Loaded when the map starts |
| `function`   | What `CallScriptFunction` runs with no parameter |
| `code`       | What `RunScriptCode` runs with no parameter |

Hooks

Define these and the engine calls them.

A function called through CallScriptFunction may take the caller’s name, or take nothing — both spellings work, so the unused parameter is never forced on you.

fn on_used(who) {
    print(`used by ${who}`);
}

The API

The language is Rhai. Everything below is the whole of it — a scripting surface nobody can read in one sitting is one nobody can audit.

Finding things

Asking about something that is not there gives () rather than throwing: checking whether a thing exists is not a mistake.

Entities

e.fire on an entity with no targetname addresses that entity and no other. Without that, acting on one of a dozen unnamed lights would mean all of them, or none.

Entity I/O

ent_fire("gate", "Open");
ent_fire("gate", "Open", "");           // with a parameter
ent_fire("counter", "SetValue", "3", 1.5);  // ...and a delay in seconds

Firing goes through the same event queue an output wired in Chisel uses, so the ordering and the delays are the ones the rest of the level plays by.

The console and the world

The game UI

See Game UI.

The store: platform (or steam)

Steam when the game is built with it, a stand-in otherwise. The same calls work on both.

Achievement ids and stat names must be declared in the .kproj. The object works inside functions, unlike top-level variables, and so platform and steam cannot be used as variable names. See Steam.

Vectors

let a = Vector(0.0, 0.0, 64.0);
let b = player().origin;
print(`${distance(a, b)}`);

+ - *, .x .y .z, length, distance, dot, normalize, to_string. Distances are kerosene units; see the units section of the README.

What a script cannot do

• Reach the filesystem. There is no module resolver, so import fails. It would have been a way around every limit below.
• Run forever. Operations, call depth, string and array sizes are all bounded. A level’s scripts are content, edited by people who make mistakes, and an infinite loop should stop the script rather than the game.
• Queue unbounded work. A runaway loop calling ent_fire is cut off, the same way the engine refuses to dispatch entity I/O forever.
• See the world mid-tick. A script reads a snapshot taken when it starts and its effects are applied when it finishes, so a run is a pure function of the world at one instant. That is why the same script run twice on the same world does the same thing.
• Hold a reference across a death. An entity handle carries its slot’s generation, so a handle kept over a respawn cannot come back pointing at whatever moved into the slot.

Why a snapshot and a queue

The obvious design hands the script a live reference to the entity world. It cannot be done safely — script functions outlive the call that registered them, so the borrow would have to be 'static — and it should not be done anyway. A script that mutates the world halfway through a frame can observe the world in a state no other code ever sees, and that is where the hard-to-reproduce bugs live.

Cheat protection

script, script_execute and script_reload are cheat-protected: they can move entities and set convars, which is not something to hand out for free. A map’s own script loads without sv_cheats, because shipping a level means shipping its script.

An example

The demo level’s, content/scripts/kero_start.kscr in Kerosene Demo, is written to be read: it plays a room tone, puts the objective on the HUD and says when the map has been running two seconds.

Game UI

HUDs, menus, screen overlays and screens in the level are all built the same way: an XML layout, a CSS stylesheet, and optionally a Rhai script, loaded from the content tree like any other asset. It is the shape of Source 2’s Panorama, with one idea borrowed from HTMX: an element says what game state it shows, in its attributes, instead of a script finding it and updating it.

<Label text="{weapon.ammo} / {weapon.reserve}" class:low="{weapon.ammo < 5}"/>
<Panel class="crosshair xh-{weapon.active}"/>

That label shows the ammo count and turns red when it runs low; the crosshair swaps its look whenever the weapon changes. No script is involved. Most of a HUD is built like this.

Edit a layout, stylesheet or script with the game running and it reloads a second later.

Files

The stock game ships these under content/ui/:

A keypad panel – buttons, a display, a script that checks the code and fires OnUnlock – is in Kerosene Demo, as content/ui/panels/keypad.*, with a test that presses its buttons.

They are written to be read. Copying one is the fastest way to start.

A layout

<root interactive="true" z="100">
    <styles>
        <include src="ui/menus/menu.kcss"/>
    </styles>
    <scripts>
        <include src="ui/menus/pause.kscr"/>
    </scripts>

    <Panel id="menu">
        <Label class="title" text="Paused"/>
        <Button text="Resume" onactivate="resume()"/>
    </Panel>
</root>

The outer element is always <root>. Its attributes:

<style> and <script> blocks may also be written inline, directly under <root>. You don’t need to escape < and && in bindings and scripts: the loader escapes them before the XML reader sees them.

Elements

Controls make parts of their own for the stylesheet to style: .slider-track, .slider-fill, .slider-thumb, .toggle-box, .toggle-knob, .progress-fill, and a Label inside a Button or Toggle. Their look before any sheet of yours comes from crates/kerosene-ui/src/default.kcss, which is compiled into the engine.

A <Repeat> has no box of its own. What it makes is laid out in its parent as if written there, so a row of slots made by a Repeat inside #slots { flex-direction: row } is a row. Because of that, select what a Repeat made with a descendant selector (#slots .slot), not >.

Attributes every element takes

Bindings

Anything in braces is a Rhai expression, and published game state is its variables: player.health is the health entry of the player map.

<ProgressBar value="{player.health / 100.0}"/>
<Label text="{if weapon.reloading { 'Reloading' } else { weapon.active }}"/>
<Panel visible="{player.alive && ability.dash.ready}"/>

• An attribute that is exactly one expression keeps its type, so visible and class: get a real true or false. Anything else becomes text.
• A binding is evaluated again only when a value it reads changes. A HUD with a hundred bindings costs nothing on a frame where none of their values moved.
• A value nobody has published yet reads as nothing (()), not as an error. visible="{objective.text}" stays hidden until a script sets an objective.
• Strings may be written in single quotes, which is the natural way inside a double-quoted attribute.
• {{ and }} are literal braces.

What is published

Run ui_dump in the console for the live list. The engine publishes:

The stock game (kerosene::game::Stock) adds its weapons and ability:

A game publishes its own from Rust with engine.ui_set("key", value). A level script uses ui_set("key", value), and a map uses a logic_ui entity’s SetValue input. The HUD doesn’t know or care which one set a value.

Events

Events are one-off: something happened. Listen with on:NAME or a script’s on_event(name, data).

Send your own with engine.ui_emit(...), ui_event(...) in a level script, logic_ui’s Emit input, or ui_emit at the console.

Styles

A stylesheet is ordinary CSS: rules, selectors, specificity, comments, @keyframes, @font-face. Selectors can use element names, .class, #id, descendant and > child combinators, and :hover :active :focus :disabled :checked :first-child :last-child.

Layout is flexbox, and a panel’s children stack in a column unless told otherwise.

Lengths are UI pixels. The screen is 1080 of them tall however many real pixels it has, so a HUD laid out at 1080p keeps its shape at 720p and at 4K. % is the parent, as on the web, and vw/vh are the screen.

Kerosene adds three properties a game HUD needs:

Transitions and animations can move opacity, colours, transform, -kero-fill, width height and the insets. An animation stays on its last frame when it ends, which is what a flash or a fade-out wants. To play one again, a script calls trigger_class.

font-weight: bold uses a bold face when a stylesheet has loaded one:

@font-face { font-family: "Hud"; src: url("ui/fonts/hud-bold.ttf"); font-weight: bold; }

Without one, the text is drawn slightly heavier. The built-in face is egui’s Ubuntu Light.

A property the stylesheet can’t read is reported once in the console with the file it came from, and the rest of the rule still applies.

Scripts

Bindings show state. A script is for behaviour: a menu page that opens, a keypad that checks a code, a toast that appears and fades. Every layout gets its own sandboxed Rhai VM, with the same limits as a level script, and:

The engine calls two hooks if a script defines them: on_load() and on_event(name, data). Code in an attribute (onactivate="resume()") runs with target, the element it’s on, and data, the event’s data or the control’s value.

In Rhai a function can’t see the script’s top-level variables. Keep state in the store with set_store, which also lets the layout bind to it. This is how the demo’s ui/panels/keypad.kscr works.

Layers

Each shown layout sits on a named layer. Showing a layer loads its file, or keeps the one already loaded along with its state. Hiding a layer keeps the document, so showing it again is instant.

• hud is managed by the engine. It shows ui_hud whenever a map is running.
• menu is Escape’s while a map runs: it toggles ui_pausemenu. With no map running it holds the main menu, ui_mainmenu. While a layer marked interactive is visible, the mouse is released and every key and click goes to it. When the menu closes, the mouse goes back to the game, whether it closed by Escape, a Resume button or a script.
• loading holds ui_loading for the frame before a map or a save loads.
• splash holds ui_splash for a moment as a window opens on the main menu.
• Any other name is yours.

The front end

A game started from its shortcut opens on the main menu, not in a map. The base content’s menus are a starting point; a game replaces any of them by shipping a file at the same path.

What the menus read: game.title; saves.count and, for each save, saves.<i>.name, .map and .when, newest first, published as a menu opens; and error.message, why the last map would not load.

A +map on the command line, -nomenu, a headless run and kerosene-tools play skip the menu and the splash, and go straight to the map. -nosplash skips only the splash. game_end in a map, and disconnect, come back to the main menu.

The developer console always comes first. It opens over a menu, and its keys close it.

World panels

A point_worldpanel entity puts a layout on a surface in the level. The layout is rendered into a texture, only when what it shows has changed, and that texture is drawn in the world, depth-tested and glowing.

When the player looks at an interactive panel within reach, the crosshair works as the panel’s pointer, and use or attack clicks. The panel takes the press, so the wall behind it isn’t used and the gun doesn’t fire.

A panel’s script talks to the level through emit:

emit("OnUnlock", code);   // fires the panel entity's OnUnlock output

Every event fires the panel’s OnPanelEvent output with the event’s name as the parameter. An event whose name starts with On also fires the output of that name with its data, so the mapper wires OnUnlock in Chisel like any other output. Its Enable, Disable and Emit inputs work the other way.

Set reference-height on the panel layout’s <root> to the entity’s resolution to lay the panel out in its texture’s own pixels.

Decals

Bullet holes, cracks, scorch marks and signs are projected onto the world. When one is placed, the world triangles under it are cut to its square. The decal keeps the lightmap of the surface it lies on, so a decal in shadow is in shadow, and it’s drawn with the world’s own shading, dynamic lights included.

• infodecal entity: texture (a material) and size. It lands on the surface nearest its origin when the map starts.
• decal [material] [size] at the console (cheat): wherever you are looking.
• place_decal(material, origin, normal, size) in a level script, or engine.place_decal(...) in Rust.
• Every stock weapon’s shots.

A decal material is an ordinary .kmat whose texture has alpha, such as content/materials/decals/bullet.kmat. The newest r_decals decals are kept (default 256) and the oldest are dropped. r_cleardecals removes them all, and a new map starts clean.

Decals land on the static world only, not on doors or props. A decal placed while part of the level is streamed out does not appear on that part.

Console

Weapons and the dash

The stock game’s weapons exist so the HUD has something real to show. They are a starting point, not a combat system. Keys: 1 2 3 select the pistol, shotgun or rifle, Q switches to the last weapon, R reloads, mouse1 fires, and mouse2 dashes. The commands behind them are slot1–slot3, lastinv, invnext, invprev, reload and +ability1. Shots trace from the eye and leave bullet holes. Nothing takes damage, because nothing in the engine has health but the player. A game with real weapons replaces kerosene::game::Stock rather than extending it. See crates/kerosene-game/src/weapons.rs.

Using it from a game

The engine owns the UI. A game only publishes state and listens:

#![allow(unused)]
fn main() {
impl Game for MyGame {
    fn tick(&mut self, engine: &mut Engine, _: &InputState, _: f32) {
        engine.ui_set("score.kills", self.kills);
    }
    fn ui_event(&mut self, engine: &mut Engine, name: &str, data: &str, source: &str) {
        if name == "buy" {
            // a shop menu's button: data is the item
        }
    }
}
}

Game::ui, egui, still works and still draws on top. It remains the quickest way to put a debug window on screen.

Threads and memory

The simulation, rendering and the console run on one thread: the one that owns the window. Everything else the engine runs is a module, started and stopped by kerosene::lifecycle.

Start and stop

Modules start in three phases and stop in the opposite order:

1. Engine: the engine’s own parts (today, the level-streaming workers).
2. Modules: the ones a game hands over in Game::modules.
3. Game: the game itself, through Game::setup and Game::shutdown.

Starting is two steps. Every module’s preload runs, in order, before any module’s start, so a module can load what it needs while nothing is running. stop runs in reverse. By the time a module’s stop is called, its threads have been told to stop and have been waited for. A thread that ignores the request is logged and left behind after five seconds, so a stuck worker can never hang the exit.

A module of your own

#![allow(unused)]
fn main() {
use kerosene::lifecycle::{Ctx, Module};

struct Telemetry;

impl Module for Telemetry {
    fn name(&self) -> &'static str { "telemetry" }

    fn start(&mut self, ctx: &mut Ctx) -> kerosene::internals::kerror::Result<()> {
        ctx.spawn("flush", |token| {
            // `sleep` returns true as soon as a stop is asked for.
            while !token.sleep(std::time::Duration::from_secs(10)) {
                // ...send what has piled up...
            }
        })
    }
}
}

Return it from Game::modules. Spawn threads through the Ctx, never std::thread: that is what names them (kerosene-telemetry-flush), counts their memory under the module’s name, and lets the manager stop them. A panic on a managed thread is reported as a fatal kengineThreadError and shuts the engine down cleanly. ctx.pool("name", n) gives a bounded pool of workers; a job that panics is logged and does not take its worker with it.

The streaming pool has at most four workers. KEROSENE_THREADS=n sets the count for everything that asks default_workers().

Memory

TrackingAllocator wraps the system allocator and counts. It is installed by one line in the binary, because a library cannot choose the allocator; new games have it already, and so does the stock kerosene binary:

#![allow(unused)]
fn main() {
#[global_allocator]
static ALLOCATOR: kerosene::lifecycle::TrackingAllocator =
    kerosene::lifecycle::TrackingAllocator::new();
}

The console command mem prints live and peak bytes, how many allocations were made and freed, and a line per tag. A tag is a module’s name for the threads it owns, and misc for the main thread and everything else. mem reset_peak starts the peak over. A free is counted under the tag of the thread that frees, so a buffer handed between threads moves between tags and a tag’s figure can briefly be negative.

Without the line, mem says tracking is off and costs nothing: the system allocator runs untouched. Delete the line from a release build if the few atomic adds per allocation matter to you.

Tool reference

One application, kerosene-tools. Open it with no arguments and you get one window holding every tool, switched from a sidebar down the left edge:

Across the top, a bar says where you are, holds a search box and a Play button, and shows any running build or pack with its elapsed time and a way to stop it. Along the bottom, one output panel (ctrl-`) that every job – a compile, a build, a pack, a play session – logs into. It comes up on its own when a job starts, counts each log’s errors and warnings, and can be filtered by text, narrowed to problems, or copied. None of it is the engine, and none of it depends on it.

ctrl-P (or ctrl-K) opens the command palette: type a few letters of any map, model, sound, tab, job or recent project and press Enter. The match is forgiving – bf finds Build (fast), arena finds maps/dm/arena.kmap – and the matched letters are highlighted.

Home is where the window opens: which project this is and where its content is, the four things people come to do (new map, build, pack, play), counts of maps, materials, textures, models, sounds and scripts – click one to browse them – and the maps themselves, each marked compiled, stale or not compiled.

Assets lists everything under the content folder by category. Sources that compile to something – maps, meshes under models/, sounds under sound/, images under art/ – say whether their compiled form is there and newer than they are. Double-click a map, model or sound to open it in its tool; right-click for show in folder and copy path.

The start page comes up when no project is found, and from Switch project on Home or the project menu at the bottom of the sidebar. It lists recent projects and has three forms: Open a project folder, project file or content folder; start a New game (what kerosene-tools new does); or Make a project of an existing folder (what kerosene-tools init does). Switching away from an unsaved map asks first.

The same stages also run headless, as subcommands, so a script or build server can drive them without a screen: kerosene-tools cleave map.kmap, and so on. Each subcommand is the program it used to be, unchanged in argument and output. A mistyped one is answered with the one it nearly was (unknown command "kilm". Did you mean \kiln`?`).

doctor — is this machine ready?

kerosene-tools doctor

Checks what a first build trips on, and says what to do about each: a Rust older than Kerosene’s minimum, the ALSA headers on Linux, a GPU the renderer can use (and whether it is only a software one), the project here, and which of the toolchain’s pieces can be found. It changes nothing, and exits with an error when something is in the way.

clean — delete what the build wrote

kerosene-tools clean [--content <dir>] [--dry-run]

The same as kiln --clean: deletes every compiled texture, sound and map file under the content tree, and the project’s archive, and nothing else. Models are left, since a .kmdl may have no source to rebuild it from. --dry-run says how much it would delete.

init — starting a project

kerosene-tools init [dir] [--name "My Mod"] [--content content]

Writes a .kproj and creates the content tree beside it: maps, materials, art, textures, models, sound, scripts. Without a --name the directory’s own name is used, and the project file is named after it.

It is safe to run on a directory that is already a project. The project file is the one thing here somebody is expected to have edited, so an existing one is left exactly as it is, and only missing directories are created — which makes this the way to fill in a directory the engine has started using since the tree was made.

A project may name its own directories instead; see formats.md.

Nothing requires this command: the engine and the toolset both create the tree on their own the first time they find a content root. It exists so that starting a project is a thing you do, rather than a thing you discover you should have done.

Chisel — the world editor

A tab in the toolset window, and openable straight to a map:

kerosene-tools                 # the toolset window, on Home
kerosene-tools chisel [map.kmap] [--content <dir>]   # straight to the editor

Finding the content. Chisel needs the content root – the tree holding maps/, materials/ and the .kdef class definitions – to show entity classes and materials at all. The search lives in kerosene-vfs and every tool and the engine share it, so they cannot disagree about which tree is in use.

The reliable way to settle it is a project file: a .kproj at the top of a project naming its content directory. See formats. Without one, the tree is inferred, which works and is why a fresh clone needs no setup – but inference is a guess, and a project file is how you overrule it. Three places are searched, nearest first: the tree the map lives in, the working directory, and the directory the executable is in. In each of them a project file wins over a guess, even a guess found closer down; between them, nearness decides. So a map sitting in a content tree of its own is not claimed by a project on the far side of the disk.

Failing a project file, each place is searched like this: --content if given, then beside the map being opened, then the working directory, then beside its own executable, climbing up to six levels from each looking for a directory holding kerosene.kdef (or, failing that, both maps/ and materials/). Opening a map from anywhere in a project therefore just works, and the map’s own tree wins over the working directory on purpose – editing another project’s map should not show this project’s entities.

The status bar says what it found: 20 classes, 41 materials when the content is there, no entity classes in red when it is not, and n materials unbuilt in amber when a material has no texture behind it. If the first is red, nothing in the editor will look right, and kerosene-tools chisel --help lists the search order. cargo run -p kerosene-chisel --example diagnose prints the same thing without opening a window – discovery, classes, materials, which materials have no texture, and which maps have never been compiled – which is the fastest way to answer “why does Chisel show no entities”. It changes nothing unless given --build.

Textures are built on the way in. Before the editor finishes loading it runs the same texture build Alchemy’s build command does: the developer set is regenerated, then every image under art/ is compiled into materials/. Anything already compiled is skipped, so the cost after the first run is a directory walk. It happens before the materials are scanned, because scanning first and building second is an editor with no textures in it and no way to tell. --no-build turns it off; F9 does it again before compiling the map, so a texture added during a session is compiled before the map that uses it.

Files. ctrl-S saves. A map that has never been saved is asked for a name first rather than being written to untitled.kmap somewhere – the name is what kerosene +map <name> loads, so an editor that picks one for you is an editor whose output you have to go looking for. ctrl-shift-S and file → save as… ask for a name outright. A bare name means a map in this project: typing arena writes <content>/maps/arena.kmap. An absolute path is taken as given.

file → rename… moves the map and the artefacts compiled from it – the .kbsp, .kprt and .kleak. Leaving a .kbsp behind under the old name is worse than clutter: the game still loads it, so a renamed map appears to work under a name that no longer exists and to be missing under the one that does. Renaming onto a map that already exists is refused.

Autosave. A map with unsaved changes is written to arena.kmap~ beside it every minute – never over arena.kmap, so a bad afternoon cannot replace the last good version. Saving removes it. Opening a map whose autosave is newer asks whether to recover it (escape keeps the file and asks next time); a session that died before its first save leaves untitled.kmap~, offered when the editor starts with no map.

file → open lists the maps in the project. Anything that would throw away unsaved changes asks first, and offers to save. The title bar and the status bar both name the file, with a * when there are unsaved changes; a map with no file yet says not saved rather than showing an invented one.

The layout is Hammer 5’s. A strip of tool icons down the left edge – hover one for its name and key. Across the top, two rows: the toolbar, for what applies whatever you are doing (undo, the grid and snap, the cordon, how the 3D view draws, which helpers are shown, how many views, the asset browser, compile), and under it the options bar, which belongs to the tool in hand and changes with it – the select tool’s pick mode and gizmo, the block tool’s material, the shape tool’s shape and sides, the entity tool’s class, the texture tool’s modes, the clip tool’s side. Its right end says, in one line, how to use the tool.

On the right, a dock in two halves, split where you last dragged it. The Outliner above lists every entity in the map by family – lights, players, sounds, logic, props – named ones first, with a search that matches any part of a class or a name; click to select, double-click to fly there. Its VisGroups tab is what is shown (see below). Properties below is whatever is selected; for an entity it has three tabs, Properties, Outputs and Inputs (see Wiring). Along the bottom, when M or the toolbar asks for it, the asset browser is docked. The status bar names the file, the selection’s size, the pointer’s place in the world, the grid, and what content was found.

The layout is remembered between sessions – how many views, whether the asset browser is open, the helper mode, how the 3D view draws, where the panes divide – in chisel.layout in your user data directory, never in the project.

Four panes fill the middle – or two side by side, or one, from the toolbar – each showing whichever view you point it at: 3D, or any of the six flat views – top, bottom, front, back, left and right. Brush geometry is axis-aligned far more often than not and an orthographic view along an axis is the only way to place a vertex exactly without typing numbers. Each pane has a header: its view is a menu there, its zoom or fly speed is written beside it, and the button at the right end (or a double-click on the header, or shift-space) makes it the only pane. Drag the bars between the panes to resize them.

Keys only reach the pane the pointer is over, and none of them fire while a property field has the keyboard – naming an entity wasd_door should not fly the camera across the level.

Seeing what things are. In the flat views point entities are drawn as what they are: a lamp for a light, a figure for the player start, a speaker for a sound, a diamond for logic, a crate for a prop. Their names are written beside them when you are zoomed in close enough to read them, and always for what is selected. In the 3D view a prop is its model – the one its model key names, or its class’s default – posed by its angles; anything without a model is a small box in its family’s colour. Rest the pointer on anything, in any view, and a card comes up: the class, its name, the first line of its help, the keys it sets, how many outputs and inputs it has and how many of them are broken. On a brush it gives the size and the material of the face under the pointer.

Helpers are what an entity looks like beyond its marker, as the game’s .kdef declares them: a spot light’s cone, pointing where it shines; a light’s two spheres, where it lights a surface fully and where it has all but faded; a sound’s audible radius; a panel’s rectangle; an arrow along the player start’s facing; a line to whatever a target key names. They are drawn for the selection by default – a level with every light’s sphere drawn at once is a level you cannot see – and the bulb on the toolbar cycles between the selection’s, every entity’s, and none. Flat views draw their outlines; the 3D view fills the cones.

The 3D view runs on the GPU, in the same window, so it keeps up with a whole level while you fly. Selected brushes are tinted and outlined, and their outline is drawn faintly through walls as well, so something selected behind a wall can still be found. Tool brushes – triggers, clips – are see-through. (Where there is no GPU, as in the tests, the older software rasteriser draws the pane instead.)

Shapes are drawn rather than loaded from files: an icon set is a set of things to ship, scale, theme and keep in step with the class list, and a dozen lines of geometry is none of those. Classes are matched by prefix, so a game that adds light_dynamic gets the right icon without anything here changing.

The asset browser is docked along the bottom (M, or the pictures icon on the toolbar), with a tab for materials and one for models. Names, folders, a size slider and a search that matches words in any order – so wood crate and crate wood both find props/crate_wood. Materials show what each one does on hover, read from Cleave’s table; models show a rendered preview, because a name is not a shape. Clicking a material makes it the one new brushes wear, and applies it to the selection. Clicking a model arms the entity tool with it: the next click in a view places a prop_static wearing it (or whatever prop class was already chosen), shown in place as a see-through ghost until you click. The options bar says which model is armed, and its x goes back to the class’s own. view → materials in a window... is the same browser floating, for a property field that wants a model.

The old picker was a two-column strip of unlabelled 48-pixel swatches in a 120-point panel, which is a keyhole rather than a browser. Worse, every swatch was drawn from a mip two from the end of the chain — a 2x2 image for a 256-pixel texture — so every material in the list was the same grey smudge and the only way to tell two apart was to hover both. Swatches are built from the smallest mip that is still bigger than the swatch, and a checkerboard looks like a checkerboard.

Resizing. Something selected in a 2D pane wears eight grips: four corners and four edge midpoints. Drag a corner to scale both axes at once, an edge to scale one; the opposite grip holds still, so the selection grows away from where you are pulling rather than wandering across the level. The axis the pane cannot see is left alone. Dragging a grip past the far side stops at one grid square instead of turning the brush inside out — an inverted brush is not a small brush, it is a hole in the world that compiles cleanly. The preview shows the shape it will become and its new size while you drag. The texture stays put in world space rather than stretching, so making a wall twice as wide tiles the bricks twice instead of drawing bricks twice the size.

Key-values on anything. Every object in a map – an entity, a brush, a face – carries key-values, and the Properties panel edits whatever is selected. An entity shows every key its class reads, set or not, with a widget for each (a colour picker for a colour, a dropdown for a choice, checkboxes for flags); a brush or a face shows the keys it carries, and + add a key puts any key at all on any of them. The { } toggle is Hammer’s SmartEdit switched off: every key as plain text, only the keys the object actually has. Selecting several things edits them together: a key they agree on shows its value, a key they disagree on says differs and is left alone on every one of them unless you type over it, which is how one speed lands on six doors at once. With nothing selected the tab shows the world’s own keys (the sky, the level title). Alt+Enter opens the same editor as a window, which is where the add-a-key row and the wiring editor live when there is no room in the tab. A brush’s keys mean nothing to the game – a brush that should do something is tied to an entity – but two of them mean something to the compiler: detail 1 keeps a brush out of the vis tree, section <name> puts it in a streamed section. Under the keys sit the editor’s own notes: a colour to draw the object in, and comments.

Wiring. Outputs are how a map behaves without scripting: a button’s OnPressed fires a door’s Open. An entity’s Outputs tab lists what it fires, one connection a line – output -> target.input, with the parameter, the delay and once when there are any – in the order they will fire. The light at the start of each line says whether it will do anything:

Hover the light for the reason. Click a line and a form opens under the list for that connection: the output (with its help), the target (every name in the map, and the four special targets), the input – offered from what the target’s class actually takes, with its help and what its parameter means – the parameter, the delay and only once. + Add starts another connection after the picked one, on the same output and target, which is how a sequence is built; Copy and Paste move a connection between entities. Target names are matched exactly, ignoring case, as the engine matches them: there are no wildcards, and a door* is flagged as the name nobody has.

The Inputs tab is the same list turned round: every connection on any entity that fires at this one. It answers “what opens this door?”, which a list of outputs cannot. Click one to go to the entity it is on. The tab headings count both ways, and say in red how many outputs are broken, so a broken wire is seen without opening the tab. Map → Check for problems lists every broken wire in the map with the rest.

In the views, the selected entity’s wiring is drawn: green arrows to what its outputs fire at, red where the target cannot take the input, blue from whatever fires at it. They are drawn through walls, because a wire does not care what is between.

Brush modelling. The select tool picks whole objects by default. Its other modes, in the options bar or Shift+2..Shift+4, put handles on the selected brushes: squares on the vertices, diamonds on the edges, circles on the faces. Click a handle to pick it, shift-click to add another, and drag one in a flat view to move everything picked; it snaps to the grid, and the brush is drawn as it will be while you drag. A brush has to stay convex, so a drag that would dent one is refused: the preview turns red and says why, and nothing changes. Pull a top corner up for a slope, drag two top corners down onto the bottom for a wedge, push a face out to lengthen a brush. Faces keep their material and texture alignment through all of it. In face mode, extrude grows a new brush off each picked face, as far out as the options bar says. In object mode, merge (also in the Tools menu) makes the selected brushes one, when together they are convex – two halves of a clipped block back into the block. Handles can be picked in the 3D view too, so a corner can be found by looking at it; moving it is done in whichever flat view suits.

Groups and VisGroups. Ctrl+G groups the selection, and from then on a click on any member takes the whole group – unless the select tool’s whole groups option is off, which is how you nudge one thing in a group. Ctrl+U ungroups. VisGroups are named sets you can hide together: select the things that make up a room and press Ctrl+Shift+G, name it, and the VisGroups tab has a checkbox that makes the room vanish from every pane – not drawn, not clickable, not in select-all – and a colour every member is drawn in while it is shown. VisGroups nest (right-click one for new child), and a hidden parent hides its children. Below the user’s groups the tab lists the automatic ones, made from what the map holds: every entity, every world brush, every tool brush, every class that is placed. Untick light and the lights are gone until you tick it back. H hides the selection outright, Ctrl+H hides everything but it, and U brings back whatever was hidden that way. The status bar counts what is hidden, because a hidden brush that is still there is the classic way to compile something you cannot see. Hiding is an edit: Ctrl+Z undoes it.

A visgroup marked with the stack icon is a streamed section: the engine loads and unloads its geometry around the player. See architecture for what that does and does not do.

The cordon. The box icon on the toolbar turns the cordon on: only what is inside the box is shown, and only what is inside is compiled – Cleave seals the box with its own walls, so a corner of a large map compiles and runs on its own in seconds. The arrows icon beside it puts the box’s grips in place of the selection’s so it can be dragged to size in a 2D pane. The box is drawn dashed in red, dimmer when it is off, and it is saved with the map.

Clip, carve and hollow. The clip tool (6) is how a wall gets a doorway or a slab gets a bevel: drag a line across the selection in a 2D pane, and the cut is the plane through that line running along the axis the pane looks down. An arrow on the line shows which side is front; 6 again cycles between keeping both halves, the front or the back, and Enter cuts. The new face wears the material of the face most nearly facing the same way, aligned as that one is. Carve (Ctrl+Shift+C) takes the selected brushes out of every world brush they overlap and then deletes them – a doorway through a wall in one step, at the cost of the wall becoming four brushes. Hollow (Ctrl+Shift+H) turns a brush into walls of a given thickness, mitred at the corners so no two overlap; a negative thickness builds the walls outward around it. A room is a hollowed box. All three keep a brush’s keys and visgroups on every piece.

Meshes. Tools → Convert to mesh turns the selected world brushes into polygon meshes: same shape, same materials and alignment, drawn in their own colour. A mesh is detail – drawn, lit and collided with, but it no longer seals the map or blocks visibility, so converting a wall that seals the map makes it leak and the compile says so. Meshes select, move, resize, duplicate, delete, hide and take a material like brushes; editing their vertices is not in Chisel yet. See .kmap in formats.md.

Transform. Ctrl+M rotates, scales or moves the selection by numbers, about its centre or the world origin; R is a quarter turn about the axis the active pane looks along; Ctrl+L and Ctrl+I flip it; Ctrl+B moves it so its lowest corner sits on the grid. Rotation turns the texture with the brush so a surface keeps its texel, the way moving does.

The entity report (Ctrl+Shift+E) lists every entity in the map: filter by class or name, point or brush, click one to select and frame it in every pane, double-click for its properties. It marks every output aimed at a name no entity has, which is otherwise found by playing the map and wondering why the door did not open. Edit → History... is the undo stack with names on it; click a step to go back to it.

Shapes that are not boxes. A brush is a convex solid and no convex solid is curved, so an archway cannot be one brush. It is several, arranged to read as a curve — which is miserable to do by hand and is why people give up on curves. The shape tool (5) generates them: drag a box in a 2D pane the way you would with the block tool, and it fills it.

The pane you draw in decides which way the shape stands: a cylinder drawn from above is a pillar, the same drag in the front view is a pipe lying across the room. Sides, arc and wall thickness are on the options bar, and only the ones the chosen shape uses are shown. The preview draws the actual shape and the number of brushes it will cost, not the box it is being fitted into. A whole arch is one undo step.

cargo run -p kerosene-chisel --example shape_sheet -- shapes.png renders every shape in both orientations. Geometry has a way of being valid and still wrong; a test can say the brushes are solid, only a picture can say they are an arch.

Brush properties. A brush’s type is a setting on it, at the top of its panel: world geometry, detail, door, trigger_multiple, and so on. Choose one and its settings appear underneath, in the same panel, with nothing to press first. There is no “tie to entity” step — that was a mode change to reach settings that were never anywhere else, and it left detail, which is a wall and has nothing to configure, looking exactly as configurable as a door.

Changing the type is one operation and one undo step, and it keeps the name and the wiring: dropping a targetname would silently break every output pointing at it.

A trigger textures itself. Pick a trigger_* type and its brushes become tools/trigger, so it is invisible and compiles as a region. Forgetting to do that by hand compiles a solid block where a doorway was meant to be, and the map looks broken in a way that has nothing to do with triggers. A door keeps whatever it was textured with, because only a designer knows which door.

The panel also says what the brushes will compile as, read from Cleave’s own material table rather than a copy of it, so the editor and the compiler cannot disagree. It is where tool textures stop being paint: tools/clip says “blocks players only; bullets and sight pass through”. Two rules that surprise everybody are called out on the spot:

• One tool face changes the whole brush. Solid is the absence of anything more specific, so a single tools/clip face on an otherwise ordinary box stops the box being a wall.
• A misspelt tool material is not an error. tools/clipp compiles as ordinary world geometry, which is how a doorway gets walled off by a typo nobody sees. The panel says so in red.

Where a door goes. Select a brush entity that moves and the 2D panes draw its travel: an arrow along movedir, an outline where it ends up, and a label saying how far and which way. The distance comes from kerosene_game’s own formula, so the picture and the door agree by construction rather than by luck. Anything with angles gets a facing arrow the same way.

Building a level. Draw brushes with the block tool in a 2D view; they snap to the grid, outward, so a brush is never smaller than the rubber band. Pick a material from the asset browser (M) — picking one with something selected applies it. Place entities with the entity tool; its class is picked on the options bar, grouped by family and searchable. Give brushes a type in the Properties panel to make them a door or a trigger. Wire outputs to inputs on the entity’s Outputs tab.

Wiring, in firing order. A .kmap stores wiring as a flat list of connections. The Outputs tab lists them grouped by output and sorted by delay – the order they will actually fire in – and + Add after a picked line starts the next step of a sequence a tenth of a second later, because two actions at the same instant fire in whatever order the file happens to hold.

Alternatives need an entity that can choose. Every other class fires a list; firing one of two lists depending on something is a decision, and a decision cannot be faked in the editor. That is what logic_branch is for: it remembers a yes or no and fires OnTrue or OnFalse, never both. When one side of a pair is wired and the other is not, the Outputs tab says so, with a button to wire the other — an OnTrue with nothing on OnFalse does nothing half the time, which is a bug you find by playing rather than by reading.

Dragging a selection shows a ghost of it at the destination, in every pane at once including the 3D one, with the offset written out in kerosene units. The rubber band a drag sweeps out is not where anything ends up, so it is not what gets drawn.

Clicking a brush that belongs to an entity selects the entity, not the brush: that is what a designer means by “the door”.

Entity properties. The inspector is driven by the game’s class definitions – the .kdef files Chisel finds under the content root. For a selected entity it lists every key its class reads, whether or not the entity has been given a value for one, with the type, the game’s default and a line of help. Keys are edited with a widget suited to what they hold: a colour picker for a light’s colour, checkboxes for a spawnflag field, a menu of the map’s entity names when wiring an output. A key the definitions do not describe is still shown – that is how a typo becomes visible rather than silent.

Without a .kdef the inspector can only show the keys an entity already carries, which for a freshly placed entity is none. Chisel says so in the status bar rather than looking like a game with no settings.

The 3D pane draws the materials themselves, mipped and filtered, with a selected face tinted rather than painted over so you can still see what it is wearing. view switches between textured, flat colour (each material’s average, when a texture is too busy to read shape through), shaded only (untextured grey, for hunting a brush in the wrong place) and walkmap – which colours each face by its walkmap rule (green to go, red to stay away) without touching the texture, so you can read where NPCs may go without compiling. Lighting is not previewed; compiling and running the map is one keystroke away.

Tool volumes are drawn see-through, as they are in Hammer, because that is what they are: a trigger is a region, not a wall, and one drawn solid hides the room it is sitting in. tools/nodraw and the other solid tool materials are the exception – those are walls, just ones nobody sees, so they stay opaque. A volume does not write depth either, so two overlapping ones both show and neither erases what is behind it.

It reads the compiled .ktex, through the same VFS the engine uses, so what it shows is what the engine will draw – including from inside a .vault archive. The consequence is worth stating plainly: the content has to be built. A material Alchemy has not compiled yet shows as a flat colour derived from its name, so it is a wrong colour rather than a black hole, and view → reload textures picks up a rebuild without restarting.

Materials are picked from a grid of what they actually look like, with a filter box. A list of names is only usable by someone who already knows what every name looks like, which is nobody on their first level.

Face editing. With the texture tool, clicking a face in the 3D pane selects it (shift adds, ctrl picks its material up), and the inspector becomes a face editor: scale, shift, rotation, fit, align to world or to the face itself, justify to an edge or the middle, the lightmap scale, and the face’s walkmap rule – allow, deny, avoid or always – which decides whether the compiler puts that face in the NPC walkmap. Everything acts on the whole selection as one undo step, and a value the selected faces disagree about shows as -- rather than as one of them.

The texture tool has two settings, chosen in the toolbar: what it selects – single face or whole brush (a brush entity is selected whole, as the door) – and when it applies, cycled with T: select only, apply on double-click (the default) or always apply. Shift always just selects, in every combination. The face editor only applies when a face is selected, so it simply has nothing to show for a whole-brush selection.

Compiling. The compile button on the toolbar (or F9) compiles fast and runs. map → compile settings... opens the settings with three buttons: compile runs exactly what the dialog is showing, while fast and full apply a quality preset and leave every other choice alone. That distinction matters – “build even if the map leaks” is not something a quality preset gets to forget. The dialog closes when the compile starts; the log streams into the toolset’s output panel, where it does not cover the map.

A compile starts by running Alchemy over content/art, so a texture added or changed since the last build is compiled before the map that uses it, and the editor’s own texture cache is reloaded when the compile finishes – a new texture shows up in the pane without a restart. Uncheck build materials to skip that stage when the art has not moved.

When a map is not sealed, Cleave writes a .kleak trace beside it and Chisel loads it and draws the route out in red, through every pane. Follow the line to the wall it goes through. map → clear the leak trace puts it away.

Chisel runs the compilers by re-invoking the same executable with the compiler’s name as a subcommand, so they are always present. map → check tools are installed still says which pieces it found, including the engine runtime it launches after a compile.

Developer textures. kerosene-tools alchemy dev-textures writes the standard set, and scripts/build-content.sh runs it: dev/ measurement checkerboards where one cell is 16 ku at the default texture scale, and the full tools/ set – nodraw, clip, playerclip, trigger, hint, skip, skybox and the rest – each a flat colour with its own name written across it. The compiler already understood every one of those; until now none of them had a texture, so picking one in the editor showed nothing.

Units. Distances are kerosene units (ku); one is an inch. A player is 72 ku tall and runs at 320 ku/s, which is the scale a room is judged against. The status bar carries the unit on every number, with metres and a player-height comparison on hover.

Cleave — the BSP compiler

kerosene-tools cleave map.kmap [-o out.kbsp] [--ignore-leaks] [--no-fill] [--dry-run] [-v]
                     [--content <dir>] [--cordon "minx miny minz maxx maxy maxz"] [--no-cordon]

.kmap → .kbsp plus a .kprt portal graph for Umbra, and a .kwalk NPC walkmap built from the world’s flat walkable faces. The walkmap is written every compile – the compiler already has the final face polygons, so the designer does not run a separate step to get one.

Reports every brush and entity problem in one pass rather than stopping at the first, because a designer would rather fix five brushes in one cycle than five.

Leaks. If the flood fill escapes to the void, the map is not sealed and Cleave refuses to build it — visibility would be nearly useless and the compile would take far longer. --ignore-leaks builds it anyway and writes a .kleak trace naming the route out, which is the only practical way to find a one-unit gap in a large map.

A compile that seals the map deletes any .kleak left beside it by an earlier one. A stale trace is worse than none: Chisel loads whatever is on disk, so a map that leaked once would go on reporting a leak through every successful compile after it.

Tool materials

Compile-time intent is expressed with the texture applied to a face, as in Source. Everything under tools/ is a tool material.

An entity’s classname overrides its brushes’ materials: a trigger_multiple is a trigger whatever its faces are textured with, and a detail is detail.

Detail brushes stay out of the world tree. A handrail modelled from thirty brushes would otherwise carve the room into thirty slivers, each of which the visibility compile then has to consider. This is the single biggest lever a designer has over compile time.

Umbra — the visibility compiler

kerosene-tools umbra map.kbsp [--portals map.kprt] [--fast] [--dry-run]

Computes which clusters can see which, and writes the PVS back into the map.

Reports “clusters visible per cluster” — the single best predictor of frame rate in a BSP engine. Lower is better.

--fast stops after the base estimate: much quicker, leaves far too much visible, and exactly what you want while a layout is still moving.

Umbra also writes the potentially audible set — the PVS grown by one room — which is what lets the engine silence a sound that has no way of reaching you.

Resonance — the acoustics compiler

kerosene-tools resonance map.kbsp [--content DIR] [--portals map.kprt]
                  [--fast | --extra] [--rooms] [--dry-run]

Works out what each part of the map sounds like, and writes it back so the engine’s reverb reads it straight off the map. An empty concrete hall rings; a carpeted office does not; a courtyard open to the sky barely does at all — and nobody placed anything to make it so. See audio.md for what the engine does with it.

It listens by throwing rays. From inside every leaf a few hundred rays go out and bounce until they have nothing left, and each surface they strike gives up how much it soaks up per band — from the material’s $surfaceprop, or its $acoustics key when a designer has said otherwise. The averages are what Eyring’s formula wants, measured rather than assumed, in a shape no formula assumes. Leaves that touch and sound alike are then gathered into rooms, one record each, so a hall the BSP cut into twenty pieces is one hall again and a doorway is a boundary because the two sides disagree.

--rooms prints the table. --fast uses a third of the rays, which is rougher and several times quicker; --extra four times as many, for a final build. It needs the materials, so it is told where the content is like Cleave is, and it reads the portal file Umbra reads to know which leaves touch — without one it joins leaves whose bounds touch, which is close.

The whole thing is deterministic — the rays are seeded from the leaf index — so the same map compiles to the same bytes, and a room that rings differently after a rebuild does so because the map changed.

Radiance — the lighting compiler

kerosene-tools radiance map.kbsp [--samples 1-8] [--bounces 0-8] [--scale N]
                  [--ambient-scale N] [--cubemap-size 4-256] [--fast] [--dry-run]

Bakes static lighting from the map’s own light entities, then the reflection probes.

Brightness reads directly at 100 inches with the default quadratic falloff, so a _light of "255 255 255 200" delivers 200 units of light at normal room distance.

pitch on a light entity is upward-positive, so a lamp shining at the floor is pitch -90.

--samples softens shadow edges at quadratic cost. --bounces 1 is what turns a room lit by a single lamp from a hard pool of light into something that reads as an interior.

A map with no lights compiles fine and is then pitch black, which looks like a broken renderer — so Radiance says so.

Reflection probes. After the lightmaps, Radiance stands at each env_cubemap and records what it sees in every direction – one ray a texel, the colour being the lightmap where the ray landed times the surface’s reflectivity, or the sky’s colour if it escaped. --cubemap-size is the edge of each face, 32 by default, which is what Source ships its cubemaps at; the renderer blurs them further for rough surfaces. Put one at head height in each room. Every smooth or metal face reflects the nearest probe it can see, and a room with none reflects an even glow instead. A probe inside a wall sees nothing and Radiance says which. Unlike Source’s buildcubemaps, this is part of the compile: there is no step to forget.

Alchemy — textures and materials

kerosene-tools alchemy compile art/grid.png -o materials/dev/grid.ktex [--normal] [--clamp] [--ui]
kerosene-tools alchemy material dev/grid --basetexture dev/grid --shader lit
kerosene-tools alchemy batch art -o materials --make-materials
kerosene-tools alchemy new-texture Walls/brick --basecolor b.png --normal b_n.png
kerosene-tools alchemy texture-set content/textures/Walls/brick
kerosene-tools alchemy build content
kerosene-tools alchemy info materials/dev/grid.ktex

Compiles PNG/JPEG/TGA into .ktex, authors .kmat materials, and compiles them to the .kmat_c the engine loads.

new-texture is the deliberate way to add one. It makes a folder under content/textures/, copies the images in under canonical names, and writes the texture.kcfg that documents what the set can say — as against the older route of dropping a PNG under art/ and relying on a filename suffix to be guessed correctly. The folder is a texture set: colour, normals, roughness, emissive and occlusion compiled together, plus the material binding them. See formats.md for the folder layout and the config keys.

texture-set compiles one such folder by hand. It derives the set’s name the same way a full build does — by climbing to the textures/ directory above it — so a set compiled either way ends up called the same thing. Pass --root to say otherwise.

build is the whole texture half of a content build for one project: the developer set is generated into art/, then everything under art/ is compiled into materials/, then every texture set under textures/ is. Sets go last, so a set may deliberately shadow a loose image of the same name: the folder is the more specific statement of the two. A project with no textures/ directory builds as it always did. It is one command because three callers need exactly it – this tool, scripts/build-content.sh, and Chisel on the way to opening its window – and three callers with three ideas of what “build the textures” meant is how the editor came to open with no textures in it while the build script insisted everything was fine. Alchemy is a library as well as a command so the editor can call it rather than shell out to a sibling binary that may not be on the path.

batch and build skip an image whose .ktex is already newer than it, so a build with nothing to do costs a directory walk.

Alpha is dropped when an image does not use it, which saves a quarter of the memory. In batch mode, a file ending _normal or _n is taken to be a normal map — the convention beats a flag, because batch compiles run unattended.

Forge — the model compiler

kerosene-tools forge compile art/crate.obj -o models/props/crate.kmdl
                            [--scale-metres] [--z-up] [--scale N]
                            [--material old=new] [--recompute-normals]
kerosene-tools forge compile art/turret.glb -o models/props/turret.kmdl
                            [--scale N] [--material old=new] [--once clip]
kerosene-tools forge info models/props/crate.kmdl

OBJ or glTF (.gltf, .glb) → .kmdl, splitting by material and welding vertices.

glTF carries what OBJ cannot: a skeleton and its animations. Forge reads every triangle mesh in the default scene, the first skin as the model’s bones (parents first, rest poses from the skin’s inverse bind matrices), and every animation, resampled at 30 fps; bone translation and rotation are kept and animated scale is warned about. glTF is metres, Y-up and faces +Z by definition, so there is no --scale-metres or --z-up to get wrong. Clips loop unless named with --once. Kiln picks up .gltf and .glb under art/ beside .obj. A prop_dynamic plays the result.

Two conversions happen on the way in, and getting either wrong produces a model that is subtly rotated or a hundred times too small. OBJ is Y-up with -Z forward; Kerosene is Z-up with +X forward. And modelling packages usually work in metres — --scale-metres converts.

Winding is taken from the OBJ as-is (the axis remap preserves handedness), so export your faces counter-clockwise from the front: .kmdl stores them that way, and a face wound the other way renders inside out. --recompute-normals rebuilds normals from the winding and ignores any in the source, but it does not repair a source that was wound backwards to begin with.

Welding is by the full corner tuple, not by position: two faces meeting at a hard edge legitimately share a position while needing different normals, and merging them rounds off every corner of the model.

Kiln — building a project

The Build tab in the toolset window – stages as cards with a switch each, fast, rebuild everything, ignore leaks and dry run as options, Build and Cancel, and the log in the output panel – and also a headless stage:

kerosene-tools kiln                              # build everything, from here
kerosene-tools kiln --content path/to/content    # or from there
kerosene-tools kiln --only maps --fast           # just relight, quickly
kerosene-tools kiln --only textures              # after adding art
kerosene-tools kiln --dry-run                    # say what would run
kerosene-tools kiln --tools                      # which pieces can be found
kerosene-tools kiln --force -j 4                 # rebuild everything, on four threads
kerosene-tools kiln --clean                      # delete what the build wrote
kerosene-tools kiln --watch --fast               # build again on every save
kerosene-tools kiln --ship dist                  # build, then assemble a distribution

Runs the whole content pipeline over a project: the texture build, then models through Forge, then every map through Cleave, Umbra, Resonance and Radiance, then the pack into a .vault.

It is a program rather than a shell script for one reason, and it is the reason that matters: a script is not shipped. Install the tools, or copy them somewhere, and the thing that knows how to use them stays behind in a git checkout — so the first thing anyone does with a fresh copy of the toolchain is discover the build step is missing. Kiln is part of the one toolset executable, so it needs no shell.

The compilers are stages of the same toolset and Kiln drives them by re-invoking the executable with the stage’s name as a subcommand, exactly as Chisel does. You can still run any stage by hand or from a build server. Only the texture build is a library call, because Chisel makes the same one and the two must not be able to disagree.

Sources decide what gets built: every .obj under art/ becomes a .kmdl at the matching path under models/, and every .kmap under maps/ becomes a .kbsp. Nothing has a list to keep up to date.

A map is rebuilt when its source is newer than its .kbsp, when it was built fast and this build is not, and when any material or texture changed since: Cleave sizes every face by its texture and Resonance reads every material. The compilers are told the same things Chisel’s F9 tells them – one list, kerosene_vfs::toolchain::MapStages, decides both.

--watch stays running after the build and builds again whenever a source changes, polling the tree twice a second and waiting out a burst of saves. What the build writes is not watched. kerosene-tools play --watch does the same while the game runs, and starts the game with map_autoreload 1, so a rebuilt map is loaded again with the player where they stood.

A map that leaks still compiles, and is reported at the end rather than stopping the build — finding out on the first of forty maps that the run is over is not a service. With --ignore-leaks it is built in full and the leak is a warning. The archive is named after the project and written inside the content tree, which is where the engine looks for it.

scripts/build-content.sh in this repository is a thin wrapper: it builds the toolset from source and regenerates the base room from the code that defines it, then calls Kiln and packs the engine’s base content. None of that belongs in a shipped tool.

--ship <dir> is the stage after the content: it builds the project’s game package if the .kproj names one (or takes the kerosene runtime beside the toolset if not), then assembles a distribution — the binary, the .vault under content/, a .kproj pointing at it, both licence texts and a README.txt carrying the notices the licences require. It copies a named list of files rather than a directory, so no tool ever ends up in a player’s hands, and it refuses an archive that is missing or older than the content tree rather than shipping maps nobody built. What it does and does not do for a release is the subject of Publishing.

Vault — content archives

The Archive tab in the toolset window – pack and verify, with the log in the output panel, whether the archive is older than what it packs, and its contents as a searchable table – and also a headless stage:

kerosene-tools vault pack content -o content/kerosene_content.vault [--ext ktex] [--exclude tmp]
kerosene-tools vault list content/kerosene_content.vault [--long]
kerosene-tools vault verify content/kerosene_content.vault
kerosene-tools vault unpack content/kerosene_content.vault -o extracted

The archive belongs inside the content tree, which is where a shipped game keeps its archives and where the engine looks without being told. Writing it into the tree it packs is safe: .vault is never one of the extensions packed.

Packs a content tree into one archive. Every entry carries a CRC, checked on read and by verify.

Loose files still shadow packed ones when both are mounted, so a developer can drop a file next to a shipped archive without repacking.

kerosene — the runtime

kerosene [+command ...] [--content <dir>] [--vault <file>] [--headless <ticks>]

Arguments beginning with + are console commands, so any convar is settable from the command line with no flag needing to exist for it:

kerosene +map kerosene_room
kerosene +map kerosene_room +sv_gravity 200 +developer 1
kerosene --headless 640 +map kerosene_room
kerosene --content path/to/content --vault extra.vault +map kerosene_room

--headless runs the simulation with no window at all — which is what a dedicated server is, not a testing mode bolted on the side.

With no --content, the engine finds the content tree the way every tool does (see Chisel, above) and says which one it took. With no --vault, every .vault in that tree is mounted, in name order, so a packed install runs without being told about its own archives. Loose files still win over packed ones, which is what makes dropping a file beside a shipped archive work.

A map that will not load says why rather than saying “not found in any search path”. The usual reason is that it has never been compiled — the .kmap is right there and nothing turned it into a .kbsp — so that is what it says, along with the command to run and the list of paths it searched.

The console

` opens it, ` or escape closes it, and toggleconsole does the same from a binding or the command line. Those two keys are read by the host before anything else sees them and are never passed on — a way out that the thing you are trying to leave can capture is not a way out, and handling them any later meant the console’s own text field swallowed them. The same mistake put the backtick that opened it into the prompt, so every command typed afterwards began with a character that made it unknown.

While it is open the console takes the keyboard completely and releases the mouse: a console you cannot type an n into without walking forward is not a console. Tab completes the command word and cycles the candidates, up and down walk history, page up and down scroll without disturbing what you are typing.

It introduces itself the first time it opens, because an empty box with a blinking cursor reads as “this accepts nothing”:

Kerosene console -- 52 commands and convars. `find <text>` searches them,
`help <name>` explains one, `cvarlist` lists the lot. Tab completes, up walks
back, ` or escape closes.

Log lines from the engine appear in it as they happen. Crates that are not ours — the graphics backend, the window library — are held to warnings, so opening the console to read one line does not mean scrolling past a page of Vulkan loader chatter. RUST_LOG lifts that: someone who sets it is debugging the thing they set it for.

Useful convars

sv_air_max_wishspeed is the air-speed cap that makes bunny-hopping and surfing work. It is 30 by default, and it is not a bug: changing it changes the game.

Timbre — the sound compiler

Turns .wav, .flac and .mp3 into .kaud. It is the one tool with no Source counterpart, because Source shipped .wav and paid for it in download size; this pays a compile step instead. It is the sound tab in the toolset window, and also a headless stage:

kerosene-tools timbre                          # the sound tab
kerosene-tools timbre build                    # compile a project's sounds
kerosene-tools timbre compile a.wav --gain 0.8 --mono
kerosene-tools timbre info a.kaud

What it reads

WAV goes through the engine’s own decoder — the one that also reads smpl chunk loop points. FLAC and MP3 go through Symphonia, which is a dependency this project would not accept in the engine and does accept in a build tool: see licensing.md.

MP3 is read because people have MP3s, not because it is a good thing to build from. Compiling one to ADPCM is lossy-to-lossy — the artifacts compound rather than cancelling, and the second encoder spends its bits describing the first one’s mistakes. Timbre says so every time, and says so again if the result comes out larger than the source, which for an already-compressed input it often does.

A file whose extension lies about its contents is named as such rather than reported as corrupt: a .wav that is really an MP3 is a thing that happens to downloaded files, and “not a RIFF/WAVE file” sends you looking for the wrong problem.

FLAC can carry a loop region in LOOPSTART/LOOPLENGTH Vorbis comments, which is what game audio has settled on, and Timbre reads it — otherwise a looping ambience compiled from FLAC loses what the same sound in a WAV would keep.

What it decides

Encoding. ADPCM at a quarter the size, or 16-bit PCM. Per sound, not per project: ADPCM is close to transparent on impacts, speech and machinery, and audible on a quiet room tone with a lot of air in it. It also has an attack transient — the quantiser starts at its smallest step and takes a few milliseconds to reach a loud signal — which softens a sharp onset. PCM16 is the escape hatch for material where either matters.

Gain. Applied before encoding rather than at play time, so a sound recorded too hot is fixed once instead of in every entity that plays it.

Loop points. Read out of the WAV’s smpl chunk if it has one. Before this, looping was all-or-nothing: a room tone with a proper loop region had it thrown away and was repeated end to end, click and all.

Channels. A sound placed in the world has to be mono — there is one pan and a stereo file already carries its own left and right, so positioning it applies a pan to a signal that is not a point. Timbre says so, and can fold it down.

The window

timbre with no arguments opens it, because every one of those decisions is better made by seeing and hearing the result than by reading a number. A gain of 0.8 means nothing on a command line; the same 0.8 with the waveform redrawn under it and the clipped samples marked in red means something at a glance.

• The waveform is the samples that will actually be written, not the source.
• Peak and a live level meter, the second following the playhead.
• Play through the same mixer the engine uses.
• Gain in decibels, encoding, mono, and the loop region shaded on the wave.

Settings are written to sound/timbre.kcfg and read back by timbre build, so the window and the command line cannot disagree about what a build is — the same discipline that makes the texture build a library call rather than a second implementation.

Where the window comes from

kerosene-toolui is a window with egui in it, and the look every tool shares: winit’s application handler, a wgpu surface, an egui integration and the frame loop that drives them, plus theme (the palette, the spacing and the Phosphor icon font, installed once by run), widgets (tool buttons, tabs, sections, chips, menu items with their shortcuts on the right, a dialog) and output (the panel every job logs into). Implement App, call run. It exists because the window is three hundred lines with nothing to do with any particular tool, and a second copy of them is a second place for a resize bug to live – and because a palette each tool chose for itself would be three palettes.

The window icon is the Kerosene mark from .github/Images/, compiled into every binary that opens a window (kerosene_config::icon) and set on the window. X11, Windows and macOS show it from there. Wayland does not let a window carry its own icon: the compositor shows the icon of the .desktop file whose name matches the window’s app id, which is kerosene. scripts/install-desktop.sh installs that entry and the icon set under ~/.local for the current user; --uninstall takes them out again.

Versioning

Kerosene has one version number, and it is the kerosene crate’s. That crate is what a game depends on, so its API is what a version number has to be honest about. It follows Semantic Versioning:

Kerosene is developed as a workspace of crates — the engine’s parts, the tools, the formats — and published as one. cargo xtask bundle folds every workspace crate into kerosene as a module, so crates.io holds exactly one crate, a game adds exactly one line, and there is nothing to mix: every part of a given version was built and tested together.

What the promise covers

Covered, where a breaking change needs a major version:

• The items at the root of kerosene: launch, LaunchOptions, Game, Engine, EngineConfig, VERSION, and kerosene::prelude.
• The modules kerosene::engine, entity, math, console, physics, script, ui, platform, vfs, game and, with the tools feature, tools.
• The third-party crates kerosene re-exports for a game’s own use: egui, glam, rhai, winit, serde_json, anyhow and log. A breaking release of one of them reaches Kerosene only in a major release.
• The Cargo features audio, steam and tools.
• What a game’s content relies on: the entity classes and their keys, inputs and outputs; the .kproj keys; the console commands and convars the engine registers; the Rhai functions scripts can call; and the command-line flags of the engine and the tools. A map that loads and plays in 1.2 loads and plays in 1.3.
• The file formats, as the next section says.
• The minimum Rust version, rust-version in Cargo.toml. Raising it is a minor change, never a patch, and is always in the changelog.

Not covered, and free to change in a minor release:

• kerosene::internals: asset, audio, bsp, config, kv, map, material, render and walk, and physics::rigid. They are public because tools and ambitious games need them, and they change as the engine does.
• Anything #[doc(hidden)], such as Engine::level and Engine::physics.
• kerosene::__k, where the bundle keeps the workspace’s crates. It is hidden, and everything a game needs from it is re-exported above.
• Log messages, console output wording and the look of the editor.

How Kerosene keeps it

• Types that will grow are built to. LaunchOptions, EngineConfig and kerosene_tools::Options are #[non_exhaustive] with constructors and setters, so a new option is not a breaking change. The same goes for enums a game only matches on, such as the error enums, PlatformAction and StatKind.
• Enums the engine dispatches on are not #[non_exhaustive]. ScriptAction, UiAction, PlatformEvent, WeaponEvent and the two Value enums are matched exhaustively inside the engine, so that a new variant cannot be forgotten there. The price is that adding a variant to one of them is a major change.
• Game’s methods all have defaults, so a new hook is a minor change.
• Checked at release. cargo semver-checks compares kerosene’s API with the last release, as a step of releasing. During the 1.0.0 pre-releases it reports; from 1.0.0 it blocks the release.

Formats

Compiled files and saved games have their own version numbers, apart from the crate’s:

A format change is judged by what it does to files people already have:

• A new version that still reads the old one — a new lump, a new optional key — is a minor change.
• A new version that cannot read the old one is a major change, even if no Rust signature moved. A game’s players have saved games, and a game’s developers have compiled maps.

Compiled content is rebuilt from source with cargo play or kiln, so a format change is also listed in the changelog with what to rebuild.

Pre-releases

Until 1.0.0, versions are 1.0.0-aN (alpha), then 1.0.0-bN (beta), then 1.0.0-rc.N. A pre-release may break the API from the one before, and the changelog marks each such change Breaking with what to do. Cargo never picks a pre-release for a game on its own: a game opts in by naming one.

Making a release

scripts/bump-version.sh <version> sets every crate’s version and exact pins, dates the changelog’s Unreleased section and updates Cargo.lock. Tags are the bare version, 1.0.0-a2, and pushing one builds the toolset and runtime for each platform and attaches them to a GitHub release. Releasing is the whole checklist.

Releasing

How a version of Kerosene goes out. Versioning says which number it gets; this is the order of things.

Before

1. Choose the number. Read the changelog’s Unreleased section against what the promise covers. Anything marked Breaking is a major version (or the next pre-release, before 1.0.0). cargo semver-checks -p kerosene --baseline-rev <last tag> says what changed in the API since the last release; it is advice before 1.0.0 and a gate after.
2. Base content. If anything under content/ that the engine’s base content holds has changed, run scripts/build-content.sh, which repacks crates/kerosene-engine/base/base.vault. cargo test -p kerosene-engine base fails when it is stale.
3. Green. cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings and cargo test --workspace, and CI green on every job. cargo +<rust-version> check --workspace with the rust-version from Cargo.toml keeps that promise.

The release

scripts/bump-version.sh 1.0.0-a3
git diff                          # Cargo.toml, CHANGELOG.md, Cargo.lock
git commit -am "Kerosene 1.0.0-a3"
git push
cargo xtask publish               # checks, publishes, and offers to tag
git push origin 1.0.0-a3

Pushing the tag runs .github/workflows/release.yml. It builds kerosene-tools and the stock kerosene runtime for Linux, Windows and macOS, and attaches them to a draft GitHub release. The release’s text is the changelog’s section for the version, and a version with a - in it is marked a pre-release. It is a draft because the repository’s releases are immutable: once published, a release takes no more files, so the archives go on first and you publish the draft from the Releases page when they are all there.

So do not make the release by hand before the workflow runs: if one already exists for the tag, the workflow stops and says so. Delete it and re-run the release job.

crates.io

Kerosene is published as one crate, kerosene, with the whole workspace folded into it. Publishing is done by hand, because it cannot be undone, and from the repository root:

cargo xtask publish --dry-run          # everything but the upload
cargo xtask publish

Before it uploads anything, publish checks for the usual mistakes:

A dry run shows every finding and carries on to the bundle and cargo publish --dry-run regardless. After a real publish, it offers to tag the commit with the version; pushing the tag (git push origin <version>) runs the release workflow. --yes answers yes to every question, for a script; with no terminal and no --yes, the answer is no.

By hand, the same is:

cargo xtask bundle                     # target/bundle/kerosene
cd target/bundle/kerosene
cargo publish --allow-dirty            # the bundle is generated, so git ignores it

cargo xtask bundle copies every workspace crate into target/bundle/kerosene/src/__k/ as a module, rewrites the paths between them, flattens their features into the facade’s (audio, steam, tools), gathers their dependencies into one manifest, and adds the kerosene and kerosene-tools binaries and the licence texts. Nothing in the workspace is published by itself; every package there says publish = false.

CI’s bundle job does all of that on every push, and runs cargo package, which builds the packaged crate again on its own, as crates.io will, and checks it is under the 10 MB limit. The new-game job makes a game against the bundle on all three platforms and plays it. So the dry run should hold no surprises.

Players and game developers install the toolset from it:

cargo install kerosene --features tools     # kerosene-tools and kerosene

The licence expression is GPL-3.0-or-later WITH AdditionRef-Kerosene-Exception-1.0, in every crate’s Cargo.toml and every source file’s SPDX-License-Identifier line. AdditionRef- is how SPDX (from 2.3) names an addition to a licence that is not on its list, which the Kerosene Exception is. cargo-deny parses it and cargo package carries it as written; deny.toml allows Kerosene’s crates under exactly that expression, never the bare GPL. crates.io accepted it for 1.0.0-a2.

After

• Check the draft release has three archives, publish it, and check each one runs: kerosene-tools new then cargo play against the released version.
• Start the next Unreleased section of the changelog as changes land.

Software design document

This is the top-down design of the Kerosene engine: what it is for, how it is put together, why it is put together that way, and where it is going. It is the place to start when you need the whole picture, and the place to record a design decision so it is not lost.

It is deliberately not a second copy of the rest of the book. Each chapter states the design and the reasoning, then links to the page that holds the detail:

Chapters

1. Goals and scope
2. Design principles
3. Architecture
4. Runtime
5. Data and the build pipeline
6. World and entities
7. Subsystems
8. Tools
9. Public API
10. Quality
11. Decision log
12. Status and roadmap
13. Open issues

Editing this document

• One chapter is one file in src/sdd/. Edit it, and keep the chapter list above and in src/SUMMARY.md in step.
• Change Last reviewed above when you review the document, not on every typo fix.
• State a design as a rule plus a reason. A rule with no reason cannot be re-examined later.
• Anything that must stay true of the code belongs in a check (cargo xtask layers, a test), with the chapter pointing at it. A claim only in prose drifts.
• New decisions go in the decision log; known gaps go in open issues. Remove an issue when it is fixed.
• Diagrams are mermaid blocks, as in the devnotes.
• Relative links only: CI runs scripts/check-links.py over the book.

To preview: mdbook serve in the repository root.

Goals and scope

What Kerosene is

Kerosene is a Source-1-style game engine written in Rust: BSP levels built from brushes, baked visibility, lighting and acoustics, entity I/O wiring, and a fixed-rate simulation. It ships as one published crate, kerosene, that a game depends on, plus the toolset (an editor and compilers) a game uses to make its content.

The crate is the product. Its public surface is what the engine’s version number follows; see Public API and Positioning.

Goals

1. A game is a crate. A game implements the Game trait, registers its own entity classes and calls kerosene::launch. The engine owns no game.
2. Fast runtime, slow build. Everything expensive (visibility, lighting, acoustics, texture and model compilation) happens in tools. The runtime loads compiled files only.
3. A complete toolchain. Level editor, compilers, asset tools and a whole-project build ship with the engine, so a game does not need to build its own.
4. Headless by construction. The simulation runs with no window, GPU or input device, so it can be tested and later hosted as a server.
5. Stable where it matters. One lockstep version, SemVer over the facade’s stable modules.
6. One declaration per fact. An entity field is declared once and the map loader, saves, editor and scripts all read that declaration.

Non-goals

• Not a general-purpose engine. There is no scene graph, no open-world streaming of arbitrary assets, no visual scripting. The shape of a level is a BSP of brushes.
• No runtime compilation of source content. .kmap source is linked only by tools.
• No networking yet. There is no client/server protocol, replication or prediction. The headless Engine is the groundwork. See Status and roadmap.
• No migration tooling in alpha. Breaking changes need no migrate command or shim until 1.0 or until real games depend on the engine. See the decision log.

Users

Constraints

• Rust edition 2024, MSRV 1.94, toolchain pinned in rust-toolchain.toml.
• Linux, Windows and macOS; CI builds all three.
• GPL-3.0-or-later with the Kerosene exception, so games built on the engine are not forced to be GPL. See Licensing.
• Units: 1 ku (Kerosene unit) = 1 inch, Z up.

See also

• Positioning
• Missing features
• Licensing

Design principles

Three rules govern the whole engine. Each is enforced, or should be, by something other than good intentions.

1. Nothing points upward

Crates sit in layers and depend only on the layers below. Subsystems (render, physics, audio, entities, scripting, UI) do not depend on each other; when two need to share something, it moves down a layer or the engine passes it across.

Why: it keeps each subsystem testable alone, and stops the engine growing a tangle where changing audio breaks rendering.

Enforced by: cargo xtask layers, which reads the table in xtask/src/layers.rs and runs in CI. A new crate is an error until it is given a layer. See Architecture.

2. Everything expensive happens at build time

Source content is compiled by tools into formats the runtime reads directly. Visibility, lighting and acoustics are baked. The runtime does no CSG, no lightmap solving and no format conversion.

Why: it makes the runtime small and its frame time predictable, and gives a clear line between “the editor” and “the game”.

Enforced by: kerosene-map (the .kmap source format) may only be linked at layer 5 or above. See Data and the build pipeline.

3. The engine owns no game

The engine defines the Game trait and the machinery around it. Doors, triggers, weapons and the rest are a game, and the stock set lives in kerosene-game as one implementation among possible others. kerosene-engine does not depend on it.

Why: a game must be able to replace any of the rules, not work around them.

Enforced by: the dependency graph: kerosene-game is a dev-dependency of the engine for tests only. See Runtime.

Supporting conventions

See also

• Crate map
• Architecture
• Refactor design document (the audit that set these rules)

Architecture

Layers

---
config:
  layout: elk
---
flowchart TB
    L7["7 runtime binary<br/>apps/kerosene"]
    L6["6 facade<br/>kerosene"]
    L5["5 tools<br/>chisel, cleave, umbra, resonance, radiance,<br/>alchemy, timbre, forge, kiln, vault, loupe, tools, toolui"]
    L4["4 host and game<br/>engine, game"]
    L3["3 subsystems<br/>render, physics, anim, audio, entity, script, ui"]
    L2["2 data and hardware<br/>resource, asset, bsp, walk, map, scene, rhi, material"]
    L1["1 core services<br/>config, reflect, ecs, vfs, platform"]
    L0["0 core<br/>math, kv, console"]
    L7 --> L6 --> L4 --> L3 --> L2 --> L1 --> L0
    L6 --> L5
    L5 --> L4

A crate may depend on any lower layer. Layer 3 crates may not depend on each other, with one recorded exception (ui → script, listed with its reason in xtask/src/layers.rs as something to revisit). kerosene-map may only be linked from layer 5 up.

The authoritative table is xtask/src/layers.rs; the full per-crate graph and summaries are in the Crate map.

What each layer is for

The four seams

Layering says what may not connect. Four seams say where connection happens.

Details and diagrams: Crate map.

Packaging

None of the workspace crates is published on its own. cargo xtask bundle folds them into the single kerosene crate (xtask/src/bundle.rs): each package becomes a module, internal paths are rewritten, tool crates sit behind the tools feature, and the dependencies merge into one manifest. A game therefore depends on one crate and one version.

Third-party foundations

Versions drift; Cargo.toml at the repository root is authoritative. Why these are wrapped is in the decision log.

See also

• Crate map
• Architecture (user-facing)
• Tools and the build

Runtime

Two layers, one boundary

• Engine (crates/kerosene-engine/src/engine.rs) is the entire simulation. It has no window, no GPU and no input device.
• host (crates/kerosene-engine/src/host.rs) owns the winit event loop, the wgpu surface and egui, and calls Engine::frame once per redraw.

Why: an engine that cannot start without a GPU cannot host a server or run in CI. The boundary is enforced structurally: Engine has no surface field. --headless N runs Engine alone for N ticks.

Start-up

kerosene::launch(game, LaunchOptions) (crates/kerosene-engine/src/launch.rs):

1. installs the logger and crash handler;
2. parses arguments (--content, --vault, --headless, +map, +cvar);
3. finds the content root, project (.kproj) and engine.kcfg;
4. runs headless, or enters host::run_with.

Engine::with_game then asks the game for its classes, calls setup (after the console exists, before config.cfg/autoexec.cfg/command line run, so a game’s convars can be set from any of them), and executes the startup commands.

If no map is named, the engine loads the built-in fallback map kerosene_room (FALLBACK_MAP in crates/kerosene-engine/src/base.rs), compiled into the binary with a small base content set.

Fixed tick, variable frame

---
config:
  layout: elk
---
flowchart LR
    real["real_dt (cap 0.25 s)"] --> acc["accumulator += real_dt<br/>cap 8 × interval"]
    acc --> loop{"accumulator ≥ interval?"}
    loop -- yes --> tick["Engine::tick"] --> loop
    loop -- no --> draw["draw with alpha =<br/>accumulator / interval"]

Simulation runs at sv_tickrate (default 64 Hz). Rendering runs as fast as it can and interpolates between the last two states. The accumulator cap stops a breakpoint or window drag causing a burst of catch-up ticks. The host takes the latest input for view angles and blends only positions, so the camera responds at frame rate.

One tick

Order matters; it is documented step by step in Runtime and the tick. In outline:

1. game.pre_tick: change movement parameters before they are read
2. player movement (kerosene_physics::player_move), footsteps, listener
3. triggers, then entities.run (events, thinks, removals)
4. engine and game answer entity requests
5. game.tick: game rules, after I/O and before props step
6. rigid-body step, streaming update, map script on_tick

The Game trait