# Cairn

> Cairn is a 3D game engine in C++20 on Vulkan, with an editor, Lua or TypeScript scripting, physics, audio, and a command interface for AI agents.

## Blog

- [Blog](/blog/index.md): Posts about building Cairn, a 3D game engine for people and AI agents.
- [Zombie Survival in the browser: Cairn's first web export](/blog/zombie-survival-web-export.md): Cairn now exports 3D games to the web. Zombie Survival, built in Cairn, runs in the browser on WebGL2 from an 8.5 MB zip on itch.io. Play it and see how it works.

## Releases

- [Releases](/releases/index.md): What changed in Cairn, the 3D game engine, release by release: web export, Box3D physics, TypeScript scripting, the editor redesign and every milestone before.

## Others

- [Command reference](/agents/commands.md): Every JSON command an AI agent or program can send to the Cairn editor, with its parameters: scenes, entities, assets, play mode and export.
- [Examples](/agents/examples.md): Worked examples of driving the Cairn editor with JSON commands: build a level, add scripts, play the game and take screenshots, all without a window.
- [Agent overview](/agents/index.md): How AI agents and programs drive the Cairn game engine: every editor action is a JSON command, sent from a file, a local server or the command line.
- [Templates](/agents/templates.md): How Cairn project templates work: files to copy and agent commands that build the scene, and how to make a template of your own.
- [Testing a game](/agents/testing.md): Test a Cairn game the way a player plays it: press keys with input.set, run frames with play.run and check the result with lua.run.
- [Assets](/guide/editor/assets.md): The Cairn editor's Assets panel: browse project files, import models and textures, make materials and scripts, and rename or move assets safely.
- [Components](/guide/editor/components.md): Every built-in component in the Cairn game engine, from Transform to UI Element, with a picture of each and what every field does.
- [Console and history](/guide/editor/console-and-history.md): The Cairn editor's console shows logs and script errors, and its history lists every change so you can undo back to any step.
- [Debugging](/guide/editor/debugging.md): Find bugs in a Cairn game: read errors in the console, print values, draw debug lines, pause and step frames, and inspect the running scene.
- [Exporting a game](/guide/editor/export.md): Export a Cairn project as a standalone game for macOS, Windows or Linux, or as a web game for itch.io: the runtime and one pack file, with no editor code inside.
- [Hierarchy](/guide/editor/hierarchy.md): The Cairn editor's hierarchy: make, rename, reorder and parent entities, switch them off, search a big scene and expand or collapse the tree.
- [The project hub](/guide/editor/hub.md): The Cairn project hub: open recent projects, start a new one from a template, try the sample games and find the tutorials.
- [Inspector](/guide/editor/inspector.md): The Cairn editor's inspector: edit an entity's components and script fields, add components, edit materials and tune render settings.
- [The interface](/guide/editor/interface.md): A map of the Cairn editor window: top bar, viewport, hierarchy, inspector, assets, console, history and status bar, with a page for each.
- [Performance](/guide/editor/performance.md): Measure a Cairn game's speed: frame time, CPU and GPU time per system and pass, memory, and the in-game stats overlay.
- [Placing scenes](/guide/editor/placing-scenes.md): Place a Cairn scene inside another, many times, like an entity: fences, enemies and menus made once, edited in their own scene, and followed by every copy.
- [Play mode](/guide/editor/play-mode.md): Play a Cairn game inside the editor, in its own window or full screen, with hot reload of scripts and the scene restored when you stop.
- [Preferences](/guide/editor/preferences.md): Cairn editor preferences: dark or light theme, interface scale, text size, snapping, the script editor to open, how exported games are signed and the agent command server.
- [Project settings](/guide/editor/project-settings.md): Cairn project settings: game name and icon, start scene, input actions and key bindings, physics layers and gravity, and audio buses.
- [Scenes and entities](/guide/editor/scenes-and-entities.md): How Cairn scenes are built from entities and components, with conventions for units and axes, and how to switch an entity off.
- [Top bar and menus](/guide/editor/top-bar.md): Every menu in the Cairn editor's top bar explained: File, Edit, Entity, Assets, View and Help, plus the play controls and export.
- [Updating a game to a newer editor](/guide/editor/updating.md): Move a Cairn game to a newer version of the editor: what the editor changes when it opens an older project, what to do yourself, and how to export the game again.
- [Viewport](/guide/editor/viewport.md): Move around and edit a scene in the Cairn viewport: fly controls, selection, move, rotate and scale gizmos, snapping and view options.
- [Animation](/guide/features/animation.md): Animate characters in Cairn: skinned meshes from glTF, animator controllers with states and transitions, animation events and tweens.
- [Audio](/guide/features/audio.md): Play sound in a Cairn game: audio sources, 3D spatial sound, music streaming with loop points, buses with volume, low-pass and reverb.
- [Cameras](/guide/features/cameras.md): Cameras in Cairn: perspective and orthographic views, the primary camera, turning a mouse click into a world point and following the player.
- [Input](/guide/features/input.md): Read player input in Cairn with named actions bound to keys, mouse buttons and gamepads, including axes for movement and rebinding.
- [Lights](/guide/features/lights.md): Light a Cairn scene with directional, point and spot lights, real-time shadows and image-based light from the sky.
- [Particles](/guide/features/particles.md): Make fire, smoke, sparks and dust in Cairn with particle systems: rate and bursts, lifetime, speed, colour and size over life.
- [Physics engines](/guide/features/physics-engines.md): Cairn runs physics on Jolt or Box3D, picked per project and changeable at any time. How to switch, what stays the same, and how the two compare in speed.
- [Physics](/guide/features/physics.md): Physics in Cairn on Jolt or Box3D: colliders, collision and trigger callbacks, the character controller, raycasts, overlaps and collision layers.
- [Rendering](/guide/features/rendering.md): How Cairn draws a scene on Vulkan: PBR materials, HDR sky lighting, cascaded shadows, ambient occlusion, bloom, tonemapping and FXAA.
- [Rigid bodies and joints](/guide/features/rigid-bodies.md): Rigid bodies in Cairn: static, dynamic and kinematic bodies, forces and impulses from scripts, and fixed, hinge and distance joints.
- [Saving and scenes](/guide/features/saving.md): Save game progress and player settings in Cairn, and switch or add scenes while the game runs, keeping persistent entities.
- [UI and text](/guide/features/ui.md): Build game menus and HUDs in Cairn with screen UI: buttons, sliders, toggles and progress bars that scale to any resolution, plus 3D text.
- [A first look at the editor](/guide/start/editor-tour.md): A quick tour of the Cairn editor: the six areas of the window, how to move around a scene, change things and play your game.
- [Quick start](/guide/start/first-project.md): Make your first Cairn project from a template and play it in a minute: open the project hub, pick a template and press play.
- [Introduction](/guide/start/introduction.md): Cairn is a 3D game engine in C++20 on Vulkan, with an editor, Lua or TypeScript scripting, physics, audio and an AI agent interface.
- [Key concepts](/guide/start/key-concepts.md): The ideas behind Cairn: projects, scenes, entities, components, assets, scripts and placed scenes, and how they fit together.
- [3. A camera that follows](/guide/tutorial/camera.md): Part 3 of the Cairn tutorial: write a camera script in Lua or TypeScript that follows the player smoothly around the level.
- [5. Coins and a score](/guide/tutorial/coins.md): Part 5 of the Cairn tutorial: make a spinning coin, save it as a scene to place many times, collect it with a trigger and show the score on screen with UI.
- [7. Export and next steps](/guide/tutorial/finish.md): Last part of the Cairn tutorial: export your finished game as a standalone program, and where to go next.
- [Your first game](/guide/tutorial/index.md): Build a complete two-level 3D game in Cairn, step by step: a level, a player, a camera, physics, coins, a score and export.
- [1. A project and a level](/guide/tutorial/level.md): Part 1 of the Cairn tutorial: make a new project and build a first level with a ground, walls, steps and materials.
- [6. A second level](/guide/tutorial/levels.md): Part 6 of the Cairn tutorial: add a second level and a portal that loads it, keeping the score across scenes.
- [4. Physics](/guide/tutorial/physics.md): Part 4 of the Cairn tutorial: add colliders and rigid bodies so crates fall, get pushed and stack, and see the collider outlines.
- [2. A player you can move](/guide/tutorial/player.md): Part 2 of the Cairn tutorial: add a player with a character controller and a script that walks, runs and jumps from keyboard or gamepad.
- [Architecture](/reference/architecture.md): How the Cairn game engine is built: the engine library, editor and runtime programs, rendering on Vulkan through nvrhi, and its libraries.
- [Command line](/reference/command-line.md): Every command-line option of the Cairn editor, runtime and CLI: hidden and headless runs, screenshots, agent commands and test flags.
- [File formats](/reference/file-formats.md): The files a Cairn project is made of: project, scene, material and animator files in YAML, meta files and asset IDs.
- [Shortcuts](/reference/shortcuts.md): Every keyboard shortcut in the Cairn editor: viewport flying, gizmo tools, selection, undo, save, play mode and panels.
- [Troubleshooting](/reference/troubleshooting.md): Fixes for common Cairn problems: Vulkan and MoltenVK setup, scripts that do not run, physics that misbehaves and export issues.
- [Scripting API](/scripting/api.md): Every function, property and component a Cairn game script can use, in Lua and TypeScript, generated from the engine's bindings.
- [Entities and components](/scripting/components.md): Read and change entities and components from Lua or TypeScript scripts in Cairn: transforms, finding entities, adding and removing components.
- [Code editor setup](/scripting/editor-setup.md): Set up VS Code or Zed for Cairn scripts: autocomplete, hover docs and type checking for Lua and TypeScript.
- [Scripting overview](/scripting/index.md): Script games in Cairn with Lua or TypeScript: how a script is shaped, its lifecycle functions, exposed fields, hot reload and events.
- [2. Decisions and loops](/scripting/lua/control.md): Learn Lua part 2: if statements, comparisons and loops, explained for game scripting with examples you can run.
- [3. Functions](/scripting/lua/functions.md): Learn Lua part 3: write and call functions, pass arguments, return values and use functions as values in game scripts.
- [Learn Lua](/scripting/lua/index.md): A short Lua course for people who have never programmed, in six pages, with a cheat sheet for people who know another language.
- [5. Objects and scripts](/scripting/lua/objects.md): Learn Lua part 5: objects, methods and the colon, and how a Cairn game script is an object with fields and functions.
- [6. Mistakes everyone makes](/scripting/lua/pitfalls.md): Learn Lua part 6: the mistakes every Lua beginner makes, from global variables to nil and counting from one, and how to avoid them.
- [4. Tables](/scripting/lua/tables.md): Learn Lua part 4: tables as lists and dictionaries, looping over them and keeping game data in them.
- [1. Values and variables](/scripting/lua/values.md): Learn Lua part 1: numbers, strings, booleans and nil, variables and local, explained from nothing for game scripting.
- [Recipes](/scripting/recipes.md): Copy-ready Cairn script recipes in Lua and TypeScript: movement, shooting, spawning, timers, health, doors, pickups and more.
- [TypeScript](/scripting/typescript.md): Write Cairn game scripts in TypeScript: the editor compiles them to Lua with TypeScriptToLua, with full types for the engine API.