Flint Engine

A CLI-first, AI-agent-optimized 3D game engine written in Rust.

Flint is a general-purpose 3D game engine designed from the ground up to provide an excellent interface for AI coding agents, while maintaining effective workflows for human developers. Unlike existing engines that optimize for GUI-driven workflows, Flint prioritizes programmatic interaction, introspection, and validation.

The Core Idea

Current game engines are built around visual editors, drag-and-drop workflows, and GUI-heavy tooling. These become friction points when AI agents attempt to make changes programmatically — the agent ends up fighting against abstractions designed for human spatial reasoning and visual feedback loops.

Flint inverts this: the primary interface is CLI and code, with visual tools focused on validating results rather than creating them.

Every scene is a TOML file you can read, diff, and version. Every operation is a composable CLI command. Every piece of engine state is queryable as structured data. The viewer exists to answer one question: “Did the agent do what I asked?”

Built with Flint

FlintKart: a kart racing game built as a standalone project using Flint’s game project architecture — custom schemas, scripts, and assets layered on top of the engine via git subtree.

Visual Showcase

The Luminarium showcase scene: Cook-Torrance PBR shading with cascaded shadows, textured walls and floors, glTF models, and emissive materials.

Wireframe debug mode reveals mesh topology — one of eight built-in shading modes (chosen from the F4 Rendering & Effects menu, or --debug-mode headlessly) for inspecting geometry, normals, depth, UVs, and material properties.

What It Looks Like

Create a scene, add entities, query them, and view the result — all from the command line:

# Initialize a project
flint init my-game

# Create a scene and populate it
flint scene create levels/tavern.scene.toml --name "The Tavern"
flint entity create --archetype room --name "main_hall" --scene levels/tavern.scene.toml
flint entity create --archetype door --name "front_door" --parent "main_hall" --scene levels/tavern.scene.toml

# Query what you've built
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml

# Validate against constraints
flint validate levels/tavern.scene.toml --fix --dry-run

# See it in 3D with PBR rendering
flint edit levels/tavern.scene.toml --watch

# Walk around in first person
flint play levels/tavern.scene.toml

Current Status

The engine supports:

• Entity CRUD via CLI with archetype-based creation
• Scene serialization in human-readable TOML
• Query language for filtering and inspecting entities
• Schema system for component and archetype definitions
• Constraint validation with auto-fix capabilities
• Asset management with content-addressed storage and glTF import
• PBR renderer with Cook-Torrance shading, cascaded shadow mapping, and glTF mesh rendering
• GPU skeletal animation with glTF skin/joint import, vertex skinning, and crossfade blending
• egui inspector with entity tree, component editing, and constraint overlay
• Hot-reload viewer that watches for file changes
• Headless rendering for CI and automated screenshots
• Physics simulation via Rapier 3D with kinematic character controller
• First-person gameplay with WASD movement, mouse look, jumping, and sprinting
• Game loop with fixed-timestep accumulator for deterministic physics
• Spatial audio via Kira with 3D positioned sounds, ambient loops, and event-driven triggers
• Property animation with TOML-defined keyframe clips (Step, Linear, CubicSpline interpolation)
• Skeletal animation with glTF skin import, GPU bone matrix skinning, and crossfade blending
• Rhai scripting with entity/input/audio/animation APIs, event callbacks, and hot-reload
• Interactable entities with HUD prompts, proximity detection, and scripted behaviors
• AI asset generation with pluggable providers (Flux textures, Meshy 3D models, ElevenLabs audio), style guides, batch scene resolution, model validation, and build manifests
• Billboard sprites with camera-facing quads and sprite sheet animation
• GPU particle system with instanced rendering, per-emitter pooling, alpha/additive blending, and configurable emission shapes
• Extensible input system with config-driven bindings for keyboard, mouse, and gamepad with runtime rebinding
• Data-driven UI system with TOML-defined layouts, style classes, anchor-based positioning, flow layouts, and runtime scripting API
• Game project architecture for standalone games that include the engine as a git subtree

See the Roadmap for the full development history.

Who Is This For?

• AI agent developers building game content programmatically
• Technical game developers who prefer code over visual editors
• Tooling enthusiasts who want to compose game development operations
• Rust game developers looking for a deterministic, introspectable engine

Reading This Guide

• Start with Why Flint? to understand the motivation
• Follow the Getting Started guide to build from source and create your first project
• Explore Core Concepts to learn about the engine’s systems
• Check the Architecture section if you want to understand the codebase
• Browse the API Reference for per-crate Rust documentation

Quick Reference

A scannable cheat sheet for daily Flint development.

CLI Commands

Music commands are detailed in Music Commands.

Keyboard Shortcuts

Player (flint play)

The old per-effect keys (F1 debug mode, F4 shadows, F5 bloom, F6 post) are gone; everything is in the F4 menu. | Escape | Release cursor / Exit |

Scene Viewer (flint edit <scene.toml>)

Spline Editor (flint edit <scene.toml> --spline)

Rendering & Effects Menu (F4, player and viewer)

One panel for everything the old F-keys flipped. Sections: Post chain (enable, exposure, vignette, chromatic aberration, radial blur, desaturate; player-only “freeze script post overrides”), SSAO (radius, intensity, bias, samples), Depth of field (strength, focus distance, range; viewer adds DoF-follow-selection), Fog and height fog, Bloom with film grain and FXAA, Kuwahara, Render mode (none / Matrix / blood / drunk / Tron / underwater, mix, params), Dither / Volumetric, Shadows (enable, resolution — rebuilds the shadow pass), Lighting (ambient sky/ground, diffuse wrap, Oren-Nayar, sheen, reset), Camera (vertical FOV), Shading (debug mode combo). The viewer also has an authored-vs-viewer-default post switch.

File Type Auto-Detection (flint edit)

Common TOML Snippets

Minimal Entity

[entities.my_thing]
archetype = "furniture"

[entities.my_thing.transform]
position = [0, 1, 0]
rotation = [0, 45, 0]
scale = [1, 1, 1]

PBR Material

[entities.my_thing.material]
base_color = [0.8, 0.2, 0.1]
roughness = 0.6
metallic = 0.0
emissive = [1.0, 0.4, 0.1]
emissive_strength = 2.0

Physics Body

[entities.wall.collider]
shape = "box"
size = [10.0, 4.0, 0.5]

[entities.wall.rigidbody]
body_type = "static"

Particle Emitter (Fire)

[entities.fire.particle_emitter]
emission_rate = 40.0
max_particles = 200
lifetime_min = 0.3
lifetime_max = 0.8
speed_min = 1.5
speed_max = 3.0
direction = [0, 1, 0]
gravity = [0, 2.0, 0]
size_start = 0.15
size_end = 0.02
color_start = [1.0, 0.7, 0.1, 0.9]
color_end = [1.0, 0.1, 0.0, 0.0]
blend_mode = "additive"
shape = "sphere"
shape_radius = 0.15
autoplay = true

Post-Processing

[post_process]
bloom_enabled = true
bloom_intensity = 0.04
bloom_threshold = 1.0
vignette_enabled = true
vignette_intensity = 0.3
exposure = 1.0
ssao_samples = 16               # 1-64; 16 is ~4x cheaper than the default 64
desaturate = 0.0                # 0 = full colour, 1 = ash-grey
dof_strength = 0.0              # 0 = sharp
dof_focus_distance = 10.0       # view metres
dof_focus_range = 5.0
kuwahara_enabled = false        # painterly pre-pass
film_grain = 0.0                # 0.02-0.05 is subtle
grade_lift = [0.0, 0.0, 0.0]    # after ACES; neutral 0,0,0
grade_gamma = [1.0, 1.0, 1.0]
grade_gain = [1.0, 1.0, 1.0]
fxaa = false                    # off by default so pixel gates stay single-path

Lighting Levers

[environment]
ambient_sky = [0.35, 0.40, 0.50]
ambient_ground = [0.18, 0.14, 0.10]
diffuse_wrap = 0.3      # 0 = legacy sharp terminator
oren_nayar = 0.7        # 0 = Lambert
sheen_color = [1.0, 0.9, 0.8]
sheen_strength = 0.15   # keep <= ~0.3

Authored Camera

[camera]
position = [0, 4, 12]
target = [0, 1, 0]
fov = 60.0

UI Layout

# ui/hud.ui.toml
[ui]
name = "HUD"
style = "ui/hud.style.toml"

[elements.score_panel]
type = "panel"
anchor = "top-right"
class = "hud-panel"

[elements.score_text]
type = "text"
parent = "score_panel"
class = "score-value"
text = "0"

UI Style

# ui/hud.style.toml
[styles.hud-panel]
width = 160
height = 50
bg_color = [0.0, 0.0, 0.0, 0.6]
rounding = 6
padding = [10, 8, 10, 8]
x = -10
y = 10

[styles.score-value]
font_size = 28
color = [1.0, 1.0, 1.0, 1.0]
text_align = "center"
width_pct = 100

Script Attachment

[entities.npc.script]
source = "npc_behavior.rhai"
enabled = true

[entities.npc.interactable]
prompt_text = "Talk"
range = 3.0
interaction_type = "talk"

Audio Source

[entities.campfire.audio_source]
file = "audio/fire_crackle.ogg"
volume = 0.8
loop = true
spatial = true
min_distance = 1.0
max_distance = 15.0

Prefab Instance

[prefabs.player]
template = "kart"
prefix = "player"

[prefabs.player.overrides.kart.transform]
position = [0, 0, 0]

Top Scripting Functions

Render Command Quick Examples

# Basic screenshot
flint render scene.toml -o shot.png --schemas schemas

# Framed hero shot
flint render scene.toml -o hero.png --distance 20 --pitch 30 --yaw 45 --target 0,1,0 --no-grid

# Debug views
flint render scene.toml -o wireframe.png --debug-mode wireframe
flint render scene.toml -o normals.png --debug-mode normals
flint render scene.toml -o depth.png --debug-mode depth

# Post-processing control
flint render scene.toml -o bloom.png --bloom-intensity 0.08
flint render scene.toml -o raw.png --no-postprocess
flint render scene.toml -o dof.png --dof 0.6 --dof-focus 8 --dof-range 3
flint render scene.toml -o graded.png --grade-lift 0.03,0.02,0.015 --grade-gain 1.04,1,0.94 --film-grain 0.03
flint render scene.toml -o drained.png --desaturate 0.85

# Anti-aliasing and lighting levers (both default off; ADR 0058 / 0048)
flint render scene.toml -o smooth.png --msaa 4 --fxaa
flint render scene.toml -o clay.png --oren-nayar 0.7 --sheen-strength 0.15 --sheen-color 1,0.9,0.8

# Cheaper SSAO for quick iteration
flint render scene.toml -o fast.png --ssao-samples 16

Why Flint?

The Problem

Game engines today — Unity, Unreal, Godot — are designed around visual editors. You drag objects into scenes, connect nodes in graphs, click through property inspectors. These workflows are excellent for humans using a mouse, but they create friction in two growing scenarios:

1. AI agents building game content. When an AI coding agent needs to place a door in a scene, it shouldn’t need to simulate mouse clicks on a GUI. It should issue a command and get structured feedback.

2. Automation and CI pipelines. Validating a scene, running regression tests on visual output, or batch-processing hundreds of entities — these tasks fight against editor-centric architectures.

The core tension: existing engines treat programmatic access as a secondary concern. The API exists, but it’s bolted onto a system designed for spatial interaction. Scene formats are binary or semi-readable. Introspection is limited. Determinism is not guaranteed.

The Thesis

Flint starts from the opposite assumption: the primary interface is CLI and code. Visual tools are for validation, not creation.

This doesn’t mean Flint is hostile to humans. It means every operation flows through a composable, scriptable interface first. If you can do it in the CLI, you can automate it. If you can automate it, an AI agent can do it. The viewer is the place where a human confirms: “Yes, that’s what I wanted.”

What This Enables

For AI agents

An agent working with Flint has a clean contract:

• Issue CLI commands, get structured JSON/TOML responses
• Query any aspect of engine state with a SQL-inspired language
• Validate work against declarative constraint rules
• Produce visual artifacts (headless renders) for verification

No simulated GUI interaction. No screen scraping. No ambiguous visual state.

For humans

A developer working with Flint gets:

• Scene files that are human-readable TOML, easily diffable in git
• A query language for exploring what’s in a scene without opening an editor
• Constraint rules that serve as living documentation of what a “correct” scene looks like
• A hot-reload viewer that updates in real-time as files change

For teams

A team using Flint gets:

• Deterministic builds — same inputs always produce identical outputs
• Text-based formats that merge cleanly in version control
• Structured output for CI pipelines and automated testing
• A shared vocabulary between human developers and AI tools

Comparison

The Name

Flint is a tool for starting fires. Simple, reliable, fundamental. Strike it and something sparks into existence. That’s the idea: minimal friction between intent and result.

Design Principles

Flint’s architecture follows six principles that guide every design decision. They are listed in priority order — when principles conflict, higher-ranked ones win.

1. CLI-First

Every operation is expressible as a composable command. There is no operation that requires a GUI. The CLI is the source of truth for what the engine can do.

This means:

• All commands accept flags for output format (--format json, --format toml)
• Commands compose via pipes and standard shell tooling
• Batch operations are first-class, not afterthoughts
• The viewer is a consumer of state, not a producer of it

2. Introspectable

You can query any aspect of engine state as structured data. Nothing is hidden behind opaque handles or binary blobs.

# What entities exist?
flint query "entities where archetype == 'door'"

# What does a door look like?
flint schema door

# What would this change break?
flint validate levels/tavern.scene.toml --fix --dry-run

The query language is the same whether you’re exploring interactively or writing constraint rules. Learn it once, use it everywhere.

3. Deterministic

Same inputs always produce identical outputs. No hidden state, no ambient randomness, no order-dependent behavior.

• Entity IDs are stable across save/load cycles
• Procedural generation uses explicit seeds
• Build manifests record exact asset hashes
• Headless renders are reproducible for regression testing

4. Text-Based

Scene and asset formats are human-readable, machine-parseable, and diffable. TOML is the primary format throughout.

[entities.front_door]
archetype = "door"
parent = "main_hall"

[entities.front_door.transform]
position = [5, 0, 0]

[entities.front_door.door]
style = "hinged"
locked = false

This isn’t just about readability — it’s about collaboration. Text files merge cleanly in version control. Diffs are meaningful. AI agents can read and write them directly.

5. Constraint-Driven

Declarative rules define what a valid scene looks like. The engine validates against these rules and can optionally auto-fix violations.

Constraints serve multiple roles:

• Validation — catch errors before they become runtime bugs
• Documentation — constraints describe what “correct” means
• Automation — auto-fix rules handle routine corrections
• Communication — constraints are a shared contract between human and AI

6. Hybrid Workflows

Humans and AI agents collaborate effectively on the same project. Neither workflow is an afterthought.

The typical loop:

1. An AI agent creates or modifies scene content via CLI
2. Constraints validate the changes automatically
3. A human reviews the result in the viewer
4. Feedback flows back to the agent as structured data

This principle ensures Flint doesn’t optimize so hard for agents that humans can’t use it, or so hard for humans that agents can’t automate it.

CLI-First Workflow

Flint’s primary interface is the command line. Every engine operation — creating entities, querying scenes, validating constraints, importing assets, generating content — is a composable CLI command. Visual tools exist to validate results, not to create them.

Why CLI-First?

Traditional game engines center on visual editors: drag a mesh into a viewport, tweak a slider, click Save. This works well for a single human at a desk, but it creates friction for:

• Automation — you can’t script a drag-and-drop operation
• Reproducibility — a sequence of mouse clicks isn’t version-controllable
• AI agents — they see text, not pixels
• CI/CD — headless servers have no windows to click in
• Collaboration — binary project files don’t merge cleanly in git

Flint inverts the priority: text-first, visual-second. The CLI is the engine’s native language.

Composable Commands

Every command reads structured input and produces structured output. This means standard shell patterns work naturally:

# Create a scene with several entities
flint scene create levels/dungeon.scene.toml --name "Dungeon Level 1"
flint entity create --archetype room --name "entrance" --scene levels/dungeon.scene.toml
flint entity create --archetype door --name "iron_gate" --parent "entrance" --scene levels/dungeon.scene.toml

# Query and filter with standard tools
flint query "entities where archetype == 'door'" --scene levels/dungeon.scene.toml --format json

# Validate and capture results
flint validate levels/dungeon.scene.toml --format json

# Render a preview image for review
flint render levels/dungeon.scene.toml --output preview.png --width 1920 --height 1080

Structured Output

Commands support --format json and --format toml output modes, making their results machine-readable. This enables pipelines like:

# Count entities of each archetype
flint query "entities" --scene levels/tavern.scene.toml --format json | jq 'group_by(.archetype) | map({archetype: .[0].archetype, count: length})'

# Check if validation passes (exit code 0 = clean, 1 = violations)
flint validate levels/tavern.scene.toml --format json && echo "Scene is valid"

JSON output follows consistent schemas, so tools can parse results reliably across engine versions.

Batch Operations

Because every operation is a command, building complex scenes is just a script:

#!/bin/bash
SCENE="levels/tavern.scene.toml"

flint scene create "$SCENE" --name "The Rusty Flagon"

# Build the structure
for room in main_hall kitchen storage; do
    flint entity create --archetype room --name "$room" --scene "$SCENE"
done

# Add doors between rooms
flint entity create --archetype door --name "kitchen_door" --parent "main_hall" --scene "$SCENE"
flint entity create --archetype door --name "storage_door" --parent "kitchen" --scene "$SCENE"

# Validate the whole thing
flint validate "$SCENE" --fix

This script is version-controllable, reproducible, and can run in CI.

The Viewer as Validator

The flint edit --watch viewer and flint play command are verification tools, not authoring tools. They answer the question: “Does the scene I built look correct?”

# Edit the TOML in your text editor, viewer updates automatically
flint edit levels/tavern.scene.toml --watch

# Walk through the scene to verify physics, audio, and interactions
flint play levels/tavern.scene.toml

The viewer hot-reloads when the scene file changes. Edit TOML, save, see the result — no GUI interaction required.

Headless Rendering for CI

Scenes can be rendered to PNG without a window, enabling automated visual validation:

flint render levels/tavern.scene.toml --output screenshots/tavern.png --width 1920 --height 1080

This is the foundation for visual regression testing in CI pipelines — render a baseline, then compare future renders against it.

Contrast with GUI Engines

This doesn’t mean Flint is text-only. It means the text interface is complete — anything you can do in the viewer, you can do (and automate) from the command line.

Further Reading

• AI Agent Interface — how this philosophy benefits AI coding agents
• Design Principles — the broader design philosophy
• CLI Reference — full command documentation

AI Agent Interface

Flint is designed from the ground up to be an excellent interface for AI coding agents. Where traditional engines optimize for human spatial reasoning and visual feedback, Flint optimizes for text-based reasoning, structured data, and automated validation.

The Problem with GUI Engines

AI agents working with traditional game engines face fundamental friction:

• Screenshot parsing — agents must interpret rendered pixels to understand scene state, an unreliable and lossy process
• GUI automation — clicking buttons and dragging sliders through accessibility APIs or screenshot analysis is brittle
• Binary formats — proprietary project files can’t be read, diffed, or generated as text
• Implicit state — engine state lives in inspector panels, viewport selections, and undo histories that agents can’t access

Flint eliminates all of these friction points.

Structured Input and Output

Every Flint command accepts text input and produces structured text output:

# JSON output for machine parsing
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format json

# Exit codes signal success (0) or failure (1)
flint validate levels/tavern.scene.toml --format json
echo $?  # 0 = valid, 1 = violations found

An agent can create entities, modify scenes, and inspect state entirely through text — no screenshots, no pixel coordinates, no GUI automation.

Query-Based Introspection

The query language gives agents programmatic access to scene state. Instead of reading a screenshot to count doors, an agent can:

# How many doors are in this scene?
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format json | jq length

# Is this door locked?
flint query "entities where door.locked == true" --scene levels/tavern.scene.toml --format json

# What components does the player entity have?
flint query "entities where archetype == 'player'" --scene levels/tavern.scene.toml --format json

Queries return structured data that agents can parse, reason about, and use to plan their next action.

Constraint Validation as Feedback

Constraints provide an automated feedback loop. An agent doesn’t need a human to check its work — it can validate programmatically:

# Agent creates some entities...
flint entity create --archetype door --name "secret_door" --scene levels/tavern.scene.toml

# Then checks if the scene is still valid
flint validate levels/tavern.scene.toml --format json

