![Kaigen](https://api.kaigen3d.com/docs/img/kaigen-logo.png) # Getting started with Kaigen Kaigen is a high-performance 3D realtime engine written in modern C. This page gets you started with using the engine. *Note: Some of the documentation and tooling still refers to the engine's former name: Horizon (HZ)* --- ## Kaigen is AI-native Kaigen is built to be compatible with coding agents. You can use AI to learn about engine functionality, as well as automating a significant part of feature development and bug chasing (see below). **Claude Code** ``` /plugin marketplace add Kaigen-Technologies/kaigen-plugins /plugin install kaigen@kaigen ``` **Codex** ``` codex plugin marketplace add Kaigen-Technologies/kaigen-plugins ``` **Cursor, Copilot, Gemini CLI, Windsurf, anything else** ```bash npx skills add https://api.kaigen3d.com/skill.md -g ``` What you can do with agents: - **It installs the engine for you.** Say *"set up Kaigen, my key is KGEN-…"* and it runs the whole sequence and tells you what to fix if something is off. - **It knows the engine inside and out.** You can ask *"how do I do X in the engine"* and the answer comes from the engine's own internal documentation. - **End to end feature development.** Kaigen provides custom tooling to allow agents to independently implement *and test* entire features. Your AI can code, build, run the app, send input, debug and test visually completely autonomously. --- ## 1. Install Pick one route. All three end in the same place. ### Kaigen Launcher (UI) | macOS | Windows | |---|---| | [Download](https://api.kaigen3d.com/hub/macos/latest) | [Download](https://api.kaigen3d.com/hub/windows/latest) | Open it, paste your licence key, install an engine version. ### The CLI **macOS** ```bash curl -fsSL https://api.kaigen3d.com/install.sh | sh export PATH="$HOME/.kaigen/bin:$PATH" # add to ~/.zshrc to persist ``` **Windows** ```powershell irm https://api.kaigen3d.com/install.ps1 | iex [Environment]::SetEnvironmentVariable('PATH', [Environment]::GetEnvironmentVariable('PATH','User') + ';' + "$env:LOCALAPPDATA\kaigen\bin", 'User') ``` Then license the machine: ```bash kaigen activate KGEN-XXXX-XXXX-XXXX kaigen doctor ``` ### Using a Coding Agent With the plugin installed, just ask: *"set up Kaigen, my key is KGEN-XXXX-XXXX-XXXX"*. --- ## 2. Create a project ```bash kaigen engine install kaigen new my_app --template starting-template ``` `kaigen engine install` with no version fetches the latest engine. `kaigen new` uses the newest engine installed on this machine (with none, it stops and tells you to run `kaigen engine install`), downloads the template if it is not on this machine yet, scaffolds the project, and initialises a git repository with one commit (pass `--no-git` to skip). Templates are downloaded on demand, per engine version. `kaigen templates` lists the ones available for your engine and which are already downloaded. Start from `starting-template` (the default) for a third-person character on a grid floor, or from a full game: `proving-grounds` (first-person arena shooter), `wanderer` (exploration on a procedural island), `vampire-survivors` (survive the horde), `canyon-rally` (lap racing) or `scene-visualization` (a product configurator). Useful flags: `--engine ` to use a specific engine (installed first if needed), `--swift` (macOS only) to nest the project under a native SwiftUI host, `--embed` to copy the engine into the project instead of linking it. --- ## 3. Anatomy of a project ``` my_app/ ├── hzproject.hzt project config: name, source/asset roots, engine pin ├── hz -> symlink to the installed engine (machine-local) ├── src/ │ └── my_app/ │ └── my_app.c entry module ├── assets/ source assets, authored (.hzt and friends) ├── shaders/ your shaders (optional; the engine ships its own) ├── tests/ ├── cooked/ build output: assets compiled for the target ├── out/ build output: binaries and objects ├── .vscode/ build, run and debug tasks, preconfigured ├── .claude/ the engine's skills and agents, linked from the drop ├── AGENTS.md engine guidance for non-Claude agents └── compile_commands.json regenerated each build; drives clangd ``` By default **`hz` is a symlink, and it is machine-local.**. Developers on the project need to download their own install of the engine. Source clients might prefer to use a local, shared version of the engine, in which case please refer to section [6. Working from an engine source tree]. **`hzproject.hzt` is the project config.** Its `engine_version` line is the pin that makes builds reproducible across a team. `src_roots` / `asset_roots` / `test_roots` tell the build system what belongs to you. **A module is a folder.** `src/my_app/my_app.c` is the module root; any other `.c` file in that folder is `#include`d by it rather than compiled separately. That is the engine's unity-build convention, and the compile database understands it, so your editor indexes all of it. `cooked/` and `out/` are generated. Delete them any time. --- ## 4. Development loop From inside the project: ```bash hz/hzbuild # build without running hz/hzbuild run # build, cook assets, run hz/hzbuild cook # assets only hz/hzbuild shaders # shaders only hz/hzbuild clean # clean build artifacts ``` IMPORTANT: Inside a project you use `hz/hzbuild`, not `kaigen`. In VS Code the same commands are wired up: **Run Build Task** builds and runs, and the debug configurations attach lldb (macOS) or the Visual Studio debugger (Windows) to your binary. Install the recommended extensions when prompted; clangd provides completion and go-to-definition into the engine source. --- ## 5. Updating the engine ```bash kaigen engine list # what is installed kaigen engine install 0.6.0 # fetch a version ``` To move a project, edit `engine_version` in `hzproject.hzt`, then: ```bash kaigen restore hz/hzbuild run ``` Engines are shared between projects, so a version you already have is instant. Projects built against an engine source tree have no pin — see below. **iOS and web are separate downloads.** A fresh install carries only `core`, which builds for the host desktop. If an iOS or web build fails on a new machine, this is why: ```bash kaigen engine add ios # iOS support kaigen engine add wasm # web/browser support kaigen engine add tests # the engine test suite ``` Run those inside the project and the version comes from its pin. --- ## 6. Working from an engine source tree **Source licences only.** If you have the binary edition there is no engine source on your machine and these commands will leave the project unbuildable. With a source licence you can point a project at your own checkout of the engine and build against it directly: ```bash kaigen use source /path/to/kaigen-engine # point ./hz at a checkout kaigen use source # the checkout owning this binary kaigen use --status # what am I pointed at right now? kaigen use 0.6.0 # switch back to an installed version ``` Three things to know: **The pin goes away.** `engine_version` is removed from `hzproject.hzt` while you are on a source tree — your engine version is whatever your checkout is at, so `kaigen restore` no longer applies. Switching back with `kaigen use ` restores the pin. **`use --status` tells you exactly what you are building against**, including a short identity string with the engine's git sha. That is the fastest answer to "which engine is this build?". **Switching modes forces a full rebuild**, because the engine identity changes. Expected, but surprising the first time. --- ## 7. When something breaks ```bash kaigen doctor ``` It checks your licence, installed engines, the current project and the toolchain, and prints the exact command that fixes anything it finds. Start there before reading anything else — including this page. If your agent is set up, *"kaigen doctor says X, fix it"* is usually enough. --- ## Where to go next - Engine reference and guides: `/.claude/skills/` and `/hz/wiki/` - CLI reference for agents: - Licence, machine slots and renewals: contact Kaigen.