The Manatee Game Engine

by James Kienle, inspired by The Rust Book by Steve Klabnik and Carol Nichols

This book is currently a living document and is heavily subject to change. Once a first, stable version of Manatee is released, this book will be versioned identically to the engine itself and packaged alongside it.

Forward

Your scientists were so preoccupied with whether or not they could, they didn’t stop to think if they should.

-- Dr. Ian Malcolm (Jurassic Park)

Abandon all hope, ye who enter here.

-- Dante (Inferno)

You ever just wake up one day and think "fuck it, I'm capable of doing whatever I want, I'm going to build my own game engine"? No, just me? Well, one day I woke up and decided I wanted to build my own game engine with no prior knowledge of how to build a game engine, and this project is the result of that impulse.

In truth, I've always been interested in building my own games. I remember spending my free time in middle school modding Cube 2: Sauerbraten and thinking I was the shit, hell I even almost enrolled in a game design college after high school (shoutout my cousin Ryan for convincing me to not move forward with that one, my life is a lot better than it would've been), but I ultimately found myself in the world of full stack web development. Don't get me wrong, I love my day job, and I'm genuinely very good at what I do, but my true passion has always been in games.

Around May 2024 I decided to finally start making my own game. I did tons of research on tooling, and decided to run with Unreal Engine. Call it a skill issue, but I couldn't get much further than implementing character movement. Unreal Engine is undeniably a great tool, but my tiny web developer brain just couldn't wrap its head around the engine's documentation and tutorials. After one particularly painful night of banging my head against the wall trying to understand the engine's builtin ability system I had finally had enough. I popped a 10mg edible, went to bed (early and defeated), and woke up the next day determined to build something better than Unreal. It was at that point that Epic Games was my mortal enemy, and I started researching.

Now realistically I know I'll never get to the point of Unreal Engine feature parity (at least not by myself and not for a very long time), and that's totally okay. This engine is an amazing learning process for me, and I can't wait to one day build my very own game with it and (hopefully) watch others do the same. Thanks for reading all of this, thanks for checking out Manatee, and I sincerely hope you enjoy building some amazing fucking games.

-- James Kienle

Introduction

Welcome to The Manatee Game Engine, a book about building games using Manatee. The Manatee Game Engine is a set of tools to help you build amazing, optimized, and performant video games, without sacrificing developer experience. Manatee is built using the Zig programming language, making it a perfect fit for either starting a brand new project or leveling up an existing C/C++ game.

Who Manatee is For

Right now Manatee is built just for myself (James Kienle), however in the future I'm hoping that Manatee will be usable for many more. My dream is that Manatee will one day be used by

  • Game Design and Computer Science Students
  • Indie Developers / Hackers
  • Artists with Amazing Ideas
  • Game Studios from Indie to AAA

Who This Book is For

This book assumes two things

  1. You have a moderate understanding of how to use a computer (managing your files, installing software, running basic commands, etc.)
  2. You've played video games before and want to build one

