autoebiten

README

autoebiten

CLI tool for automating Ebitengine games via input injection, screenshots, scripted sequences, and custom commands.

Installation

go install github.com/s3cy/autoebiten/cmd/autoebiten@latest

Quick Start

1. Add the library to your game

import "github.com/s3cy/autoebiten"

func (g *Game) Update() error {
    if !autoebiten.Update() {
        return errors.New("exit requested")
    }
    // Your update logic
    return nil
}

func (g *Game) Draw(screen *ebiten.Image) {
    // Your draw logic
    autoebiten.Capture(screen) // Call at the end
}

2. Run your game

./my-game

3. Control it via CLI

# Press a key
autoebiten input --key KeyW --action press

# Hold a key for 6 ticks (default)
autoebiten input --key KeySpace --action hold

# Move mouse and click
autoebiten mouse --action position -x 100 -y 200
autoebiten mouse --action press --button MouseButtonLeft
autoebiten mouse --button MouseButtonLeft  # defaults to hold action
autoebiten mouse -x 100 -y 200 --button MouseButtonLeft  # move to positen, then trigger the button

# Scroll wheel
autoebiten wheel -y -3

# Get injected positions (returns last injected values, not real OS positions)
autoebiten get_mouse_position
autoebiten get_wheel_position

# Take a screenshot
autoebiten screenshot --output shot.png

# Run a script file
autoebiten run --script script.json

# Run an inline script
autoebiten run --inline '{"version":"1.0","commands":[{"input":{"action":"press","key":"KeySpace"}}]}'

# Get JSON Schema for IDE support
autoebiten schema > autoebiten-schema.json

# Check connection
autoebiten ping

# List available keys
autoebiten keys

# List mouse buttons
autoebiten mouse_buttons

Custom Commands

Games can register custom commands that can be invoked from the CLI:

Game Side

// In your game initialization
autoebiten.Register("getPlayerInfo", func(ctx autoebiten.CommandContext) {
    info := fmt.Sprintf("Health: %d, Mana: %d", playerHealth, playerMana)
    ctx.Respond(info)
})

autoebiten.Register("heal", func(ctx autoebiten.CommandContext) {
    playerHealth = min(playerHealth+20, 100)
    ctx.Respond(fmt.Sprintf("Healed to %d", playerHealth))
})

The CommandContext provides:

• Request() string - The request data sent from CLI
• Respond(response string) - Send response back to CLI (can be called immediately or deferred)

CLI Side

# List available custom commands
autoebiten list_custom

# Execute a custom command
autoebiten custom getPlayerInfo

# Execute with request data
autoebiten custom echo --request "hello world"

See examples/custom_commands for a complete example.

Scripted Automation

Create a JSON script for complex sequences:

{
  "version": "1.0",
  "commands": [
    {"input": {"action": "press", "key": "KeyW"}},
    {"delay": {"ms": 100}},
    {"repeat": {"times": 3, "commands": [
      {"input": {"action": "press", "key": "KeyA"}},
      {"delay": {"ms": 200}}
    ]}}
  ]
}

Run from a file:

autoebiten run --script script.json

Or pass an inline JSON string:

autoebiten run --inline '{"version":"1.0","commands":[{"input":{"action":"press","key":"KeySpace"}}]}'

JSON Schema

Generate the JSON Schema for IDE autocompletion and validation:

autoebiten schema > autoebiten-schema.json

The schema defines all available commands, their fields, and valid values. Use it with editors that support JSON Schema for intelligent autocomplete and inline validation.

Multiple Game Instances

Each game instance uses a PID-based socket at /tmp/autoebiten/autoebiten-{PID}.sock.

Target a specific game:

autoebiten --pid 12345 input --key KeySpace --action press

Or set the socket path manually:

AUTOEBITEN_SOCKET=/tmp/autoebiten/autoebiten-12345.sock autoebiten ping

Public API

// In your game loop
autoebiten.Update()        // Process RPC commands, returns false on exit
autoebiten.Capture(screen) // Capture screenshot (call in Draw)

// Query input state
autoebiten.IsKeyPressed(key ebiten.Key)           // bool
autoebiten.IsMouseButtonPressed(button ebiten.MouseButton) // bool
autoebiten.CursorPosition()                       // (x, y int)
autoebiten.Wheel()                               // (x, y float64)

// inpututil wrappers (respect input mode)
autoebiten.IsKeyJustPressed(key ebiten.Key)       // bool
autoebiten.IsKeyJustReleased(key ebiten.Key)      // bool
autoebiten.KeyPressDuration(key ebiten.Key)       // int (ticks)
autoebiten.IsMouseButtonJustPressed(button ebiten.MouseButton)  // bool
autoebiten.IsMouseButtonJustReleased(button ebiten.MouseButton) // bool
autoebiten.MouseButtonPressDuration(button ebiten.MouseButton)  // int (ticks)

// Configure input mode
autoebiten.SetMode(autoebiten.InjectionFallback) // default: injected + real input

// Custom commands
autoebiten.Register(name string, handler func(CommandContext)) // Register a custom command
autoebiten.Unregister(name string) bool                        // Remove a custom command
autoebiten.ListCustomCommands() []string                       // List registered commands

Input Modes

The library operates in different input modes to control how real and injected inputs are combined:

Mode	Description
InjectionOnly	Only CLI-injected input is recognized
InjectionFallback	Injected input takes priority; falls back to real input (default)
Passthrough	All input passes through to ebiten directly; no injection

