DOCSEARCHbyAlgolia
Submit Docs

Kaiju Engine Documentation

repository·master·Indexed 26 days ago

https://github.com/kaijuengine/kaiju

A high-performance development environment for creating games and applications. Features include a workspace-based editor (Project, Stage, and Content workspaces), a managed asset database system using GUIDs and virtual organization, and the AI Driver HTTP server for driving games via input injection and state observation. Includes specialized Agent Skills for AI integration with tools like Claude Code, Cursor, and Windsurf.

Tokens
32.3K
Snippets
60
Records
195
Agent score
89%

What's inside Kaiju Engine

  1. Overview of Kaiju Agent Skills

    master

    Kaiju Agent Skills are specialized instruction sets designed for AI agents to work with the Kaiju Engine. Each skill is a directory containing a SKILL.md file (with name and description in YAML frontmatter) and optional reference/ files for on-demand loading.

    Available skills:

    • kaijuengine-game-dev: For building games/tools (covers GameInterface, Host runtime, entities, matrix library, Vulkan Drawing, UI, build tags, and testing).
    • kaijuengine-aidriver: For driving a running Kaiju game via the AI Driver HTTP server (requires the ai_driver build tag).

  2. Understand Kaiju Engine terminology

    master

    To use the editor effectively, familiarize yourself with these core concepts:

    • Stage: A collection of entities to be loaded (similar to a map, scene, or level). Stages can be merged together at runtime.
    • Template: A singular entity including its transform, shader data, and all attached entity data (including children). Updating a template updates all its usages across the game (similar to prefabs or blueprints).
    • Table of Contents: A collection of content IDs grouped together for easy referencing. Allows accessing content via friendly string names at runtime instead of using constant string IDs.

  3. Imported FBX features

    master

    The importer extracts the following data from binary FBX assets:

    • Geometry: Mesh geometry from Geometry objects (including Vertices and PolygonVertexIndex) with triangle fan triangulation for polygons.
    • Vertex Data: Normals, UVs, and vertex colors (supporting ByPolygonVertex, ByVertice, ByVertex, or ByControlPoint mapping). Generates face normals if normal layer data is missing.
    • Hierarchy & Transforms: Model hierarchy, local translation/rotation/scale, and global axis settings (converted to Kaiju's -Z forward convention). Geometric transforms are baked into mesh vertices.
    • Materials & Textures: Materials connected to geometry/nodes, external texture paths, and embedded Video texture content. UV V-coordinates are flipped to match Kaiju's sampling convention.
    • Skeletal Animation: Skin clusters (up to four normalized influences per vertex), blend shape vertex offsets, and animation curves for local translation, rotation, and scale (raw keyed curves only).

  4. Understand the Terrain Texture Authoring Model

    master

    Terrain texture painting uses a split model between CPU-side authoring data and GPU-side splat textures.

    Data Structures

    • terrain.TerrainLayerSet: Owns the ordered list of layers and a single terrain.TextureWeightMap.
    • terrain.TerrainLayer: Stores layer metadata including name, albedo content ID, filter, tiling, tint, lock state, preview visibility, and reserved normal/roughness content IDs.
    • terrain.TextureWeightMap: Stores normalized blend weights in cell-major order using the formula: ((x + z*Resolution) * Layers) + layer.

    Resolution Settings

    • TerrainConfig.Resolution: Controls the height vertex resolution.
    • TerrainConfig.PaintResolution: Controls the weight map resolution. If not set, it defaults to the height resolution.

  5. Matrix Math SIMD Optimizations Overview

    master

    Kaiju Engine uses hand-crafted SIMD assembly for core matrix operations to achieve high performance on modern CPUs. The engine provides optimized paths for AMD64 (Windows) and ARM64 (macOS/Linux), significantly reducing the cost of transforms, camera projections, and skinning calculations compared to plain scalar Go arithmetic.

    Key performance benefits include:

    • AMD64: Up to 17.0× speed-up for Vec4MultiplyMat4.
    • ARM64: Up to 9.6× speed-up for Mat4Multiply.

    For platforms without SIMD support, the engine automatically falls back to traditional Go implementations located in src/matrix/matrix.none.go.

  6. Choose a Kaiju Engine workflow

    master

    Kaiju Engine offers two primary workflows that share the same runtime:

    1. Visual Editing (Editor Workflow): Use the integrated visual workspace for managing scenes, assets, shader previews, and play testing. The editor itself runs inside Kaiju.
    2. Code-First (Go Workflow): Use Kaiju directly as a Go library for maximum control over runtime code. You can write gameplay and systems in Go using engine caches, entities, transforms, and drawings, bringing your own project structure.

  7. Requirements for implementing terrain tessellation

    master

    To enable terrain tessellation in the Kaiju Engine, several components must be updated to transition from triangle lists to patch-based rendering. The backend supports tessellation, but the terrain implementation currently uses Triangles topology and lacks tessellation control/evaluation shaders.

    Required updates:

    1. Shader Definitions: Update terrain.shader to include paths for TessellationControl and TessellationEvaluation shaders.
    2. New Shaders: Create terrain.tesc (Tessellation Control) and terrain.tese (Tessellation Evaluation) files.
    3. Pipeline Configuration: Update terrain.shaderpipeline to set InputAssembly Topology to Patches and define PatchControlPoints (e.g., 3 or 4).
    4. Mesh Generation: Update terrain.go to generate mesh data compatible with patches and ensure Indexes are formatted for patch lists.
    5. Vertex Shader: Adjust terrain.vert if necessary to accommodate tessellation logic.

  9. Analyze traces with Gotraceui

    master

    Once the engine closes, the trace.out file is automatically passed to Gotraceui.

    To identify performance bottlenecks:

    1. Open the trace in Gotraceui.
    2. Locate the pink blocks in the timeline area.
    3. Zoom in on these blocks to inspect the stacks of function calls.
    4. Scroll down to view work being performed on other threads (also represented by pink boxes).

  10. Manage entities in the Hierarchy Panel

    master

    The Hierarchy Panel (located on the left) displays the scene's entity structure as a tree. Use it to organize your scene:

    • Select an entity: Click on the entity name.
    • Multi-select: Hold Ctrl while clicking to select multiple entities.
    • Reorder entities: Drag and drop entities within the list.
    • Create parent-child relationships: Drag an entity onto another entity to make it a child.
    • Delete entities: Select an entity and press Delete.
    • Duplicate entities: Select an entity and press Ctrl+D.

  12. Use Editor Overlays for contextual actions

    master

    Overlays are used for specific tasks and block input to the rest of the editor while active.

    • File browser overlay: Used for selecting files or folders. Includes a path input bar and file list.
    • Confirm overlay: A simple dialog with a title, description, and two options (typically 'Okay' and 'Cancel').
    • Input overlay: Provides a title, description, and an input box for string entry.
    • Progress bar overlay: Displays current progress with a progress bar and a status label. Can optionally include a title and description.