Ebitengine

https://ebitengine.org/en/documents
Admin
Ebitengine is a 2D game engine written in Go that supports multiple platforms including mobile,...
Tokens:22,467
Snippets:270
Trust Score:8.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run Ebitengine Rotate Example

Source: https://ebitengine.org/en/documents/install.html

Execute a sample Ebitengine program to confirm the environment setup. This command requires Go to be installed.

```bash
go run github.com/hajimehoshi/ebiten/v2/examples/rotate@latest
```

--------------------------------

### Install ebitenmobile Command

Source: https://ebitengine.org/en/documents/mobile.html

Install the `ebitenmobile` command-line tool using `go install`. This command is essential for creating mobile bindings.

```bash
go install github.com/hajimehoshi/ebiten/v2/cmd/ebitenmobile@latest

```

--------------------------------

### Install Solus Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Solus using eopkg.

```bash
sudo eopkg install libglvnd-devel libx11-devel libxrandr-devel libxinerama-devel libxcursor-devel libxi-devel libxxf86vm-devel alsa-lib-devel pkg-config
```

--------------------------------

### Install Void Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Void Linux using xbps.

```bash
sudo xbps-install libXcursor-devel libXi-devel libXinerama-devel libXrandr-devel libXxf86vm-devel MesaLib-devel pkg-config
```

--------------------------------

### Install GCC on Ubuntu

Source: https://ebitengine.org/en/documents/install.html

Use apt to install the GCC compiler on Ubuntu systems.

```bash
apt install gcc
```

--------------------------------

### Run Shader Example

Source: https://ebitengine.org/en/documents/shader.html

Execute the shader example provided with Ebitengine to see custom shaders in action.

```bash
go run github.com/hajimehoshi/ebiten/v2/examples/shader@latest

```

--------------------------------

### Install FreeBSD Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on FreeBSD using pkg.

```bash
pkg install alsa-lib libxcursor libxi libxinerama libxrandr mesa-libs pkgconf
```

--------------------------------

### Shader Example

Source: https://ebitengine.org/en/documents/shader.html

An example of a fragment shader written in Kage, demonstrating uniform variables and pixel color calculation.

```APIDOC
## Fragment Shader Example (Kage)

### Description
This is an example of a fragment shader written in Kage. It demonstrates how to use uniform variables like `Time` and `Cursor`, access source image data, and calculate the final pixel color based on lighting effects.

### Language
Kage (Ebitengine's shading language)

### Code
```go
//kage:unit pixels

package main

// Uniform variables.
var Time float
var Cursor vec2

// Fragment is the entry point of the fragment shader.
// Fragment returns the color value for the current position.
func Fragment(dstPos vec4, srcPos vec2, color vec4) vec4 {
	// You can define variables with a short variable declaration like Go.
	pos := dstPos.xy - imageDstOrigin()

	lightpos := vec3(Cursor, 50)
	lightdir := normalize(lightpos - vec3(pos, 0))
	normal := normalize(imageSrc1UnsafeAt(srcPos) - 0.5)
	const ambient = 0.25
	diffuse := 0.75 * max(0.0, dot(normal.xyz, lightdir))

	// You can treat multiple source images by
	// imageSrc[N]At or imageSrc[N]UnsafeAt.
	return imageSrc0UnsafeAt(srcPos) * (ambient + diffuse)
}
```
```

--------------------------------

### Install Debian/Ubuntu Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Debian or Ubuntu using apt.

```bash
sudo apt install libc6-dev libgl1-mesa-dev libxcursor-dev libxi-dev libxinerama-dev libxrandr-dev libxxf86vm-dev libasound2-dev pkg-config
```

--------------------------------

### Install Alpine Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Alpine Linux using apk.

```bash
sudo apk add alsa-lib-dev libx11-dev libxrandr-dev libxcursor-dev libxinerama-dev libxi-dev mesa-dev pkgconf
```

--------------------------------

### Typical Ebitengine Game Implementation

Source: https://ebitengine.org/en/documents/cheatsheet.html

This example shows a basic implementation of the `ebiten.Game` interface and how to run it using `ebiten.RunGame`. It includes setting window size and title.

```go
// Game implements ebiten.Game interface.
type Game struct{}

// Update proceeds the game state.
// Update is called every tick (1/60 [s] by default).
func (g *Game) Update() error {
    // Write your game's logical update.
    return nil
}

// Draw draws the game screen.
// Draw is called every frame (typically 1/60[s] for 60Hz display).
func (g *Game) Draw(screen *ebiten.Image) {
    // Write your game's rendering.
}

// Layout takes the outside size (e.g., the window size) and returns the (logical) screen size.
// If you don't have to adjust the screen size with the outside size, just return a fixed size.
func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
    return 320, 240
}

func main() {
    game := &Game{}
    // Specify the window size as you like. Here, a doubled size is specified.
    ebiten.SetWindowSize(640, 480)
    ebiten.SetWindowTitle("Your game's title")
    // Call ebiten.RunGame to start your game loop.
    if err := ebiten.RunGame(game); err != nil {
        log.Fatal(err)
    }
}

```

--------------------------------

### Install Clang on FreeBSD

Source: https://ebitengine.org/en/documents/install.html

Use pkg to install the Clang compiler on FreeBSD systems.

```bash
pkg install clang
```

--------------------------------

### Install Fedora Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Fedora using dnf.

```bash
sudo dnf install libglvnd-devel libXrandr-devel libXcursor-devel libXinerama-devel libXi-devel libXxf86vm-devel alsa-lib-devel pkg-config
```

--------------------------------

### Install Arch Dependencies

Source: https://ebitengine.org/en/documents/install.html

