Hajimehoshi/ebiten: a 2D game engine for Go that stays out of your way

What Ebitengine solves, and who it is actually for

Most 2D engines ask you to learn their scene model before you can draw a rectangle. Ebitengine takes the opposite position. The README calls it "a dead simple 2D game engine for Go," and the package list backs that up: the core ebiten package holds the game loop, the image type, input, and windowing, while everything else sits in subpackages you import only when you need them.

The audience is narrow and specific. You already write Go, you want a 2D game, and you would rather write your own entity management than adopt someone else's. Ebitengine gives you the loop, the draw calls, and the platform layer. It does not give you a scene graph, an editor, or an asset pipeline. The examples directory, with entries such as examples/2048/, examples/flappy/, examples/blocks/ and examples/camera/, is the intended starting point; there is no scaffolding command in the README.

That framing matters when you compare it to engines that ship an editor. Ebitengine is closer to a rendering and input library with a fixed game loop than to a full authoring environment.

The game loop, images and the draw model

The architecture visible in the repository is a classic fixed-interface loop. A game type implements Update and Draw, and the engine calls them on its own schedule. The README lists the graphics features as 2D geometry and color transformation by matrices, various composition modes, offscreen rendering, text rendering, automatic batches and automatic texture atlas, plus custom shaders.

The batching and atlas behavior is the part worth understanding before you design anything. Because the engine batches draw calls and packs textures automatically, the cost of a draw is not simply one call per sprite in the way a naive immediate-mode renderer would be. The trade-off is that you have less direct control over draw ordering and texture residency than you would with an engine that exposes the underlying batch. The repository also exposes lower-level drawing primitives through vector/ and colorm/, and shader handling through shader.go and the exp/shaderprecomp package.

Audio is not one API. The README lists audio as Ogg/Vorbis, MP3, WAV and PCM, and the package tree confirms these are separate subpackages under audio/: audio/mp3, audio/vorbis, audio/wav. If your pipeline produces one format, you import one package. That is a real design decision, not a wrapper you can ignore.

Installing Ebitengine and drawing a first frame

The README points desktop users at the installation instructions on ebitengine.org rather than embedding steps. What the repository does show is the module path and the Go version. The go.mod file declares the module as github.com/hajimehoshi/ebiten/v2 and requires go 1.25.0, so a toolchain at or above that version is the baseline.

Add the engine to an existing Go module with the module path the repository declares:

go get github.com/hajimehoshi/ebiten/v2

The README links an API Reference, a Cheat Sheet and an examples directory, and those are the places to look for the exact signatures of the game interface. The repository root file run.go holds the entry point that starts the loop, and the examples/ directory contains runnable programs such as examples/2048/ and examples/flappy/ that you can execute directly to confirm the toolchain and the platform layer work on your machine before writing any code of your own.

Start from one of those examples rather than from an empty file. The README does not document a scaffolding command, so copying an example and editing it is the path the repository itself supports.

Where Ebitengine stops: text, mobile and the Cgo boundary

The clearest limitation is that text rendering is its own package, text/v2, and the README lists it as a separate entry rather than folding it into the core. Font handling therefore is something you configure, not something the engine assumes. If your game is text-heavy, budget time for that package rather than expecting the core image type to handle it.

Mobile is the second boundary. The README marks Android and iOS as requiring Cgo, and the same note applies to Nintendo Switch and Xbox. That changes your build setup: a pure-Go cross-compile is not the path here. The mobile/ package and run_mobile.go in the repository root are where the mobile entry point lives, and the README links to a separate mobile document. Xbox support is described in the README as limited and not available to everyone, with negotiations underway, so it is not a target you can plan a release around today.

The third limitation is the one that catches Go developers by surprise: this is a library, not a framework. There is no Ebitengine project file, no asset manifest, no scene serialization. If your team expects to hand level design to a non-programmer, Ebitengine is the wrong tool, and no amount of package exploration changes that.

Ebitengine against a general-purpose engine

The honest comparison is with an engine that owns the whole pipeline, such as a scene-graph engine with a bundled editor. The difference is not performance, it is where the decisions live. A scene-graph engine decides how objects are stored, updated and drawn, and you adapt to that. Ebitengine decides only that Update runs, Draw runs, and images are drawn with matrices and composition modes; the structure between those two calls is yours.

That makes Ebitengine a poor fit for a team that wants the engine to make architectural choices. It makes it a good fit for a Go team that already has opinions. The cost shows up in the middle of a project: you will write your own entity storage, your own collision, and your own level loading. The repository does include github.com/jakecoffman/cp/v2 as a dependency and an examples/chipmunk/ directory, so a physics engine is available in the ecosystem, but it is an example and a dependency rather than a core feature.

The second comparison is with writing directly against a graphics API. Ebitengine's automatic batching and texture atlas mean you get a working renderer without writing one, and the trade-off is the control you give up over batching details.

Maintenance, releases and what Apache-2.0 means here

The repository is not archived, and the last push was on 2026-08-15, the same date as the v2.9.10 release. Before that, v2.9.9 landed on 2026-03-06 and v2.9.8 on 2026-01-29. That is a release cadence with gaps of weeks to months between patch versions, which is worth knowing if you pin a version and expect frequent upstream fixes.

The licence is Apache-2.0, stated in the README and present as a LICENSE file at the repository root. Two practical consequences for a project that depends on it. First, the NOTICE.md file bundles third-party libraries with their own licences, and the README points at it explicitly; a redistributed binary carries those obligations too, so read NOTICE.md before you ship rather than after. Second, the Ebitengine logo is licensed separately under Creative Commons Attribution 4.0, so using the logo in marketing material is a different question from using the code. None of this is legal advice; it is what the repository files say.

Upgrade cost is bounded by the API surface. Because the core package is small and the rest is subpackages, a major version change touches the parts you imported. The go.mod file pins a large dependency set, including golang.org/x/image, golang.org/x/text and github.com/go-text/typesetting, so a Go toolchain bump can pull in unrelated updates.

Editorial conclusion

Adopt Ebitengine if your game is 2D, your team already writes Go, and you want to ship to desktop plus mobile or WebAssembly without maintaining separate renderers. Do not adopt it if you need a 3D pipeline, a visual editor, or an engine that handles asset import and scene graphs for you; the repository is a library, not a tool suite, and the examples directory is the closest thing to a project template. Before committing, run one of the examples under examples/ on every target platform you care about, and check the audio package you need against the formats listed in the README, since MP3, Ogg/Vorbis, WAV and PCM are separate subpackages rather than one unified decoder.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes