File: docs/getting_started/start_with_editor.md Copy Chapter

title: Getting Started With Editor | Kaiju Engine keywords: Kaiju Engine, editor, getting started, installation, tutorial, game development Copy Chapter

Getting started with the editor

The best way to get started with the engine is to get the editor up and running and create a project. I'd highly recommend watching through the Sudoku port series I've created on YouTube to learn the basics on how to use the engine/editor.

Installing the editor Copy Chapter

Kaiju is a portable program and doesn't require installation at this time. You can either download a prebuilt version or build from source.

WINDOWS NOTE: If you have any errors or missing DLL files when trying to run,
please see the Windows Development
section of the building from source page. You may need Vulkan SDK, DirectX runtime,
and/or MinGW built dlls.

Learn through the Sudoku series Copy Chapter

Launching the editor Copy Chapter

When you launch the editor, you will be presented with the project select window. In this window, you can either select an existing project from the list of previously opened projects, or create a new project.

Selecting a project folder Copy Section

If you clicked on the "Select project folder" button, an overlay will pop up, allowing you to browse your file system and select a folder. Navigate into the folder you wish to select, and then click on the "Select" button in the top right.

If the folder is empty, a new project will be created inside of that folder. if there are content inside of the folder, Then the engine will try to determine if it is a kaiju engine project. If it is, it will be opened. If it's not, you will be presented with a warning that the selected folder is not a kaiju project.

You will then be loaded into the main editor window.

Selecting an existing project Copy Section

Back on the project select window, there is a list of existing projects if you have previously opened any. By clicking on any of the labels with the project name you're interested in, it will immediately be opened. If that project no longer exists, you will get a warning, and the project will be removed from the list.

You will then be loaded into the main editor window.

Launch parameters Copy Section

The editor supports several command-line flags that can be passed when launching from a terminal.

For example, to create a new project from the command line:

kaiju -newproject /path/to/my/project -projectname "My Game"

Or to create a project from a template:

kaiju -newproject /path/to/my/project -projectname "My Game" -projecttemplate /path/to/template.zip

Special terms Copy Chapter

Stage - A collection of entities that are to be loaded, others may call it a "map", "scene", "level", etc. Stages help you build out your map in "stages", they can be merged together at runtime. The term "Stage" is also a throw-back to what we would call maps/levels for games in the 90s

Template - A singular entity, it's transform, shader data, any entity data attached to it, and all of the child entities likewise. In other environments people would call these "prefabs" or "blueprints". When a template is updated, all usages of the template across the game are updated as well.

Table of Contents - A collection of content ids that are grouped together for easy referencing. You can use a friendly string name to access various content found in the table at runtime. This can help reduce the need to have const string ids to content in your game code.

Editor Controls Copy Chapter

The primary editor window gives you access to all other editor windows. The main window is also the primary viewport for your game stage (level/map/scene).

Notes Copy Section

[1] Parenting selection will parent all selected entities to the last selected entity. If there is only 1 entity selected when parenting, then it will be removed from it's parent and moved to the root.

[2] If a stage is currently open, that stage will be automatically loaded into by the debug instance that runs.

[3] This will start from the main entry point of the game, it will not load the current stage.

File: docs/getting_started/start_without_editor.md Copy Chapter

title: Getting Started Without Editor | Kaiju Engine keywords: Kaiju, getting started, no editor, Go, build, run, engine Copy Chapter

Getting started without the editor (pure code)

This guide explains how to build and run a Kaiju game without using the graphical editor. The workflow relies on the main.test.go file, which is compiled when the **editor build tag is not present. By following the steps below you can create a game from scratch using only Go code.

Prerequisites Copy Chapter

• Go 1.22+ installed and available on your PATH.
• A recent Git client to clone the repository.
• A C compiler is required because the engine relies on CGo.

1. Clone the repository Copy Chapter

git clone --recurse-submodules https://github.com/kaijuengine/kaiju.git
cd kaiju/src

2. Build the engine *without* the `editor` tag Copy Chapter

The file src/main.test.go contains the build constraint:

//go:build !editor

This means it is compiled only when the editor tag is absent. The default VS Code tasks in this repository build with -tags=editor,filedrop. To build a binary that runs the pure-code path, invoke go build without those flags:

# Build from the src directory and output the executable one level up
go build -o kaiju .

The resulting kaiju executable lives in the repository root.

3. Run the binary Copy Chapter

The executable name differs by platform. After building, you will have either kaiju.exe on Windows or kaiju on macOS/Linux.

• Windows
  powershell Copy

  .\kaiju.exe