Install necessary development libraries for Ebitengine on Arch Linux using pacman.

```bash
sudo pacman -S mesa libxrandr libxcursor libxinerama libxi pkg-config
```

--------------------------------

### Run Blocks Example with Debug Build Tag

Source: https://ebitengine.org/en/documents/performancetips.html

Execute the 'blocks' example with the 'ebitenginedebug' build tag to view detailed logs of actual drawing commands. This helps in understanding how draw calls are batched or separated.

```bash
go run -tags=ebitenginedebug github.com/hajimehoshi/ebiten/v2/examples/blocks@latest
```

--------------------------------

### Run Ebitengine Rotate Example on WSL

Source: https://ebitengine.org/en/documents/install.html

When using Windows Subsystem for Linux (WSL), set the GOOS environment variable to 'windows' before running the example.

```bash
GOOS=windows go run github.com/hajimehoshi/ebiten/v2/examples/rotate@latest
```

--------------------------------

### Notarize a macOS application

Source: https://ebitengine.org/en/documents/steam.html

Example usage of the notarize library to sign and notarize an application bundle. Requires the APP_PASSWORD environment variable to be set.

```go
package main

import (
	"fmt"
	"os"

	"github.com/hajimehoshi/notarize"
)

func main() {
	appPassword := os.Getenv("APP_PASSWORD")
	if appPassword == "" {
		fmt.Fprintln(os.Stderr, "an environment variable APP_PASSWORD must be set. see https://support.apple.com/en-us/HT204397")
		os.Exit(1)
	}

	op := &notarize.NotarizeOptions{
		AppleID:         "yourname@yourgame.example.com",
		SigningIdentity: "Developer ID Application: Your Name (YOURTEAMID)",
		TeamID:          "YOURTEAMID",
		AppPassword:     appPassword,
		ProgressOutput:  os.Stdout,
	}
	if err := notarize.Notarize("YourGame.app", op); err != nil {
		fmt.Fprintf(os.Stderr, "%v\n", err)
		os.Exit(1)
	}
}
```

--------------------------------

### Running the Game: ebiten.RunGame

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `RunGame` function starts the Ebitengine game loop, calling the `Update` and `Draw` methods of the provided `Game` implementation.

```APIDOC
## Function: ebiten.RunGame

### Description
Runs the game loop. `game`'s `Update` is called every tick and `game`'s `Draw` is called every frame. Returns an error if OpenGL, audio, or game logic errors occur.

### Signature
```go
func RunGame(game Game) error
```

### Usage Example
```go
// Game implements ebiten.Game interface.
type Game struct{}

// Update proceeds the game state.
func (g *Game) Update() error {
    // Write your game's logical update.
    return nil
}

// Draw draws the game screen.
func (g *Game) Draw(screen *ebiten.Image) {
    // Write your game's rendering.
}

// Layout takes the outside size and returns the logical screen size.
func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
    return 320, 240
}

func main() {
    game := &Game{}
    ebiten.SetWindowSize(640, 480)
    ebiten.SetWindowTitle("Your game's title")
    if err := ebiten.RunGame(game); err != nil {
        log.Fatal(err)
    }
}
```
```

--------------------------------

### iOS Binding with ebitenmobile bind

Source: https://ebitengine.org/en/documents/mobile.html

Instructions and code examples for binding an Ebitengine game to iOS using `ebitenmobile bind`.

```APIDOC
## iOS Binding with ebitenmobile bind

### Description
This section details how to bind your Ebitengine game for iOS using the `ebitenmobile bind` command. It covers the minimum required iOS version, the binding command, and how to integrate the generated `.xcframework` into an Xcode project.

### Minimum iOS Version
13.0

### Binding Command
```bash
cd /path/to/yourgame
ebitenmobile bind -target ios -o path/to/YourGame.xcframework .
```

### Integration into Xcode Project
After generating the `.xcframework`, you can integrate it into your Xcode project by either:
1. Changing the parent class of the default `ViewController` from `UIViewController` to `(Package Name)EbitenViewController`.
2. Defining a custom `ViewController` class that inherits from `(Package Name)EbitenViewController` and setting it as the custom class for the view controller in `Main.storyboard`.

### Importing the Framework
To use `(Package Name)EbitenViewController`, import your game's framework:
```objectivec
#import <YourGame/YourGame.h>
```

### EbitenViewController Definition
The view controller class in the generated `.xcframework` is defined as follows:

```objectivec
@interface YourgamemobileEbitenViewController : UIViewController

// onErrorOnGameUpdate is called on the main thread when an error happens when updating a game.
// You can define your own error handler, e.g., using Crashlytics, by overwriting this method.
- (void)onErrorOnGameUpdate:(NSError*)err;

// suspendGame suspends the game.
// It is recommended to call this when the application is being suspended e.g.,
// UIApplicationDelegate's applicationWillResignActive is called.
- (void)suspendGame;

// resumeGame resumes the game.
// It is recommended to call this when the application is being resumed e.g.,
// UIApplicationDelegate's applicationDidBecomeActive is called.
- (void)resumeGame;

@end
```

### Dependencies
- GameController.framework

### Example Project
Refer to the `go-inovation` project for a complete example of using `ebitenmobile bind`.
```

--------------------------------

### Inspect Draw Command Logs

Source: https://ebitengine.org/en/documents/performancetips.html

Example logs generated when using the 'ebitenginedebug' build tag. These logs show the details of 'draw-triangles' commands, including source and destination images, color matrices, blend modes, filters, and address modes.