Build Tags

autoebiten uses build tags to control which implementation is included:

• Default (go run or go build): Full RPC server enabled. Your game listens for CLI commands via Unix socket.
• Release (go build -tags release): RPC server disabled. All functions are no-ops that delegate directly to ebiten. Use this when shipping your game to players.

# Development (default)
go build ./cmd/autoebiten

# Release build (no CLI automation)
go build -tags release ./cmd/autoebiten

Note: When using the library integration method, you need to use autoebiten.IsKeyPressed() and other wrapper functions instead of Ebiten's native functions. This may require changes if your game already uses Ebiten's input functions directly.

Deeper Integration (Patching Ebiten)

For games that use Ebiten's native input functions directly without modification, autoebiten can be integrated at the Ebiten engine level via a patch. This approach requires no code changes to your game.

Setup Instructions

1. Clone the Ebiten repository to a local directory:

git clone https://github.com/hajimehoshi/ebiten.git /path/to/ebiten
cd /path/to/ebiten
git checkout v2.9.9  # Ensure correct version

1. Apply the autoebiten patch:

git apply /path/to/autoebiten/ebiten.patch

1. In your game's go.mod, add a replace directive to use the local Ebiten:

replace github.com/hajimehoshi/ebiten/v2 => /path/to/ebiten

1. Build and run your game normally - no code changes required!

Limitations

• Version dependent: The patch relies on Ebiten's internal implementation details and has only been tested with Ebiten v2.9.9. It may not apply cleanly to other versions.
• Maintenance: You will need to re-apply the patch when updating Ebiten versions.
• Compatibility: Patch may require adjustment for significant Ebiten version changes.

License

MIT

Documentation

Index

• func Capture(screen image.Image)
• func CursorPosition() (x, y int)
• func GetCustomCommand(name string) func(CommandContext)
• func IsKeyJustPressed(key ebiten.Key) bool
• func IsKeyJustReleased(key ebiten.Key) bool
• func IsKeyPressed(key ebiten.Key) bool
• func IsMouseButtonJustPressed(button ebiten.MouseButton) bool
• func IsMouseButtonJustReleased(button ebiten.MouseButton) bool
• func IsMouseButtonPressed(button ebiten.MouseButton) bool
• func KeyPressDuration(key ebiten.Key) int
• func ListCustomCommands() []string
• func MouseButtonPressDuration(button ebiten.MouseButton) int
• func Register(name string, handler func(CommandContext))
• func SetMode(mode Mode)
• func Unregister(name string) bool
• func Update() bool
• func Wheel() (x, y float64)
• type CommandContext
• type Mode
  • func GetMode() Mode

Functions

func Capture

func Capture(screen image.Image)

Capture processes screenshots for injection.

func CursorPosition

func CursorPosition() (x, y int)

CursorPosition returns the cursor position, respecting the current mode.

func GetCustomCommand

func GetCustomCommand(name string) func(CommandContext)

GetCustomCommand returns the handler for a custom command. Returns nil if the command is not registered. This is primarily for internal use.

func IsKeyJustPressed

func IsKeyJustPressed(key ebiten.Key) bool

func IsKeyJustReleased

func IsKeyJustReleased(key ebiten.Key) bool

func IsKeyPressed

func IsKeyPressed(key ebiten.Key) bool

IsKeyPressed returns whether the key is pressed, respecting the current mode.

func IsMouseButtonJustPressed

func IsMouseButtonJustPressed(button ebiten.MouseButton) bool

func IsMouseButtonJustReleased

func IsMouseButtonJustReleased(button ebiten.MouseButton) bool

func IsMouseButtonPressed

func IsMouseButtonPressed(button ebiten.MouseButton) bool

IsMouseButtonPressed returns whether the mouse button is pressed, respecting the current mode.

func KeyPressDuration

func KeyPressDuration(key ebiten.Key) int

func ListCustomCommands

func ListCustomCommands() []string

ListCustomCommands returns a list of all registered custom command names.

func MouseButtonPressDuration

func MouseButtonPressDuration(button ebiten.MouseButton) int

func Register

func Register(name string, handler func(CommandContext))

Register registers a custom command handler. The name must be unique; registering a duplicate name will panic. The handler receives a CommandContext containing the request and a Respond method.

Example:

autoebiten.Register("getPlayerInfo", func(ctx autoebiten.CommandContext) {
	info := getPlayerInfo() // user-defined function
	ctx.Respond(fmt.Sprintf("Health: %d, Mana: %d", info.Health, info.Mana))
})

func SetMode

func SetMode(mode Mode)

SetMode sets the input handling mode.

func Unregister

func Unregister(name string) bool

Unregister removes a custom command handler. Returns true if the command was found and removed, false otherwise.

func Update

func Update() bool

Update runs the internal update loop.

func Wheel

func Wheel() (x, y float64)

Wheel returns the mouse wheel scroll amount, respecting the current mode.

Types

type CommandContext

type CommandContext = custom.Context

CommandContext provides context for custom command execution. It contains the request data and a method to send the response.

type Mode

type Mode int

Mode represents the input handling mode.

const (
	// InjectionOnly mode returns only injected input results.
	InjectionOnly Mode = iota
	// InjectionFallback mode returns injected results if available,
	// otherwise falls back to ebiten's native input handling.
	InjectionFallback
	// Passthrough mode only uses ebiten's native input handling.
	Passthrough
)

func GetMode

func GetMode() Mode

GetMode returns the current input handling mode.