## File: docs/getting_started/start_with_editor.md

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

# 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
Kaiju is a portable program and doesn't require installation at this time. You can either [download a prebuilt version](https://github.com/KaijuEngine/kaiju/tags) or [build from source](../engine/build_from_source.md).

**WINDOWS NOTE:** If you have any errors or missing DLL files when trying to run,
please see the [Windows Development](https://kaijuengine.com/engine/build_from_source/#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


## Launching the editor
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
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
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
The editor supports several command-line flags that can be passed when launching from a terminal.

| Flag                | Description                                                    |
|---------------------|----------------------------------------------------------------|
| `-newproject`       | Create a new blank project at the specified path               |
| `-projectname`      | Name of the project to create (used with `-newproject`)        |
| `-projecttemplate`  | Path to a template zip to use (used with `-newproject`)        |
| `-generate`         | Run a generator, e.g. `pluginapi`                              |
| `-record_pgo`       | Capture a `default.pgo` profile for this run                   |

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
**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
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).

| Shortcut       | Description                                |
|----------------|--------------------------------------------|
| `Alt + LMB`    | Rotate viewport                            |
| `MMB`	         | Pan viewport                               |
| `Space + LMB`  | Pan viewport                               |
| `Alt + RMB`    | Zoom viewport                              |
| `Scroll`       | Zoom viewport                              |
| `F`            | Focus the selection                        |
| `G`            | Grab/move selection                        |
| `R`            | Rotate selection                           |
| `S`            | Scale selection                            |
| `X`            | Locks transform mod to X axis              |
| `Y`            | Locks transform mod to Y axis              |
| `Z`            | Locks transform mod to Z axis              |
| `C`            | Toggle content panel                       |
| `H`            | Toggle hierarchy panel                     |
| `D`            | Toggle details panel                       |
| `Ctrl + S`     | Save the current stage                     |
| `Ctrl + T`     | Create template from selected              |
| `Ctrl + P`     | Parent selection [1](#note_1)              |
| `F5`           | Build and run a debug build [2](#note_2)   |
| `Ctrl + F5`    | Build and run a release build [3](#note_3) |

### Notes
<a id="note_1"></a>
[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.

<a id="note_2"></a>
[2] If a stage is currently open, that stage will be automatically loaded into by the debug instance that runs.

<a id="note_3"></a>
[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

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

# 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

* **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

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

---
## 2. Build the engine *without* the `editor` tag

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

```go
//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:

```powershell
# 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

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

* **Windows**
	```powershell
	.\kaiju.exe
	```
* **macOS / Linux**
	```bash
	./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

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

```go
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

```go
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

```go
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

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
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

* **`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

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:

```go
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

| Question | Answer |
|---|---|
| *Do I need the editor at all?* | No. The engine can run completely head‑less; the editor is only a convenience for asset editing.
| *Do I need the stock engine content?* | Yes. The engine expects the default assets (textures, shaders, etc.) that are shipped with the repository. They are copied automatically on first run if `game_content` is missing.
## 7. Custom asset database (optional)

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.