```text
--
draw-triangles: dst: 7 <- src: 1, colorm: <nil>, mode copy, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 7 <- src: 2, colorm: <nil>, mode source-over, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 1, colorm: <nil>, mode clear, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 7, colorm: <nil>, mode copy, filter: screen, address: clamp_to_zero
--
draw-triangles: dst: 7 <- src: 1, colorm: <nil>, mode copy, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 7 <- src: 2, colorm: <nil>, mode source-over, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 1, colorm: <nil>, mode clear, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 7, colorm: <nil>, mode copy, filter: screen, address: clamp_to_zero
--
draw-triangles: dst: 7 <- src: 1, colorm: <nil>, mode copy, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 7 <- src: 2, colorm: <nil>, mode source-over, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 1, colorm: <nil>, mode clear, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 7, colorm: <nil>, mode copy, filter: screen, address: clamp_to_zero
--
draw-triangles: dst: 7 <- src: 1, colorm: <nil>, mode copy, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 7 <- src: 2, colorm: <nil>, mode source-over, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 1, colorm: <nil>, mode clear, filter: nearest, address: clamp_to_zero
draw-triangles: dst: 8 (screen) <- src: 7, colorm: <nil>, mode copy, filter: screen, address: clamp_to_zero
--
...
```

--------------------------------

### Copy wasm_exec.js (Unix/Linux)

Source: https://ebitengine.org/en/documents/webassembly.html

Copy the wasm_exec.js file, which is required to run WebAssembly binaries, from the Go installation directory. Use the appropriate path based on your Go version.

```bash
# Go 1.24 and newer
cp $(go env GOROOT)/lib/wasm/wasm_exec.js .

# Go 1.23 and older
cp $(go env GOROOT)/misc/wasm/wasm_exec.js .

```

--------------------------------

### Get Image Size

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `Size` method returns the width and height of an `Image` in pixels.

```go
func (i *Image) Size() (width, height int)

```

--------------------------------

### Kage Fragment Shader Example

Source: https://ebitengine.org/en/documents/shader.html

A basic fragment shader written in Kage that calculates pixel colors based on cursor position and image data. It uses pixel mode for unit calculations.

```kage
//kage:unit pixels

package main

// Uniform variables.
var Time float
var Cursor vec2

// Fragment is the entry point of the fragment shader.
// Fragment returns the color value for the current position.
func Fragment(dstPos vec4, srcPos vec2, color vec4) vec4 {
	// You can define variables with a short variable declaration like Go.
	pos := dstPos.xy - imageDstOrigin()

	lightpos := vec3(Cursor, 50)
	lightdir := normalize(lightpos - vec3(pos, 0))
	normal := normalize(imageSrc1UnsafeAt(srcPos) - 0.5)
	const ambient = 0.25
	diffuse := 0.75 * max(0.0, dot(normal.xyz, lightdir))

	// You can treat multiple source images by
	// imageSrc[N]At or imageSrc[N]UnsafeAt.
	return imageSrc0UnsafeAt(srcPos) * (ambient + diffuse)
}

```

--------------------------------

### Run Ebitengine Game

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `RunGame` function starts the Ebitengine game loop. It calls the `Update` and `Draw` methods of the provided `Game` implementation. Ensure `RunGame` is called only once per process.

```go
func RunGame(game Game) error

```

--------------------------------

### Get Vector Path Bounds

Source: https://ebitengine.org/en/documents/2.9.html

Calculates the bounding box of a vector path. This is a new API introduced in v2.9.0.

```go
(*vector.Path).Bounds
```

--------------------------------

### Copy wasm_exec.js (Windows PowerShell)

Source: https://ebitengine.org/en/documents/webassembly.html

Copy the wasm_exec.js file, required for running WebAssembly binaries, from the Go installation directory on Windows. The path varies slightly for Go versions 1.24+ and older.

```powershell
$goroot = go env GOROOT

# Go 1.24 and newer
cp $goroot\lib\wasm\wasm_exec.js .

# Go 1.23 and older
cp $goroot\misc\wasm\wasm_exec.js .

```

--------------------------------

### Resolve AudioContext Autoplay Issue

Source: https://ebitengine.org/en/documents/webassembly.html

If you encounter the 'AudioContext was not allowed to start' error in Chrome, add the 'allow="autoplay"' attribute to the iframe element in your host HTML.

```html
The AudioContext was not allowed to start. It must be resume (or created) after a user gesture on the page. https://goo.gl/7K7WLu

```

--------------------------------

### Initialize Ebitengine Project

Source: https://ebitengine.org/en/documents/install.html

Set up a new Ebitengine project by creating a directory, navigating into it, and initializing the Go module.

```bash
# Create a directory for your game.
mkdir yourgame
cd yourgame

# Initialize go.mod by `go mod init`.
go mod init github.com/yourname/yourgame
```

--------------------------------

### Ebitengine Hello World Program

Source: https://ebitengine.org/en/documents/install.html

A basic Ebitengine program that displays 'Hello, World!' in a window. This code requires the ebiten package.

