Getting Started

Installation

To initialize, run and build projects made with bonsai it is required to install the CLI.

Prerequisites

Before installing the CLI, ensure you have the following installed:

• Odin Compiler: Required to compile your game code.

  Ensure odin is in your system PATH.

• Git: Required to download templates and libraries.

For web builds:

• Emscripten SDK: Required to compile for the browser (WASM).

  Ensure emcc is in your system PATH.

The CLI

There are two ways to install the CLI.

The cargo Way

If you have cargo installed, simply run:

cargo install bonsai-cli

The cargo-dist Way

You can also install the binary via a shell/powershell script:

On Linux/MacOS*

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nihiL7331/bonsai/releases/latest/download/bonsai-cli-installer.sh | sh

On Windows

powershell -ExecutionPolicy Bypass -c "irm https://github.com/nihiL7331/bonsai/releases/latest/download/bonsai-cli-installer.ps1 | iex"

Now, with the CLI in your hands, you can run the following command:

bonsai init <project_name>

It will automatically generate the basic bonsai template.

Tip

For an in-depth explanation of every command, visit the CLI repository.

But what exactly does the template contain?

Project Structure

Tip

Most of the text highlighted like this can be clicked and will redirect you to the referenced piece of code. Try it yourself!

There are three main directories that every bonsai project contains - assets, bonsai and source.

assets

Assets are, you’ve guessed it - the place where assets live. The important thing is the automation and the structure it requires.

There are three subdirectories in the assets directory.

audio is where the sound files are stored. Currently, bonsai only works with WAV audio files. Just drop them in, and use the generated.AudioName enum to play your audio files using the bonsai:core/audio package.

fonts is where the font files are stored. Currently, bonsai only works with TTF font files. Just drop them in, and use the generated.FontName enum to write text using the font of your choice, using the bonsai:core/render package.

Note

bonsai comes with one default font built-in - PixelCode.

images is where the image files are stored. Currently, bonsai only works with PNG. Drop a sprite in, and use the generated.SpriteName enum to draw your sprites using the bonsai:core/render package.

Note

All images from the assets directory get loaded to one sprite atlas image, stored in bonsai/core/render/atlas.

Sprites also can be loaded in as animations or tilesets.

You can declare an animation strip by naming your image file name as <image>_{X}x1.png. Then, when drawing a sprite you can use the animationIndex to manipulate the currently drawn frame.

You can declare a tileset by storing it in assets/images/tilesets and naming it <tileset>_{W}x{H}.png, where WxH is the size of one tile in the tileset in pixels. The CLI will automatically load each tile separately to the atlas. A more in-depth explanation of this process can be found on the bonsai:core/render package reference page.

bonsai

This is where the instance of framework source code for this project belongs. It’s also where the systems directory, containing all installed and created systems live. All of its contents are thoroughly described in the Reference section of this website.

source

This is where the game code lives. It consists of main.odin and the game directory.

main.odin acts as a bridge between the framework source code and the game code. It’s responsible for initializing and cleaning up all core processes.

Tip

While main.odin isn’t intended to be edited, it’s recommended to check what it contains, to get a better understanding of how bonsai works.

game is where your game code lives. The template comes prepackaged with the game.odin file, where the basic functions like init, update, draw and shutdown live. There are also two subdirectories in the game directory: scenes and shaders.

scenes is where you can create your own scenes. An in-depth explanation of the process of scene creation can be found on the bonsai:core/scene package reference page.

shaders is where you can create your own custom shaders. A sample shader code for bonsai can be found in the bonsai:shaders package reference page.

Note

There’s also a custom shader tutorial coming. For now, the most important thing is included in the bonsai:shaders package reference page. It’s also worth noting, that the custom shader should use shader_vs_core.glsl and shader_fs_core.glsl to ensure it passes the same data as the default shader.

Now that you have been introduced with the basic structure, let’s write your first “Hello, Pot!” code.

Hello, Pot

Let’s write your ‘Hello, World!’ code in bonsai. Rather than to the world, you’ll be saying hello to Pot.

Let’s open the game.odin file in the source/game directory. By default, it should contain these four functions: init, update, draw and shutdown.

We will use the bonsai:core/render package to render the text and to get a position for the said text we want to draw. Simply import it at the top of the file:

import "bonsai:core/render"

Let’s draw the text on the center of the UI screen space. To do that, in your draw functions you can use the imported functions:

draw :: proc() {
  render.setScreenSpace()

  centerPosition := render.getViewportPivot(.centerCenter)
  render.drawTextSimple(centerPosition, "Hello, Pot!", pivot = .centerCenter)
}

Finally, your code should look like this:

// This file is the entry point for all gameplay code.

package game

import "bonsai:core/render"

init :: proc() {
}

update :: proc() {
}

draw :: proc() {
  render.setScreenSpace()

  centerPosition := render.getViewportPivot(.centerCenter)
  render.drawTextSimple(centerPosition, "Hello, Pot!", pivot = .centerCenter)
}

shutdown :: proc() {
}

Run it with this CLI command:

bonsai run

You can also try it on web by adding the --web flag:

bonsai run --web

then you should see a beautifully pixelated text saying “Hello, Pot!”. And you’re done!

What’s next?

Currently there are no tutorials for bonsai. Feel free to experiment and read the Reference, which contains in-depth explanations of every package and many examples.

Interested in the CLI? Check the CLI repository. It contains a full walkthrough of all commands with explanation.

For the framework source code, visit this repository.