game

README

game

ECS components and game world. Uses mlange-42/ark for entity management.

Components

Component	Description
Position	X, Y coordinates
Velocity	Movement speed
Collider	AABB hitbox
Sprite	ASCII character and color
Player	Player ID and name
Health	Current/max HP
Damage	Damage amount (for projectiles)
Gravity	Gravity multiplier
Grounded	Is touching ground

World

world := game.NewWorld()
world.SpawnPlayer(1, "Alice", 100, 200)
world.SpawnEnemy("slime", 300, 200)

// Each tick
world.Update()

Systems (run order)

1. Input - Apply player intents to velocity
2. Physics - Apply gravity, velocity to position
3. Collision - Detect and resolve overlaps
4. Damage - Process hits, reduce health
5. Cleanup - Remove dead entities

ECS Library

Using ark for:

• Type-safe component access via generics
• Entity relationships (player → projectile)
• Serialization via ark-serde (for networking)

See adr/2025-12-27-ecs-library.md.

Documentation

Overview

Package game defines ECS components and game logic.

Index

• Constants
• func DemoLevel() *collision.TileMap
• func DemoLevelForViewport(width, height int) *collision.TileMap
• func RenderTileMap(tm *collision.TileMap) [][]rune
• func StatesMatch(a, b *WorldState, tolerance float64) bool
• type AttackState
• type Collider
• type Controller
• type Damage
• type EntityState
• type Fist
• type Gravity
• type Grounded
• type Health
• type Player
• type Position
• type Renderable
• type Sprite
• type Velocity
• type World
  • func NewWorld() *World
  • func (w *World) GetPlayerPosition() (float64, float64, bool)
  • func (w *World) GetRenderables() []Renderable
  • func (w *World) Restore(state WorldState)
  • func (w *World) SetPlayerIntent(playerID int, intents protocol.Intent)
  • func (w *World) SetTileMap(tm *collision.TileMap)
  • func (w *World) Snapshot() WorldState
  • func (w *World) SpawnEnemy(enemyType string, x, y float64) ecs.Entity
  • func (w *World) SpawnFist(x, y float64, facingRight bool, maxDistance float64, ownerID int) ecs.Entity
  • func (w *World) SpawnPlayer(id int, name string, x, y float64) ecs.Entity
  • func (w *World) Update()
• type WorldState
  • func (state *WorldState) ToProtocolSnapshot() protocol.StateSnapshot

Constants

const (
	MaxChargeTicks  = 180  // 3 seconds at 60 TPS = maximum charge
	MinFistDistance = 1.0  // Minimum distance (no charge)
	MaxFistDistance = 20.0 // Maximum distance (full charge) - 20x character width
	FistSpeed       = 0.8  // Speed of the flying fist per tick
)

Charge constants

const AttackCooldown = 15 // ~250ms at 60 TPS

AttackCooldown is how many ticks must pass before another attack can be initiated

const AttackDuration = 8

AttackDuration is how many ticks the punch animation lasts

Functions

func DemoLevel

func DemoLevel() *collision.TileMap

DemoLevel creates a simple test level with default size

func DemoLevelForViewport

func DemoLevelForViewport(width, height int) *collision.TileMap

DemoLevelForViewport creates a test level sized to fit the given viewport

func RenderTileMap

func RenderTileMap(tm *collision.TileMap) [][]rune

RenderTileMap returns ASCII representation of the tilemap

func StatesMatch

func StatesMatch(a, b *WorldState, tolerance float64) bool

StatesMatch compares two world states for equivalence within tolerance

Types

type AttackState

type AttackState struct {
	Attacking   bool // Currently in attack animation (post-release)
	TicksLeft   int  // Animation ticks remaining
	FacingRight bool // Direction of attack

	// Charging state
	Charging    bool // Currently charging (key held)
	ChargeTicks int  // How long the key has been held

	// Attack key tracking for edge detection
	AttackWasPressed bool // Was attack key pressed last frame (for edge detection)
}

AttackState tracks attack animation state

type Collider

type Collider struct {
	OffsetX, OffsetY float64
	Width, Height    float64
}