```go
package main

import (
	"log"

	"github.com/hajimehoshi/ebiten/v2"
	"github.com/hajimehoshi/ebiten/v2/ebitenutil"
)

type Game struct{}

func (g *Game) Update() error {
	return nil
}

func (g *Game) Draw(screen *ebiten.Image) {
	ebitenutil.DebugPrint(screen, "Hello, World!")
}

func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
	return 320, 240
}

func main() {
	ebiten.SetWindowSize(640, 480)
	ebiten.SetWindowTitle("Hello, World!")
	if err := ebiten.RunGame(&Game{}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Initializing Vector and Matrix Types

Source: https://ebitengine.org/en/documents/shader.html

Demonstrates how to initialize vector and matrix types in Kage using their type names as functions. Supports various argument combinations for flexibility.

```kage
v1 := vec4(0)              // Returns a vec4 whose components are all 0.
v2 := vec4(1, 2, 3, 4)     // Returns a vec4 whose components are 1, 2, 3 and 4.
v3 := vec3(5, 6, 7)
v4 := vec4(1, v3)          // Returns a vec4 whose components are 1, 5, 6 and 7.
```

```kage
m1 := mat4(2)              // Returns a mat4 whose diagonal components are 2 and the others are 0.
m2 := mat4(v1, v2, v3, v1) // Returns a mat4 whose columns are v1, v2, v3 and v1.
```

--------------------------------

### Create Mobile Binding Package

Source: https://ebitengine.org/en/documents/mobile.html

Set up a Go package for mobile use with `ebitenmobile`. Ensure your game implements the `ebiten.Game` interface and use `mobile.SetGame` to register it. A dummy exported function is required for `gomobile` to compile.

```go
package yourgamemobile

import (
    "github.com/hajimehoshi/ebiten/v2"
    "github.com/hajimehoshi/ebiten/v2/mobile"

    "github.com/yourname/yourgame"
)

func init() {
    // yourgame.Game must implement ebiten.Game interface.
    // For more details, see
    // * https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2#Game
    mobile.SetGame(&yourgame.Game{})
}

// Dummy is a dummy exported function.
//
// gomobile doesn't compile a package that doesn't include any exported function.
// Dummy forces gomobile to compile this package.
func Dummy() {}

```

--------------------------------

### Run Ebitengine Program

Source: https://ebitengine.org/en/documents/install.html

Execute your Ebitengine application using the 'go run' command in the project's root directory.

```bash
go run .
```

--------------------------------

### Get Mouse Cursor Position

Source: https://ebitengine.org/en/documents/cheatsheet.html

Returns the current (x, y) coordinates of the mouse cursor on the screen.

```go
func CursorPosition() (x, y int)
```

--------------------------------

### Create a macOS .app bundle

Source: https://ebitengine.org/en/documents/steam.html

A shell script to build a universal binary for amd64 and arm64, organize the bundle structure, and generate the Info.plist file.

```bash
name=yourgame
app_name=YourGame.app
bundle_id=com.example.yourgame

rm -rf ${app_name}
mkdir -p ${app_name}/Contents/MacOS
mkdir -p ${app_name}/Contents/Resources
env CGO_ENABLED=1 CGO_CFLAGS=-mmacosx-version-min=10.12 CGO_LDFLAGS=-mmacosx-version-min=10.12 GOARCH=amd64 go build -o ${name}_amd64 .
env CGO_ENABLED=1 CGO_CFLAGS=-mmacosx-version-min=10.12 CGO_LDFLAGS=-mmacosx-version-min=10.12 GOARCH=arm64 go build -o ${name}_arm64 .
lipo ${name}_amd64 ${name}_arm64 -create -output ${app_name}/Contents/MacOS/${name}
rm ${name}_amd64
rm ${name}_arm64
cp icon.icns ${app_name}/Contents/Resources/icon.icns
echo '<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleExecutable</key>
    <string>{{.Name}}</string>
    <key>CFBundleIdentifier</key>
    <string>{{.BundleID}}</string>
    <key>CFBundleIconFile</key>
    <string>icon.icns</string>
    <key>CFBundleVersion</key>
    <string>0.0.0</string>
    <key>CFBundleShortVersionString</key>
    <string>0.0.0</string>
    <key>NSHighResolutionCapable</key>
    <true />
    <key>LSMinimumSystemVersion</key>
    <string>10.12.0</string>
  </dict>
</plist>' |
    sed -e "s/{{.Name}}/${name}/g" |
    sed -e "s/{{.BundleID}}/${bundle_id}/g" > ${app_name}/Contents/Info.plist
```

--------------------------------

### Why use ebitenmobile bind?

Source: https://ebitengine.org/en/documents/mobile.html

Explains the advantages of using `ebitenmobile bind` over `gomobile bind` and why a shared library approach is preferred over a complete application.

```APIDOC
## Why use ebitenmobile bind?

### Advantages over gomobile bind
- Requires less boilerplate code.
- Hides implementation details completely (e.g., graphics backend like OpenGL ES or Metal), allowing for future updates like Vulkan migration without affecting the user.

### Why not a complete application?
It is not feasible to write a complete mobile application solely in Go at this time due to:
- The need to access native APIs for various features.
- The common requirement to integrate native components (e.g., ad banners).
- The complexities of handling certifications and other files required for app store submission, which are typically managed by IDEs like Android Studio or Xcode.
```

--------------------------------

### Basic HTML for WebAssembly Execution

Source: https://ebitengine.org/en/documents/webassembly.html

Create an HTML file that includes wasm_exec.js and uses WebAssembly.instantiateStreaming to load and run your compiled Go WebAssembly binary.

```html
<!DOCTYPE html>
<script src="wasm_exec.js"></script>
<script>
const go = new Go();
WebAssembly.instantiateStreaming(fetch("yourgame.wasm"), go.importObject).then(result => {
    go.run(result.instance);
});
</script>

```

--------------------------------

### Build Ebitengine for Windows using PowerShell

Source: https://ebitengine.org/en/documents/steam.html

Use this command sequence in PowerShell to build your game for Windows while applying necessary ldflags to prevent freezing and hide the console window.

```powershell
$Env:GOARCH = 'amd64'
go build -o yourgame_windows_amd64.exe -ldflags="-X=runtime.godebugDefault=asyncpreemptoff=1 -H=windowsgui" .
Remove-Item Env:GOARCH
```

--------------------------------

### Get SubImage

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `SubImage` method returns a new `Image` representing a rectangular portion of the original image. The returned image shares pixels with the original and is available as a rendering source.

```go
func (i *Image) SubImage(r image.Rectangle) image.Image

