Introduction
Game Programming with Usagi
A beginner-friendly guide to coding games with Lua
by Brett Chalupa
NOTE: this book is a work in progress!
Hi, my name is Brett Chalupa! I’m the creator of Usagi Engine and primary author of Game Programming with Usagi. This book is a guide for how to jump into making games. It’s project-based and starts with the fundamentals of programming. This book, much like Usagi itself, is simple, accessible, and free.
The advice often given to new game developers is to make a lot of small games. That way the new developer can learn the fundamentals of game development, explore ideas, and figure out what games they enjoy making. The problem though is that most game engines aren’t conducive to making small games quickly. After making small games for over twenty years, I decided to try to solve that problem by creating Usagi Engine, a free and open source game engine that’s specifically focused on making small 2D games and being able to quickly share them. Your code, art assets, audio files, and data are live reloaded as you change them, removing the laborious step of having to constantly re-launch your game after every change to test it. If you want to see if a different color looks better, just edit your sprite, save it, and see it update instantly. I can’t overstate how useful this is.
Usagi games are programmed with Lua, a simple and widely-used language. There are many different game engines and libraries that use Lua, which means the knowledge you gain from learning to make games with Usagi is useful even if you stop using the engine. When you code a game, the engine provides functions, which are named pieces of code that do something like draw a shape on the screen or play a sound effect. Large game engines have hundreds or thousands of functions, requiring you to study complex manuals to find what you need. Usagi, on the other hand, embraces constraints and has a limited number of functions that cover the functionality most games need.
Why Usagi
Usagi is not the everything engine. There’s a lot it doesn’t do. But it excels at being simple, approachable, and fast. When you’re exploring an idea or participating in a game jam, you don’t want to spend your time coding input mapping or where to put save data on Linux computers. You want to focus on making your game fun to play. Usagi provides input mapping, simple ways to check for player input via keyboard and gamepad, easy save data, and a fully-featured Pause menu. Also, with a single command you can export your game for web, Linux, macOS, and Windows.
Here are some of my favorite aspects of Usagi and why it’s enjoyable to use:
- Live reload of code and assets in your running game for rapid development
- Single command cross-platform export
- Unified, simple input checking for gamepads and keyboard
- Built-in Pause menu with settings, including input mapping
Book Overview
This book, Game Programming with Usagi Engine, is written for someone just getting started out making games. If you’ve coded games before, great! You’ll be able to pick up on things even quicker. But if you haven’t, don’t worry. We’ll go through making games step-by-step in guided tutorials. The second half of the book contains recipes that are focused lessons on specific functionality.
There are two sections to the book: Tutorials and Recipes.
The Tutorials are guided, project-based lessons where you’ll make a game from scratch. The complexity of each chapter steadily grows, so if you’re new to game programming, it’s best to start at the beginning and go through each one in order. If you’ve programmed games before, jump around a bit!
The Recipes are deep-dives into specific topics. Sort of like blog posts on various topics related to Usagi Engine. They’re great for learning a specific concept as opposed to guided programming and engine fundamentals.
If you’re looking for Usagi’s reference manual, you’ll want to read through usagiengine.com.
This book is written for humans, by humans! No generative AI was used in the writing of this book.
Getting the Most Out of the Book
Each chapter is broken down into sections, each of which cover a key concept in the game we’ll be building out. The source code snippets are shown in a block of text and then beneath it I explain what that code does. At the end of each section, there’s a link to the full source code at that point in time of the project, that way you can see the full files and where your version might differ.
You’ll be tempted to copy and paste the code from the book, but I strongly recommend you type it out yourself. Part of learning how to code is getting familiar with the process of typing text into your editor and getting use to those ergonomics.
The tutorial chapters may be missing obvious features you think the game might need, like sprites or music or sound effects. I’d encourage you to add those things yourself, change the code, and make it your own game. It might also be that the concept is too complex for that point in the book and that it’ll be covered in a future game.
Most of all, have fun! Game programming can be challenging but it’s quite rewarding. To get to play your game after building some new feature and see it get better and better is an amazing feeling.
If you’re stuck or run into an issue, join the Usagi Engine Discord and ask for help in the #book channel.
Getting Started
There are three things you need to get started with Usagi:
- A computer running Linux, macOS, or Windows
- A text editor for writing code; here are some free, privacy-respecting options:
- Usagi installed; follow the instructions at usagiengine.com
Usagi is interacted with via the command line. You type in commands rather than click buttons in a graphical user interface. On Linux and macOS, the command-line program is called the Terminal. On Windows, the two primary tools are called the Command Prompt and PowerShell (you can use either with Usagi). While the command line can be daunting at first, there are only a few commands you’ll need to know to work with Usagi most of the time.
We’ll cover all of the essential commands and make our first basic game in the upcoming chapters.