• macOS / Linux
  bash Copy

  ./kaiju

On the first run the engine will detect that the game_content directory is missing and will automatically copy the stock assets from the embedded editor content (see Step 4). After the copy completes the game window will appear, showing a simple rotating sphere – the default demo implemented in main.test.go.

4. What `main.test.go` does – a walkthrough Copy Chapter

The file provides a minimal, fully‑functional game implementation. Below is a detailed description of each required piece so you can recreate it in your own project.

4.1 Package imports Copy Section

import (
	"kaijuengine.com/bootstrap"
	"kaijuengine.com/engine"
	"kaijuengine.com/engine/assets"
	"kaijuengine.com/matrix"
	"kaijuengine.com/registry/shader_data_registry"
	"kaijuengine.com/rendering"
	"log/slog"
	"math"
	"os"
	"path/filepath"
	"reflect"
	"slices"
	"strings"
)

These packages give you access to the engine core, asset handling, math utilities, logging, and the standard library for file I/O.

4.2 Constants – paths used by the engine Copy Section

const rawContentPath = `editor/editor_embedded_content/editor_content`
const gameContentPath = `game_content`

• rawContentPath points to the embedded editor assets shipped with the repository.
• gameContentPath is the directory the engine expects to find game‑specific assets (textures, meshes, shaders, etc.). If it does not exist, the engine will call gameCopyEditorContent() to populate it with the default assets.

4.3 The `Game` type Copy Section

type Game struct {
	host *engine.Host
	ball *engine.Entity
}

• host gives you access to the engine subsystems (rendering, material cache, etc.).
• ball is a simple entity we create to demonstrate rendering.

4.4 Required interface methods Copy Section

Kaiju expects a type that implements the bootstrap.GameInterface. The following methods satisfy that contract:

• PluginRegistry() – returns a slice of plugin types. The example returns an empty slice because no custom plugins are needed.
• ContentDatabase() – creates (or copies) the asset database. It checks for gameContentPath and calls gameCopyEditorContent() if missing, then returns assets.NewFileDatabase(gameContentPath).
• Launch(host *engine.Host) – called once the engine is ready. Here we:
  1. Store the host.
  2. Create a sphere mesh.
  3. Retrieve a basic shader and material.
  4. Build a rendering.Drawing that ties the mesh, material, and shader data together.
  5. Register the drawing with the host and schedule the update method to be called each frame.

4.5 Updating your game Copy Section

Notice the update(deltaTime float64) function, it is a helper function (not part of the GameInterface) that is registered with the host updater to run each frame. It provides a simple animation that moves the sphere in a sinusoidal pattern. This function is registered with the host.Updater in the Launch.

4.6 Helper functions Copy Section

• getGame() – required by the bootstrap package; it returns a pointer to a Game instance.
• gameCopyEditorContent() – copies the default editor assets into game_content. It walks the editor/editor_embedded_content/editor_content directory, skips the editor and meshes sub‑folders, and writes each file to the target directory.

5. Creating your own game from scratch Copy Chapter

1. Create a new Go file (e.g., mygame.go) in the src folder.
2. Define a struct that holds any state you need (similar to Game).
3. Implement the four interface methods listed in section 4.4. You can reuse most of the example code and replace the sphere with your own entities, shaders, or assets.
4. Add your assets to a new folder (e.g., my_game_content). Update the constants accordingly:

const rawContentPath = `editor/editor_embedded_content/editor_content`
const gameContentPath = `my_game_content`

5. Build and run the binary exactly as in Step 2 and Step 3.

   Important: If you create your own game implementation, you should either replace or delete the existing src/main.test.go file to avoid the example code being compiled alongside your own code.

6. Frequently asked questions Copy Chapter

7. Custom asset database (optional) Copy Chapter

The engine uses an assets.Database implementation to load textures, meshes, shaders, and other resources. The example uses the built‑in file‑based database (assets.NewFileDatabase). If you prefer a different storage mechanism (e.g., embedded assets, network‑based loading, or a custom format), you can implement the assets.Database interface yourself and return it from ContentDatabase().

Typical steps for a custom database:

1. Create a type that satisfies the methods defined in kaiju/engine/assets/database.go.
2. Implement asset lookup, loading, and any caching you need.
3. In ContentDatabase(), return an instance of your custom type instead of assets.NewFileDatabase.

This flexibility allows you to integrate the engine with existing pipelines or package assets in a way that best fits your project.
| What if I want to keep the editor assets but add my own? | Place your custom assets in game_content (or a sub‑folder) and reference them by path in your code. The engine will prioritize files in game_content over the embedded defaults.