If validation fails, the JSON output tells the agent exactly what’s wrong and how to fix it. The --fix --dry-run mode even previews what auto-fixes would apply. This creates a tight create-validate-fix loop that agents can execute without human intervention.

Schema Introspection

Agents can discover what components and archetypes are available without reading documentation:

# What fields does the 'door' component have?
flint schema door

# What components does the 'player' archetype include?
flint schema player

This means an agent can learn the engine’s data model at runtime, then use that knowledge to create valid entities.

Headless Rendering

Visual verification without a window:

# Render the scene to an image file
flint render levels/tavern.scene.toml --output preview.png --width 1920 --height 1080

An agent (or its supervisor) can render a preview image to check that the scene looks correct, without opening a GUI. This enables visual regression testing in CI and supports workflows where an agent builds a scene, renders a preview, and a human reviews the image.

TOML as Scene Format

Scenes are plain TOML text files. An agent can:

• Read a scene file directly as text
• Write entity data by editing TOML
• Diff changes with standard tools (git diff)
• Generate entire scenes programmatically
• Merge changes from multiple agents without conflicts (each entity is a distinct TOML section)

No proprietary binary formats, no deserialization libraries, no SDK required.

AI Asset Generation

Phase 5 extends the agent interface to asset creation. Agents can generate textures, 3D models, and audio through CLI commands:

# Generate a texture using AI
flint asset generate texture -d "rough stone wall with mortar lines" --style medieval_tavern

# Batch-generate all missing assets for a scene
flint asset resolve my_scene.scene.toml --strategy ai_generate --style medieval_tavern

Style guides ensure generated assets maintain visual consistency, and model validation checks results against constraints — the same automated feedback loop that works for scene structure now works for asset quality.

Further Reading

• CLI-First Workflow — the composable command interface
• AI Agent Workflow — step-by-step guide for agent developers
• AI Asset Generation — the AI asset generation pipeline

Installation

Flint is built from source using the Rust toolchain. There are no pre-built binaries yet.

Prerequisites

• Rust (stable, 1.75+) — install from rustup.rs
• Git — for cloning the repository
• A GPU with Vulkan, Metal, or DX12 support (for the renderer and viewer)

Build from Source

Clone the repository and build in release mode:

git clone https://github.com/chrischaps/flint.git
cd flint
cargo build --release

The binary is at target/release/flint (or target/release/flint.exe on Windows).

Verify Installation

cargo run --bin flint -- --version

You should see the Flint version string.

Running Without Installing

You can run Flint directly through Cargo without installing it system-wide:

cargo run --bin flint -- <command>

For example:

cargo run --bin flint -- init my-game
cargo run --bin flint -- serve demo/showcase.scene.toml --watch

Running Tests

To verify everything is working:

cargo test

This runs the full test suite across all crates.

Optional: Add to PATH

To use flint directly without cargo run:

cargo install --path crates/flint-cli

Or copy the release binary to a directory on your PATH.

What’s Next

With Flint built, follow Your First Project to create a scene from scratch.

Your First Project

This guide walks through creating a Flint project and building a simple scene using only CLI commands.

Initialize a Project

flint init my-tavern

This creates a project directory with the standard structure:

my-tavern/
├── schemas/
│   ├── components/
│   │   ├── transform.toml
│   │   ├── bounds.toml
│   │   └── door.toml
│   ├── archetypes/
│   │   ├── room.toml
│   │   ├── door.toml
│   │   ├── furniture.toml
│   │   └── character.toml
│   └── constraints/
│       └── basics.toml
├── levels/
└── assets/

The schemas/ directory contains default component definitions, archetype bundles, and constraint rules. You’ll modify and extend these as your project grows.

Create a Scene

flint scene create my-tavern/levels/tavern.scene.toml --name "The Rusty Flint Tavern"

This creates an empty scene file:

[scene]
name = "The Rusty Flint Tavern"
version = "1.0"

Add Rooms

Build out the space with room entities:

flint entity create --archetype room --name "main_hall" \
    --scene my-tavern/levels/tavern.scene.toml \
    --schemas my-tavern/schemas \
    --props '{"transform":{"position":[0,0,0]},"bounds":{"min":[-7,0,-5],"max":[7,4,5]}}'

The --archetype room flag tells Flint to create an entity with the components defined in schemas/archetypes/room.toml (transform + bounds). The --props flag provides the specific values.

Add a kitchen connected to the main hall:

flint entity create --archetype room --name "kitchen" \
    --parent "main_hall" \
    --scene my-tavern/levels/tavern.scene.toml \
    --schemas my-tavern/schemas \
    --props '{"transform":{"position":[0,0,-9]},"bounds":{"min":[-4,0,-3],"max":[4,3.5,3]}}'

The --parent flag establishes a hierarchy — the kitchen is a child of the main hall.

Add a Door

flint entity create --archetype door --name "front_entrance" \
    --parent "main_hall" \
    --scene my-tavern/levels/tavern.scene.toml \
    --schemas my-tavern/schemas \
    --props '{"transform":{"position":[0,0,5]},"door":{"style":"hinged","locked":false}}'

Query Your Scene

See what you’ve built:

flint query "entities" --scene my-tavern/levels/tavern.scene.toml

Filter for specific archetypes:

flint query "entities where archetype == 'door'" --scene my-tavern/levels/tavern.scene.toml

Inspect the Scene File

The scene is plain TOML. Open my-tavern/levels/tavern.scene.toml and you’ll see:

[scene]
name = "The Rusty Flint Tavern"
version = "1.0"

[entities.main_hall]
archetype = "room"

[entities.main_hall.transform]
position = [0, 0, 0]

[entities.main_hall.bounds]
min = [-7, 0, -5]
max = [7, 4, 5]

[entities.kitchen]
archetype = "room"
parent = "main_hall"

[entities.kitchen.transform]
position = [0, 0, -9]

[entities.kitchen.bounds]
min = [-4, 0, -3]
max = [4, 3.5, 3]

[entities.front_entrance]
archetype = "door"
parent = "main_hall"

[entities.front_entrance.transform]
position = [0, 0, 5]

[entities.front_entrance.door]
style = "hinged"
locked = false

Everything is readable, editable, and diffable. You can modify this file directly — the CLI isn’t the only way to edit scenes.

View It

Launch the hot-reload viewer:

flint edit my-tavern/levels/tavern.scene.toml --watch --schemas my-tavern/schemas

A window opens showing your scene as colored boxes:

• Blue wireframes for rooms
• Orange boxes for doors
• Green boxes for furniture
• Yellow boxes for characters

The viewer hot-reloads — any change to the scene file (from the CLI, a text editor, or an AI agent) updates the view instantly.

Camera controls:

What’s Next

• Your First Scene dives deeper into scene file structure
• Querying Entities covers the query language
• Building a Tavern walks through a complete scene build

Your First Scene

A Flint scene is a TOML file describing entities, their components, and their relationships. This page explains the scene format by building one from scratch.

Scene Structure

Every scene file has two sections: metadata and entities.

# Metadata
[scene]
name = "My Scene"
version = "1.0"
description = "An optional description"

# Entities
[entities.my_entity]
archetype = "room"

[entities.my_entity.transform]
position = [0, 0, 0]

The [scene] table holds metadata. Everything under [entities.*] defines the objects in your world.

Entities

An entity is a named thing in the scene. Its name is the key under [entities]:

[entities.main_hall]
archetype = "room"

Entities can optionally have:

• An archetype — a schema-defined bundle of components
• A parent — another entity this one is attached to
• Components — data tables nested under the entity

Components

Components are data attached to entities. They’re defined as nested TOML tables:

[entities.main_hall]
archetype = "room"

[entities.main_hall.transform]
position = [0, 0, 0]

[entities.main_hall.bounds]
min = [-7, 0, -5]
max = [7, 4, 5]

The transform and bounds components are defined by schema files in schemas/components/. The schema tells Flint what fields are valid and what types they are.

Parent-Child Relationships

Entities form hierarchies through the parent field:

[entities.main_hall]
archetype = "room"

[entities.main_hall.transform]
position = [0, 0, 0]

[entities.kitchen]
archetype = "room"
parent = "main_hall"

[entities.kitchen.transform]
position = [0, 0, -9]

The kitchen is a child of the main hall. In the viewer, child transforms are relative to their parent.

A Complete Example

Here’s a small but complete scene — a room with a door and a table:

[scene]
name = "Simple Room"
version = "1.0"

[entities.room]
archetype = "room"

[entities.room.transform]
position = [0, 0, 0]

[entities.room.bounds]
min = [-5, 0, -5]
max = [5, 3, 5]

[entities.door]
archetype = "door"
parent = "room"

[entities.door.transform]
position = [0, 0, 5]

[entities.door.door]
style = "hinged"
locked = false
open_angle = 90.0

[entities.table]
archetype = "furniture"
parent = "room"

[entities.table.transform]
position = [0, 0, 0]

[entities.table.bounds]
min = [-0.6, 0, -0.6]
max = [0.6, 0.8, 0.6]

Editing Scenes

You can edit scene files in three ways:

1. CLI commands — flint entity create, flint entity delete, etc.
2. Text editor — open the TOML file directly
3. Programmatically — any tool that can write TOML

All three approaches produce the same result. The flint edit --watch viewer detects changes from any source and reloads automatically.

Validating Scenes

Run the constraint checker to verify your scene is well-formed:

flint validate levels/my-scene.scene.toml --schemas schemas

This checks your scene against the rules defined in schemas/constraints/. See Constraints for details.

What’s Next

• Entities and ECS explains the entity-component system
• Schemas covers how components and archetypes are defined
• Scenes goes deeper into the scene system internals

Querying Entities

Flint includes a SQL-inspired query language for filtering and inspecting entities. Queries let you search scenes by archetype, component values, or nested field data.

Basic Syntax

All queries follow the pattern:

entities where <condition>

The simplest query returns all entities:

flint query "entities" --scene levels/tavern.scene.toml

Filtering by Archetype

The most common filter — find entities of a specific type:

# Find all doors
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml

# Find all rooms
flint query "entities where archetype == 'room'" --scene levels/tavern.scene.toml

Comparison Operators

Querying Component Fields

Access component fields with dot notation:

# Find locked doors
flint query "entities where door.locked == true" --scene levels/tavern.scene.toml

# Find entities above a certain height
flint query "entities where transform.position.y > 2.0" --scene levels/tavern.scene.toml

# Find loud audio sources
flint query "entities where audio_source.volume > 0.8" --scene levels/tavern.scene.toml

Output Formats

Query results can be formatted for different consumers:

# Human-readable (default)
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml

# JSON for scripting and AI agents
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format json

# TOML for configuration workflows
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format toml

Combining with Shell Tools

JSON output composes with standard tools:

# Count doors
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format json | jq length

# Get just the names
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml --format json | jq '.[].name'

# Find entities with a specific parent
flint query "entities" --scene levels/tavern.scene.toml --format json | jq '.[] | select(.parent == "main_hall")'

Further Reading

• Queries — full grammar reference and advanced usage
• Constraints — queries used in validation rules
• CLI Reference — all command options

The Scene Viewer

The Flint viewer is a real-time 3D window for validating scenes. It renders your scene with full PBR shading and shadows, applies the scene’s own post-processing, and provides an egui inspector panel for browsing entities and editing component properties.

Launching the Viewer

flint edit levels/tavern.scene.toml --watch --schemas schemas

The --watch flag enables hot-reload: edit the scene TOML file, and the viewer re-parses and re-renders automatically. The entire file is re-parsed on each change (not incremental), which keeps the implementation simple and avoids synchronization issues.

flint serve still works as a hidden alias for the same viewer.

Camera Controls

The viewer uses an orbit camera that rotates around a focus point. If the scene has a [camera] block, the orbit starts from that authored framing.

Any manual orbit input cancels auto-orbit. Start in turntable mode with --auto-orbit.

Transform Gizmo

When you select an entity in the inspector, a gizmo appears at its position with colored axis arrows and plane handles:

• Red arrow — drag to move along X axis
• Green arrow — drag to move along Y axis
• Blue arrow — drag to move along Z axis
• Plane handles (small squares at axis intersections) — drag to move in two axes simultaneously

While an entity is selected, W, E and R switch the gizmo to translate, rotate and scale instead of orbiting the camera.

The gizmo uses constraint-plane dragging: for single-axis movement, it automatically picks the plane most perpendicular to your camera view. Inactive axes dim while dragging to clearly show the active constraint.

Editing Shortcuts

All position changes are tracked in an undo/redo stack. Saving writes the modified positions back to the scene TOML file.

The Inspector Panel

The egui-based inspector panel (on the left side of the viewer) provides:

• Entity tree — hierarchical list of all entities in the scene, reflecting parent-child relationships
• Component editor — select an entity to view and edit its component values; position fields are editable via drag-value widgets with color-coded labels (red/green/blue matching the gizmo axes)
• Constraint overlay — validation results from flint-constraint, highlighting any rule violations

Rendering Features

The viewer renders scenes with the same PBR pipeline used by the player:

• Cook-Torrance physically-based shading
• Cascaded shadow mapping from directional lights
• glTF mesh rendering with material support
• The scene’s [post_process] block, applied on load
• Render stats overlay (F2)
• Normal arrows (F3)
• The Rendering & Effects menu (F4)
• Fullscreen toggle (F11)

The Rendering & Effects Menu (F4)

F4 opens one window holding every render and post-process control: post-processing on/off, exposure, vignette, SSAO, depth of field, fog, bloom, color grade and film grain, FXAA, Kuwahara, render modes, dither and volumetric light, shadows and their resolution, the lighting levers, vertical FOV, and the shading debug mode (PBR, wireframe overlay, wireframe, normals, depth, UV, unlit, metal/rough). Changes apply immediately.

Two controls are specific to the viewer:

• Authored post vs viewer default — swap between the scene’s [post_process] block and the viewer’s neutral look, to check what a scene’s grading is actually doing
• DoF follow — the depth-of-field focus plane tracks the last selected entity, so you can pick a focus distance by clicking

See Post-Processing for the full section list.

Playing a Scene

To experience a scene in first-person with physics, use play instead of edit:

flint play levels/tavern.scene.toml

See the CLI Reference for full play command details and controls.

Headless Rendering

For CI pipelines and automated screenshots, render to PNG without opening a window:

flint render levels/tavern.scene.toml --output preview.png --width 1920 --height 1080

Entities and ECS

Flint uses an Entity-Component-System (ECS) architecture, built on top of the hecs crate. This page explains how entities, components, and IDs work in Flint.

What Is ECS?

In an ECS architecture:

• Entities are unique identifiers (not objects with methods)
• Components are pure data attached to entities
• Systems are logic that operates on entities with specific component combinations

Flint’s twist: components are dynamic. Instead of being Rust structs compiled into the engine, they’re defined at runtime as TOML schema files and stored as toml::Value. This means you can define new component types without recompiling the engine.

Entity IDs

Every entity gets a stable EntityId — a 64-bit integer that:

• Is unique within a scene
• Never gets recycled (monotonically increasing)
• Persists across save/load cycles
• Is deterministic (the same scene always produces the same IDs)

Internally, Flint maintains a bidirectional map (BiMap) between EntityId values and hecs Entity handles. This allows efficient lookup in both directions.

#![allow(unused)]
fn main() {
// From flint-core
pub struct EntityId(pub u64);
}

When loading a saved scene, the ID counter is adjusted to be higher than any existing ID, preventing collisions when new entities are created.

Named Entities

While entity IDs are the internal identifier, entities in Flint are also named. The name is the key in the scene file:

[entities.front_door]     # "front_door" is the name
archetype = "door"

Names must be unique within a scene. They’re used in:

• CLI commands: --name "front_door"
• Parent references: parent = "main_hall"
• Query results
• Constraint violation messages

Components as Dynamic Data

In most ECS implementations, components are Rust structs:

#![allow(unused)]
fn main() {
// NOT how Flint works
struct Transform { position: Vec3, rotation: Vec3 }
}

In Flint, components are toml::Value maps, defined by schema files:

# schemas/components/transform.toml
[component.transform]
description = "Position and rotation in 3D space"

[component.transform.fields]
position = { type = "vec3", default = [0, 0, 0] }
rotation = { type = "vec3", default = [0, 0, 0] }
scale = { type = "vec3", default = [1, 1, 1] }

This design trades some type safety and performance for flexibility — archetypes and components can be defined, modified, and extended without touching Rust code.

Parent-Child Relationships

Entities can form hierarchies. A child entity references its parent by name:

[entities.kitchen]
archetype = "room"
parent = "main_hall"

The ECS layer tracks these relationships, enabling:

• Hierarchical transforms (child positions are relative to parent)
• Tree queries (“find all children of main_hall”)
• Cascading operations (deleting a parent removes children)

Archetypes

An archetype is a named bundle of components that defines an entity “type”:

# schemas/archetypes/door.toml
[archetype.door]
description = "A door entity"
components = ["transform", "door"]

[archetype.door.defaults.door]
style = "hinged"
locked = false

When you create an entity with --archetype door, Flint ensures it has the required components and fills in defaults for any missing values. The scene loader does the same at load time: archetype defaults go in first, then the authored fields, then any component-schema default for a field the author left out (see Scenes).

Archetypes are not rigid types — an entity can have components beyond what its archetype specifies. The archetype defines the minimum set.

Working with Entities via CLI

# Create an entity
flint entity create --archetype door --name "vault_door" \
    --scene levels/dungeon.scene.toml \
    --schemas schemas \
    --props '{"transform":{"position":[0,0,0]},"door":{"locked":true}}'

# Delete an entity
flint entity delete --name "vault_door" --scene levels/dungeon.scene.toml

# List entities in a scene
flint query "entities" --scene levels/dungeon.scene.toml

# Filter by archetype
flint query "entities where archetype == 'door'" --scene levels/dungeon.scene.toml

Further Reading

• Schemas — how components and archetypes are defined
• Scenes — how entities are serialized to TOML
• Queries — how to filter and inspect entities

Schemas

Schemas define the structure of your game world. They specify what components exist, what fields they contain, and how they bundle together into archetypes. Schemas are TOML files stored in the schemas/ directory of your project.

Component Schemas

A component schema defines a reusable data type. Components live in schemas/components/:

# schemas/components/door.toml
[component.door]
description = "A door that can connect spaces"

[component.door.fields]
style = { type = "enum", values = ["hinged", "sliding", "rotating"], default = "hinged" }
locked = { type = "bool", default = false }
open_angle = { type = "f32", default = 90.0, min = 0.0, max = 180.0 }

Field Types

vec2 and vec4 have no dedicated variant; the parser maps them to a float array so validation reports a bad value as “expected float array” rather than misreporting the field as a string. Any type name the parser does not recognise falls back to string.

Field Constraints

Fields can include validation constraints:

open_angle = { type = "f32", default = 90.0, min = 0.0, max = 180.0 }
required_key = { type = "entity_ref", optional = true }

• default — value used when not explicitly set. Defaults are consumed in two places: flint entity create writes them into the new entity, and the scene loader fills them into any component the entity lists but leaves partially specified (see Scenes: loading). Scripts can therefore rely on a schema default existing at runtime.
• min / max — numeric range bounds
• optional — whether the field can be omitted (defaults to false)
• values — valid options for enum types

Validation runs in two modes. At scene load it is advisory: a field that fails its constraints is logged as a warning and the scene still loads. Under flint validate it is authoritative and the command reports every failure.

Built-in Components

Flint ships with several built-in component schemas:

Transform

# schemas/components/transform.toml
[component.transform]
description = "Position and rotation in 3D space"

[component.transform.fields]
position = { type = "vec3", default = [0, 0, 0] }
rotation = { type = "vec3", default = [0, 0, 0] }
scale = { type = "vec3", default = [1, 1, 1] }

Bounds

# schemas/components/bounds.toml
[component.bounds]
description = "Axis-aligned bounding box"

[component.bounds.fields]
min = { type = "vec3", default = [0, 0, 0] }
max = { type = "vec3", default = [10, 4, 10] }

Door

# schemas/components/door.toml
[component.door]
description = "A door that can connect spaces"

[component.door.fields]
style = { type = "enum", values = ["hinged", "sliding", "rotating"], default = "hinged" }
locked = { type = "bool", default = false }
open_angle = { type = "f32", default = 90.0, min = 0.0, max = 180.0 }

Material

# schemas/components/material.toml
[component.material]
description = "PBR material properties"