This book assumes no prior programming or game design knowledge (however it's super helpful to have) and is meant to be as broadly accessible as possible to a wide variety of backgrounds. I had no knowledge of game design before building Manatee, and I believe that if I could build this, than anyone should be able to use it!

With all of that being said, it would be incredibly helpful to learn a few things before going too deep with learning Manatee. These things include:

  1. Git. FreeCodeCamp has an amazing tutorial for beginners.
  2. Zig. Zig is the programming language that Manatee is written in, and you'll need to learn it in order to build games with Manatee. Unfortunately Zig's documentation is lacking in places, but this book tries to compensate for that where it can. The Zig Guide can be a helpful resource for those new to Zig.
  3. A little bit of game design theory. Elvtr has a really nice article going over some of the fundamentals.

How to Use This Book

This book is best used by reading it, either with your eyeballs or with a screen reader if you have any sight-related disabilities (maybe one day I'll pay someone to record a dramatic, full-cast audio book for this, accepting volunteers!). In all seriousness, use this book however you want. It's written to be read front to back, but feel free to pop into whatever chapter you want and grab the information you need.

Source Code

This book is free, open source (under the MIT License), and entirely written in Markdown using mdBook to generate its static website. If you're interested in digging through the source code, you can find it in the main Manatee repository in the ./book directory.

Getting Started

It's time to start your journey building games with Manatee. Cozy up, grab a snack, stay hydrated, and get ready: there's a lot to learn. In this chapter, you'll learn

  • How to set up Zig
  • How to build and run the Manatee editor
  • How to set up a basic "Hello World" project with Manatee

System Setup

Before you can get started building games with Manatee, there's a few things we'll need to get set up on your computer first. This section will cover setting up Zig and cloning the Manatee source code.

A Quick Note on Command Line Notation:

In this page (and the rest of the book), you'll be asked to enter some commands in your system's terminal. Any command that you'll need to enter will be denoted by a $ character. **Do not type the $ character when entering these commands, that character is only there to denote that the thing on the screen is, in fact, a command you need to enter.

Installing Zig

If you've never installed a programming language before, installing Zig can seem a little daunting at first. The following steps install the latest stable version of Zig, as well as a system package management tool to help you keep Zig up to date.

Installing Zig on Windows

Before we can install Zig we'll want to install a package manager. By installing a package manager, you'll greatly simplify the process of installing and updating your Zig installation. Think of a package manager kind of like an app store, but you install your apps using the command line rather than a UI. This guide uses Chocolatey as its package manager for Windows. To install Chocolatey, do the following:

  1. Open your start menu and find "Command Prompt". Once you've found it, right click the tile and click "Run as Administrator". From here forward, all commands will be entered in Command Prompt.
  2. Once Command Prompt is open, enter the following command: 
    $ @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  3. Let's verify that Chocolatey was successfully installed by entering the following command: 
    $ choco --version

Chocolatey is installed, yay! Now that we have that out of the way, let's install Zig by doing the following:

  1. Enter the following command: 
    $ choco install zig
  2. Let's verify that Zig was successfully installed by entering the following command: 
    zig version

Congratulations, both Chocolatey and Zig have been successfully installed, now you can move on to actually using Manatee!

Installing Zig on MacOS

Before we can install Zig we'll want to install a package manager. By installing a package manager, you'll greatly simplify the process of installing and updating your Zig installation. Think of a package manager kind of like an app store, but you install your apps using the command line rather than a UI. This guide uses Homebrew as its package manager for MacOS. To install Homebrew, do the following:

  1. Open applications and find "Terminal". Once you've found it, open it. From here forward, all commands will be entered in Terminal.
  2. Once Terminal is open, enter the following command 
    $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  3. Let's verify that Homebrew was successfully installed by entering the following command: 
    brew --version

Homebrew is installed, yay! Now that we have that out of the way, let's install Zig by doing the following:

  1. Enter the following command: 
    $ brew install zig
  2. Let's verify that Zig was successfully installed by entering the following command: 
    zig version

Installing Zig on Linux

If you're using Linux I'm going to assume two things about you

  1. You have a pretty damn good understanding of how computers, terminals, and package managers work
  2. You probably don't need help installing Zig.

Given the fact that Linux has a seemingly infinite number of package managers, and I have no way to tell which distro / package manager you're using, I'm going to link you to the Zig docs for instructions on installing Zig with your package manager of choice.

Setting Up Manatee

Now that we have Zig set up, it's time to install Manatee.

TODO: I need to write instructions on how to setup Git, this will come soon but I really should actually be building this game engine instead of writing a book on using it when it doesn't exist yet. For now I'll assume you have git installed

Let's start off by cloning Manatee. I personally prefer to clone Manatee into my Documents folder, let's do that!

Cloning Manatee on Windows

$ cd %userprofile%\Documents
$ git clone https://github.com/jrkienle/manatee.git
$ cd manatee

Cloning Manatee on MacOS / Linux

$ cd ~/Documents
$ git clone https://github.com/jrkienle/manatee.git
$ cd manatee

Now that we've cloned Manatee, let's compile it! Compiling Manatee will allow you to actually run the editor and start building games! Luckily for us, Zig makes compiling code a breeze. In the same terminal you used to clone Manatee, run the following command:

$ zig build

Once that command completes (it may take awhile depending on how powerful your machine is), you should see a new folder named zig-out appear inside of Documents/manatee. Open up that folder, then open the bin folder inside it, and you should see manatee-editor.exe if you're on windows, or manatee-editor if you're on MacOS or Linux. Double click that file, and congratulations, you're now officially running the Manatee editor!