Most game engines ask you to learn a lot before you see anything move. Usagi does the opposite. It is a small, open source 2D engine for making pixel art games in Lua, built around one idea: prototype fast, see changes instantly, and export with a single command. You write a game in Lua, run `usagi dev`, and every time you save, the running game updates without restarting or losing its state. That tight loop is the whole point, and it is why Usagi is worth a look if you have a game idea you want to test this weekend instead of next month.
Key Takeaways
>
Usagi is an open source 2D game engine for rapid pixel art prototyping in Lua 5.5, created by Brett Chalupa and released into the public domain under the Unlicense.
Its headline feature is live reload: `usagi dev` watches your code and assets, so saves apply instantly without losing game state.
One command, `usagi export`, packages a game for Linux, macOS, Windows, and the web.
Its constraints are deliberate: a 320x180 default resolution, a 16x16 default sprite grid, and a single `sprites.png` for textures.
The GitHub mirror at brettchalupa/usagi has 871 stars, and development happens on Codeberg.
Watch the 30-second repo signal: Build 2D Pixel Games Fast With Usagi
Read this article in Indonesian: Usagi: Buat Game Pixel 2D Cepat Dengan Lua dan Live Reload
What Usagi Actually Is
Usagi describes itself plainly: a simple 2D game engine for rapid prototyping. The engine itself is written in Rust, but you build games in Lua 5.5, a small language widely used in game tooling. The GitHub repository is a mirror; active development happens at codeberg.org/brettchalupa/usagi, and the latest release is v1.3.3. It is free software by Brett Chalupa, dedicated to the public domain, so you can use it without worrying about license fees or royalties.
Usagi is not trying to be everything. Its own docs say it is not a fantasy console and not a Love2D replacement. It does not target mobile or VR, and it is not built for medium to large polished games. That honesty is useful, because it tells you exactly when to reach for it: when you want to try an idea quickly, when you are new to game programming, when you have outgrown a more constrained toy, or when you want something simpler than a full general purpose engine.
Getting Started in Three Commands
Starting a Usagi project takes three commands, all documented in the project's README:
`usagi init my_game` creates a project with a `main.lua` file, type stubs for Lua language server support, and a copy of the docs.
`cd my_game` moves into the project folder.
`usagi dev` starts the game in development mode, watching your files.
The generated `main.lua` gives you three stubs: `_init` runs once at startup, `_update` runs every frame, and `_draw` renders the frame. Drawing text is as short as it gets:
function _draw(_dt) gfx.clear(gfx.COLOR_BLACK) gfx.text("Hello, Usagi!", 10, 10, gfx.COLOR_WHITE) end
From there, you add sprites, input, sound, and game logic in the same file, or split it up as the project grows. The engine ships with an online book at book.usagiengine.com that walks through the API, so you are not left guessing what each function does.
Why Live Reload Changes Prototyping
Live reload sounds like a small convenience, but in practice it changes how you design. In a normal workflow, you tweak a value, restart the game, play back to the spot you were testing, and then judge the change. With Usagi, you edit a sprite in your editor, save, and the running game shows the new art immediately, with its state intact. You can tune jump height, enemy speed, or a color palette while the game is still running in front of you, and feel the difference in seconds rather than minutes.
That matters most at the prototype stage, when you are answering questions like: is this jump fun, is this level readable, does this enemy feel fair? Fast answers mean more ideas tested, and more ideas tested mean a better chance of finding one worth finishing. The engine's docs frame the same point as "constraints to inspire creativity": a small, fixed API gives you what you need for a great 2D game, and leaves out the rest.
The Constraints, and Why They Help
Usagi's defaults look strict at first glance, and that is the point:
Aspect | Usagi default | Why it helps |
|---|---|---|
Resolution | 320x180 | Every game shares a crisp retro canvas, and scaling stays simple |
Sprite grid | 16x16 | Art stays consistent, and one sprite sheet is easy to manage |
Textures | A single sprites.png | No asset pipeline to configure before you start |
Language | Lua 5.5 | Small, readable, and easy to pick up for beginners |
Save data | One function for a Lua table | Saving and loading need no database or file format work |
A single `sprites.png` plus a small API means your first hour goes to the game, not to tooling. The trade is real: if you need 3D, mobile builds, or a huge open world, Usagi is the wrong tool, and its docs say so. But if your idea is a tight arcade game, a puzzle game, or a game jam entry, those constraints remove decisions instead of adding them.
Built In, Not Bolted On
Two features that usually require extra work in small engines come built into Usagi. The first is a pause menu, with sound and music volume controls, a fullscreen toggle, and per-game keyboard and gamepad remapping. Players expect that menu, and building it yourself can eat a weekend. The second is save data: one function saves your game state as a Lua table, and one loads it back. Together, they make a prototype feel like a finished game much earlier, which makes playtesting with friends far more useful.
Export is the other piece that usually hurts. `usagi export` packages a game for Linux, macOS, Windows, and the web in one step. That means the same prototype you tuned on your laptop can be shared as a web build for quick feedback, then shipped as desktop builds when it is ready. You can also install the engine from Codeberg, GitHub, or itch.io, or via Homebrew with the community tap, all listed in the README.
Who Should Try Usagi
Usagi fits a few people very well. Beginners get a gentle on ramp: one language, one sprite sheet, and instant feedback. Game jam developers get speed: a playable prototype in an evening, with export ready when the deadline lands. Experienced developers get a sketchbook: a place to test a mechanic before committing to a bigger engine. If you have ever said "I want to try that idea, but setting up a project is too much work," Usagi removes that excuse.
It is not for everyone. Teams building a large commercial game, developers targeting phones, or anyone who needs 3D should look elsewhere. But open source thrives on tools that do one job well, and Usagi's job is clear: get a pixel art game idea playable as fast as possible.
FAQ
Is Usagi free?
Yes. Usagi is free software dedicated to the public domain under the Unlicense, so there are no license fees. Its author accepts voluntary support through a coffee link, but the engine itself costs nothing.
Do I need to know Rust to use Usagi?
No. The engine is written in Rust, but games are written in Lua 5.5. You only touch Lua, plus a sprite sheet and your sound and music tools of choice.
Where is Usagi developed?
The GitHub repository at brettchalupa/usagi is a mirror. Active development happens on Codeberg, and the official site is usagiengine.com.
Can I export my game to the web?
Yes. `usagi export` packages games for Linux, macOS, Windows, and the web, so you can share a playable web build for feedback.
The Bottom Line
Usagi will not replace a big engine, and it does not try to. It gives you Lua, a sprite sheet, live reload, and one-command export, then gets out of the way. If you have a pixel art idea sitting in a notebook, this is one of the fastest ways to see it move. Grab the engine, run `usagi init`, and find out in an evening whether your idea is fun. That is what a prototyping engine is for.