[component.material.fields]
texture = { type = "string", default = "", optional = true }
roughness = { type = "f32", default = 0.5, min = 0.0, max = 1.0 }
metallic = { type = "f32", default = 0.0, min = 0.0, max = 1.0 }
color = { type = "vec3", default = [1.0, 1.0, 1.0] }
emissive = { type = "vec3", default = [0.0, 0.0, 0.0] }

Rigidbody

# schemas/components/rigidbody.toml
[component.rigidbody]
description = "Physics rigid body"

[component.rigidbody.fields]
body_type = { type = "enum", values = ["static", "dynamic", "kinematic"], default = "static" }
mass = { type = "f32", default = 1.0, min = 0.0 }
gravity_scale = { type = "f32", default = 1.0 }

Collider

# schemas/components/collider.toml
[component.collider]
description = "Physics collision shape"

[component.collider.fields]
shape = { type = "enum", values = ["box", "sphere", "capsule"], default = "box" }
size = { type = "vec3", default = [1.0, 1.0, 1.0] }
friction = { type = "f32", default = 0.5, min = 0.0, max = 1.0 }

Character Controller

# schemas/components/character_controller.toml
[component.character_controller]
description = "First-person character controller"

[component.character_controller.fields]
move_speed = { type = "f32", default = 5.0, min = 0.0 }
jump_force = { type = "f32", default = 7.0, min = 0.0 }
height = { type = "f32", default = 1.8, min = 0.1 }
radius = { type = "f32", default = 0.4, min = 0.1 }
camera_mode = { type = "enum", values = ["first_person", "orbit"], default = "first_person" }

Sprite

# schemas/components/sprite.toml
[component.sprite]
description = "Billboard sprite rendered as a camera-facing quad"

[component.sprite.fields]
texture = { type = "string", default = "", description = "Sprite sheet texture name" }
width = { type = "f32", default = 1.0, min = 0.01, description = "World-space width" }
height = { type = "f32", default = 1.0, min = 0.01, description = "World-space height" }
frame = { type = "i32", default = 0, min = 0, description = "Current frame index" }
frames_x = { type = "i32", default = 1, min = 1, description = "Columns in sprite sheet" }
frames_y = { type = "i32", default = 1, min = 1, description = "Rows in sprite sheet" }
anchor_y = { type = "f32", default = 0.0, description = "Vertical anchor (0=bottom, 0.5=center)" }
fullbright = { type = "bool", default = true, description = "Bypass PBR lighting" }
visible = { type = "bool", default = true }

The sprite component is used for billboard sprites that always face the camera. See Rendering: Billboard Sprites for details on the rendering pipeline.

Archetype Schemas

Archetypes bundle components together with defaults. They live in schemas/archetypes/:

# schemas/archetypes/room.toml
[archetype.room]
description = "A room or enclosed space"
components = ["transform", "bounds"]

[archetype.room.defaults.bounds]
min = [0, 0, 0]
max = [10, 4, 10]

The components array lists which component schemas an entity of this archetype requires. The defaults section provides values used when a component field isn’t explicitly set.

Built-in Archetypes

Introspecting Schemas

Use the CLI to inspect schema definitions:

# Show a component schema
flint schema door --schemas schemas

# Show an archetype schema
flint schema room --schemas schemas

This outputs the component fields, types, defaults, and constraints — useful for both humans exploring the schema and AI agents discovering what fields are available.

Creating Custom Schemas

To add a new component:

1. Create a file in schemas/components/:

# schemas/components/health.toml
[component.health]
description = "Hit points and damage tracking"

[component.health.fields]
max_hp = { type = "i32", default = 100, min = 1 }
current_hp = { type = "i32", default = 100, min = 0 }
armor = { type = "f32", default = 0.0, min = 0.0, max = 1.0 }

2. Reference it in an archetype:

# schemas/archetypes/enemy.toml
[archetype.enemy]
description = "A hostile NPC"
components = ["transform", "health"]

[archetype.enemy.defaults.health]
max_hp = 50
current_hp = 50

3. Use it in a scene:

[entities.goblin]
archetype = "enemy"

[entities.goblin.transform]
position = [10, 0, 5]

[entities.goblin.health]
max_hp = 30
current_hp = 30
armor = 0.1

No engine recompilation needed — schemas are loaded at runtime from the TOML files.

Game Project Schemas

Games can define their own schemas that extend or override the engine’s built-in schemas. The --schemas flag accepts multiple paths, with later paths taking priority:

# From a game project root (engine at engine/)
cargo run --manifest-path engine/Cargo.toml --bin flint-player -- \
  scenes/arena.scene.toml \
  --schemas engine/schemas \
  --schemas schemas

In this example, engine/schemas/ provides the engine’s built-in components (transform, material, rigidbody, etc.) and the game’s own schemas/ adds game-specific components (health, weapon, enemy AI). If both directories define a component with the same name, the game’s definition wins.

Game Project Directory Structure

Game projects live in their own repositories with the engine included as a git subtree:

my_game/                    (standalone git repo)
├── engine/                 (git subtree ← Flint repo)
│   ├── crates/
│   ├── schemas/            (engine schemas)
│   └── Cargo.toml
├── schemas/
│   ├── components/
│   │   ├── health.toml
│   │   ├── weapon.toml
│   │   └── enemy_ai.toml
│   └── archetypes/
│       ├── enemy.toml
│       └── pickup.toml
├── scripts/
│   ├── enemy_ai.rhai
│   ├── weapon.rhai
│   └── hud.rhai
├── scenes/
│   └── level_1.scene.toml
├── sprites/
│   └── imp.png
└── audio/
    ├── shotgun.ogg
    └── imp_death.ogg

This separation keeps game-specific data out of the engine directory, allowing multiple games to share the same engine schemas while defining their own components and archetypes. See Building a Game Project for the full setup guide.

Further Reading

• Entities and ECS — how schemas connect to the entity system
• Constraints — rules that validate entities against schemas
• Scenes — how schema-defined entities are serialized
• Rendering — billboard sprite rendering pipeline
• CLI Reference — multi-schema CLI usage

Scenes

A scene in Flint is a TOML file that describes a collection of entities and their data. Scenes are the primary unit of content — they’re what you load, save, query, validate, and render.

File Format

Scene files use the .scene.toml extension and have two sections:

# Metadata
[scene]
name = "The Rusty Flint Tavern"
version = "1.0"
description = "A showcase scene demonstrating Flint engine capabilities"

# Entity definitions
[entities.main_hall]
archetype = "room"
# ...

The [scene] Table

The [entities.*] Tables

Each entity is a table under [entities], keyed by its unique name:

[entities.front_door]
archetype = "door"
parent = "main_hall"

[entities.front_door.transform]
position = [0, 0, 5]

[entities.front_door.door]
style = "hinged"
locked = false
open_angle = 90.0

Top-level fields:

• archetype — the archetype schema name (optional but recommended)
• parent — name of the parent entity (optional)

Component tables are nested under the entity. Each component name (e.g., transform, door, bounds) corresponds to a schema in schemas/components/.

Scene Operations

Creating a Scene

flint scene create levels/tavern.scene.toml --name "The Tavern"

Listing Scenes

flint scene list

Getting Scene Info

flint scene info levels/tavern.scene.toml

Loading and Saving

The flint-scene crate handles serialization. Scenes are loaded into the ECS world as entities with dynamic components, and saved back to TOML with stable ordering.

When a scene is loaded:

1. The TOML is parsed into a scene structure
2. Each entity definition creates an ECS entity with a stable EntityId
3. If the entity names an archetype, the archetype’s defaults are written in first for every component the entity did not author itself
4. Each authored component is validated against its component schema. Failures are warnings, not errors: the loader logs [scene] entity '<name>' component '<comp>': <reason> through tracing and keeps going. Without a tracing subscriber you will not see them, so a scene that loads is not necessarily a scene that validates. Run flint validate for an authoritative answer.
5. The authored data is merged field-by-field into whatever the archetype put there (see Schemas)
6. For every component the entity explicitly lists, any field that has a default in its component schema and is still unset is filled in. Defaults are applied only to components the entity wrote a table for, not to archetype-required components it left out entirely, and validation in step 4 ran on the authored data before defaults landed, so a missing required field still warns even though a default will fill it.
7. Parent-child relationships are established
8. The entity ID counter is adjusted to be above any existing ID (preventing collisions on subsequent creates)

Step 6 is why scripts can read get_field(id, "item", "enabled") and get a bool rather than () even when the scene author never wrote the field.

When a scene is saved:

1. All entities are serialized to their TOML representation
2. Component data is written as nested tables
3. Parent references use entity names (not internal IDs)

Reload Behavior

Scene reload is a full re-parse. When flint edit --watch detects a file change:

1. The entire scene file is re-read and re-parsed
2. The old world state is replaced with the new one
3. The renderer picks up the new state on the next frame

This approach is simple and correct — there’s no incremental diffing that could get out of sync. For the scene sizes Flint targets, re-parsing is fast enough.

Scene as Source of Truth

A key design decision: the scene file is the source of truth, not the in-memory state. This means:

• You can edit the file with any text editor
• AI agents can write TOML directly
• Git diffs show exactly what changed
• No hidden state lives only in memory

The CLI commands (entity create, entity delete) modify the scene file, and the in-memory world loads from that file. The viewer watches the file, not the internal state.

Example: The Showcase Scene

The demo scene demo/showcase.scene.toml demonstrates the full format:

[scene]
name = "The Rusty Flint Tavern"
version = "1.0"
description = "A showcase scene demonstrating Flint engine capabilities"

# Rooms - rendered as blue wireframe boxes
[entities.main_hall]
archetype = "room"

[entities.main_hall.transform]
position = [0, 0, 0]

[entities.main_hall.bounds]
min = [-7, 0, -5]
max = [7, 4, 5]

# Doors - rendered as orange boxes
[entities.front_entrance]
archetype = "door"
parent = "main_hall"

[entities.front_entrance.transform]
position = [0, 0, 5]

[entities.front_entrance.door]
style = "hinged"
locked = false
open_angle = 90.0

# Furniture - rendered as green boxes
[entities.bar_counter]
archetype = "furniture"
parent = "main_hall"

[entities.bar_counter.transform]
position = [-4, 0, 0]

[entities.bar_counter.bounds]
min = [-1.5, 0, -3]
max = [0, 1.2, 3]

# Characters - rendered as yellow boxes
[entities.bartender]
archetype = "character"
parent = "main_hall"

[entities.bartender.transform]
position = [-5, 0, 0]

This scene defines 4 rooms, 4 doors, 9 pieces of furniture, and 6 characters — all in readable, diffable TOML.

Prefabs

Prefabs are reusable entity group templates that reduce scene file duplication. A prefab defines a set of entities in a .prefab.toml file, and scenes instantiate them with variable substitution and optional overrides.

Defining a Prefab

Prefab files live in the prefabs/ directory and follow the same entity format as scenes, with a [prefab] metadata header:

[prefab]
name = "kart"
description = "Racing kart with body, wheels, and driver"

[entities.kart]

[entities.kart.transform]
position = [0, 0, 0]

[entities.kart.model]
asset = "kart_body"

[entities.wheel_fl]
parent = "${PREFIX}_kart"

[entities.wheel_fl.transform]
position = [-0.4, 0.15, 0.55]

[entities.wheel_fl.model]
asset = "kart_wheel"

All string values containing ${PREFIX} are substituted with the instance prefix at load time. Entity names are automatically prefixed (e.g., kart becomes player_kart when the prefix is "player").

Using Prefabs in a Scene

Scenes reference prefabs in a [prefabs] section:

[prefabs.player]
template = "kart"
prefix = "player"

[prefabs.player.overrides.kart.transform]
position = [0, 0, 0]

[prefabs.ai1]
template = "kart"
prefix = "ai1"

[prefabs.ai1.overrides.kart.transform]
position = [3, 0, -5]

Each prefab instance specifies:

• template — the prefab name (matches the .prefab.toml filename without extension)
• prefix — substituted for ${PREFIX} in all string values and prepended to entity names
• overrides — per-entity component field overrides (deep-merged with the template)

Override Deep Merge

Overrides are merged at the field level, not the component level. If a prefab template defines a component with five fields and an override specifies one field, only that one field is replaced — the other four are preserved from the template.

Path Resolution

The loader searches for prefab templates in:

1. <scene_directory>/prefabs/
2. <scene_directory>/../prefabs/

This means a prefabs/ directory at the project root is found when loading scenes from scenes/.

Previewing Prefabs

Use the CLI to visually inspect a prefab template:

flint prefab view prefabs/kart.prefab.toml --schemas schemas

Splines

Splines define smooth paths through 3D space using Catmull-Rom interpolation. They’re used for track layouts, camera paths, and procedural geometry generation.

Spline Component

Attach a spline to an entity with the spline component:

[entities.track_path]

[entities.track_path.spline]
source = "oval_plus.spline.toml"

The engine loads the .spline.toml file, samples it into a dense point array stored as the spline_data ECS component, and makes it available for script queries via the Spline API.

Spline Meshes

The spline_mesh component generates geometry by sweeping a rectangular cross-section along a spline:

[entities.road_surface]

[entities.road_surface.spline_mesh]
spline = "track_path"
width = 12.0
height = 0.3
offset_y = -0.15

[entities.road_surface.material]
base_color = [0.3, 0.3, 0.3]
roughness = 0.8

One spline can feed multiple mesh entities (road surface, walls, guardrails) with different cross-section dimensions and materials.

Further Reading

• Your First Scene — hands-on guide to building a scene
• Entities and ECS — how scene entities map to the ECS
• Schemas — how component structure is defined
• Constraints — how to validate scenes
• File Formats — prefab and spline file format details

Queries

Flint’s query system provides a SQL-inspired language for filtering and inspecting entities. Queries are parsed by a PEG grammar (pest) and executed against the ECS world.

Grammar

The query language is defined in crates/flint-query/src/grammar.pest:

query     = { resource ~ (where_clause)? }
resource  = { "entities" | "components" }
where_clause = { "where" ~ condition }
condition = { field ~ operator ~ value }
field     = { identifier ~ ("." ~ identifier)* }
operator  = { "==" | "!=" | "contains" | ">=" | "<=" | ">" | "<" }
value     = { string | number | boolean }

Whitespace is ignored between tokens. The where keyword is case-insensitive.

Resources

Two resource types can be queried:

Operators

Field Paths

Fields use dot notation to access nested values:

Examples:

# Top-level entity properties
flint query "entities where archetype == 'door'"
flint query "entities where name contains 'wall'"

# Component fields
flint query "entities where door.locked == true"
flint query "entities where audio_source.volume > 0.5"
flint query "entities where material.roughness >= 0.8"
flint query "entities where collider.shape == 'box'"

Value Types

Use in Constraints

Queries power the constraint system. Each constraint rule includes a query field that selects which entities the constraint applies to:

[[constraint]]
name = "doors_have_transform"
query = "entities where archetype == 'door'"
severity = "error"
message = "Door '{name}' is missing a transform component"

[constraint.kind]
type = "required_component"
archetype = "door"
component = "transform"

The query selects all door entities, and the constraint checks that each one has a transform component. See Constraints for details.

CLI Usage

# Basic query
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml

# JSON output for machine consumption
flint query "entities" --scene levels/tavern.scene.toml --format json

# TOML output
flint query "entities where door.locked == true" --scene levels/tavern.scene.toml --format toml

# Specify schemas directory
flint query "entities" --scene levels/tavern.scene.toml --schemas schemas

Limitations

• Conditions are currently single-clause (one field-operator-value comparison per query at the parser level)
• Boolean combinators (and, or, not) are part of the grammar design but not yet implemented in the parser
• Queries operate on in-memory ECS state, not directly on TOML files
• Performance is linear in entity count (queries scan all entities matching the resource type)

Further Reading

• Querying Entities — getting started tutorial
• Constraints — using queries in validation rules
• CLI Reference — command-line options

Constraints

Constraints are declarative validation rules that define what a correct scene looks like. They live in TOML files under schemas/constraints/ and are checked by flint validate.

Constraint File Format

Each constraint file can contain multiple [[constraint]] entries:

[[constraint]]
name = "doors_have_transform"
description = "Every door must have a transform component"
query = "entities where archetype == 'door'"
severity = "error"
message = "Door '{name}' is missing a transform component"

[constraint.kind]
type = "required_component"
archetype = "door"
component = "transform"

Constraint Kinds

required_component

Ensures that entities matching the query have a specific component:

[constraint.kind]
type = "required_component"
archetype = "door"
component = "transform"

Use case: every door must have a position in the world.

required_child

Ensures that entities have a child entity of a specific archetype:

[constraint.kind]
type = "required_child"
archetype = "room"
child_archetype = "door"

Use case: every room must have at least one door.

value_range

Checks that a numeric field falls within a valid range:

[constraint.kind]
type = "value_range"
field = "door.open_angle"
min = 0.0
max = 180.0

Use case: door angles must be physically possible.

reference_valid

Checks that an entity reference field points to an existing entity:

[constraint.kind]
type = "reference_valid"
field = "door.target_room"

Use case: a door’s target room must actually exist in the scene.

query_rule

The most flexible kind — validates that a query returns the expected number of results:

[constraint.kind]
type = "query_rule"
rule_query = "entities where archetype == 'player'"
expected = "exactly_one"

Use case: a playable scene must have exactly one player entity.

Auto-Fix Strategies

Some constraint violations can be fixed automatically. The fix section defines how:

• set_default — set a missing field to its schema default
• add_child — create a child entity with the required archetype
• remove_invalid — remove entities that violate the constraint
• assign_from_parent — copy a field value from the parent entity

Auto-fix runs in a loop: fix violations, re-validate, fix new violations. Cycle detection prevents infinite loops.

CLI Usage

# Check a scene for violations
flint validate levels/tavern.scene.toml

# JSON output for parsing
flint validate levels/tavern.scene.toml --format json

# Preview what auto-fix would change
flint validate levels/tavern.scene.toml --fix --dry-run

# Apply auto-fixes
flint validate levels/tavern.scene.toml --fix

# Specify a schemas directory
flint validate levels/tavern.scene.toml --schemas schemas

The exit code is 0 if all constraints pass, 1 if any errors are found. Warnings do not affect the exit code.

Real Example

From schemas/constraints/basics.toml:

[[constraint]]
name = "doors_have_transform"
description = "Every door must have a transform component"
query = "entities where archetype == 'door'"
severity = "error"
message = "Door '{name}' is missing a transform component"

[constraint.kind]
type = "required_component"
archetype = "door"
component = "transform"

[[constraint]]
name = "rooms_have_bounds"
description = "Every room must have a bounds component"
query = "entities where archetype == 'room'"
severity = "error"
message = "Room '{name}' is missing a bounds component"

[constraint.kind]
type = "required_component"
archetype = "room"
component = "bounds"

[[constraint]]
name = "door_angle_range"
description = "Door open angle must be between 0 and 180 degrees"
query = "entities where archetype == 'door'"
severity = "warning"
message = "Door '{name}' has an open_angle outside the valid range"

[constraint.kind]
type = "value_range"
field = "door.open_angle"
min = 0.0
max = 180.0

Further Reading

• Writing Constraints — practical guide to authoring rules
• Queries — the query language used in constraint selectors
• File Formats — constraint file format reference

Assets

Flint uses a content-addressed asset system with SHA-256 hashing. Every imported file is identified by its content hash, which means identical files are automatically deduplicated and any change to a file produces a new, distinct hash.

Content Addressing

When you import a file, Flint computes its SHA-256 hash and stores it under a content-addressed path:

.flint/assets/<first-2-hex>/<full-hash>.<ext>

This means:

• Deduplication — importing the same file twice stores it only once
• Change detection — if a source file changes, its hash changes, and the new version is stored separately
• Integrity — the hash verifies the file hasn’t been corrupted

Asset Catalog

The asset catalog is a searchable index of all imported assets. Each entry tracks:

• Name — a human-friendly identifier (e.g., tavern_chair)
• Hash — the SHA-256 content hash
• Type — asset type (mesh, texture, material, etc.)
• Tags — arbitrary labels for organization and filtering
• Source path — where the file was originally imported from

Importing Assets

Use the CLI to import files into the asset store:

# Import a glTF model with name and tags
flint asset import models/chair.glb --name tavern_chair --tags furniture,medieval

# Browse the catalog
flint asset list --type mesh

# Check asset references in a scene
flint asset resolve levels/tavern.scene.toml --strategy strict

glTF/GLB Import

The flint-import crate provides full glTF/GLB support, extracting:

• Meshes — vertex positions, normals, texture coordinates, and indices
• Materials — PBR properties (base color, roughness, metallic, emissive)
• Textures — embedded or referenced image files

Imported meshes are rendered by flint-render with full PBR shading.

