Ebitengine

Ebitengine (formerly Ebiten) is a dead simple 2D game engine for the Go programming language. It provides a simple API for developing 2D games that can be deployed across multiple platforms, including desktop, mobile, web, and consoles.

Core Features

• 2D Graphics: Supports geometry and color transformation via matrices, various composition modes, offscreen rendering, text rendering, automatic batching, automatic texture atlases, and custom shaders.
• Input: Supports Mouse, Keyboard, Gamepads, and Touches.
• Audio: Supports Ogg/Vorbis, MP3, WAV, and PCM formats.

The host driver controls the guest's execution through a specific sequence of calls within the host's Update loop. This allows for deterministic, high-speed execution (faster than real-time).

Execution Sequence

1. d.guest.AdvanceTicks(n): Queues n ticks to run back-to-back. This compresses wall-clock time because the guest is not paced to the host's TPS.
2. d.guest.AdvanceFrame(): Requests the final frame after the ticks have run.
3. d.guest.WaitFrame(): Blocks until all queued ticks have run and the frame is rendered.
4. d.guest.CompositeFrame(): Composites the guest's frame into the host's screen image.

Error Handling

• guest.Err(): Becomes non-nil if the guest terminates, crashes, or times out.
• A panicking guest will print its stack trace to stderr and stop the driver.

Ebitengine supports a wide range of platforms. Note that some platforms require Cgo to be enabled.

• Desktop: Windows, macOS, Linux, FreeBSD
• Mobile: Android (Cgo required), iOS (Cgo required)
• Web: WebAssembly
• Consoles: Nintendo Switch (Cgo required), Xbox (Cgo required; support is limited and access is restricted)

To quickly capture a single screenshot of an Ebitengine app without writing custom input logic, use the provided driver template. Run the driver from the ebiten repository root, pointing to the package you want to test.

Command:

go run ./skills/run-ebitengine-app-headless/_driver \
  -pkg ./examples/rotate -ticks 60 -out /tmp/frame.png

Flags:

• -pkg: The path to the guest package.
• -ticks: Number of ticks to run before dumping the frame and exiting.
• -out: Path where the PNG will be saved.
• -w/-h: Logical screen size (defaults to 320×240).

To perform end-to-end testing of an application within a go test suite rather than using a standalone driver, you can use the internal testing helpers.

Note: These helpers use internal/testing's MainWithRunLoop, which is only importable from within the Ebiten module itself. You can find implementation patterns in:

• exp/vmhost/guest_test.go (using startGuest and tickAndFrame helpers)
• exp/vmhost/readpixels_test.go

The Blend struct defines how source colors (the image being drawn) and destination colors (the existing content on the target) are combined.

To create a custom blend mode, you must specify both Blend Factors (multipliers for source/destination values) and Blend Operations (the mathematical operator used to combine them).

The final color is calculated as:

• c_out = BlendOperationRGB((BlendFactorSourceRGB) × c_src, (BlendFactorDestinationRGB) × c_dst)
• α_out = BlendOperationAlpha((BlendFactorSourceAlpha) × α_src, (BlendFactorDestinationAlpha) × α_dst)

Note: c_src, c_dst, and c_out represent alpha-premultiplied RGB values.

blend := ebiten.Blend{
    BlendFactorSourceRGB:        ebiten.BlendFactorOne,
    BlendFactorDestinationRGB:   ebiten.BlendFactorZero,
    BlendOperationRGB:           ebiten.BlendOperationAdd,
    // ... other fields
}

A ColorM represents a matrix used to transform colors when rendering an image. It operates on straight alpha colors, even though Ebitengine images use alpha-premultiplied formats. The engine automatically handles un-multiplying colors before applying the matrix and re-multiplying them afterward.

Note: ColorM is deprecated as of v2.5. For new projects, use the colorm package or ColorScale instead.

// Example of initializing a ColorM (though deprecated)
var cm ebiten.ColorM

Ebitengine provides two ways to handle screen scaling via the Layout method:

• Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int): The standard method using integer pixel dimensions.
• LayoutF(outsideWidth, outsideHeight float64) (screenWidth, screenHeight float64): A float-based version for higher precision.

Note: If your Game implements LayoutFer, Ebitengine will call LayoutF and ignore the standard Layout method.