Collider component (AABB bounds relative to position)

type Controller

type Controller struct {
	Intents protocol.Intent
}

Controller tracks which intents are active for an entity

type Damage

type Damage struct {
	Amount int
}

Damage component (for projectiles, hazards)

type EntityState

type EntityState struct {
	Entity    ecs.Entity
	Position  Position
	Velocity  Velocity
	Grounded  Grounded
	HasPlayer bool
	Player    Player
	HasAttack bool
	Attack    AttackState
}

EntityState captures the full state of an entity for snapshot/restore

type Fist

type Fist struct {
	StartX      float64 // Starting X position
	MaxDistance float64 // Maximum distance to travel
	FacingRight bool    // Direction of travel
	OwnerID     int     // Player who threw the fist
}

Fist component marks a flying fist projectile

type Gravity

type Gravity struct {
	Scale float64 // Multiplier (1.0 = normal, 0 = no gravity)
}

Gravity component (affected by gravity)

type Grounded

type Grounded struct {
	OnGround bool
}

Grounded component (touching ground)

type Health

type Health struct {
	Current int
	Max     int
}

Health component

type Player

type Player struct {
	ID   int
	Name string
}

Player component (marks player-controlled entities)

type Position

type Position struct {
	X, Y float64
}

Position component

type Renderable

type Renderable struct {
	X, Y     float64
	SpriteID string
	Color    uint32 // Color hint (renderers may use their atlas colors instead)
	FlipX    bool   // Flip sprite horizontally (facing left)
}

Renderable represents an entity that can be drawn

type Sprite

type Sprite struct {
	ID    string // Sprite identifier (e.g., "player", "slime", "platform")
	Color uint32 // RGB color hint (renderers may use or ignore)
}

Sprite component (for rendering) Uses abstract sprite IDs - renderers map these to their native format

type Velocity

type Velocity struct {
	X, Y float64
}

Velocity component

type World

type World struct {
	Tick     uint64
	ECS      *ecs.World
	TileMap  *collision.TileMap
	TileSize float64 // Size of each tile in world units
	// contains filtered or unexported fields
}

World holds all game state using ark ECS

func NewWorld

func NewWorld() *World

NewWorld creates a new game world

func (*World) GetPlayerPosition

func (w *World) GetPlayerPosition() (float64, float64, bool)

GetPlayerPosition returns the first player's position

func (*World) GetRenderables

func (w *World) GetRenderables() []Renderable

GetRenderables returns all entities with position and sprite for rendering

func (*World) Restore

func (w *World) Restore(state WorldState)

Restore applies a saved world state, rolling back to that point in time

func (*World) SetPlayerIntent

func (w *World) SetPlayerIntent(playerID int, intents protocol.Intent)

SetPlayerIntent sets the input intent for all players

func (*World) SetTileMap

func (w *World) SetTileMap(tm *collision.TileMap)

SetTileMap sets the collision tile map

func (*World) Snapshot

func (w *World) Snapshot() WorldState

Snapshot creates a complete snapshot of the current world state This captures all entity states needed for rollback and replay

func (*World) SpawnEnemy

func (w *World) SpawnEnemy(enemyType string, x, y float64) ecs.Entity

SpawnEnemy creates an enemy entity

func (*World) SpawnFist

func (w *World) SpawnFist(x, y float64, facingRight bool, maxDistance float64, ownerID int) ecs.Entity

SpawnFist creates a flying fist projectile The fist spawns at chest height (0.5 units above the character's foot position)

func (*World) SpawnPlayer

func (w *World) SpawnPlayer(id int, name string, x, y float64) ecs.Entity

SpawnPlayer creates a player entity

func (*World) Update

func (w *World) Update()

Update advances the world by one tick

type WorldState

type WorldState struct {
	Tick     uint64
	Entities []EntityState
	Checksum uint32
}

WorldState is a complete snapshot of the game world for rollback

func (*WorldState) ToProtocolSnapshot

func (state *WorldState) ToProtocolSnapshot() protocol.StateSnapshot

ToProtocolSnapshot converts a WorldState to a protocol.StateSnapshot for network transmission