Resolution Strategies

When a scene references assets, Flint can resolve them using different strategies:

The ai_generate, human_task, and ai_then_human strategies are part of the AI Asset Generation pipeline.

Asset Sidecar Files

Each asset in the catalog has a .asset.toml sidecar file storing metadata:

[asset]
name = "tavern_chair"
type = "mesh"
hash = "sha256:a1b2c3..."
source_path = "models/chair.glb"
tags = ["furniture", "medieval"]

Runtime Catalog Resolution

The player can load the asset catalog at startup for name-based asset resolution. When an entity references an asset by name, the resolution chain is:

1. Look up the name in the AssetCatalog
2. If found, resolve the content hash
3. Load from the ContentStore path (.flint/assets/<hash>)
4. Fall back to file-based loading if not in the catalog

This allows scenes to reference both pre-imported and AI-generated assets by name without hardcoding file paths.

Further Reading

• Importing Assets — step-by-step import guide
• AI Asset Generation — AI-powered asset creation pipeline
• Schemas — the material component schema for PBR properties
• File Formats — asset sidecar TOML format reference

Rendering

Flint uses wgpu 23 for cross-platform GPU rendering, providing physically-based rendering (PBR) with a Cook-Torrance BRDF, cascaded shadow mapping, optional 4x MSAA, and full glTF mesh support.

PBR Shading

The renderer implements a metallic-roughness PBR workflow based on the Cook-Torrance specular BRDF:

• Base color — the surface albedo, optionally sampled from a texture
• Roughness — controls specular highlight spread (0.0 = mirror, 1.0 = diffuse)
• Metallic — interpolates between dielectric and metallic response
• Emissive — self-illumination for light sources and glowing objects

Materials are defined in scene TOML via the material component, matching the fields in schemas/components/material.toml.

Diffuse shading is Lambert by default, but the scene can blend toward Oren-Nayar, soften the terminator with diffuse wrap, and add a Charlie-sheen rim through the [environment] block. Those levers, the light component, and area lights are documented on the Lighting page.

Shadow Mapping

Directional lights cast shadows via cascaded shadow maps. Multiple shadow cascades cover different distance ranges from the camera, giving high-resolution shadows close up and broader coverage at distance. A directional light with a non-zero angular_size gets contact-hardening PCSS shadows instead of the fixed PCF kernel.

Shadows are toggled at runtime from the Rendering & Effects menu (F4), which also offers the shadow-map resolution (512 to 4096). Headlessly, use --no-shadows and --shadow-resolution. See Lighting for details.

Camera Modes

The renderer supports two camera modes that share the same view/projection math:

The camera mode is determined by the entry point: edit uses orbit, play uses first-person. Both produce the same view and projection matrices. A scene’s [camera] block seeds the orbit camera in the viewer and the framing in flint render; in the viewer, Space returns to that authored framing.

glTF Mesh Rendering

Imported glTF models are rendered with their full mesh geometry and materials. The flint-import crate extracts meshes, materials, and textures from .glb/.gltf files, which the renderer draws with PBR shading.

Skinned Mesh Pipeline

For skeletal animation, the renderer provides a separate GPU pipeline that applies bone matrix skinning in the vertex shader. This avoids the 32-byte overhead of bone data on static geometry.

How it works:

1. flint-import extracts joint indices and weights from glTF skins alongside the mesh data
2. flint-animation evaluates keyframes and computes bone matrices each frame (local pose -> global hierarchy -> inverse bind matrix)
3. The renderer uploads bone matrices to a per-entity storage buffer and applies them in the vertex shader

Key types:

• SkinnedVertex — extends the standard vertex with joint_indices: [u32; 4] and joint_weights: [f32; 4] (6 attributes total vs. 4 for static geometry)
• GpuSkinnedMesh — holds the vertex/index buffers and material for a skinned asset
• Skinned pipeline uses bind groups 0–3: transform, material, lights, and bones (storage buffer, read-only, vertex-visible)

Bone buffers are keyed by entity, not by asset. Two entities that instance the same skinned model animate independently; before this change every instance showed whichever skeleton uploaded last. Skinned meshes also cast shadows through a dedicated vs_skinned_shadow shader entry point that applies bone transforms before depth rendering, and both wireframe debug modes draw them posed, using a per-draw unique-edge index buffer.

Billboard Sprites

Billboard sprites are camera-facing quads used for 2D elements in 3D space — enemies, pickups, particle effects, and environmental details. They always face the camera, like classic Doom-style sprites.

The BillboardPipeline is a separate rendering pipeline from PBR, optimized for flat textured quads:

• No vertex buffer — quad positions are generated procedurally from vertex_index (4 vertices per sprite)
• Per-sprite uniform buffer — each sprite gets its own instance data (position, size, frame, anchor)
• Binary alpha — the fragment shader uses discard for transparent pixels (avoids order-independent transparency complexity)
• Sprite sheet animation — supports multi-frame sprite sheets via frame, frames_x, and frames_y fields
• Render order — billboard sprites render after skinned meshes in the pipeline

Sprite Component

Attach a sprite to any entity with the sprite component:

[entities.imp]
archetype = "enemy"

[entities.imp.transform]
position = [10, 0, 5]

[entities.imp.sprite]
texture = "imp_spritesheet"
width = 1.5
height = 2.0
frames_x = 4
frames_y = 1
frame = 0
anchor_y = 0.0
fullbright = true

Design Decisions

Billboard sprites use a separate pipeline rather than extending the PBR pipeline. This keeps the PBR shaders clean and allows sprites to opt out of lighting entirely (fullbright = true). The discard-based alpha approach is simple and avoids the significant complexity of order-independent transparency, at the cost of no partial transparency (pixels are either fully opaque or fully transparent).

MSAA

Every scene pipeline (PBR, skinned, sky, skybox, ocean, terrain, grass, particles, billboards, 2D sprites) takes a sample count, so the scene passes can run at 4x MSAA (ADR 0058). Post-processing, shadow and blit passes stay single-sample, and depth-reading effects consume a sample-0 depth resolve. Enable it with flint render --msaa 4 or flint-player --msaa 4; the default is 1 so headless pixel gates stay single-sample.

Post-Processing

The renderer includes an HDR post-processing pipeline that applies bloom, SSAO, fog, volumetric light, depth of field, Kuwahara, color grade, film grain, tonemapping, vignette, FXAA and render modes as fullscreen passes. See Post-Processing for full details.

When post-processing is active, all scene pipelines render to an Rgba16Float HDR intermediate buffer. A composite fullscreen pass then applies exposure, ACES tonemapping and the rest of the chain to produce the final sRGB output.

Configure post-processing per-scene via the [post_process] TOML block, override with flint render flags (--no-postprocess, --bloom-intensity, --exposure, --dof, --grade-gain, and the rest of the set listed on the post-processing page), or tune it live from the F4 menu.

PBR Materials

PBR materials with varying roughness and metallic values. Left to right: rough dielectric, smooth dielectric, rough metal, polished metal.

Debug Visualization

The renderer provides eight shading modes, selected from the Shading combo in the Rendering & Effects menu (F4) or with --debug-mode headlessly:

Both wireframe modes draw skinned meshes in their animated pose; rigged models used to get no lines at all in the overlay and vanished in wireframe-only.

Additional overlays:

• Normal arrows (F3 in the viewer, --show-normals in render) — draws face-normal direction arrows
• Skeleton overlay (model previewer) — draws the armature over a rigged model, following the animated pose, with a colour mode that paints joints by last writer, layer weight, mask, or keyed joints. See Animation.
• Render stats (F2 in the viewer and the player) — frame time, draw counts, resolution

Wireframe debug mode showing mesh topology.

Normal debug mode mapping world-space normals to RGB channels.

Viewer vs Headless

The renderer operates in two modes:

Viewer mode (flint edit scene.toml --watch) opens an interactive window with:

• Real-time PBR rendering, with the scene’s [post_process] block applied on load
• egui inspector panel (entity tree, component editor, constraint overlay)
• Hot-reload: edit the scene TOML and the viewer updates automatically
• The Rendering & Effects menu (F4) for every render and post toggle, shading mode, shadows, lighting levers and FOV
• Auto-orbit turntable (O, with [ / ] for speed) and --auto-orbit to start in it

Headless mode (flint render) renders to a PNG file without opening a window — useful for CI pipelines and automated screenshots:

flint render levels/tavern.scene.toml --output preview.png --width 1920 --height 1080

Technology

The rendering stack uses winit 0.30’s ApplicationHandler trait pattern (not the older event-loop closure style). wgpu 23 provides the GPU abstraction, selecting the best available backend (Vulkan, Metal, or DX12) at runtime.

Further Reading

• Lighting — the light component, shadows, area lights, and the [environment] shading levers
• The Scene Viewer — getting started with the viewer
• Scripting — UI draw API for script-driven HUD overlays
• Schemas — sprite component schema definition
• Animation — the animation system that drives skinned meshes
• Physics and Runtime — the game loop and first-person gameplay
• Headless Rendering — CI integration guide

Lighting

Lights in Flint are ordinary entities with a light component. The renderer reads them every frame, sorts them by name so the shadow-casting sun is stable across reloads, and feeds them to the PBR shader alongside a set of scene-wide shading levers authored in the [environment] block. This page owns all of that: the light component, cascaded and contact-hardening shadows, area lights, and the “clay look” levers.

The Light Component

[entities.sun.light]
type = "directional"
direction = [0.5, 1.0, 0.3]        # points toward the light
color = [1.0, 0.98, 0.95]
intensity = 3.0
angular_size = 0.5                 # degrees; drives PCSS penumbra

[entities.lantern.light]
type = "point"
color = [1.0, 0.7, 0.4]
intensity = 8.0
range = 12.0
source_radius = 0.15               # meters; softens the specular hotspot

[entities.spot.light]
type = "spot"
direction = [0.0, -1.0, 0.0]
color = [1.0, 1.0, 1.0]
intensity = 20.0
range = 15.0
inner_angle = 0.3                  # radians
outer_angle = 0.5
source_radius = 0.1

Point and spot lights sit at their entity’s world position, so they follow transform hierarchies and animation like any other entity. Directional lights ignore position.

There is no light.toml in schemas/components; the renderer reads these keys straight from the component table, so flint validate will not catch a typo in a light field. Scenes that need a schema can add one in their own schemas/ layer.

Limits: the shader takes a fixed number of directional, point and spot lights. Only one directional light casts cascaded shadows: the one with the highest intensity, with entity-name order breaking ties (ADR 0045), so a fill light can never steal the sun’s shadows because of how it was named. If no scene light exists at all, the renderer falls back to a built-in warm key light and cool fill.

Area Lights

source_radius on point and spot lights, and angular_size on directional lights, turn punctual lights into small area sources (ADR 0056). The specular lobe uses the representative-point approximation: effective roughness widens by source_radius / (2 * distance) and shading distance never falls inside the source, so the hotspot on a glossy floor becomes a soft disc instead of a pinprick. Diffuse lighting is unaffected. A value of 0 takes the original code path exactly.

Shadows

Directional lights cast shadows through cascaded shadow maps: several cascades cover increasing distance bands from the camera, giving crisp shadows nearby and broad coverage far away. Shadows can be disabled per launch with --no-shadows, and toggled at runtime in the Rendering & Effects menu (F4).

Resolution. --shadow-resolution defaults to 2048 texels per cascade. Before ADR 0049 the shader hardcoded a 1/2048 texel size, so any other resolution filtered incorrectly and the flag was effectively decorative. The texel size is now uploaded with the cascade uniforms, so 512, 1024 and 4096 are real choices; the F4 menu’s Shadows section rebuilds the shadow pass when you pick one.

Contact hardening (PCSS). When the shadow-casting directional light has a non-zero angular_size, the shader switches from a fixed 3x3 PCF kernel to percentage-closer soft shadows (ADR 0057): a Vogel-disk blocker search estimates the average occluder depth, the penumbra width grows with the occluder-to-receiver distance and tan(angular_size), and the filter kernel is sized to match. Shadows are sharp where an object touches the ground and soften as it lifts away. angular_size = 0 takes the legacy PCF path verbatim, which keeps existing renders byte-identical.

Skinned casters. Skinned meshes cast shadows through a dedicated vs_skinned_shadow entry point that applies bone transforms before the depth write.

The [environment] Block

Scene-wide shading lives in [environment], next to the skybox path. Every lever here follows the same convention: absent or zero means the exact original shading, so scenes that never set them look the way they always did.

[environment]
skybox = "textures/dusk.hdr"
ambient_sky = [0.12, 0.13, 0.18]
ambient_ground = [0.06, 0.05, 0.04]
diffuse_wrap = 0.3
oren_nayar = 0.7
sheen_color = [1.0, 0.9, 0.8]
sheen_strength = 0.15

Fog is not here; it lives in [post_process].

How they combine in the shader: hemisphere ambient interpolates between the two colors by the surface normal’s Y. Diffuse wrap replaces the raw n·l term; Oren-Nayar scales the diffuse magnitude; the Charlie sheen adds a rim lobe on top. The three are orthogonal, and when all are zero the shader takes the original code path. The wrap and Oren-Nayar values ride the w components of the ambient uniforms encoded as 1 + value, which is why a stale or default uniform (w = 0) still means “off”.

The clay look

ADRs 0042 through 0052 grew these levers to give a scene a soft, sculpted, matte “clay” reading without touching materials. A recipe that works on the tavern showcase:

The tavern with default shading: Lambert diffuse, sharp terminator, neutral grade.

The same frame with Oren-Nayar 0.7, sheen 0.15, and a warm grade gain.

[environment]
diffuse_wrap = 0.25
oren_nayar = 0.7
sheen_color = [1.0, 0.9, 0.8]
sheen_strength = 0.15

[post_process]
ssao_samples = 16
grade_lift = [0.03, 0.02, 0.015]
grade_gain = [1.04, 1.0, 0.94]
film_grain = 0.02

The same levers are available headlessly, and CLI values win over the scene block:

flint render scene.toml --oren-nayar 0.7 --sheen-strength 0.15 --sheen-color 1,0.9,0.8 \
    --grade-gain 1.04,1,0.94 --ssao-samples 16

Runtime Control

The Rendering & Effects menu’s Lighting section exposes all six [environment] levers with a Reset button, plus shadow enable and resolution under Shadows. In code, SceneRenderer offers set_ambient / reset_ambient, set_diffuse_wrap, set_oren_nayar, set_sheen, set_shadow_resolution, and lighting_levers() to read the current state back for seeding UI.

Scripts do not currently have bindings for these levers; they are a per-scene look, not a per-frame effect. For per-frame mood changes use the sticky post-process overrides on the Post-Processing page.

Further Reading

• Rendering — the PBR pipeline these lights feed
• Post-Processing — volumetric shafts, grade and grain
• Sky — the procedural sky, which carries its own ambient_sky / ambient_ground on the sky component, distinct from the [environment] keys here
• File Formats — the [environment] block reference

Sky

The sky component replaces the texture skybox with a procedural sky: a vertical gradient, a sun disc that follows the scene’s light, a hashed starfield, and FBM clouds that drift.

Every value in this frame is a number on one component. Nothing here is a texture.

[entities.sky_dome]
[entities.sky_dome.sky]
zenith_color = [0.10, 0.32, 0.70, 1.0]
horizon_color = [0.55, 0.75, 0.90, 1.0]
haze_color = [0.80, 0.88, 0.95, 0.55]
cloud_coverage = 0.38
star_opacity = 0.0

Add it and the skybox pipeline steps aside. One sky per scene.

Time of day belongs to your game

Flint does not have a time-of-day system, and that is deliberate. The sky component is a state, not a clock. There is no hour field, no sun path built into the engine, no assumption that your world has 24-hour days at all.

A game that wants a day/night cycle writes a script that interpolates its own keyframes into these fields with set_field each frame. That script owns what “dusk” means for that game — how long it lasts, what color it is, whether the day is ten minutes or ten hours, whether there are days at all.

The payoff is that the same component serves a game with a wheeling sunrise-to-starscape cycle, a game permanently frozen at golden hour, and a game whose sky is driven by something other than time entirely.

The engine’s contribution is the Day / Time debug panel (F3), which drives a game-side time_of_day component by convention — see the CLI reference.

Fields

The sun

The sun disc is drawn where directional_lights[0] points — it is not positioned independently. Move the light and the disc follows, which means the visible sun and the light actually casting your shadows can never disagree.

Flint’s light direction points from surfaces toward the light.

Ambient

ambient_sky and ambient_ground override the hemisphere ambient in the light uniforms. This is how a night gets genuinely dark: a script drops both along with the sun’s intensity, and unlit surfaces fall away instead of staying suspiciously legible.

Stars

Stars are a hash function, not a texture — no seams, no resolution, and free to fade with star_opacity. The hash is deliberately sinless: fract(sin(x)) loses precision far from the origin on some GPUs and breaks into a visible lattice.

Reflections

An ocean with sky_reflection_strength > 0 takes a per-frame snapshot of the sky’s gradient and reflects it, Fresnel-weighted. Change the sky and the water follows with no extra wiring.

The snapshot carries the gradient only, never the sun disc — see Ocean: water clarity for why.

See also

• Ocean — reflects this sky
• Rendering — lights, shadows, and the texture skybox
• Scripting — set_field for per-frame sky drives

Ocean

Flint renders an endless, physically-grounded ocean: a sum of Gerstner waves shaped by a JONSWAP wind-sea spectrum, drawn on a camera-following grid and shaded in hard cel bands. The waves are believable — real dispersion, real directional spread — while the look stays graphic.

Flat bold blues, hard-edged white foam. The wave physics is real; the shading is a woodblock print.

Add one ocean component to a scene and you have a horizon-to-horizon sea:

[entities.ocean]
[entities.ocean.ocean]
seed = 7
num_waves = 12
wavelength_min = 5.0
wavelength_max = 70.0
amplitude = 0.85
choppiness = 0.7
wind_speed = 7.0
fetch_km = 60.0

One ocean per scene. The grid follows the camera, so there is no world size to configure and no edge to sail off.

The parity contract

This is the single most important thing to know about the ocean.

flint-core/src/ocean.rs is the sole source of truth for wave math. It builds the wave array on the CPU, and the GPU only sums the array it is given — ocean_shader.wgsl contains no spectrum logic of its own. That is what lets a script ask ocean_height(x, z) and get the same answer the renderer drew, which is what buoyancy, splash detection and camera work all depend on.

If you change the wave math, CPU and GPU must move together. Two guards exist:

• gpu_packing_matches_cpu_evaluation in flint-core asserts the packed GPU layout evaluates to the CPU result.
• A wave_probe script pinning a visible buoy to ocean_height will visibly detach from the surface the moment parity breaks.

A related trap: wave phase is precomputed per frame in f64 on the CPU and uploaded. Never accumulate phase in f32 in the shader — over a long session it drifts and the sea starts to shimmer.

The spectrum

Waves are not chosen by hand. You describe a sea state and the spectrum generates the wave set.

Each wave obeys the deep-water dispersion relation, so longer waves genuinely travel faster. wind_speed and fetch_km are the expressive controls: raising both moves energy into long swell and gives you an ocean that feels like it has weather behind it.

Phase-safe fields

If you animate the ocean at runtime (a weather system, say), only some fields can change without visibly popping the sea:

• Safe to ramp: amplitude, choppiness, wind_speed, fetch_km. Regenerating the spectrum preserves existing wave phases.
• Load-time only: direction_deg, spread_deg, seed, speed_scale, and the wavelength band. Changing these re-rolls the wave set and the surface jumps.

Pick a wavelength band wide enough at load time to cover every sea state you intend to reach, then move energy within it with wind and fetch.

Shading

The fragment shader is deliberately not a water shader in the photoreal sense. Lighting is quantized into ramp_steps hard bands, and foam is a hard-edged mask rather than a soft blend.

Foam comes from the Jacobian of the Gerstner displacement — that is, from where the surface is actually compressing toward a breaking crest. It is a physical quantity, not a height threshold, which is why the foam sits where foam belongs even in a confused sea.

The ocean writes depth, so scene fog applies to it correctly. It also fogs itself to the scene fog color before the composite’s sky cutoff, otherwise the far water would render as an unfogged dark band at the horizon.

Bioluminescence

foam_glow (0 = off) makes foam emissive in foam_glow_color. Drive it from a time-of-day script to get plankton bloom nights where the wake lights up.

Contact foam

Give any entity an ocean_contact component and the ocean grows a splash ring around its hull:

[entities.boat.ocean_contact]
half_x = 1.2
half_z = 1.15