```

--------------------------------

### Initialize Steamworks and check app launch

Source: https://ebitengine.org/en/documents/steam.html

Use this snippet to ensure the application was launched via the Steam client and to initialize the Steamworks SDK.

```go
package main

import (
	"fmt"
	"os"

	"github.com/hajimehoshi/go-steamworks"
)

const appID = 480 // Use your application ID.

func init() {
	if steamworks.RestartAppIfNecessary(appID) {
		os.Exit(1)
	}
	if err := steamworks.Init(); err != nil {
		panic(fmt.Sprintf("steamworks.Init failed: %v", err))
	}
}
```

--------------------------------

### Create Image from image.Image

Source: https://ebitengine.org/en/documents/cheatsheet.html

`NewImageFromImage` creates a new Ebitengine `Image` from a standard Go `image.Image`.

```go
func NewImageFromImage(source image.Image) *Image

```

--------------------------------

### Build Game as GUI App on Windows

Source: https://ebitengine.org/en/documents/faq.html

Use this ldflag when building your game with `go build` to prevent an unknown process like "Console Window Host" from appearing on Windows. This flag helps identify your application as a GUI app rather than a console app.

```bash
go build -ldflags -H=windowsgui path/to/your/game
```

--------------------------------

### Create Player for Short Sound Effect in Go

Source: https://ebitengine.org/en/documents/performancetips.html

It is acceptable to create a new audio player for each short sound effect. This function uses `NewPlayerFromBytes` to create a player from raw byte data.

```Go
// PlaySE plays a sound effect.
func PlaySE(bs []byte) {
    sePlayer := audioContext.NewPlayerFromBytes(bs)
    // sePlayer is never GCed as long as it plays.
    sePlayer.Play()
}

```

--------------------------------

### Add Ebitengine Dependencies

Source: https://ebitengine.org/en/documents/install.html

Run 'go mod tidy' in your project directory to automatically download and add Ebitengine and its dependencies to your go.mod file.

```bash
go mod tidy
```

--------------------------------

### Create New Image

Source: https://ebitengine.org/en/documents/cheatsheet.html

`NewImage` creates a new, empty image with the specified width and height.

```go
func NewImage(width, height int) *Image

```

--------------------------------

### Build Linux Binaries with Steam Runtime

Source: https://ebitengine.org/en/documents/steam.html

Uses a Docker container based on the Steam Runtime Sniper environment to compile the game for Linux.

```bash
name=yourgame
STEAM_RUNTIME_VERSION=3.0.20250108.112707
GO_VERSION=$(go env GOVERSION)

mkdir -p .cache/${STEAM_RUNTIME_VERSION}

