README
¶
kukichalang/game
A beginner-friendly 2D game library for Kukicha, wrapping Ebitengine with a simple, pipe-friendly API. Build browser games with WebAssembly — no game engine experience required.
Install
Requires the Kukicha compiler. The game package is part of Kukicha's standard library — just import it:
import "stdlib/game"
Quick Start
import "stdlib/game"
function main()
_ = game.Window("My Game", 640, 480)
|> game.OnDraw(draw)
|> game.Run() onerr panic "{error}"
function draw(screen game.Screen)
game.Clear(screen, game.MakeColor(30, 30, 60, 255))
game.DrawText(screen, "Hello, Kukicha!", 240, 220, game.White)
Build for the browser:
kukicha build --wasm my-game.kuki
# Produces: my-game.wasm, wasm_exec.js, index.html
API
Window & Lifecycle
| Function | Description |
|---|---|
game.Window(title, width, height) |
Create a game window |
game.OnSetup(app, fn) |
Register a one-time setup callback |
game.OnUpdate(app, fn) |
Register a per-frame update callback |
game.OnDraw(app, fn) |
Register a per-frame draw callback |
game.Run(app) |
Start the game loop |
All builder functions return App and are designed for pipe chains:
_ = game.Window("Breakout", 800, 600)
|> game.OnSetup(setup)
|> game.OnUpdate(update)
|> game.OnDraw(draw)
|> game.Run() onerr panic "{error}"
Drawing
| Function | Description |
|---|---|
game.Clear(screen, color) |
Fill the screen with a solid color |
game.DrawRect(screen, x, y, w, h, color) |
Draw a filled rectangle |
game.DrawCircle(screen, x, y, radius, color) |
Draw a filled circle |
game.DrawLine(screen, x1, y1, x2, y2, color) |
Draw a line between two points |
game.DrawText(screen, text, x, y, color) |
Draw debug text |
Input
| Function | Description |
|---|---|
game.IsKeyDown(key) |
true if the key is currently held |
game.IsKeyPressed(key) |
true if the key was just pressed this frame |
game.MousePosition() |
Current cursor position (float64, float64) |
game.MouseClicked() |
true if left mouse button was just clicked |
Key constants: KeyLeft, KeyRight, KeyUp, KeyDown, KeySpace, KeyEnter, KeyEscape
Collision Detection
| Function | Description |
|---|---|
game.Overlaps(a, b) |
Two rectangles overlap |
game.OverlapsCircle(a, b) |
Two circles overlap |
game.CircleOverlapsRect(c, r) |
Circle and rectangle overlap |
Utilities
| Function | Description |
|---|---|
game.MakeColor(r, g, b, a) |
Create a color from RGBA (0-255) |
game.Random(min, max) |
Random int in [min, max) |
game.RandomFloat(min, max) |
Random float64 in [min, max) |
game.FrameCount() |
Frames elapsed since game start |
Types
Color— RGBA color (R, G, B, A int)Position— X, Y coordinate (float64)Size— Width, Height (float64)Rect— X, Y, Width, Height (float64) — for drawing and collisionCircle— X, Y, Radius (float64) — for drawing and collisionScreen— Draw target (passed to your draw callback)App— Game configuration (built viaWindow+ builder functions)
Color Constants
Red, Green, Blue, White, Black, Yellow, Orange, Purple, Gray
Tutorials
The Kukicha repo includes an 8-lesson game tutorial series that builds up to a full Breakout clone:
- Hello World — Window, text, colors
- Drawing Shapes — Rectangles, circles, lines
- Keyboard Input — Moving objects with keys
- Animation — Frame-based movement
- Collision — Detecting overlaps
- Score & State — Game state management
- Sound & Setup — Audio and initialization
- Breakout — Full game project
Architecture
This package is a separate Go module (codeberg.org/kukichalang/game) that wraps Ebitengine. The Kukicha compiler maps import "stdlib/game" to this module automatically. A registry stub in the main Kukicha repo (stdlib/game/game.kuki) provides type information for compile-time checks.
WASM-only build constraint
The generated game.go has a //go:build js constraint. Ebitengine's native backends require platform-specific headers (X11 on Linux) which aren't needed for WASM games. The Kukicha compiler automatically adds this constraint to both the game package and any user code that imports stdlib/game, so go build ./... and go test ./... skip game code on native platforms. Always build with kukicha build --wasm.
Acknowledgements
This package is built on Ebitengine by Hajime Hoshi — a production-grade 2D game engine for Go. Ebitengine is licensed under Apache 2.0.
Development
go get codeberg.org/kukichalang/kukicha@v0.50.0 (version you are targetting)
go mod tidy
rm main.go
kukicha brew game.kuki
GOOS=js GOARCH=wasm go build ./...
License
MIT
Documentation
¶
Index ¶
- Variables
- func CircleOverlapsRect(c Circle, r Rect) bool
- func Clear(screen Screen, c Color)
- func DrawCircle(screen Screen, x float64, y float64, radius float64, c Color)
- func DrawLine(screen Screen, x1 float64, y1 float64, x2 float64, y2 float64, c Color)
- func DrawRect(screen Screen, x float64, y float64, w float64, h float64, c Color)
- func DrawText(screen Screen, msg string, x int, y int, _ Color)
- func FrameCount() int64
- func IsKeyDown(key ebiten.Key) bool
- func IsKeyPressed(key ebiten.Key) bool
- func MouseClicked() bool
- func MousePosition() (float64, float64)
- func Overlaps(a Rect, b Rect) bool
- func OverlapsCircle(a Circle, b Circle) bool
- func Random(lo int, hi int) int
- func RandomFloat(lo float64, hi float64) float64
- func Run(app App) error
- func TouchJustClicked() bool
- func TouchPosition() (float64, float64, bool)
- type App
- type Circle
- type Color
- type Position
- type Rect
- type Screen
- type Size
Constants ¶
This section is empty.
Variables ¶
var KeyDown ebiten.Key = ebiten.KeyArrowDown
var KeyEnter ebiten.Key = ebiten.KeyEnter
var KeyEscape ebiten.Key = ebiten.KeyEscape
var KeyLeft ebiten.Key = ebiten.KeyArrowLeft
var KeyRight ebiten.Key = ebiten.KeyArrowRight
var KeySpace ebiten.Key = ebiten.KeySpace
var KeyUp ebiten.Key = ebiten.KeyArrowUp
Functions ¶
func CircleOverlapsRect ¶
func FrameCount ¶
func FrameCount() int64
func IsKeyPressed ¶
func MouseClicked ¶
func MouseClicked() bool
func MousePosition ¶
func OverlapsCircle ¶
func RandomFloat ¶
func TouchJustClicked ¶
func TouchJustClicked() bool
Source Files