The renderer tracks the hull’s center, yaw and extents, differentiates its position for velocity, and the shader computes churn from the water’s orbital velocity relative to the hull, projected into the nearest hull face. A flat sea stays quiet, the lee side stays quiet, and the windward face flares.

On genuinely glassy water, set splash_baseline = 0 — a foam ring hugging a motionless hull on a mirror reads as a bug.

Rain

rain_ripple (0..1) scatters expanding impact rings across the surface, hashed on a world-space grid and scanned over a 3×3 cell neighborhood so rings crossing cell boundaries do not tile into visible squares. They fade out by ~30 m. Drive it from the same weather signal that drives your rain particles.

Water clarity

With post-processing enabled the ocean does a grab pass and refracts whatever is underwater:

The sky reflection is a snapshot of the procedural sky’s gradient, so reflections track the time of day for free. It deliberately contains no sun disc — the cel specular already is the sun’s reflection, and including it here would draw two suns.

Surfaces seen from below flip their normal and drop both sky reflection and specular, so the underside of the water reads as water rather than as an opaque mirror of the sky.

The grid

The mesh is a normalized grid, radially warped so the center has sub-meter cells and the rim reaches kilometers — past the geometric horizon at eye height, so the water’s edge is never visible. It follows the camera snapped to inner-cell multiples, which keeps waves world-anchored instead of swimming with the view.

Querying the ocean from scripts

let h  = ocean_height(x, z);        // Eulerian surface height (m)
let v  = ocean_velocity_y(x, z);    // vertical surface velocity (m/s)
let n  = ocean_normal(x, z);        // #{x, y, z} surface normal

ocean_height is what buoyancy is built on — sample it at a few points under a hull and drive the transform from the result:

fn on_update() {
    let me = entity();
    let p = get_field(me, "transform", "position");
    let h = ocean_height(p.x, p.z);
    // ... ease the hull toward h, tilt from ocean_normal ...
}

ocean_velocity_y is the analytic ∂h/∂t, not a finite difference, and it is the signal you want for impact cues: the relative approach speed between water and hull tells you how hard a wave struck, which is what separates a lap from a slam.

Sampling is cheap enough for a handful of probes per frame. It is not cheap enough for thousands.

Debugging

The Ocean Debug panel (F3 in the player) exposes the whole component live — spectrum, colors, foam, contact foam, band edges, clarity, grid — and Commit to File writes your tuning back into the scene TOML.

show_probe parks a bright buoy on the surface as a standing CPU/GPU parity check.

Headless:

flint render scene.toml --schemas schemas --width 2560 --height 1440 --no-grid \
  --distance 9 --pitch 18 --yaw 35 --target 0,0.4,0

Note that flint render runs no scripts. If your hull floats by script, it will render at its authored transform rather than on the water — frame around it, or bake a fixture scene with the values you want.

See also

• Sky — the procedural sky the ocean reflects
• Post-Processing — including underwater render mode 5
• Scripting — the full Rhai API

Post-Processing

Flint includes an HDR post-processing pipeline that transforms the raw scene render into polished final output: bloom, SSAO, fog, volumetric lighting, depth of field, a painterly Kuwahara filter, color grading, film grain, tonemapping, vignette, FXAA, and whole-screen render modes.

How It Works

Instead of rendering directly to the screen, the scene is drawn to an intermediate HDR buffer (Rgba16Float format) that can store values brighter than 1.0. A series of fullscreen passes then process this buffer:

Scene render        Depth       Kuwahara     SSAO       Volumetric   Bloom chain    Composite pass        FXAA
(PBR, skinned,  ->  resolve  -> (optional -> depth-  -> shadow-   -> downsample  -> DoF, AO, god rays  -> (optional
 billboard,         (MSAA       painterly    based      based        upsample       bloom, fog, exposure    edge AA)
 particles,         sample 0)   pre-pass)    AO         god rays                    ACES, grade, desat,
 sky, ocean,                                                                        render mode, vignette,
 terrain, grass)                                                                    grain, dither
     |                 |            |           |           |            |                |                   |
 Rgba16Float       depth       filtered     AO         vol          bloom          sRGB surface or       sRGB
 HDR buffer        texture     HDR          texture    texture      texture        FXAA intermediate     surface

All scene pipelines — PBR, skinned mesh, billboard sprite, particle, skybox, sky, ocean, terrain and grass — render to the HDR buffer when post-processing is active. The PBR shader’s built-in tonemapping is automatically disabled so it outputs linear HDR values for the composite pass to process. Kuwahara and FXAA resources are only allocated when their effect is enabled.

Bloom

Bloom creates the soft glow around bright light sources — emissive materials, fire particles, bright specular highlights. The implementation uses the technique from Call of Duty: Advanced Warfare:

1. Threshold — pixels brighter than bloom_threshold are extracted
2. Downsample — a 5-level mip chain progressively halves the resolution using a 13-tap filter
3. Upsample — each mip level is upsampled with a 9-tap tent filter and additively blended back up the chain
4. Composite — the final bloom texture is mixed into the scene at bloom_intensity strength

Post-processing enabled: bloom creates halos around emissive surfaces and bright lights.

Post-processing disabled: the same scene rendered with shader-level tonemapping only.

The mip chain depth is calculated as floor(log2(min(width, height))) - 3, capped at 5 levels, ensuring the smallest mip is at least 8x8 pixels.

SSAO (Screen-Space Ambient Occlusion)

SSAO darkens crevices, corners, and areas where surfaces meet, adding depth and realism to a scene without requiring extra light sources. The implementation samples the depth buffer around each pixel to estimate how much ambient light would be blocked by nearby geometry.

SSAO is the heaviest per-pixel pass in the post stack. The sample kernel is strided, so lower counts keep full radius coverage; ssao_samples = 16 is usually indistinguishable on soft matte scenes and roughly four times cheaper. The clay-look demo scenes use 16.

An SSAO depth bias (default 0.025) is exposed in the Rendering & Effects menu but has no scene key.

Depth of Field

Depth of field defocuses everything outside a focus band. The composite pass computes a circle of confusion per pixel from the depth buffer and gathers a CoC-weighted disc from the HDR source, so in-focus foreground does not bleed into defocused regions.

Focus plane at 3 m: the foreground is sharp and the room behind it falls away.

Focus plane at 12 m: the same frame with the focus pushed back.

Distances are plain view-space meters. Earlier builds linearized depth with the OpenGL [-1, 1] convention, which made focus values drift with the far plane; ADR 0055 moved every depth consumer to wgpu’s [0, 1] convention, so dof_focus_distance = 10 now means ten meters from the camera.

In the scene viewer, the Rendering & Effects menu offers DoF follow: the focus plane tracks the last selected entity, which is a fast way to find a focus distance by eye.

Fog

Distance-based fog blends a configurable fog color into the scene based on pixel depth. Height-based falloff can be layered on top so fog is thicker near the ground and thins out at higher elevations. Fog is applied in linear HDR space, before tonemapping.

Volumetric Lighting (God Rays)

Volumetric lighting simulates light scattering through participating media (dust, fog, haze), producing visible shafts of light (god rays). The effect ray-marches from each pixel toward the camera, sampling the shadow map at each step to determine whether that point in space is lit or in shadow.

How it works

1. For each screen pixel, reconstruct its world position from the depth buffer
2. March volumetric_samples steps along the view ray from the pixel back toward the camera
3. At each step, project the position into shadow-map space and sample the cascaded shadow map
4. Accumulate light contribution where the sample is not in shadow, applying exponential decay
5. The resulting volumetric texture is additively blended into the scene during the composite pass

Because volumetric lighting depends on the shadow map, it requires at least one directional light with shadows enabled. The effect is disabled when shadows are off.

Per-light configuration

Each directional light can control its volumetric contribution independently via its light component (see Lighting for the full component):

[entities.sun.light]
type = "directional"
direction = [0.4, 0.6, 0.05]
color = [1.0, 0.92, 0.75]
intensity = 6.0
volumetric_intensity = 4.0               # god ray brightness (0 = no rays)
volumetric_color = [1.0, 0.88, 0.6]      # tint for the light shafts

Global scene settings

The [post_process] block controls the overall volumetric pass:

Example: dungeon window

[post_process]
volumetric_enabled = true
volumetric_samples = 64
volumetric_density = 30.0
volumetric_max_distance = 15.0
volumetric_decay = 0.998
exposure = 2.5

[entities.sun.light]
type = "directional"
direction = [0.4, 0.4, 0.05]
color = [1.0, 0.92, 0.75]
intensity = 6.0
volumetric_intensity = 4.0
volumetric_color = [1.0, 0.88, 0.6]

High volumetric_density with a short volumetric_max_distance and decay close to 1.0 produces thick, concentrated shafts — good for dusty interiors. For outdoor haze, use lower density and longer distance.

Kuwahara (Painterly Filter)

The anisotropic Kuwahara filter turns the HDR image into flat, brush-like patches that follow local edge direction. It runs as a pre-pass on the HDR buffer before SSAO and bloom, so lighting effects stay crisp on top of the painted surface. Three shaders cooperate: a structure-tensor pass, a tensor blur, and the sector filter itself.

The tavern showcase with the Kuwahara pre-pass disabled.

The same frame with the anisotropic Kuwahara filter, radius 4.

The filter’s textures and pipelines are allocated the first time it is enabled, so scenes that never use it pay nothing.

Color Grade, Film Grain and FXAA

Three finishing controls from ADR 0050 sit at the end of the composite pass.

Color grade is an ASC-CDL-shaped lift/gamma/gain applied right after ACES tonemapping, so it grades the display-referred image: pow(max(color * gain + lift, 0), 1 / gamma). The grade is skipped entirely while all three are neutral.

Film grain is hash noise on pixel coordinates, luma-weighted so highlights stay clean, and time-quantized to 24 Hz. It reads the shared post time, which flint render fixes at 0 unless you pass --grain-time, so headless renders stay deterministic.

FXAA is a separate fullscreen pass after composite. It is off by default because the headless pixel-diff gates run without it.

Desaturation, Chromatic Aberration and Radial Blur

These three are the “feel” levers scripts reach for most; see the script notes below for which ones are sticky.

Desaturation mixes toward luma * 0.62 rather than neutral grey on purpose: it matches the disintegration ladder of the music-session harness, so the language of “the world draining” reads the same in both.

Vignette, Exposure and Dither

MSAA

The scene passes can run with 4x multisample anti-aliasing (ADR 0058). Post-processing, shadow and blit passes stay single-sample; depth consumers such as SSAO, fog and DoF read a sample-0 depth resolve.

Left: single-sample. Right: --msaa 4. Geometry edges smooth out; post effects are unchanged.

MSAA is a launch option, not a scene key: flint render --msaa 4, flint-player --msaa 4, or RendererConfig::sample_count in code. Valid values are 1 and 4; anything else is clamped to 1 with a warning. The default stays 1 so headless pixel gates remain single-sample.

Scene Configuration

Add a [post_process] block to your scene TOML to configure per-scene settings:

[post_process]
bloom_enabled = true
bloom_intensity = 0.04
bloom_threshold = 1.0
ssao_enabled = true
ssao_radius = 0.5
ssao_intensity = 1.0
ssao_samples = 16
fog_enabled = true
fog_density = 0.02
fog_color = [0.7, 0.75, 0.82]
volumetric_enabled = false
dof_strength = 0.4
dof_focus_distance = 8.0
dof_focus_range = 4.0
kuwahara_enabled = false
grade_lift = [0.03, 0.02, 0.015]
grade_gamma = [1.0, 1.0, 1.0]
grade_gain = [1.04, 1.0, 0.94]
film_grain = 0.03
fxaa = false
vignette_enabled = true
vignette_intensity = 0.3
exposure = 1.0

All fields are optional — omitted values use their defaults. The full key list with defaults is in File Formats.

When the pipeline is disabled (--no-postprocess or the menu checkbox), most effects are zeroed: bloom, vignette, fog, dither, desaturate, film grain, DoF, render mode and grade. Two are not: chromatic_aberration and radial_blur predate the gate and stay live even with post-processing off.

The scene viewer applies the scene’s [post_process] block on load (ADR 0046). The Rendering & Effects menu can swap between the authored block and the viewer’s default look.

CLI Flags

Override post-processing settings from the command line:

# Disable all post-processing
flint render scene.toml --no-postprocess

# Adjust bloom and exposure
flint render scene.toml --bloom-intensity 0.08 --bloom-threshold 0.8 --exposure 1.5

# SSAO, with the cheap sample count
flint render scene.toml --ssao-radius 0.5 --ssao-intensity 1.0 --ssao-samples 16

# Fog
flint render scene.toml --fog-density 0.02 --fog-color 0.7,0.75,0.82 --fog-height-falloff 0.1

# Volumetric lighting
flint render scene.toml --volumetric-density 1.0 --volumetric-samples 32

# Depth of field
flint render scene.toml --dof 0.6 --dof-focus 10 --dof-range 5

# Kuwahara
flint render scene.toml --kuwahara-radius 4 --kuwahara-sharpness 8 --kuwahara-hardness 8 --kuwahara-anisotropy 1

# Grade, grain, FXAA, MSAA
flint render scene.toml --grade-lift 0.03,0.02,0.015 --grade-gain 1.04,1,0.94 --film-grain 0.03 --fxaa --msaa 4

# Combine flags
flint play scene.toml --bloom-intensity 0.1 --exposure 1.2 --volumetric-density 5.0

CLI flags take precedence over scene TOML settings.

The Rendering & Effects Menu (F4)

There are no longer per-effect function keys. ADR 0053 consolidated every render and post-process debug control into one egui window, opened with F4 in both the player and the scene viewer. Every toggle above appears there with its non-binary parameters, and changes write straight through to the renderer.

The scene viewer adds two entries of its own: a toggle between the scene’s authored [post_process] block and the viewer’s default look, and DoF follow. In the player the menu is compiled in with the debug-hud feature (on by default) and F3 deliberately leaves it alone: F3 toggles the scene-component panels (ocean, grass, time of day, and so on), F4 owns this one.

When the pipeline is toggled off, the PBR shader’s built-in ACES tonemapping and gamma correction are automatically restored, so the scene always looks correct regardless of the pipeline state.

Shader Integration

When the post-processing pipeline is active, the engine sets enable_tonemapping = 0 in the PBR uniform buffer, forcing shaders to output raw linear HDR values. The composite pass then applies, in this order:

1. Drunk sway — render mode 3 warps the sample UV before anything is read
2. Radial blur — 8-tap gather from the HDR source, edges only
3. Depth of field — CoC-weighted disc gather from the same source
4. Chromatic aberration — radial red/blue channel split
5. SSAO — multiplies by the AO texture
6. Volumetric — adds the god-ray texture
7. Bloom — adds the bloom texture at bloom_intensity
8. Fog — blends fog color by depth and optional height falloff, still in linear HDR
9. Exposure and ACES tonemapping — maps HDR to displayable range
10. Color grade — lift/gamma/gain on the display-referred image
11. Desaturation — mix toward ash grey
12. Render mode — Matrix, Blood, Tron, or Underwater own the color from here
13. Vignette — edge darkening
14. Film grain — 24 Hz hash noise, before dither because grain is signal
15. Dither — 8x8 Bayer, always last inside composite

The composite output stays linear; the sRGB render target applies gamma encoding in hardware. If FXAA is on, composite renders into an intermediate texture and the FXAA pass resolves it to the surface.

When post-processing is disabled (via --no-postprocess or the menu), the shader handles tonemapping and gamma internally. This dual-path design ensures backward compatibility with scenes that don’t use post-processing.

Render Modes

Render modes are whole-screen stylizations that branch after ACES tonemapping and before vignette. They are not debug views: they are a supported way to make the world visibly stop being itself for a while.

Mode 4 over an ocean scene: depth-reconstructed world grid, Sobel edges on depth and luminance.

Mode 1: dot-matrix glyphs whose brightness and density track scene luminance.

Mode 2: the palette remap, with the ocean recoloring itself through its own shader.

Mode 3: UV sway across the whole composite chain plus a ghosting double-tap.

Mode 5: masked by the per-pixel waterline, with banded absorption and a foam lip on the line.

Four uniforms carry the state: render_mode, mode_mix (0..1 blend), mode_time, and a mode_params vec4 whose meaning is per-mode.

Modes 1–4 fade in through an fbm bleed mask whose threshold sweeps across the noise span, so patch coverage grows with mode_mix and pins to full coverage at 1. Mode 5 ignores the mask entirely: being underwater is a fact about where your eye is, not a patch that spreads.

From scripts

set_render_mode(4, 0.85);                  // mode, mix
set_render_mode_params(3.0, 0.0, 6.0, 0.0);
set_desaturation(0.5);                     // sticky
set_dof(0.6);                              // sticky
set_dof_focus(8.0, 4.0);                   // distance, range; sticky

set_render_mode is transient, and it is the only post-process override that is. Every other override (exposure, bloom, fog, chromatic aberration, desaturation, depth of field) is sticky: set it once and it persists. The render mode is zeroed the frame your script stops calling it.

That asymmetry is deliberate. A sticky render mode plus a script that crashed, hot-reloaded, or was disabled mid-effect would leave the world permanently inside a hallucination with no way out. Instead, a dead script means a healed world. The cost is that you must call it every frame the effect is active:

fn on_update() {
    let m = current_mix();          // your own envelope
    if m > 0.001 {
        set_render_mode(active_mode, m);
    }
    // stop calling -> the engine restores the world by itself
}

Sticky effects a mode borrows (FOV, radial blur, chromatic aberration) are not covered by this, so zero them yourself when your effect ends. The player’s F4 menu has a Freeze script post overrides checkbox for the moments you want to tune by hand while a script is still writing.

Headless

flint render scene.toml --schemas schemas \
  --render-mode 4 --mode-mix 1.0 --mode-params 3,0,6,0

Since flint render runs no scripts, these flags are the fixture: there is no script to drive the mode for you.

One practical note: modes 1 and 4 key off scene luminance, so they read best in daylight even if your game schedules them at night. A night scene renders the Matrix mode nearly black.

Design Decisions

• Rgba16Float for the HDR buffer provides sufficient precision for bloom extraction without the memory cost of Rgba32Float
• Progressive downsample/upsample (rather than a single Gaussian blur) produces wide, natural-looking bloom cheaply
• 1x1 black fallback texture when bloom is disabled avoids conditional bind group creation
• Lazy allocation — Kuwahara and FXAA pipelines and textures are created the first time they are enabled, so the default path pays nothing for them
• Gate-safe defaults — MSAA, FXAA and film grain default off, and grain time is pinned at 0 headlessly, so flint render output stays byte-stable for pixel-diff gates
• Resize handling — PostProcessResources are recreated on window resize since the HDR texture and bloom mip chain are resolution-dependent
• Extended shadow depth — the shadow frustum’s depth range is extended beyond the camera frustum so off-screen casters (ceilings, walls behind the camera) are captured in the shadow map, which is critical for correct volumetric shafts in enclosed spaces

Further Reading

• Rendering — the PBR pipeline that feeds into post-processing
• Lighting — the light component, shadows, and the clay-look shading levers
• Headless Rendering — using post-processing flags in CI
• CLI Reference — full command options
• File Formats — the [post_process] scene block

Audio

Flint’s audio system provides spatial 3D sound via the flint-audio crate, built on Kira 0.11. Sounds can be positioned in 3D space with distance attenuation, played as ambient loops, or triggered by game events like collisions.

Spatial Audio

Spatial sounds are attached to entities via the audio_source component. The sound’s volume attenuates with distance from the listener (the player camera):

• min_distance — full volume within this radius
• max_distance — silence beyond this radius
• Volume falls off smoothly between the two

The listener position and orientation are updated each frame to match the first-person camera, so sounds pan and attenuate as you move through the scene.

Ambient Loops

Non-spatial sounds play on the main audio track at constant volume regardless of listener position. Set spatial = false on an audio_source to use this mode — useful for background music, ambient atmosphere, and UI sounds.

Preloading

At scene load the player loads every file named by an audio_source component, then preloads every audio file it finds under audio/ (searching the scene directory, then its parent, the game root) so that play_sound("name") from a script never stalls on decode. A scene with a large stem library pays for that in load time. Opt out per scene:

[scene]
name = "Silent Corridor"
preload_audio = false

With preload_audio = false only audio_source files load, and music sessions resolve their stems through their own path. The default is true (ADR 0066, scene audio preload opt-out).

Mixer Buses

Every ordinary sound routes through one of two buses — music and sfx — both children of Kira’s main track. (A running music session adds its own six-bus stem mixer on the same device; that mixer is owned by flint-music, not by audio_source, and is described on its own page.)

main  ──┬── music     (audio_source.bus = "music")
        └── sfx       (everything else, including all one-shots)

Opt a source into the music bus in the scene:

[entities.score.audio_source]
file = "audio/theme_night.ogg"
bus = "music"
loop = true
autoplay = true

Initial gains come from the CLI:

flint play scene.toml --music-volume 0.8 --sfx-volume 1.0
flint play scene.toml --music-volume 0     # mute the score, keep the world

Bus gain multiplies underneath per-sound volume. A script crossfading between two music beds keeps working at any bus gain, and a player who has turned the music down does not have their fades overridden.

The master low-pass applies to both buses, so set_audio_lowpass muffles the entire mix — score included — which is what you want when the effect is “something is between you and the world” rather than “the sfx got quieter”.

One-shots (play_sound, play_sound_at) are always sfx.

Music Sessions

A scene that carries a music_session component turns the audio engine into the host for a rhythm-driven chart: flint-music opens a ChartSession on the same Kira manager the ordinary buses use (ADR 0017, shared audio manager), so the world’s sounds and the suite’s stems mix together and one master low-pass muffles both. For the length of the session the gamepad is handed to a 1 kHz capture thread that stamps every stick and button event with the audio clock (ADR 0018, gamepad handoff).

While a session is active, only the lean stick and the pulse button reach InputState. Every other gamepad control is consumed by the capture thread; keyboard input still flows through winit as normal. Scripts that need the pad for anything else during a chart should read the conducted parameters instead.

The component, its configuration files, the ladder and reintegration mechanics, and the seven flint subcommands that go with it are on the Music Sessions page.

Audio Schemas

Three component schemas define audio behavior:

audio_source (audio_source.toml) — a sound attached to an entity:

Looping component sources must keep autoplay = true. Components have no play/stop API — scripts can only fade their volume. If you need a sound that starts on cue, use a one-shot instead.

audio_listener (audio_listener.toml) — marks which entity receives audio:

audio_trigger (audio_trigger.toml) — event-driven sounds:

Dynamic Parameter Sync

Audio source parameters (volume and pitch) can be changed at runtime via set_field() and the engine automatically syncs changes to the playing audio each frame. This enables dynamic audio effects like engine RPM simulation or distance-based volume curves:

#![allow(unused)]
fn main() {
// Adjust engine sound pitch based on speed
let rpm_ratio = speed / max_speed;
set_field(engine_sound, "audio_source", "pitch", 0.5 + rpm_ratio * 1.5);
set_field(engine_sound, "audio_source", "volume", 0.3 + rpm_ratio * 0.7);
}

Changes are applied with a 16ms tween for smooth transitions (no clicks or pops).

Scene Transition Behavior

When a scene transition occurs (via load_scene() or reload_scene()), all playing sounds are explicitly stopped with a short fade-out before the old scene is unloaded. This prevents audio bleed between scenes — sounds from the previous scene won’t continue playing into the new one.

Architecture

The audio system has three main components:

• AudioEngine — wraps Kira’s AudioManager, handles sound file loading, listener positioning, and spatial track creation. Sounds route through spatial tracks for 3D positioning, or through a mixer bus for non-positional playback.
• AudioSync — bridges TOML audio_source components to Kira spatial tracks. Discovers new audio entities each frame and updates spatial positions from entity transforms.
• AudioTrigger — maps game events (collisions, interactions) to AudioCommands that play sounds at specific positions.

The system implements the RuntimeSystem trait, ticking in the update() phase of the game loop (not fixed_update(), since audio doesn’t need fixed-timestep processing).

Graceful Degradation

AudioManager::new() can fail on headless machines or CI environments without an audio device. The engine wraps the manager in Option and silently skips audio operations when unavailable. This means scenes with audio components work correctly in all environments — you just won’t hear anything.

Adding Audio to a Scene

# A crackling fire with spatial falloff
[entities.fireplace]
archetype = "furniture"

[entities.fireplace.transform]
position = [5.0, 0.5, 3.0]

[entities.fireplace.audio_source]
file = "audio/fire_crackle.ogg"
volume = 0.8
loop = true
spatial = true
min_distance = 1.0
max_distance = 15.0

# Background tavern ambience (non-spatial)
[entities.ambience]

[entities.ambience.audio_source]
file = "audio/tavern_ambient.ogg"
volume = 0.3
loop = true
spatial = false

Supported audio formats: OGG, WAV, MP3, FLAC (via Kira’s symphonia backend).

Scripting Integration

Audio can be controlled from Rhai scripts using deferred commands. The script API produces ScriptCommand values that the player processes after the script update phase:

#![allow(unused)]
fn main() {
// In a Rhai script:
fn on_interact() {
    play_sound("door_open");                          // Non-spatial
    play_sound_at("glass_clink", 5.0, 1.0, 3.0, 0.8); // Spatial at position
}
}

Sound names match files in the audio/ directory. All .ogg, .wav, .mp3, and .flac files are automatically loaded at startup.

Further Reading

• Scripting — full scripting API including audio functions
• Animation — animation system that can trigger audio events
• Physics and Runtime — the game loop and event bus that drives audio triggers
• Schemas — component and archetype definitions

Music Sessions

A music session turns a scene into a rhythm-driven space: a fixed set of stems plays sample-locked on the audio clock, a beatmap chart says what the player’s controller should be doing on each beat, and the world’s audio and visuals come apart or re-gather as one thing depending on how well the two agree. The machinery lives in two engine crates, flint-music and flint-input-capture, and is switched on per scene by a music_session component. It grew out of Starchild but nothing in it is game-specific: any scene with a suite manifest and a chart can run one.

The design rule throughout is “linear composition, adaptive playback”: the music is authored once as a suite, and the engine adapts how it is played back, never what it is.

The Crates

flint-music is the data-contract and judgment layer. It parses suite manifests and charts, validates them against each other and against the stem files, keeps musical time (tempo map, conductor), judges input against the chart, integrates the result into a single coherence value, drives the six-bus stem mixer through the disintegration ladder, sequences reintegration after a full fail, records and replays sessions, and renders a scripted session offline to WAV. It never touches a gamepad.

flint-input-capture owns the gamepad on a dedicated thread polling at 1 kHz (default), far above frame rate, so pulse timing resolves at millisecond granularity instead of once per frame. Every event is stamped with a compensated suite sample: the bridged audio-clock sample minus the total judgment offset (measured output latency plus tap calibration), so the event carries the musical moment the player was responding to. On Windows the crate uses gilrs on the XInput backend rather than the default (ADR 0011, gilrs XInput backend), because the default backend delivers nothing to console applications.

Neither crate is optional at build time. The player links both; without an audio device or a gamepad the session simply degrades, as described below.

Verb Space

Charts never see buttons. The capture thread maps physical controls onto a small verb space, and the chart is written in those verbs:

Which of these the pad produces is a verb map (ADR 0030, full verb map capture):

• prototype (default): left stick is lean; South button or right trigger is pulse. Byte-identical to the earliest builds.
• full: left stick is lean, South is pulse, triggers become pressure_l/pressure_r streams with press onsets, right stick becomes sway plus the flick detector. The right trigger no longer emits a plain pulse.

Select it with input_map on the component or --input-map on the CLI harnesses.

Suite Manifest and Chart

A suite is two TOML files, both carrying schema_version = 0.

The manifest (*.suite.toml) describes the music:

schema_version = 0

[suite]
id = "prologue"
title = "Prologue"

[audio]
sample_rate = 48000

[[tempo]]
sample = 0
bpm = 96.0
time_signature = [4, 4]

[[sections]]
name = "intro"
start_sample = 0
pulse_window_ms = 90.0

[reintegration]
re_entry_sections = ["intro", "verse"]
lead_bus = "home_theme"
reassembly_bars = 4

[buses.foundation]
file = "stems/foundation.wav"
[buses.harmony]
file = "stems/harmony.wav"
[buses.texture]
silent = true

The bus set is fixed at six: foundation, harmony, world_voice, home_theme, child_motif, texture. home_theme and child_motif are the motif buses and must stay isolated (never share a file with another bus). Optional [[degraded_alternates]] entries name a pre-composed degraded take for a bus over a sample range (ADR 0032, degraded alternate playback).

The chart (*.chart.toml) says what the player should do, in beats:

• [[curves]] keys: channel, beat, value (one or two numbers), interp in linear | hold | smooth.
• [[pulses]]: beat, kind in pulse | press | flick, optional window_ms, strength, direction.
• [[cues]]: beat, cue name, optional params table. Cues reach scripts through conducted_cues() (ADR 0033, cue params and conducted cues).
• [[intensity]] keys: beat, value.

Both parsers are shape-tolerant on purpose. Unknown bus names, channels or kinds parse fine and are reported by flint validate-suite as coded issues; only structurally unreadable input fails to parse.

The music_session Component

Add the component to any entity in the scene. Its schema file lives in the game’s schemas/components/ directory, not in the engine’s, so the engine reads it by name and validates the fields itself:

[entities.conductor.music_session]
manifest = "music/prologue.suite.toml"
chart = "music/prologue.chart.toml"
lean_mode = "arrival"
input_map = "full"
ladder_config = "config/ladder.toml"
bars = 64
quit_on_finish = false

Paths are resolved against the game root (the scene’s base_dir), the same place scripts/ and audio/ live.

Lifecycle

1. Shared audio manager. The session opens on the player’s existing Kira manager rather than its own (ADR 0017, shared audio manager). Stems and audio_source sounds share one device, one clock. If there is no audio device the session is skipped with a console notice and everything else in the scene runs.
2. Timing offsets. Measured output latency and tap calibration are read from the newest files under logs/latency/ in the game root. Missing values are announced loudly on the console: run the latency harness for the former and flint calibrate for the latter.
3. Gamepad handoff. The capture thread takes the pad for the session’s duration (ADR 0018, gilrs handoff and InputState downsample). The same event stream is down-sampled into the ordinary InputState so is_action_pressed and friends keep working frame-quantised, with a pulse press released on the next tick so edge detection sees a full down/up pair.
4. Teardown fades the stems over 50 ms and restores the scene’s authored post-processing values.

While a session is active only lean and pulse reach InputState. Every other pad control is dropped inside the capture crate. Keyboard input stays on winit throughout. This is an accepted gap of ADR 0018; design your session scenes so that nothing else needs the pad.

The session ticks once per frame from the player’s frame loop. Each tick drains capture events, judges them, advances coherence, observes the ladder, runs the reintegration sequencer, applies the resolved mixer state, and publishes a ConductedSnapshot for scripts.

Coherence

Everything downstream sees one number in [0, 1] (ADR 0010, coherence model). It is a leaky integrator with asymmetric, bar-denominated time constants: the continuous tracking signal sets a per-step target and the value eases toward it, rising with rise_bars and falling with fall_bars. Judged pulses enter as bounded impulses: a hit nudges up by how clean it was, a miss down by miss_penalty, a spurious pulse by spurious_penalty (default 0, because this is flow, not evaluation). The sway and pressure channels have weights that default to 0, so an unmodified config produces bit-identical values on any chart. All of it is plain f64 arithmetic in a fixed order: same records in, same value out. Every knob is in config/coherence.toml and reloadable mid-session.

The Ladder

The disintegration ladder (ADR 0015, disintegration ladder config) is ordered rungs, each with a coherence threshold and a full description of the degraded state. It is data, config/ladder.toml, hot-reloadable:

schema_version = 0
arm_above = 0.8

[[rungs]]
name = "haze"
enter_below = 0.6
exit_above = 0.7
ramp_ms = 350.0
[rungs.audio]
lpf_hz = 4000.0
thin_db = { texture = -6.0 }
[rungs.visual]
desaturate = 0.3

[[rungs]]
name = "dropout"
enter_below = 0.3
exit_above = 0.45
[rungs.audio]
drop = ["texture"]
warble_depth_semitones = 0.3
warble_rate_hz = 1.5
[rungs.visual]
chromatic = 0.5
blur = 0.4

[full_fail]
enter_below = 0.15
exit_above = 0.25
hold_ms = 1500.0

[seam]
fade_ms = 30.0
rewind_beats = 4.0
rewind_drop_semitones = -30.0
pickup_beats = 2.0
lead_in_beats = 0.0

Rules the ladder keeps:

• Rung parameters are absolute. A deeper rung states the whole degraded state; it does not stack on the rung above.
• Hysteresis is in the thresholds. enter_below is lower than exit_above, so a noisy value at a boundary never flickers the world.
• Protected buses. Only texture, world_voice and harmony can be thinned or dropped. foundation and the two motif buses are never touched by gain or dropout. The low-pass applies to every non-motif bus, foundation included: filtering the whole world is the woozy intent, silencing its pulse is not.
• Arming. The ladder arms only once coherence first reaches arm_above; the world can only come apart after it has first cohered.
• One writer. The resolved LadderParams for the current rung is the single source of truth. The audio half is applied as idempotent Kira tweens on the mixer; the visual half rides on the frame to the post-processing stack.

Full Fail and Reintegration

Below full_fail.enter_below, held for hold_ms, the reintegration sequencer takes over (ADR 0014, reintegration seam mechanism). The state machine is Playing → Failing → Reassembling → Playing:

1. Rewind. For seam.rewind_beats the whole world spins down like a record played backwards, a playback-rate ramp on every stem landing at rewind_drop_semitones, mirrored visually. The gesture is measured in beats so it starts on a beat and ends exactly at the seam.
2. Pickup. In the last pickup_beats before the seam the lead bus plays the re-entry material winding up from the spin-down rate to full speed, arriving on the re-entry downbeat.
3. Seam. On the next reachable bar line the old timeline fades out over fade_ms (an envelope, not a cut) and every stem re-plays sample-locked from the previous re-entry section. The lead motif bus enters at full level; the rest enter at -60 dB. With lead_in_beats above 0 (validated 0..8, default 0) the ensemble re-enters that many beats before the checkpoint downbeat, so the player gets a “3, 4, go” of prep time.
4. Reassembly. Over the manifest’s reassembly_bars the entering buses ramp in and the ladder runs in reverse, lerping from the deepest rung back to clean, so the world re-gathers as one thing.

Coherence is not reset. A player still absent after reassembly fails again, which is the designed loop; only the debounce restarts. Input is never interrupted and the judge is rewound at the seam.

Audio Gradient and Haptics

Two optional drivers sit beside the ladder, both pure evaluators that feed the same single mixer writer:

• Gradient (ADR 0024, error-driven audio gradient; config/gradient.toml). Tune: lean error drives the depth of a zero-mean pitch LFO on one degradable bus, so off the lean the voice wavers and on it the voice settles. Sink: at stick-neutral the mix thins by per-bus gain trims. Scripts are read-only toward audio by design; the gradient never goes through Rhai.
• Haptics (ADR 0026, haptic entrainment architecture; config/haptics.toml). Pre-beat tick, pulse-landing thump, rewind grind, pickup ticks. The driver is event-shaped: it never sees coherence or lean error, because a buzz-when-wrong reads as punishment. Motor writes happen in flint-input-capture’s rumble engine over direct XInput (ADR 0025, rumble spike direct XInput), fired early by a feel-tuned lead.

Post-Processing Integration

The rung’s visual half maps onto three post-processing fields (ADR 0021, post-stack desaturation and blur mapping): blur becomes radial blur scaled by 0.6, chromatic and desaturate map 1:1. Each frame the session writes authored + rung × scale into any slot a script has not overridden, so script overrides win, preroll leaves the world untouched, and a ladder that recovers to clean restores the authored look. The F4 menu’s “Freeze script post overrides” switch stops these stamps so panel edits stick while tuning.

Scripts

A running session publishes a ConductedSnapshot every frame and the conducted_* family in Scripting reads it (ADR 0020, conducted parameters script surface): conducted_lean(), conducted_target(), conducted_next_target(), conducted_next_pulse(), conducted_coherence(), conducted_beat_phase(), conducted_bar(), conducted_section(), conducted_pulses(), conducted_cues(), conducted_desaturate(), conducted_blur(), conducted_chromatic(), conducted_reassembly(), conducted_rewind(), conducted_no_input(), conducted_preroll(). With no session running the snapshot is neutral (coherence and reassembly 1.0, lookaheads effectively infinite), so a script binding 1 - conducted_coherence() to fog shows nothing.

Scripts are read-only toward the session. Nothing in Rhai can change a bus gain, a rung, or the chart.

Recording, Replay and Offline Render

Every judgment is logged, and the input stream can be recorded to logs/sessions/<name>.session.jsonl: one JSON header line (suite, chart, sample rate, both offsets, config snapshots) then one event per line, each stamped with its compensated suite sample. Because the stamp is already musical time, flint replay-chart feeds the identical judgment and coherence code with no clock, no audio and no gamepad, and produces the same numbers. Synthetic profiles (perfect, late:<ms>, neglect) generate a stream from the chart alone. flint render-suite plays a scripted *.events.toml (bus gain, low-pass and detune changes at bar:N, beat:F or sample:N times) through the real scheduler and mixer into a WAV, deterministically.

Debug Surfaces

All of these compile only with the player’s debug-hud cargo feature (on by default) and never ship in the felt experience:

With no gamepad visible, a debug-hud build arms a keyboard fallback (ADR 0064, debug keyboard input fallback): arrow keys are lean, Space is pulse. Prototype verbs only; it is a plumbing check, not a feel surface.

Workflow

The CLI harnesses form a pipeline; each is documented in the Music CLI reference:

1. flint validate-suite cross-checks manifest, chart and stem files.
2. flint play-suite plays the stems sample-locked with a console readout of position and per-bus state.
3. flint calibrate records the player’s median tap offset to logs/latency/.
4. flint play-chart runs the full reactive loop with live capture; --window adds wordless visual cues, --record writes a session file.
5. flint replay-chart re-judges a recorded or synthetic session headlessly.
6. flint render-suite renders a scripted session to WAV for listening tests and automated evidence.

Once the suite plays well in the harness, the music_session component brings the same session into flint play.

Further Reading

• Audio: the two-bus flint-audio mixer the session shares a device with
• Post-Processing: the fields the ladder drives
• Scripting: the conducted_* surface
• Debug Panels: how the Music Guide and Manifest Map fit the panel system

Animation

Flint’s animation system provides two tiers of animation through the flint-animation crate: property tweens for simple transform animations defined in TOML, and skeletal animation for character rigs imported from glTF files with GPU vertex skinning.

Tier 1: Property Animation

Property animations are the simplest form — animate any transform property (position, rotation, scale) or custom float field over time using keyframes. No 3D modeling tool required; clips are defined entirely in TOML.

Animation Clips

Clips are .anim.toml files stored in the demo/animations/ directory:

# animations/door_swing.anim.toml
name = "door_swing"
duration = 0.8

[[tracks]]
interpolation = "Linear"

[tracks.target]
type = "Rotation"

[[tracks.keyframes]]
time = 0.0
value = [0.0, 0.0, 0.0]

[[tracks.keyframes]]
time = 0.8
value = [0.0, 90.0, 0.0]

[[events]]
time = 0.0
event_name = "door_creak"

Interpolation Modes

Track Targets

Each track animates a specific property:

Animation Events

Clips can fire game events at specific times — useful for triggering sounds (footstep at a specific frame), spawning particles, or notifying scripts. Events fire once per loop cycle.

Attaching an Animation

Add an animator component to any entity in your scene:

[entities.platform]
archetype = "furniture"

[entities.platform.transform]
position = [2.0, 0.5, 3.0]

[entities.platform.animator]
clip = "platform_bob"
autoplay = true
loop = true
speed = 1.0

The animation system scans for .anim.toml files at startup and matches clip names to animator components.

Tier 2: Skeletal Animation

For characters and complex articulated meshes, skeletal animation imports bone hierarchies from glTF files and drives them with GPU vertex skinning.

Pipeline

glTF file (.glb)
  ├── Skin: joint hierarchy + inverse bind matrices
  ├── Mesh: positions, normals, UVs, joint_indices, joint_weights
  └── Animations: per-joint translation/rotation/scale channels
         │
         ▼
  ┌──────────────────────┐
  │   flint-import        │  Extract skeleton, clips, skinned vertices
  └──────────┬───────────┘
             │
  ┌──────────▼───────────┐
  │   flint-animation     │  Evaluate keyframes → bone matrices each frame
  └──────────┬───────────┘
             │
  ┌──────────▼───────────┐
  │   flint-render        │  Upload bone matrices → vertex shader skinning
  └──────────────────────┘

How It Works