# Download binaries for amd64.
if [[ ! -f .cache/${STEAM_RUNTIME_VERSION}/com.valvesoftware.SteamRuntime.Sdk-amd64,i386-sniper-sysroot.Dockerfile ]]; then
    (cd .cache/${STEAM_RUNTIME_VERSION}; curl --location --remote-name https://repo.steampowered.com/steamrt-images-sniper/snapshots/${STEAM_RUNTIME_VERSION}/com.valvesoftware.SteamRuntime.Sdk-amd64,i386-sniper-sysroot.Dockerfile)
fi
if [[ ! -f .cache/${STEAM_RUNTIME_VERSION}/com.valvesoftware.SteamRuntime.Sdk-amd64,i386-sniper-sysroot.tar.gz ]]; then
    (cd .cache/${STEAM_RUNTIME_VERSION}; curl --location --remote-name https://repo.steampowered.com/steamrt-images-sniper/snapshots/${STEAM_RUNTIME_VERSION}/com.valvesoftware.SteamRuntime.Sdk-amd64,i386-sniper-sysroot.tar.gz)
fi
if [[ ! -f .cache/${GO_VERSION}.linux-amd64.tar.gz ]]; then
    (cd .cache; curl --location --remote-name https://golang.org/dl/${GO_VERSION}.linux-amd64.tar.gz)
fi

# Build for amd64
(cd .cache/${STEAM_RUNTIME_VERSION}; docker build -f com.valvesoftware.SteamRuntime.Sdk-amd64,i386-sniper-sysroot.Dockerfile -t steamrt_sniper_amd64:latest .)
docker run --rm --workdir=/work --volume $(pwd):/work steamrt_sniper_amd64:latest /bin/sh -c "
export PATH=\$PATH:/usr/local/go/bin
export CGO_CFLAGS=-std=gnu99

rm -rf /usr/local/go && tar -C /usr/local -xzf .cache/${GO_VERSION}.linux-amd64.tar.gz

go build -o ${name}_linux_amd64 .
"
```

--------------------------------

### Fragment Shader Entry Point Signatures

Source: https://ebitengine.org/en/documents/shader.html

Defines the possible function signatures for the entry point of a Kage fragment shader. The signature determines the available input parameters.

```kage
func Fragment() vec4
```

```kage
func Fragment(dstPos vec4) vec4
```

```kage
func Fragment(dstPos vec4, srcPos vec2) vec4
```

```kage
func Fragment(dstPos vec4, srcPos vec2, color vec4) vec4
```

```kage
func Fragment(dstPos vec4, srcPos vec2, color vec4, custom vec4) vec4
```

--------------------------------

### Run Game with WasmServe

Source: https://ebitengine.org/en/documents/webassembly.html

Use wasmserve to quickly test your Go game in a browser. Access the game at http://localhost:8080/.

```bash
go run github.com/hajimehoshi/wasmserve@latest ./path/to/yourgame

```

--------------------------------

### Build Ebitengine for Windows using POSIX shell

Source: https://ebitengine.org/en/documents/steam.html

Use this command in a POSIX shell to build your game for Windows with the required ldflags for Steam compatibility.

```bash
env GOOS=windows GOARCH=amd64 go build -o yourgame_windows_amd64.exe -ldflags="-X=runtime.godebugDefault=asyncpreemptoff=1 -H=windowsgui" .
```

--------------------------------

### Compile Go Game to Wasm (Windows PowerShell)

Source: https://ebitengine.org/en/documents/webassembly.html

Compile your Go game into a WebAssembly binary for browser execution on Windows using PowerShell. This sets environment variables and then cleans them up.

```powershell
$Env:GOOS = 'js'
$Env:GOARCH = 'wasm'
go build -o yourgame.wasm github.com/yourname/yourgame
Remove-Item Env:GOOS
Remove-Item Env:GOARCH

```

--------------------------------

### Take Screenshot with Ebitengine

Source: https://ebitengine.org/en/documents/faq.html

To enable screenshots, set the `EBITENGINE_SCREENSHOT_KEY` environment variable to your desired key. Pressing this key during runtime will trigger a screenshot.

```bash
EBITENGINE_SCREENSHOT_KEY=q go run .
```

--------------------------------

### Download wasm_exec.js from GitHub

Source: https://ebitengine.org/en/documents/webassembly.html

If wasm_exec.js is not found locally, download it directly from the Go GitHub repository using the specific version tag that matches your Go compiler.

```bash
https://raw.githubusercontent.com/golang/go/refs/tags/go1.24.5/lib/wasm/wasm_exec.js

```

--------------------------------

### Textures and Images Explanation

Source: https://ebitengine.org/en/documents/shader.html

Explanation of Ebitengine's image representation as part of an internal texture and the differences between pixel and texel modes.

```APIDOC
## Textures and Images

Ebitengine's image (`ebiten.Image`) is actually a part of an internal texture.

In pixel mode, all units are in pixels, so there's not much to be particularly aware of. On the other hand, in texel mode, the coordinate calculations on the shader become a bit more complex. The following explanation is mainly for when using texel mode.

A pixel is a unit for one color dot. On the other hand, texel is a unit covering the whole area with values in between 0 and 1. The meaning of texels depends on a texture, then you cannot mix texels with different textures.

To convert pixels and texels each other, you can use these formulas:

(texels) = (pixels) / (the texture’s size in pixels)
(pixels) = (texels) * (the texture’s size in pixels)

\begin{aligned}
(\text{texels}) &= \frac{(\text{pixels})}{(\text{the texture's size in pixels})} \\
(\text{pixels}) &= (\text{texels}) \cdot (\text{the texture's size in pixels}) \
\end{aligned}
```

--------------------------------

### Compile Go Game to Wasm (Unix/Linux)

Source: https://ebitengine.org/en/documents/webassembly.html

Compile your Go game into a WebAssembly binary for browser execution on Unix-like systems. Ensure GOOS and GOARCH are set to 'js' and 'wasm' respectively.

```bash
env GOOS=js GOARCH=wasm go build -o yourgame.wasm github.com/yourname/yourgame

```

--------------------------------

### Generate Android AAR with ebitenmobile

Source: https://ebitengine.org/en/documents/mobile.html

Use the `ebitenmobile bind` command to create an Android Archive (`.aar`) file. Specify the target platform, Java package name, output path, and the current directory containing your Go package.

```bash
cd /path/to/yourgame
ebitenmobile bind -target android -javapkg your.package.name -o path/to/yourgame.aar .

```

--------------------------------

### Fill Image with Color

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `Fill` method fills the entire `Image` with a specified solid color.

```go
func (i *Image) Fill(clr color.Color)

```

--------------------------------

### Set Window Mouse Pass Through

Source: https://ebitengine.org/en/documents/2.9.html

Configures whether mouse events are passed through the Ebitengine window. Fixed to work properly when called before startup.

```go
ebiten.SetWindowMousePassThrough
```

--------------------------------

### NewShader Function Signature

Source: https://ebitengine.org/en/documents/shader.html

Compiles a Kage shader program. Returns an error if compilation fails.

```go
func NewShader(src []byte) (*Shader, error)

```

--------------------------------

### Set Android Environment Variables

Source: https://ebitengine.org/en/documents/mobile.html

Configure necessary environment variables for Android development on macOS. This includes setting `ANDROID_HOME` and adding the Android SDK `platform-tools` to your PATH.

```bash
# macOS
export ANDROID_HOME=~/Library/Android/sdk
export PATH=/Applications/Android\ Studio.app/Contents/jbr/Contents/Home/bin:$PATH

```

--------------------------------

### Import Game Framework in Xcode

Source: https://ebitengine.org/en/documents/mobile.html

Import your game's generated framework into your Xcode project to access its classes, such as the Ebiten view controller.

```objective-c
#import <YourGame/YourGame.h>

```

--------------------------------

### Bind Ebitengine Game for iOS

Source: https://ebitengine.org/en/documents/mobile.html

Use this command to generate an .xcframework for your Ebitengine game, which can then be integrated into an Xcode project.

```bash
cd /path/to/yourgame
ebitenmobile bind -target ios -o path/to/YourGame.xcframework .

```

--------------------------------

### Ebitengine Shader API

Source: https://ebitengine.org/en/documents/shader.html

APIs for creating and drawing with shaders in Ebitengine.

```APIDOC
## Ebitengine Shader API

### `NewShader`

#### Description
Compiles a shader program in the shading language Kage and returns the compiled shader. Returns an error if compilation fails.

#### Signature
```go
func NewShader(src []byte) (*Shader, error)
```

### `(*Image).DrawRectShader`

#### Description
Draws a rectangle with the specified width and height using the provided shader.

#### Signature
```go
func DrawRectShader(width, height int, shader *Shader, options *DrawRectShaderOptions)
```

### `DrawRectShaderOptions`

#### Description
Represents options for `DrawRectShader`.

#### Fields
- **GeoM** (`GeoM`) - Optional - A geometry matrix to apply to the drawing. Defaults to the identity matrix.
- **CompositeMode** (`CompositeMode`) - Optional - The composite mode to use for drawing. Defaults to regular alpha blending.
- **Uniforms** (`map[string]interface{}`) - Optional - A map of uniform variables for the shader. Keys are variable names, and values must be `float` or `[]float`. For array, vector, or matrix types, provide flattened slice values.
- **Images** (`[4]*Image`) - Optional - An array of up to 4 source images for the shader. All images must have the same dimensions as the rectangle being drawn.
```

--------------------------------

### Resample Audio Reader (F32)

Source: https://ebitengine.org/en/documents/2.9.html

Creates a new audio.ResampleReaderF32 for resampling audio data with F32 format. Replaces the deprecated audio.ResampleF32 function.

```go
audio.ResampleReaderF32
```

--------------------------------

### Vector Swizzling Operations

Source: https://ebitengine.org/en/documents/shader.html

Illustrates the swizzling operation for vector types in Kage, allowing for reading and writing multiple components simultaneously. Component groups must be consistent (e.g., all from xyzw or rgba).

```kage
v1 := vec4(1, 2, 3, 4)
v2 := v1.xyz           // Get vec3(1, 2, 3) and initialize v2 with this.
v2.xyz = v2.xxx        // Get vec3(1, 1, 1), and set it to all the components to v2.
                       // Then, v2 is now (1, 1, 1).
```

--------------------------------

### Min, Max, and Clamp

Source: https://ebitengine.org/en/documents/shader.html

Functions to find minimum, maximum, and clamp values within a range.

```APIDOC
## Min, Max, and Clamp

### `min(args ...T) T`
Returns the minimum value of args. Up to Ebitengine v2.8, the number of arguments was limited to 2.

### `max(args ...T) T`
Returns the maximum value of args. Up to Ebitengine v2.8, the number of arguments was limited to 2.

### `clamp(x, min_value, max_value T) T`
Returns min(max(x, min_value), max_value).
```

--------------------------------

### Kage Shading Language

Source: https://ebitengine.org/en/documents/shader.html

Information about the Kage shading language, its syntax, and unit modes.

```APIDOC
## Shading Language Kage

### Syntax
Kage's syntax is largely compatible with Go. It supports basic Go syntax but omits advanced features like structs, interfaces, pointers, goroutines, and certain built-in functions. `gofmt` can be used for formatting.

### Unit Mode
Kage supports unit modes specified via compiler directives:
- `//kage:unit texels` (Default, backward compatible)
- `//kage:unit pixels` (Recommended for new programs)

In pixel mode, all units within the Kage shader are interpreted as pixels, simplifying coordinate handling.
```

--------------------------------

### Archive the application for Steamworks

Source: https://ebitengine.org/en/documents/steam.html

Use the ditto command to create a zip file, ensuring special files within the notarized .app bundle are preserved.

```bash
ditto -c -k --keepParent YourGame.app yourgame_darwin.zip
```

--------------------------------

### Core Game Loop: ebiten.Game Interface

Source: https://ebitengine.org/en/documents/cheatsheet.html

The `Game` interface defines the essential functions for a game's lifecycle: Update, Draw, and Layout.

```APIDOC
## Interface: ebiten.Game

### Description
Defines the necessary functions for a game's lifecycle.

### Methods
- **Update() error**: Updates the game state by one tick.
- **Draw(screen *Image)**: Draws the game screen. The argument `screen` is the render target.
- **Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int)**: Accepts a native outside size and returns the game's logical screen size, adjusting rendering scale automatically.
```

--------------------------------

### Debug Print String on Image

Source: https://ebitengine.org/en/documents/cheatsheet.html

Use `ebitenutil.DebugPrint` to draw a string on the top-left corner of an image. This function is part of the `ebitenutil` package.

```go
func DebugPrint(image *ebiten.Image, str string)

```

--------------------------------

### Draw Path Options

Source: https://ebitengine.org/en/documents/2.9.html

Options for drawing paths in vector graphics. This is a new API introduced in v2.9.0.

```go
vector.DrawPathOptions
```

--------------------------------

### Exponential and Logarithmic Functions

Source: https://ebitengine.org/en/documents/shader.html

Includes functions for exponentiation, logarithms, and powers.

```APIDOC
## Exponential and Logarithmic Functions

### `pow(x, y T) T`
Returns x^y.

### `exp(x T) T`
Returns e^x.

### `log(x T) T`
Returns log_e(x).

### `exp2(x T) T`
Returns 2^x.

### `log2(x T) T`
Returns log_2(x).
```

--------------------------------

### SubImage Caching

Source: https://ebitengine.org/en/documents/2.9.html

The result of (*ebiten.Image).SubImage() is now cached internally for a certain period, improving performance.

```go
(*ebiten.Image).SubImage()
```

--------------------------------

### Trigonometric Functions

Source: https://ebitengine.org/en/documents/shader.html

Provides standard trigonometric functions like sine, cosine, and tangent, along with their inverse counterparts.

```APIDOC
## Trigonometric Functions

### `sin(x T) T`
Returns sin(x).

### `cos(x T) T`
Returns cos(x).

### `tan(x T) T`
Returns tan(x).

### `asin(x T) T`
Returns arcsin(x).

### `acos(x T) T`
Returns arccos(x).

### `atan(y_over_x T) T`
Returns arctan(y/x).

### `atan2(y, x T) T`
Returns arctan(y/x).
```

--------------------------------

### Ebiten View Controller Definition (Objective-C)

Source: https://ebitengine.org/en/documents/mobile.html

This Objective-C code defines the structure of the Ebiten view controller generated by `ebitenmobile bind`. It includes methods for handling errors, suspending, and resuming the game.

```objective-c
#import <UIKit/UIKit.h>

@interface YourgamemobileEbitenViewController : UIViewController

// onErrorOnGameUpdate is called on the main thread when an error happens when updating a game.
// You can define your own error handler, e.g., using Crashlytics, by overwriting this method.
- (void)onErrorOnGameUpdate:(NSError*)err;

// suspendGame suspends the game.
// It is recommended to call this when the application is being suspended e.g.,
// UIApplicationDelegate's applicationWillResignActive is called.
- (void)suspendGame;

// resumeGame resumes the game.
// It is recommended to call this when the application is being resumed e.g.,
// UIApplicationDelegate's applicationDidBecomeActive is called.
- (void)resumeGame;

@end

```

--------------------------------

### Set Android Activity Context

Source: https://ebitengine.org/en/documents/mobile.html

In your Android `MainActivity`, call `Seq.setContext` with the application context during `onCreate`. This is crucial for the Go runtime to function correctly within the Android environment.

```java
package your.package.name.yourgamemobile;

import androidx.appcompat.app.AppCompatActivity;
import go.Seq;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Seq.setContext(getApplicationContext());
        // ...
    }
}

```

--------------------------------

### Resample Audio Reader

Source: https://ebitengine.org/en/documents/2.9.html

Creates a new audio.ResampleReader for resampling audio data. Replaces the deprecated audio.Resample function.

```go
audio.ResampleReader
```

--------------------------------

### Color Scale Image Options

Source: https://ebitengine.org/en/documents/2.9.html

Options for drawing images with a color scale. This is a new API introduced in v2.9.0.

```go
colorm.DrawImageOptions.ColorScale
```

--------------------------------

### Avoid Cyclic Drawing

Source: https://ebitengine.org/en/documents/performancetips.html

Demonstrates a cyclic drawing pattern where image A draws image B, and image B draws image A. This pattern should be avoided to prevent potential issues.

```go
A.DrawImage(B, op)
B.DrawImage(A, op) // cyclic drawing! Avoid this if possible.
```

--------------------------------

### Enable Apple Press and Hold

Source: https://ebitengine.org/en/documents/2.9.html

Enables or disables the Apple press-and-hold behavior for the game. This is a new API introduced in v2.9.0.

```go
ebiten.RunGameOptions.ApplePressAndHoldEnabled
```

--------------------------------

### DrawImageOptions Structure

Source: https://ebitengine.org/en/documents/cheatsheet.html

Defines options for rendering an image, including geometry, color scaling, blending, and filtering.

```go
type DrawImageOptions struct {
    // GeoM is a geometry matrix to draw.
    // The default (zero) value is identify, which draws the image at (0, 0).
    GeoM GeoM

    // ColorScale is a scale of color.
    // The default (zero) value is identity, which is (1, 1, 1, 1).
    ColorScale ColorScale

    // Blend is a blending way of the source color and the destination color.
    // The default (zero) value is regular alpha blending.
    Blend Blend

    // Filter is a type of texture filter.
    // The default (zero) value is FilterNearest.
    Filter Filter
}
```

--------------------------------

### ebiten.MouseButton Type

Source: https://ebitengine.org/en/documents/cheatsheet.html

Defines the available mouse buttons.

```APIDOC
## `ebiten.MouseButton` Type

### Description
`MouseButton` represents a mouse button.

### Constants
- **MouseButtonLeft**
- **MouseButtonRight**
- **MouseButtonMiddle**

### Type Definition
`type MouseButton int`
```

--------------------------------

### Utility Function: ebitenutil.DebugPrint

Source: https://ebitengine.org/en/documents/cheatsheet.html

A utility function to draw a string on an image at the top-left corner.

```APIDOC
## Function: ebitenutil.DebugPrint

### Description
Draws the given string `str` on the `image` at the top-left corner.

### Signature
```go
func DebugPrint(image *ebiten.Image, str string)
```
```

--------------------------------

### Set Default Draw Final Screen

Source: https://ebitengine.org/en/documents/2.9.html

Configures the default draw final screen behavior. This is a new API introduced in v2.9.0.

```go
ebiten.DefaultDrawFinalScreen
```

--------------------------------

### Draw Triangles with Options

Source: https://ebitengine.org/en/documents/2.9.html

Draws triangles with specific options. This is a new API introduced in v2.9.0.

```go
(*ebiten.Image).DrawTriangles32
```

--------------------------------

### Embed WebAssembly Game using Iframe

Source: https://ebitengine.org/en/documents/webassembly.html

Embed your WebAssembly game into a host HTML page using an iframe. This method allows for automatic screen scaling and is recommended for integration.

```html
<!DOCTYPE html>
<iframe src="main.html" width="640" height="480"></iframe>

```
Tokens:
Raw