1. Import — flint-import extracts the skeleton (joint hierarchy, inverse bind matrices) and animation clips (per-joint keyframe channels) from glTF files
2. Evaluate — each frame, flint-animation samples the current clip time to produce local joint poses, walks the bone hierarchy to compute global transforms, and multiplies by inverse bind matrices to get final bone matrices
3. Render — bone matrices are uploaded to a per-entity GPU storage buffer. The skinned vertex shader transforms each vertex by its weighted bone influences. Because each entity owns its buffer, two entities instancing the same skinned asset animate independently: a crowd of the same model no longer shows whichever skeleton uploaded last.

The importer handles all three glTF interpolation modes. CUBICSPLINE samplers store three outputs per timestamp (in_tangent, value, out_tangent) and are consumed as triples; a sampler with fewer than 3 x timestamps outputs warns and degrades to LINEAR. Rotation tracks are also made hemisphere-continuous at clip load: Blender exports adjacent keys as q then -q on large joint rotations, and the Hermite curve between them would collapse through zero and snap the joint. Such keys (value and both tangents) are negated so the curve stays on one side of the sphere.

Skinned Vertices

Skeletal meshes use a separate SkinnedVertex type with 6 attributes (vs. 4 for static geometry), avoiding 32 bytes of wasted bone data on every static vertex in the scene:

Crossfade Blending

Smooth transitions between skeletal clips (e.g., idle to walk) use crossfade blending controlled by the animator component:

[entities.character.animator]
clip = "idle"
playing = true
loop = true
blend_target = "walk"      # Crossfade into this clip
blend_duration = 0.3       # Over 0.3 seconds

Blending uses slerp for rotation quaternions and lerp for translation/scale, producing smooth pose interpolation.

The engine clears blend_target when the crossfade completes. It is a request, not a state — once the fade lands, the field is retired and the clip you faded into becomes the plain clip. Scripts must not treat a non-empty blend_target as “currently blending to X” beyond the fade, and must not re-assert it every frame: a target that never retires re-arms its own crossfade forever, and the clip plays only its first blend_duration seconds on loop.

Calling blend_to with the clip that is already playing is a deliberate restart, not a no-op. That is what lets a held key chain discrete steps — each press re-triggers the same clip from the top.

flint edit <model.glb> plays clips directly and never goes through the blend path, so a clip that previews correctly can still be broken in play. Verify crossfades in flint play.

Animation Layers

Layers run extra clips on their own clocks and compose them onto the base pose, in array order, after any crossfade. Each layer has a weight, a mode, and an optional bone mask:

[entities.starthing.animator]
clip = "WalkCycle"
layers = [
  { clip = "StarCower", weight = 1.0, mode = "additive", mask = "head" },
]

Layer indices run from 0 to 254; the script API silently ignores anything at 255 or above (layer IDs travel as a byte in runtime bookkeeping).

Additive layers contribute each keyed joint’s delta from rest, scaled by weight. They suit overlays authored as “rest plus a gesture” — a breathing chest, the starthing’s cowering star-arms. Override layers blend each keyed joint toward the clip’s pose by weight — “upper body aims while the legs keep walking”, usually paired with a mask like mask = "spine".

Either way a layer only touches joints its clip actually keys (composing identity onto an un-keyed joint would corrupt one whose rest rotation is not identity), and because layers are composed after blending, they survive base crossfades — the character keeps breathing through the transition from idle to walk rather than holding its breath for 0.3 seconds.

Layers are ordered: an additive layer under an override is replaced where the override keys; an additive layer on top of an override adds to it.

The older single-layer fields still work and are treated as layers[0]:

layer_clip = "breathe"     # legacy alias for layers = [{ clip = "breathe", weight = ... }]
layer_weight = 1.0

When layers is non-empty it wins and the legacy pair is ignored. The script API (set_anim_layer & co.) migrates the legacy pair into layers[0] the first time it touches an entity.

Previewing layers

flint edit <model.gltf> has a Layers stack under the timeline: add rows, pick a clip per layer, drag weights (they work while paused), flip Add/Over, choose a mask joint, and solo/mute rows. The Skeleton colour combo under View paints the armature overlay and the node tree:

• Last writer — yellow = base clip, one colour per layer, grey = rest pose
• Ln weight — grey → layer colour by the weight that layer applied
• Ln mask / Ln keyed joints — which bones the mask / clip reaches

Hover a joint in the node tree for a per-layer breakdown. The same setup can be rendered headlessly:

flint edit models/starthing.gltf --render out.png --clip WalkCycle --layer StarCower:1.0:head
# --layer clip[:weight[:mask[:mode]]], repeatable, in order

Layer fades

A layer’s weight is a live dial, so a script that sets it pops the pose. To ramp instead, set fade_target and fade_duration on the layer table (or call fade_anim_layer(entity, index, weight, seconds)). The engine owns the weight while the ramp runs: it writes the ramped value back to layers[i].weight every frame and zeroes fade_duration when it arrives, so the next sync_from_world doesn’t re-arm it — the same contract as blend_target. Any plain set_anim_layer_weight cancels a ramp in flight. The previewer’s Layers row shows → target (seconds left) while a fade runs.

Sequences

A *.sequence.toml is a list of timestamped animator events — everything the script API can do to an animator, written down with times so it can be played, scrubbed and rendered identically in the previewer and the player:

name = "starthing_showcase"
# duration = 6.0   # optional; default = last event time + its transition
loop = false

[[events]]
time = 0.0
kind = "blend"            # crossfade the base clip (duration 0 = hard cut)
clip = "BreathingIdle"
duration = 0.0

[[events]]
time = 1.5
kind = "blend"
clip = "WalkCycle"
duration = 0.4

[[events]]
time = 2.5
kind = "layer"            # set a layer slot; omitted keys keep their value
index = 0
clip = "StarCower"
mode = "additive"
mask = "head"
weight = 1.0
fade = 0.3                # ramp the weight over 0.3 s (omit = instant)

[[events]]
time = 4.0
kind = "speed"
value = 1.3

[[events]]
time = 5.5
kind = "layer"
index = 0
weight = 0.0
fade = 0.4

[[events]]
time = 6.0
kind = "cue"              # named marker for scripts
name = "done"

Event kinds: blend { clip, duration }, layer { index, clip?, weight?, fade, mode?, mask? }, speed { value }, cue { name }. Events are sorted by time (stable, so same-time events keep authored order) and each fires exactly once when the playhead reaches its time. Sequences run before the skeletal tier each frame, so their writes land the same frame.

A looping sequence fires everything up to min(time, duration), then wraps, re-arms every event (including those at t = 0) and fires from zero again, repeating while the frame still overruns. A large dt therefore neither skips events nor delays the next pass by a frame: a 1 s loop with a cue at 0.8 s, advanced by 0.5 then 0.6, fires start, tail, start. A looping sequence whose resolved duration is zero is rejected at load (looping sequence has zero duration); a non-looping one with only t = 0 events fires them and completes on its first advance.

Base-clip changes always go through blend_target (a tracked skeletal entity never re-reads clip); a duration of 0 is clamped to 1 ms because the crossfade path ignores non-positive durations.

Previewing a sequence

flint edit models/starthing.gltf --sequence animations/starthing_showcase.sequence.toml
flint edit models/starthing.gltf --sequence animations/starthing_showcase.sequence.toml \
    --render t3.png --anim-time 3.0        # headless: pose at t = 3 s

The bottom panel gains a Sequence section: play/pause (P), Restart (R / Home), a Loop toggle (--sequence-loop sets it from the CLI; ticking it after the end restarts), a seek slider, and a marker strip with one tick per event (orange = blend, layer colour = layer, grey = speed, cyan = cue; dim = not yet fired; hover for details, click to seek). Seeking and --anim-time both replay the sequence from t = 0 in 1/120 s steps after restoring the animator to its pre-sequence state, so the pose at any time is deterministic — rendering the same --anim-time twice yields identical pixels. Cues fired during playback print [sequence] cue '<name>' at <t>s.

Sequences at runtime

The player loads every *.sequence.toml from the scene’s animations/ directory (or ../animations/) and registers it by name. Scripts start one with play_sequence(entity, name) and stop it with stop_sequence(entity); both just write animator.sequence, so a scene can also autoplay one:

[entities.hero.animator]
clip = "Idle"
playing = true
sequence = "intro_bow"

When a non-looping sequence ends the engine clears animator.sequence, so play_sequence with the same name is a fresh start. Cues reach the owning entity’s script:

#![allow(unused)]
fn main() {
fn on_sequence_cue(sequence, cue) {
    if cue == "done" { play_sequence(self_entity(), "idle_loop"); }
}
}

Rest Poses

Pose buffers are seeded from the glTF bind-local TRS, not from identity. This matters for sparse clips: a clip that keys only an arm would otherwise collapse every un-keyed limb onto its parent, and your character would fold up the moment it played.

Skeleton Schema

The skeleton component references a glTF skin:

[entities.character.skeleton]
skin = "Armature"           # Name of the glTF skin

Entities with both animator and skeleton components use the skeletal animation path. Entities with only animator use property tweens.

Animator Schema

The animator component controls playback for both tiers:

Architecture

• AnimationPlayer — clip registry and per-entity playback state for property tweens
• AnimationSync — bridges ECS animator components to property animation playback, auto-discovers new entities each frame
• SkeletalSync — bridges ECS to skeletal animation, manages per-entity skeleton state and bone matrix computation
• AnimationSystem — top-level RuntimeSystem implementation that ticks both tiers

Animation runs in update() (variable-rate), not fixed_update(), because smooth interpolation benefits from matching the rendering frame rate rather than the physics tick rate.

Scripting Integration

Animations can be controlled from Rhai scripts by writing directly to the animator component. The AnimationSync system picks up changes on the next frame:

#![allow(unused)]
fn main() {
// In a Rhai script:
fn on_interact() {
    let me = self_entity();
    play_clip(me, "door_swing");
}

fn on_init() {
    let me = self_entity();
    blend_to(me, "idle", 0.3);  // Smooth transition to idle
}
}

Further Reading

• Scripting — full scripting API including animation functions
• Audio — audio system that responds to animation events
• Rendering — the skinned mesh GPU pipeline
• Physics and Runtime — the game loop that drives animation
• File Formats — .anim.toml format reference

Terrain

Flint’s terrain system provides heightmap-based outdoor environments via the flint-terrain crate. Rolling hills, mountains, valleys, and open landscapes are defined by a grayscale heightmap image and textured with up to four blended surface layers controlled by an RGBA splat map.

How It Works

A single terrain component on an entity defines the entire terrain surface:

Heightmap PNG          flint-terrain              flint-render
  grayscale    ──►  Chunked mesh generation  ──►  TerrainPipeline
  257x257           positions/normals/UVs          PBR lighting
                    triangle indices               splat-map blending
                                                   cascaded shadows

Splat Map PNG                                    flint-physics
  RGBA channels  ──►  4-layer texture blend      Rapier trimesh
  R=grass G=dirt       tiled from world pos       collision collider
  B=rock  A=sand

The heightmap is a grayscale PNG (8-bit or 16-bit) where black is the lowest point and white is the highest. The terrain is divided into chunks for efficient rendering — each chunk is an independent draw call with its own vertex and index buffers.

Adding Terrain to a Scene

Create an entity with the terrain archetype:

[entities.ground]
archetype = "terrain"

[entities.ground.transform]
position = [-128, 0, -128]

[entities.ground.terrain]
heightmap = "terrain/heightmap.png"
splat_map = "terrain/splatmap.png"
layer0_texture = "terrain/grass.png"
layer1_texture = "terrain/dirt.png"
layer2_texture = "terrain/rock.png"
layer3_texture = "terrain/sand.png"
width = 256.0
depth = 256.0
height_scale = 50.0
texture_tile = 16.0

The transform.position sets the world-space origin of the terrain. The heightmap is placed starting at that position, extending width units along X and depth units along Z. Heights range from 0 to height_scale units along Y.

Heightmap

The heightmap is a grayscale PNG image. Each pixel encodes a height value:

• 8-bit grayscale — 256 height levels
• 16-bit grayscale — 65,536 height levels (recommended for large terrains)

The heightmap resolution determines mesh detail. A 257x257 image with chunk_resolution = 64 produces a 4x4 grid of chunks, each with 65x65 vertices (16,641 vertices per chunk, 24,576 triangles per chunk).

Heights are sampled with bilinear interpolation for smooth surfaces, even with lower-resolution heightmaps.

Creating Heightmaps

Any image editor that outputs grayscale PNGs works. Common approaches:

• Photoshop/GIMP — paint or use noise filters, export as grayscale PNG
• World Machine / Gaea — procedural terrain generation tools
• Python + Pillow — generate programmatically with noise functions
• Real-world data — USGS elevation data converted to grayscale

The dimensions should ideally be (N * chunk_resolution) + 1 for clean chunk boundaries (e.g., 257, 513, 1025).

Splat Map

The splat map is an RGBA PNG that controls how four texture layers blend across the terrain surface:

At each pixel, the RGBA weights are normalized so they always sum to 1.0. A pixel with (255, 0, 0, 0) shows pure grass; (128, 128, 0, 0) shows a 50/50 grass-dirt blend.

If no splat map is provided, the terrain uses the default white texture uniformly.

Creating Splat Maps

Splat maps can be painted manually in any image editor that supports RGBA channels, or generated algorithmically based on height and slope:

• Low flat areas — grass (red channel)
• Mid elevations — dirt (green channel)
• Steep slopes / high peaks — rock (blue channel)
• Very low areas — sand (alpha channel)

Texture Tiling

Layer textures are tiled across the terrain surface based on world position, not the terrain UV. The texture_tile field controls how many times the texture repeats per 100 world units:

Higher values produce finer detail but may show visible tiling at a distance. Future updates will add detail textures and triplanar mapping to mitigate this.

Component Schema

Grass

Terrain can carry a GPU-instanced grass layer. Blades are scattered by a compute shader, drawn as crossed quads with wind sway and bend-on-contact, and cast into the two nearest shadow cascades. Nothing is authored by hand: density comes from the splat map, so grass grows exactly where the grass layer is painted.

The Rolling Meadow demo: stylised grass driven by the splat map’s red channel, with golden-hour lighting.

Grass is a block of dotted keys on the same terrain component:

[entities.ground.terrain]
heightmap = "terrain/heightmap.png"
splat_map = "terrain/splatmap.png"
width = 384.0
depth = 384.0
"grass.enabled" = true
"grass.density" = 50.0
"grass.max_distance" = 100.0
"grass.fade_start" = 70.0
"grass.blade_height" = 0.43
"grass.color_base" = [0.12, 0.42, 0.08]
"grass.color_tip" = [0.35, 0.72, 0.18]
"grass.wind_direction" = [0.8, 0.0, 0.6]
"grass.wind_strength" = 0.09

How it works, per frame:

1. A compute pass walks a grid whose spacing is 1 / sqrt(density), samples the splat map’s density_layer at each cell, skips cells under density_threshold, applies a probabilistic falloff between fade_start and max_distance, and writes a 32-byte instance (position on the heightmap, rotation, height scale, packed tint) into a storage buffer.
2. A render pass draws one shared blade mesh per instance. The vertex shader sways blades by a time-driven wind term and pushes them away from up to eight entity positions within bend_radius; the fragment shader blends color_base to color_tip along the blade, mixes in color_dry, and shades with the same lighting levers and PCSS shadows as other geometry. The player feeds the camera position as the bend entity.
3. The shadow pass renders the instances into the nearest two cascades, so grass darkens the ground under it.

The pipeline participates in MSAA when the player runs with --msaa 4, and grass appears in flint render snapshots at time zero, so the wind is frozen but the field is fully populated.

The Grass Debug panel (F3 in the player, see Debug Panels) exposes every field above live and can commit them back to the scene file, which is how the meadow demo’s numbers were found.

Physics Collision

Terrain automatically gets a trimesh physics collider via Rapier. The mesh geometry is exported as vertices and triangle indices, then registered as a fixed (immovable) rigid body. This means:

• Characters walk on the terrain surface naturally
• Objects collide with the terrain
• Raycasts hit the terrain for line-of-sight checks

The collider shape exactly matches the rendered mesh, so what you see is what you collide with.

Height Sampling from Scripts

The terrain_height(x, z) function is available in Rhai scripts to query the terrain height at any world position:

#![allow(unused)]
fn main() {
fn on_update() {
    let me = self_entity();
    let pos = get_position(me);

    // Get terrain height at entity's XZ position
    let ground_y = terrain_height(pos.x, pos.z);

    // Snap entity to terrain surface
    set_position(me, pos.x, ground_y + 0.5, pos.z);
}
}

This is useful for:

• NPC placement — keep characters on the ground
• Projectile impact — detect when a projectile hits terrain
• Camera clamping — prevent the camera from going below ground
• Vegetation scattering — place objects at correct heights

The function uses bilinear interpolation on the heightmap data, matching the rendered surface exactly. It returns 0.0 if no terrain is loaded.

Rendering

Terrain uses its own TerrainPipeline with full PBR lighting — the same Cook-Torrance BRDF, cascaded shadow maps, point lights, and spot lights as regular scene geometry. Terrain both casts and receives shadows.

The rendering order places terrain early in the pass (after the skybox, before entity geometry) to fill the depth buffer for efficient occlusion culling of objects behind hills.

When post-processing is active, the terrain outputs linear HDR values like all other scene geometry. The composite pass handles tonemapping, bloom, fog, and other effects.

Scene Transitions

Terrain is fully cleared and reloaded during scene transitions. When load_scene() is called:

1. Current terrain draw calls and physics collider are removed
2. New scene is loaded
3. New terrain (if any) is generated, uploaded to GPU, and registered with physics
4. The terrain_height() callback is updated to use the new heightmap

Architecture

The terrain system is split across crates to maintain clean dependency boundaries:

• flint-terrain — pure data crate (no GPU dependency). Generates chunked mesh geometry from heightmap data. Outputs raw positions, normals, UVs, and indices.
• flint-render — TerrainPipeline and terrain_shader.wgsl. Assembles GPU vertex buffers from terrain data, handles splat-map texture blending and PBR lighting. GrassPipeline with grass_compute.wgsl and grass_render.wgsl owns the grass layer; flint-terrain only holds its GrassConfig.
• flint-physics — reuses existing register_static_trimesh() for collision. No terrain-specific physics code needed.
• flint-script — terrain_height(x, z) Rhai function via callback pattern.

This separation means flint-terrain can be used independently for tools, CLI commands, or headless processing without pulling in the GPU stack.

Limitations

• One terrain per scene — currently only the first terrain entity is loaded
• No mesh LOD — all chunks render at full resolution regardless of distance (chunks outside the camera frustum are culled; grass thins with distance)
• No runtime deformation — terrain is static after loading
• CPU-side simulation — no GPU compute for terrain generation
• Fixed PBR parameters — metallic and roughness are uniform across the entire terrain surface

See the Terrain Roadmap for planned features including LOD, sculpting, auto-splatting, triplanar mapping, and more.

Further Reading

• Rendering — the PBR pipeline that terrain builds on
• Post-Processing — bloom, fog, and SSAO that apply to terrain
• Physics and Runtime — the collision system terrain integrates with
• Scripting — terrain_height() and other script APIs
• Schemas — component and archetype definitions

Particles

Flint’s particle system provides GPU-instanced visual effects through the flint-particles crate. Fire, smoke, sparks, dust motes, magic effects — any volumetric visual that needs hundreds or thousands of small, short-lived elements.

Note: Particle effects are dynamic simulations that accumulate over time. Use flint play to see them in action — headless flint render captures a single frame and won’t show accumulated particles.

How It Works

Each entity with a particle_emitter component owns a pool of particles simulated on the CPU and rendered as camera-facing quads via GPU instancing. The pipeline is:

TOML component                CPU simulation              GPU rendering
particle_emitter   ──►  ParticleSync reads config  ──►  ParticlePipeline
  emission_rate         spawn/integrate/kill             instanced draw
  gravity               pack into instance buffer        storage buffer
  color_start/end       (swap-remove pool)               alpha or additive

Unlike billboard sprites (which are individual ECS entities), particles are pooled per-emitter — a single entity can own thousands of particles without overwhelming the ECS.

Adding Particles to a Scene

Add a particle_emitter component to any entity:

[entities.campfire]
[entities.campfire.transform]
position = [0, 0.2, 0]

[entities.campfire.particle_emitter]
emission_rate = 40.0
max_particles = 200
lifetime_min = 0.3
lifetime_max = 0.8
speed_min = 1.5
speed_max = 3.0
direction = [0, 1, 0]
spread = 20.0
gravity = [0, 2.0, 0]
size_start = 0.15
size_end = 0.02
color_start = [1.0, 0.7, 0.1, 0.9]
color_end = [1.0, 0.1, 0.0, 0.0]
blend_mode = "additive"
shape = "sphere"
shape_radius = 0.15
autoplay = true

Emission Shapes

The shape field controls where new particles spawn relative to the emitter:

Every shape is translated by shape_offset before the emitter position is applied, so a trail can spawn a little behind the entity that owns it.

Oriented Boxes

A box emitter can be rotated without rotating the entity (ADR 0061, prologue flight trails). shape_extents.x runs along shape_axis_u, shape_extents.y along shape_axis_v, and shape_extents.z along their cross product. The two axes are normalised and orthogonalised for you; if either is zero, or they are parallel, the box falls back to axis-aligned. Because both axes are live fields, a script can point the spawn slab along an entity’s lateral motion every frame:

fn on_update() {
    let me = self_entity();
    let p = get_position(me);
    let last = get_field(me, "trail_state", "last_pos");   // your own component
    let dx = p.x - last.x;
    let dz = p.z - last.z;
    if dx * dx + dz * dz > 0.0001 {
        set_field(me, "particle_emitter", "shape_axis_u", [dx, 0.0, dz]);
    }
    set_field(me, "trail_state", "last_pos", #{ x: p.x, y: p.y, z: p.z });
}

Blend Modes

Additive blending is order-independent, making it ideal for dense effects. Alpha blending looks best for soft, diffuse effects.

Value Over Lifetime

Particles interpolate linearly between start and end values over their lifetime:

• size_start / size_end — particles can grow (smoke expanding) or shrink (sparks dying)
• color_start / color_end — RGBA transition. Set color_end alpha to 0 for fade-out

Sprite Sheet Animation

For textured particles (flame sprites, explosion frames), use sprite sheets:

[entities.explosion.particle_emitter]
texture = "explosion_sheet.png"
frames_x = 4
frames_y = 4
animate_frames = true   # Auto-advance frames over particle lifetime

With animate_frames = true, each particle plays through the sprite sheet from birth to death.

Bursts and Duration

For one-shot effects (explosions, impacts), combine bursts with limited duration:

[entities.explosion.particle_emitter]
emission_rate = 0.0      # No continuous emission
burst_count = 50         # 50 particles on each burst
duration = 0.5           # Emitter runs for 0.5 seconds
looping = false          # Don't repeat
autoplay = true          # Fire immediately

For periodic bursts (fountain, heartbeat), set looping = true with a duration.

Component Schema

Live Fields

The particle system re-reads the component every frame, so a script can retune a running emitter with set_field. These fields take effect on the next frame without restarting the emitter:

emission_rate, gravity, damping, size_start, size_end, color_start, color_end, blend_mode, texture, direction, spread, speed_min, speed_max, lifetime_min, lifetime_max, stretch, shape, shape_offset, shape_axis_u, shape_axis_v.

Everything else (max_particles, the sprite-sheet layout, duration, looping, world_space) is read when the emitter is created. Changing playing or autoplay starts or stops it, and a start resets the emitter clock.

Scripting Integration

Particles can be controlled from Rhai scripts:

#![allow(unused)]
fn main() {
// Rhai script: burst of sparks on impact
fn on_collision() {
    let me = self_entity();
    emit_burst(me, 30);
}

// Rhai script: toggle emitter with interaction
fn on_interact() {
    let me = self_entity();
    let playing = get_field(me, "particle_emitter", "playing");
    if playing {
        stop_emitter(me);
    } else {
        start_emitter(me);
    }
}
}

Architecture

• ParticlePool — swap-remove array for O(1) particle death, contiguous alive iteration
• ParticleSync — bridges ECS particle_emitter components to the simulation, auto-discovers new emitters each frame
• ParticleSystem — top-level RuntimeSystem that ticks simulation in update() (variable-rate, not fixed-step)
• ParticlePipeline — wgpu render pipeline with alpha and additive variants, storage buffer for instances

The particle system runs after animation (emitter transforms may be animated) and before the renderer refresh. Instance data is packed contiguously and uploaded to a GPU storage buffer for efficient instanced drawing.

Recipes

Fire

emission_rate = 40.0
gravity = [0, 2.0, 0]
color_start = [1.0, 0.7, 0.1, 0.9]
color_end = [1.0, 0.1, 0.0, 0.0]
blend_mode = "additive"
shape = "sphere"
shape_radius = 0.15

Smoke

emission_rate = 8.0
gravity = [0, 0.5, 0]
damping = 0.3
size_start = 0.1
size_end = 0.6
color_start = [0.4, 0.4, 0.4, 0.3]
color_end = [0.6, 0.6, 0.6, 0.0]
blend_mode = "alpha"

Sparks

emission_rate = 15.0
speed_min = 3.0
speed_max = 6.0
spread = 45.0
gravity = [0, -9.81, 0]
size_start = 0.03
size_end = 0.01
color_start = [1.0, 0.9, 0.3, 1.0]
color_end = [1.0, 0.3, 0.0, 0.0]
blend_mode = "additive"

Dust Motes

emission_rate = 5.0
speed_min = 0.05
speed_max = 0.2
spread = 180.0
gravity = [0, 0.02, 0]
damping = 0.5
size_start = 0.02
size_end = 0.02
color_start = [1.0, 1.0, 0.9, 0.5]
color_end = [1.0, 1.0, 0.9, 0.0]
shape = "box"
shape_extents = [2.0, 1.0, 2.0]

Rain

Rain is the case stretch exists for. A camera-facing quad makes rain look like falling confetti; a velocity-aligned one makes it look like rain.

emission_rate = 4000.0
lifetime = 1.2
gravity = [0.6, -14.0, 0.0]      # tilt X/Z to slant with the wind
speed_min = 0.0
speed_max = 0.5
size_start = 0.012
size_end = 0.012
color_start = [0.72, 0.78, 0.86, 0.5]
color_end = [0.72, 0.78, 0.86, 0.0]
texture = "textures/rain_drop.png"
stretch = 0.03                   # elongate along on-screen motion
shape = "box"
shape_extents = [14.0, 0.5, 14.0]
world_space = true

stretch is in seconds: the quad elongates along its on-screen motion by |velocity| * stretch, so faster drops draw longer streaks with no extra authoring. Keep it small — 0.03 already reads as heavy rain, and large values smear particles into ribbons.

Practical notes:

• Attach the emitter to something that follows the camera and reposition it each frame. Rain only needs to exist where it can be seen.
• Budget properly: emission_rate × lifetime is roughly how many are alive. The example is ~4800, under the 6000 cap.
• Slant the fall by tilting the gravity vector rather than by giving particles horizontal velocity — it stays coherent as gusts change.
• Particles are unlit. Dim color_start/color_end to match your scene’s light, or night rain will glow.

Particle textures are resolved against the scene directory first, then its parent, and are loaded at scene load.

Further Reading

• Scripting — full scripting API including particle functions
• Animation — animate emitter transforms with property tweens
• Rendering — the GPU pipeline that draws particles
• Physics and Runtime — the game loop that drives particle simulation

Physics and Runtime

Flint’s runtime layer transforms static scenes into interactive, playable experiences. The flint-runtime crate provides the game loop infrastructure, and flint-physics integrates the Rapier 3D physics engine for collision detection and character movement.

The Game Loop

The game loop uses a fixed-timestep accumulator pattern. Physics simulation steps at a constant rate (1/60s by default) regardless of how fast or slow the rendering runs. This ensures deterministic behavior across different hardware.

The loop structure:

1. Tick the clock — advance time, accumulate delta into the physics budget
2. Process input — read keyboard and mouse state into InputState
3. Fixed-step physics — while enough time has accumulated, step the physics simulation
4. Character controller — apply player movement based on input and physics state
5. Update audio — sync listener position to camera, process trigger events, update spatial tracks
6. Advance animation — tick property tweens and skeletal playback, write updated transforms to ECS, upload bone matrices to GPU
7. Run scripts — execute Rhai scripts (on_update, event callbacks), process deferred commands (audio, events)
8. Render — draw the frame with the current entity positions, HUD overlay (crosshair, interaction prompts)

The RuntimeSystem trait provides a standard interface for systems that plug into this loop. Physics, audio, animation, and scripting each implement RuntimeSystem with initialize(), fixed_update(), update(), and shutdown() methods.

Physics with Rapier 3D

The flint-physics crate wraps Rapier 3D and bridges it to Flint’s TOML-based component system:

• PhysicsWorld — manages Rapier’s rigid body set, collider set, and simulation pipeline
• PhysicsSync — reads rigidbody and collider components from entities and creates corresponding Rapier bodies. Static bodies for world geometry (walls, floors, furniture), kinematic bodies for the player.
• CharacterController — kinematic first-person movement with gravity, jumping, ground detection, and sprint

Physics Schemas

Three component schemas define physics properties:

Rigidbody (rigidbody.toml) — determines how an entity participates in physics:

• body_type: "static" (immovable world geometry), "dynamic" (simulated), or "kinematic" (script-controlled)
• mass, gravity_scale

Collider (collider.toml) — defines the collision shape:

• shape: "box", "sphere", or "capsule"
• size: dimensions of the collision volume
• friction: surface friction coefficient

Character Controller (character_controller.toml) — first-person movement parameters:

• move_speed, jump_force, height, radius, camera_mode

The player archetype (player.toml) bundles these together with a transform for a ready-to-use player entity.

Adding Physics to a Scene

To make a scene playable, add physics components to entities:

# The player entity
[entities.player]
archetype = "player"

[entities.player.transform]
position = [0, 1, 0]

[entities.player.character_controller]
move_speed = 6.0
jump_force = 7.0

# A wall with a static collider
[entities.north_wall]
archetype = "wall"

[entities.north_wall.transform]
position = [0, 2, -10]

[entities.north_wall.collider]
shape = "box"
size = [20, 4, 0.5]

[entities.north_wall.rigidbody]
body_type = "static"

Then play the scene:

flint play my_scene.scene.toml

Raycasting

The physics system provides raycasting for line-of-sight checks, hitscan weapons, and interaction targeting. PhysicsWorld::raycast() casts a ray through the Rapier collision world and returns the first hit:

#![allow(unused)]
fn main() {
pub struct EntityRaycastHit {
    pub entity_id: EntityId,
    pub distance: f32,
    pub point: [f32; 3],
    pub normal: [f32; 3],
}
}

The function resolves Rapier collider handles back to Flint EntityIds through the collider-to-entity map maintained by PhysicsSync. An optional exclude_entity parameter lets callers exclude a specific entity (typically the shooter) from the results.

Raycasting is exposed to scripts via the raycast() function — see Scripting: Physics API for the script-level interface and examples.

Input System

The InputState struct provides a config-driven, device-agnostic input layer. It tracks keyboard, mouse, and gamepad state each frame and evaluates logical actions from physical bindings.

How It Works

All input flows through a unified Binding model:

• Keyboard keys (Key { code }) — any winit KeyCode name (e.g., "KeyW", "Space", "ShiftLeft")
• Mouse buttons (MouseButton { button }) — "Left", "Right", "Middle", "Back", "Forward"
• Mouse delta (MouseDelta { axis, scale }) — raw mouse movement for camera look
• Mouse wheel (MouseWheel { axis, scale }) — scroll wheel input
• Gamepad buttons (GamepadButton { button, gamepad }) — any gilrs button name (e.g., "South", "RightTrigger")
• Gamepad axes (GamepadAxis { axis, gamepad, deadzone, scale, invert, threshold, direction }) — analog sticks and triggers with full processing pipeline

Actions have two kinds:

• Button — discrete on/off (pressed/released). Any binding value >= 0.5 counts as pressed.
• Axis1d — continuous analog value. All binding values are summed.

Input Configuration Files

Bindings are defined in TOML files with a layered loading model:

version = 1
game_id = "doom_fps"

[actions.move_forward]
kind = "button"
[[actions.move_forward.bindings]]
type = "key"
code = "KeyW"
[[actions.move_forward.bindings]]
type = "gamepad_axis"
axis = "LeftStickY"
direction = "negative"
threshold = 0.35
gamepad = "any"

[actions.fire]
kind = "button"
[[actions.fire.bindings]]
type = "mouse_button"
button = "Left"
[[actions.fire.bindings]]
type = "gamepad_button"
button = "RightTrigger"
gamepad = "any"

[actions.look_x]
kind = "axis1d"
[[actions.look_x.bindings]]
type = "mouse_delta"
axis = "x"
scale = 2.0
[[actions.look_x.bindings]]
type = "gamepad_axis"
axis = "RightStickX"
deadzone = 0.15
scale = 1.0
gamepad = "any"

Config Layering

Configs are loaded with deterministic precedence (later layers override earlier):

1. Engine built-in defaults — hardcoded WASD + mouse baseline (always present)
2. Game default config — <game_root>/config/input.toml (checked into the repo)
3. User overrides — ~/.flint/input_{game_id}.toml (per-player remapping, written at runtime)
4. CLI override — --input-config <path> flag (one-off testing/debugging)

Scenes can also reference an input config via the input_config field in the [scene] table.

Default Action Bindings

When no config files are present, the built-in defaults provide:

Games can define any number of custom actions in their config files. Scripts access them with is_action_pressed("custom_action").

Gamepad Support

Gamepad input is handled via the gilrs crate. The player polls gamepad events each frame and routes them through the same binding system as keyboard/mouse:

• Buttons are matched by gilrs Debug names: South, East, North, West, LeftTrigger, RightTrigger, DPadUp, etc.
• Axes support deadzone filtering, scale, invert, and optional threshold for button-like behavior
• Multi-gamepad is supported via GamepadSelector::Any (first match) or GamepadSelector::Index(n) (specific controller)
• Disconnected gamepads are automatically cleaned up

Runtime Rebinding

Bindings can be remapped at runtime through the rebind_action() API:

1. Call begin_rebind_capture(action, mode) to enter capture mode
2. The next physical input (key press, mouse click, or gamepad button/axis) becomes the new binding
3. The mode determines conflict resolution:
   • Replace — clear all existing bindings, set the new one
   • Add — append to the binding list (allows multiple inputs for one action)
   • Swap — remove this binding from any other action, assign to target
4. User overrides are automatically saved to ~/.flint/input_{game_id}.toml

Runtime Physics Updates

The physics system handles several runtime updates beyond the core simulation:

• Sensor flag updates — when game logic marks an entity as dead, its collider can be set to a sensor (non-solid) so other entities pass through it
• Kinematic body sync — script-controlled position changes are written back to Rapier kinematic bodies each frame
• Collision event drain — the ChannelEventCollector collects collision and contact events each physics step; these are drained and dispatched as script callbacks (on_collision, on_trigger_enter, on_trigger_exit)

Further Reading

• Scripting — Rhai scripting system for game logic
• Audio — spatial audio with Kira
• Animation — property tweens and skeletal animation
• Rendering — the PBR rendering pipeline
• Schemas — component and archetype definitions including physics schemas
• CLI Reference — the play command and player binary

Scripting

Flint’s scripting system provides runtime game logic through Rhai, a lightweight embedded scripting language. Scripts can read and write entity data, respond to game events, control animation and audio, and hot-reload while the game is running.

Overview

The flint-script crate integrates Rhai into the game loop:

• ScriptEngine — compiles and runs .rhai scripts, manages per-entity state (scope, AST, callbacks)
• ScriptSync — discovers entities with script components, handles hot-reload by watching file timestamps
• ScriptSystem — implements RuntimeSystem for game loop integration, running in update() (variable-rate)

Scripts run each frame during the update() phase, after physics and before rendering. This gives them access to the latest physics state while allowing their output to affect the current frame’s visuals.

Script Component

Attach a script to any entity with the script component:

[entities.my_door]
archetype = "door"

[entities.my_door.script]
source = "door_interact.rhai"
enabled = true

Script files live in the scripts/ directory next to your scene file.

Event Callbacks

Scripts define behavior through callback functions. The engine detects which callbacks are defined in each script’s AST and only calls those that exist:

The on_interact callback is sugar for the common pattern of proximity-based interaction. It automatically checks the entity’s interactable component for range (default 3.0) and enabled (default true) before firing.

API Reference

All functions are available globally in every script. Entity IDs are passed as i64 (Rhai’s native integer type).

Entity API

Input API

Action names are defined by input configuration files and are fully customizable per game. The built-in defaults include: move_forward, move_backward, move_left, move_right, jump, interact, sprint, weapon_1, weapon_2, reload, fire. Games can define arbitrary custom actions in their input config TOML files and query them from scripts with is_action_pressed("custom_action").

Input bindings support keyboard, mouse, and gamepad devices. See Physics and Runtime: Input System for the config file format and layered loading model.

Time API

Audio API

Audio functions produce deferred commands that the player processes after the script update phase:

Sound names match the audio files loaded from the audio/ directory (without extension). A one-shot naming a file that is not there fails silently — it logs a warning and plays nothing.

Varying pitch slightly per trigger (say 0.9–1.1) is the cheapest way to stop a repeated one-shot sounding like a repeated one-shot.

Spatial one-shot tracks attenuate to silence at 25 m. An event further away than that must use non-spatial play_sound with a hand-scaled volume, or it will simply not be heard.

Animation API

Animation functions write directly to the animator component on the target entity. The AnimationSync system picks up changes on the next frame:

Weights are floats — write 0.5, never 0 (Rhai does not coerce ints).

Coordinate System

Flint uses a Y-up, right-handed coordinate system:

• Forward = -Z (into the screen)
• Right = +X
• Up = +Y

Euler angles are stored as (pitch, yaw, roll) in degrees, applied in ZYX order. Positive yaw rotates counter-clockwise when viewed from above (i.e., turns left).

Use the direction helpers (forward_from_yaw, right_from_yaw) to convert a yaw angle into a world-space direction vector. These encode the coordinate convention so scripts don’t need to compute the trig manually.

Math API

Ocean API

Available when the scene has an ocean component. All coordinates are world-space; all queries are evaluated on the same clock the renderer used this frame, so what you sample is what is on screen.

// Float a hull on five probe points.
let p = get_field(me, "transform", "position");
let h = ocean_height(p.x, p.z);

ocean_velocity_y is the impact signal: the relative approach speed between water and hull is what distinguishes a lap from a slam. Without a scene ocean these return 0 (and #{0,1,0}) rather than failing.

A handful of probes per frame is cheap. Thousands are not.

Input and Cursor API

any_input_just_pressed reads raw presses and bypasses action maps entirely — it is for “press any key to continue”, where the whole point is that you do not care which key.

set_cursor_captured(true) is how a scene gets mouse-look without a character-controller player entity. The engine only captures automatically for scenes that have one, so a fixed-camera or custom-camera scene must ask.

Event API

Log API

Physics API

Physics functions provide raycasting and camera access for combat, line-of-sight checks, and interaction targeting:

The raycast() function automatically excludes the calling entity’s collider from results. On a hit, it returns a map with these fields:

move_character performs collision-corrected kinematic movement using Rapier’s shape-sweep. The entity must have rigidbody and collider components. The returned map contains the corrected position and a grounded flag:

#![allow(unused)]
fn main() {
fn on_update() {
    let me = self_entity();
    let dt = delta_time();
    let result = move_character(me, 0.0, -9.81 * dt, 5.0 * dt);
    if result != () {
        set_position(me, result.x, result.y, result.z);
        if result.grounded {
            // Can jump
        }
    }
}
}

get_collider_extents returns the collider shape dimensions. The returned map varies by shape:

• Box: #{shape: "box", half_x, half_y, half_z}
• Capsule: #{shape: "capsule", radius, half_height}
• Sphere: #{shape: "sphere", radius}

Returns () if the entity has no collider.

Example: Hitscan weapon

#![allow(unused)]
fn main() {
fn fire_weapon() {
    let cam_pos = get_camera_position();
    let cam_dir = get_camera_direction();
    let hit = raycast(cam_pos.x, cam_pos.y, cam_pos.z,
                      cam_dir.x, cam_dir.y, cam_dir.z, 100.0);
    if hit != () {
        let target = hit.entity;
        if has_component(target, "health") {
            let hp = get_field(target, "health", "current_hp");
            set_field(target, "health", "current_hp", hp - 25);
        }
    }
}
}

2D Physics

For sprite games the physics world is a flat plane. These mirror the 3D calls above:

2D Camera

A follow camera with deadzone and smoothing, plus a stackable shake. All positions are world units on the sprite plane; the camera sits at z = 10 looking down -z so every sprite layer stays in front of it.