inkwell

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 24 Imported by: 0

README

inkwell — reference manual

A point-and-click adventure game framework for Go, built on top of Ebitengine. Games are composed by registering plain struct literals into per-entity *Manager registries hanging off a single *Game root. The library handles input, rendering, dialog trees, cutscenes, HUD, themes and lazy asset loading; the domain only declares content.

This document is the full library reference. The companion inkwell-demo repo at ssh://git@git.teletypegames.org:2222/games/inkwell-demo is a small end-to-end example ("Morning Coffee") that consumes this library as a plain Go module.

Module path: git.teletypegames.org/games/inkwell

import "git.teletypegames.org/games/inkwell"

Table of contents

  1. Introduction
  2. Quick start
  3. The Manager pattern
  4. The Game aggregate
  5. Geometry primitives
  6. Entity reference
  7. The action system
  8. Conditions
  9. World state
  10. The widget system
  11. Themes
  12. Asset pipeline
  13. Audio
  14. Input
  15. The game loop
  16. Scene transitions
  17. Validation
  18. Save and load
  19. Errors
  20. Testing
  21. Project layout
  22. License

1. Introduction

inkwell is not a generic engine — it is a thin Go-level DSL layer on top of Ebitengine that implements the fixed skeleton of the point-and-click adventure genre as it existed in the LucasArts SCUMM era (Maniac Mansion, Monkey Island, Day of the Tentacle):

  • scenes with hotspots and click zones,
  • a verb-based interaction grammar (Look, Use, Talk, Take, …),
  • inventory, item-on-item and item-on-hotspot combinations,
  • dialog trees with conditional choices,
  • a scripting / cutscene system built from composable Action values,
  • a widget-tree HUD that you can extend with anything Ebitengine can draw,
  • swappable color themes,
  • placeholder graphics so the game runs without any art on disk.

The design collapses to one organising pattern: every named entity is registered via Manager.Register(Entity{Name: "..."}). No builders, no fluent chains, no scattered registries. The same mental model applies to items, scenes, characters, dialogues, scripts, assets, verbs, widgets and themes alike.

A complete example game ("Morning Coffee") lives in the separate inkwell-demo repo and consumes this library as a regular Go module.

2. Quick start

Prerequisites. Go 1.24+ (for generic type aliases) and a working OpenGL context. Ebitengine handles windowing and the render loop.

Use the library in your own project:

go mod init my-game
go get git.teletypegames.org/games/inkwell

If the private host can't be reached over HTTPS, point Go at the SSH endpoint:

git config --global \
    url."ssh://git@git.teletypegames.org:2222/".insteadOf "https://git.teletypegames.org/"
export GOPRIVATE=git.teletypegames.org/*

Minimum game:

package main

import (
    "log"
    "git.teletypegames.org/games/inkwell"
)

func main() {
    g := inkwell.NewGame("Sample", 320, 200)

    g.AssetManager.Register(inkwell.Asset{
        Name: "bg/room", Path: "assets/bg/room.png", Kind: inkwell.AssetImage,
    })
    g.CharacterManager.Register(inkwell.Character{Name: "player", W: 28, H: 62})
    g.SceneManager.Register(inkwell.Scene{
        Name:       "room",
        Background: "bg/room",
        Actors:     []inkwell.SceneActor{{CharacterName: "player", At: inkwell.Point{X: 160, Y: 140}}},
        Hotspots: []inkwell.Hotspot{{
            Name:   "door",
            Area:   inkwell.Rect(260, 50, 40, 90),
            Label:  "door",
            OnLook: inkwell.Say("player", "A wooden door."),
        }},
    })

    g.StartAt("room")
    inkwell.RegisterDefaultUI(g) // optional; auto-called by Run if no widgets registered
    if err := inkwell.Run(g); err != nil {
        log.Fatal(err)
    }
}

3. The Manager pattern

Every name-addressable entity goes through one shared generic type:

// inkwell/core.manager.go

type Named interface {
    GetName() string
}

type Manager[T Named] struct { /* ... */ }

Each entity kind has its own alias (generic type alias, Go 1.24+):

type ItemManager       = Manager[Item]
type SceneManager      = Manager[Scene]
type CharacterManager  = Manager[Character]
type DialogueManager   = Manager[Dialogue]
type ScriptManager     = Manager[Script]
type AssetManager      = Manager[Asset]
type VerbManager       = Manager[Verb]
type UIManager         = Manager[Widget]
type ThemeManager      = Manager[Theme]
3.1 Public API
Method Behaviour
Register(v T) Adds v to the registry. Panics on empty or duplicate Name.
Get(name) (T, bool) Looks up by name. The boolean is false if absent.
MustGet(name) T Same as Get, but panics on missing names.
Has(name) bool True if the name is registered.
Len() int Number of registered entries.
Names() []string Returns names in insertion order (used for widget Z-order).
SortedNames() []string Returns names alphabetically.
Each(fn func(T)) Iterates in insertion order.
Remove(name string) Drops a registration; silent no-op if unknown.
3.2 The Named contract

Every registerable struct implements GetName() string. Most also implement an optional TypeLabel() string that the manager uses in panic messages for clearer errors:

func (i Item) GetName() string   { return i.Name }
func (i Item) TypeLabel() string { return "item" }
3.3 Why panic on duplicates?

A duplicate registration is a construction-time bug — code that ran once on startup. Crashing loudly during Build() surfaces the problem in development; quietly accepting the second registration would silently mask shadowed entities at runtime.

4. The Game aggregate

// inkwell/core.game.go

type Game struct {
    Title         string
    Width, Height int

    // entity managers
    ItemManager      *ItemManager
    SceneManager     *SceneManager
    CharacterManager *CharacterManager
    DialogueManager  *DialogueManager
    ScriptManager    *ScriptManager
    AssetManager     *AssetManager
    VerbManager      *VerbManager
    UIManager        *UIManager
    ThemeManager     *ThemeManager

    // runtime services
    State     *State
    Inventory *Inventory
    Audio     *AudioPlayer
    Camera    *Camera
    Input     *Input

    // log buffer
    MaxLogLines int
    /* unexported runtime fields */
}
4.1 Construction
func NewGame(title string, w, h int) *Game

Initialises every manager (empty), registers the default SCUMM verb set (look, use, talk, take), installs all four preset themes, and selects classic-scumm as the active theme. Widgets are not auto-registered — call RegisterDefaultUI(g) (or one of its siblings) explicitly, or let Run install the default set if UIManager is empty.

4.2 Lifecycle hooks
func (g *Game) StartAt(name string) *Game     // entry scene
func (g *Game) OnStart(a Action) *Game        // action run after the scene's OnEnter
func (g *Game) Validate() error               // cross-check name references
func (g *Game) Run() error                    // same as inkwell.Run(g)

StartAt and OnStart return *Game so they chain at the end of Build.

4.3 Theme accessors
func (g *Game) Theme() Theme                  // active theme value
func (g *Game) UseTheme(name string)          // switch theme (runtime ok)

The active theme is addressed by name, not by pointer — switching is just g.UseTheme("paper-notebook") and the next frame uses the new colors.

4.4 UI runtime helpers

The current selectedVerb, hoverLabel, speech and flash message live on Game. They are written by actions / the engine, read by widgets:

func (g *Game) SelectedVerb() string
func (g *Game) SetSelectedVerb(s string)

func (g *Game) HoverLabel() string            // raw target label
func (g *Game) SetHoverLabel(s string)
func (g *Game) HoverHint() string             // composed "verb + target"

func (g *Game) SetSpeech(speaker, text string)
func (g *Game) ClearSpeech()

func (g *Game) FlashLine(text string)         // ~2s status banner
4.5 Chat-log API

The engine and the Say action push entries here; the ChatLog widget reads them. Set Game.MaxLogLines to bound the ring buffer (0 = unbounded).

type LogKind int
const (
    LogAction   // "> look at door" lines (player commands)
    LogResponse // in-world replies / Say output
    LogSystem   // game/system meta
)

type LogMessage struct {
    Speaker string
    Text    string
    Kind    LogKind
}

func (g *Game) LogAction(text string)
func (g *Game) LogResponse(speaker, text string)
func (g *Game) LogSystem(text string)
func (g *Game) Messages() []LogMessage
4.6 Scene helpers
func (g *Game) CharacterInScene(name string) bool

Used by CharacterPanel to auto-hide when its character isn't an actor in the current scene.

4.7 Text drawing hook
func (g *Game) DrawText(dst *ebiten.Image, s string, x, y int, c color.Color)

Single indirection so widgets can hand a color.Color today and the library can swap to text/v2 later without changing call sites.

5. Geometry primitives

// inkwell/util.geometry.go

type Point struct{ X, Y float64 }

func (p Point) Add(q Point) Point
func (p Point) Sub(q Point) Point
func (p Point) Dist(q Point) float64

type Shape interface {
    Contains(p Point) bool
    Bounds() Rectangle
}

type Rectangle struct{ X, Y, W, H float64 }

func Rect(x, y, w, h float64) Rectangle
func (r Rectangle) Contains(p Point) bool
func (r Rectangle) Bounds() Rectangle
func (r Rectangle) Center() Point

type Polygon struct{ Points []Point }

func Poly(pts ...Point) Polygon
func (g Polygon) Contains(pt Point) bool      // ray-casting
func (g Polygon) Bounds() Rectangle           // axis-aligned bbox

Both Rectangle and Polygon satisfy Shape and can be used as a Hotspot.Area. Internally, hotspots are hit-tested against Shape.Contains each frame.

6. Entity reference

6.1 Asset
// inkwell/asset.def.go

type AssetKind int
const (
    AssetImage AssetKind = iota
    AssetAudio
    AssetFont
)

type Asset struct {
    Name string  // logical id used everywhere ("bg/kitchen")
    Path string  // disk path ("assets/bg/kitchen.png")
    Kind AssetKind
}

Assets are lazy: Register only stores the spec. The file is opened on the first loadedAssets.image(...) request. Missing files fall back to a deterministic colored placeholder so the game runs without any art — useful for prototyping or CI.

g.AssetManager.Register(inkwell.Asset{
    Name: "bg/kitchen",
    Path: "assets/bg/kitchen.png",
    Kind: inkwell.AssetImage,
})
6.2 Scene
// inkwell/scene.def.go

type Scene struct {
    Name       string
    Title      string         // optional human-readable name (TopBar widget reads this)
    Background string         // Asset.Name
    Music      string         // Asset.Name (optional)
    Hotspots   []Hotspot
    Walkboxes  []Polygon
    Triggers   []Trigger
    Actors     []SceneActor
    OnEnter    Action
    OnLeave    Action
}

type SceneActor struct {
    CharacterName string
    At            Point
}

OnEnter is queued the moment the scene becomes current (after a fade-in); OnLeave runs on the transition out. Actors lists which registered characters are placed in the scene and where their feet start.

Walkboxes constrain character movement. When non-empty, Walk(...) routes through a BFS over the polygon adjacency graph (polygons that share an edge are neighbours), with the midpoint of each shared edge used as a waypoint. Destinations outside every walkbox are clipped to the nearest boundary. With no walkboxes the character walks in a straight line — see §6.7 and §15.4.

Triggers fire on the rising edge of their When condition. The engine samples each trigger once per idle frame; see §6.4.

6.3 Hotspot
// inkwell/scene.hotspot.go

type Hotspot struct {
    Name   string
    Area   Shape           // Rectangle or Polygon
    Label  string          // hover hint
    Cursor CursorKind

    // built-in verb handlers
    OnLook Action
    OnUse  Action
    OnTalk Action
    OnTake Action
    OnGive Action

    // when the player has an item selected and clicks this hotspot,
    // the engine looks up the item's Name here first.
    OnUseWith map[string]Action

    // custom verbs registered through g.VerbManager.
    OnVerb map[string]Action
}

type CursorKind int
const (
    CursorDefault CursorKind = iota
    CursorLook
    CursorUse
    CursorTalk
    CursorTake
    CursorExit
)

Hotspots are children of Scene — not their own manager. The engine resolves a click via hotspot.handler(verbName) which maps the four built-in verbs to their On* fields and falls back to OnVerb[verbName] for custom verbs.

6.4 Trigger
// inkwell/scene.trigger.go

type Trigger struct {
    Name string
    When Condition
    Do   Action
    Once bool
}

Triggers arm when the scene is entered. Every idle frame (when the script slot is free), the engine samples each trigger's When condition; on a rising edge (false → true) it queues Do into the script slot. Once: true makes the trigger fire at most once per arming. A trigger with nil When or nil Do is silently skipped.

Triggers are not sampled while a cutscene or dialog is running, so a condition that becomes true mid-script is detected on the next idle frame — the edge is preserved across the busy window. Save/Load resets trigger state to "freshly armed", matching the behaviour of scene re-entry.

6.5 Item
// inkwell/item.def.go

type Item struct {
    Name        string
    Sprite      string                  // Asset.Name
    Description string

    OnUseSelf Action
    // targetName → action. Target can be a hotspot Name or another item Name.
    OnUseWith map[string]Action
}

Items live in the ItemManager. When the player picks one up (Give("key")) the item is appended to the Inventory. Clicking a hotspot with an item selected resolves the action via, in order:

  1. hotspot.OnUseWith[item.Name]
  2. item.OnUseWith[hotspot.Name]
  3. Otherwise the engine flashes "Nem ehhez." and deselects.
6.6 Inventory
// inkwell/item.inventory.go

type Inventory struct{ /* unexported */ }

func NewInventory() *Inventory
func (i *Inventory) Add(name string)
func (i *Inventory) Remove(name string)
func (i *Inventory) Has(name string) bool
func (i *Inventory) Select(name string)        // "" clears
func (i *Inventory) Selected() string
func (i *Inventory) Items() []string           // copy

Not a manager — pure runtime state owned by Game. Mutated by actions (Give, TakeAway) and by the InventoryBar widget on click.

6.7 Character
// inkwell/actor.def.go

type Character struct {
    Name        string
    Sprite      string                       // Asset.Name (placeholder if missing)
    Animations  map[string]AnimationClip
    Speed       float64
    SpeechColor color.Color
    Start       Point
    W, H        float64                      // size hint for placeholder
}

type AnimationClip struct {
    Frames    []Rectangle
    FrameTime float64
    Loop      bool
}

When no real sprite is on disk, drawCharacter falls back to a stylised placeholder: humanoid if W < H, quadruped otherwise. SpeechColor (if an RGBA) colours both the speech-bubble text and the placeholder body.

Animations maps a clip name to an AnimationClip. The engine auto-selects clips by name: "walk" while the character has an active path, "idle" otherwise. If only one of the two is registered, it plays in both states. FrameTime ≤ 0 or Frames empty disables the clip; missing clips fall back to the whole-sprite (or placeholder) draw.

Each Frames entry is a source rectangle into the character's Sprite image, blitted via SubImage and scaled to the character's W×H footprint. Loop: true rewinds to frame 0 after the last frame; Loop: false freezes on the final frame.

Movement is driven by the Walk action and Game.tickCharacters — stepping at Speed pixels/sec (default 60) along the waypoint list computed by walkbox routing.

6.8 Dialogue
// inkwell/dialog.def.go

type Dialogue struct {
    Name  string
    Start string                        // initial node Name; "" = first in slice
    Nodes []DialogueNode
}

type DialogueNode struct {
    Name    string
    Lines   []DialogueLine              // shown one-at-a-time on click
    Choices []DialogueChoice
}

type DialogueLine struct {
    Speaker string                      // Character.Name
    Text    string
}

type DialogueChoice struct {
    Text    string
    Show    Condition                   // nil = always visible
    Once    bool                        // hide after first pick
    Actions []Action                    // run when chosen
}

func (d Dialogue) Node(name string) (DialogueNode, bool)

The dialog flow:

  1. RunDialogue("name") action starts the dialogue; the runner keeps returning StatusRunning until the dialog closes.
  2. The DialogBox widget renders lines one at a time; click advances.
  3. After the last line, visible Choices are shown.
  4. Picking a choice runs Seq(choice.Actions...). Once choices remember that they fired via State.NoteTalked.
  5. EndDialogue() closes the conversation; GotoNode("other") jumps to another node in the same dialogue.
6.9 Script
// inkwell/action.script.go

type Script struct {
    Name    string
    Actions Action                      // typically Seq(...)
}

A Script is just a named composite action — useful when you want to reuse a cutscene (intro, victory, transition) from multiple call sites. Fire one with RunScript("name").

6.10 Verb
// inkwell/ui.verb.go

type Verb struct {
    Name    string                      // canonical id, e.g. "look"
    Label   string                      // display label, e.g. "Nézd"
    Default Action                      // run when a hotspot has no handler
}

NewGame pre-registers the four SCUMM verbs (look, use, talk, take). Add your own:

g.VerbManager.Register(inkwell.Verb{
    Name: "push", Label: "Lökd",
    Default: inkwell.Say("player", "Nem mozdul."),
})

The verb-bar and verb-wheel widgets read VerbManager.Names() every frame, so adding a verb at runtime is enough to make it appear.

7. The action system

7.1 Action and Runner
// inkwell/action.def.go

type Action interface {
    Start() Runner
}

type Runner interface {
    Tick(ctx *Ctx) Status
}

An Action is an immutable spec of work — safe to store in a Hotspot.OnLook field and use across many clicks. A Runner is one in-flight execution, created by Start(), carrying state (elapsed time, sub-runners, started-flag). The engine never ticks an Action directly; it always asks for a fresh Runner per invocation.

Only one runner is active at a time (the "script slot"). New action queues issued while one is running are dropped (logged at debug level). A multi-actor scene can still run parallel work via Par(...) inside a single composite action.

7.2 Status and Ctx
type Status int
const (
    StatusRunning Status = iota
    StatusDone
    StatusFailed
)

type Ctx struct {
    Game    *Game
    DT      float64                     // seconds since last tick
    Scene   *Scene                      // current scene (may be nil)
    Hotspot *Hotspot                    // populated only for action contexts where applicable
    Item    *Item
}

Status controls how the parent runner reacts: StatusDone advances a Seq to the next step, StatusFailed short-circuits the whole branch (RequireItem uses this to abort a sequence when the item is absent).

7.3 Built-in actions
Constructor Behaviour
Seq(a ...Action) Action Run children in order. Nested Seq are flattened. nil children are ignored.
Par(a ...Action) Action Run children simultaneously; completes when every child reports Done.
If(c Condition, then Action, els ...Action) Action Run then if c evaluates true; otherwise Seq(els...) (if any).
Wait(seconds float64) Action Block the runner for seconds.
Say(speaker, text string) Action Show the line above the speaker (SpeechBubble), append to chat-log. Click-to-skip. Duration scales with text length, 1.2s floor.
GoTo(scene string) Action Switch the current scene via a fade transition.
Walk(character string, to Point) Action Move a character to to at Character.Speed. Returns when arrived.
Give(item string) Action Add item to inventory.
TakeAway(item string) Action Remove item from inventory.
RequireItem(item string) Action If the item is not in inventory, flash "Ehhez kell egy …" and fail.
SetFlag(name string) Action State.SetFlag(name).
ClearFlag(name string) Action State.ClearFlag(name).
SetVar(name string, v any) Action State.SetVar(name, v).
PlayMusic(asset string) Action Hand off to AudioPlayer.PlayMusic. (Currently logged only.)
StopMusic() Action AudioPlayer.StopMusic.
PlaySound(asset string) Action AudioPlayer.PlaySound.
RunDialogue(name string) Action Start a registered Dialogue; runner blocks until the dialog closes.
EndDialogue() Action Close the active dialog.
GotoNode(node string) Action Jump to a node within the active dialog.
RunScript(name string) Action Run a registered Script's Actions.
ShowEnd(text string) Action Display the end-card overlay; runner never finishes.
Custom(fn func(*Ctx) Status) Action Escape hatch — wrap an arbitrary callback as an action.
7.4 Custom actions

Implement Action and Runner directly when you need long-running state (an animation, a tween, an HTTP poll):

type fadeAction struct{ target string; duration float64 }

func (a *fadeAction) Start() Runner { return &fadeRunner{spec: a} }

type fadeRunner struct {
    spec    *fadeAction
    elapsed float64
}

func (r *fadeRunner) Tick(ctx *Ctx) Status {
    r.elapsed += ctx.DT
    if r.elapsed >= r.spec.duration {
        return StatusDone
    }
    // mutate state, draw a fade, etc.
    return StatusRunning
}

For one-shot mutations, Custom is shorter:

bumpScore := inkwell.Custom(func(ctx *inkwell.Ctx) inkwell.Status {
    cur := ctx.Game.State.Var("score").(int)
    ctx.Game.State.SetVar("score", cur+10)
    return inkwell.StatusDone
})

8. Conditions

// inkwell/action.condition.go

type Condition interface {
    Eval(ctx *Ctx) bool
}
Constructor Meaning
Not(c Condition) Condition !c
And(cs ...Condition) Condition All must evaluate true.
Or(cs ...Condition) Condition At least one true.
Flag(name string) Condition State.Flag(name)
HasItem(name string) Condition Inventory.Has(name)
SelectedItem(name string) Condition Inventory.Selected() == name
InScene(name string) Condition The current Ctx.Scene matches.
VarEq(name string, v any) Condition State.Var(name) == v (Go equality).

Conditions are stateless — they are evaluated lazily, including inside If and DialogueChoice.Show.

9. World state

// inkwell/state.def.go

type State struct{ /* unexported */ }

func NewState() *State

func (s *State) Flag(name string) bool
func (s *State) SetFlag(name string)
func (s *State) ClearFlag(name string)

func (s *State) Var(name string) any
func (s *State) SetVar(name string, v any)

func (s *State) Visited(name string) int
func (s *State) NoteVisit(name string)             // engine bumps on scene enter

func (s *State) Talked(node string) int
func (s *State) NoteTalked(node string)            // DialogBox bumps on Once-choice pick

Flag/SetFlag are the workhorse for puzzle state ("cupboard_open"). SetVar accepts any value — strings for text, numbers for scores, struct references for richer dashboards. The TopBar widget reads vars by name to render score / time.

Visited and Talked underpin the "Once" semantics in dialogues and could be used by triggers once those land.

10. The widget system

The HUD is a tree of Widgets, each registered into g.UIManager. The library ships built-in widgets for every classic adventure UI piece; domain code can register arbitrary new ones — chat panels, minimaps, hotbars — without touching the library.

10.1 Widget interface
// inkwell/ui.widget.go

type Widget interface {
    Named
    Tick(ctx *UICtx)
    Draw(dst *ebiten.Image, ctx *UICtx)
}

type UICtx struct {
    Game *Game
    DT   float64
}

type MouseButton int
const (
    MouseButtonLeft MouseButton = iota
    MouseButtonRight
)

type Size struct{ W, H int }

type Align int
const (
    AlignLeft Align = iota
    AlignCenter
    AlignRight
)

A widget is responsible for its own input handling, hit-testing, state and rendering. The library does not impose a layout layer — widgets carry their own Bounds (or compute them dynamically, like RadialVerbs).

10.2 Z-order and input consumption
  • Tick runs in reverse registration order. Widgets registered later (drawn on top) get the click first. Each widget calls ctx.Game.Input.ConsumeLeft() / ConsumeRight() to claim the event; later widgets see LeftClicked() == false.
  • Draw runs in registration order — registered last → painted on top.
  • The Cursor widget is registered last by convention so it always wins on visual layer (and effectively never claims clicks).

After all widgets ticked, the engine offers the (possibly consumed) click to handleSceneInput, which is where hotspot interactions live. If a widget already consumed the click, handleSceneInput becomes a no-op for that frame.

10.3 Built-in widgets

Each widget lives in its own inkwell/ui.<name>.go file. Fields with a zero value fall back to a sensible default.

Panel (ui.panel.go)

A generic colored rectangle, optionally with a stroke border. Useful as a backdrop for grouping other widgets.

type Panel struct {
    Name        string
    Bounds      Rectangle
    BG          color.Color    // nil → Theme.PanelBG
    Border      int            // 0 = no border
    BorderColor color.Color    // nil → Theme.DialogBorder
}
StatusLine (ui.status.go)

A single line at Y. Shows the active flash message (if any) — set by Game.FlashLine — otherwise the composed hover hint (verb + target or verb + item + target).

type StatusLine struct {
    Name        string
    Y           int
    Align       Align          // default AlignCenter
    ScreenWidth int            // 0 → Game.Width
}
VerbBar (ui.verb_bar.go)

The SCUMM permanent verb panel. Reads VerbManager.Names() every frame and lays the labels into a Cols × ceil(N/Cols) grid.

type VerbBar struct {
    Name    string
    Origin  Point
    Cols    int               // default 2
    Button  Size
    Gap     Point
    PanelBG bool              // draw a Theme.PanelBG backdrop behind buttons
}

Click on a button → Game.SetSelectedVerb(name). Implements BlocksClickAt so RadialVerbs does not pop up over it.

RadialVerbs (ui.verb_radial.go)

Verb-coin or permanent verb-wheel.

type RadialVerbs struct {
    Name    string
    Trigger MouseButton                  // default MouseButtonRight
    Radius  float64                       // default 40

    // AlwaysVisible turns the widget into a permanent wheel at Center.
    // Trigger is ignored in this mode; left-click picks a slice.
    AlwaysVisible bool
    Center        Point

    // Override the rendered label per verb name (e.g. shorten "Használd"
    // → "Tedd" so it fits inside the disk).
    Labels map[string]string
}

In trigger mode (default), the wheel is invisible until the trigger mouse button is pressed somewhere not covered by a clickBlocker. The center latches to the click point. Left-click on a slice picks the verb; trigger-click again closes without picking.

In always-visible mode, the wheel is drawn permanently at Center and left-click on a slice picks the verb. Labels are positioned at 0.62 × Radius from the center so short overrides stay inside the rim.

InventoryBar (ui.inventory.go)

Item slots in a grid. Hover sets Game.SetHoverLabel(item.Description); click toggles selection (or, under the look verb, runs a Say with the item description).

type InventoryBar struct {
    Name     string
    Origin   Point
    Slots    int             // total slot count
    Cols     int             // 0 → Slots (single row)
    SlotSize int
    Gap      int
    PanelBG  bool
}

Implements BlocksClickAt covering the slot grid.

SpeechBubble (ui.speech.go)

Renders whatever Game.SetSpeech(...) last set, positioned above the speaker's head (character.pos.Y − character.def.H − OffsetY). Falls back to a screen-top position if the speaker is unknown.

type SpeechBubble struct {
    Name      string
    MaxWidth  int                // wrap width, default 200
    Padding   int                // bubble padding, default 3
    OffsetY   int                // vertical lift above head
    FallbackY int                // anchor Y when speaker unknown
}

Text color follows Character.SpeechColor when set, otherwise Theme.SpeechDefaultText.

DialogBox (ui.dialog_box.go)

Dormant unless Game.dialogueActive(). While active, consumes every click — the rest of the HUD and the scene are inert. The widget renders either the current line of runtimeDialog.Node.Lines (click → next line) or the visible Choices once the lines are exhausted.

type DialogBox struct {
    Name       string
    Bounds     Rectangle      // default Rect(0, 140, Width, 60)
    LineHeight int            // default 14
    Padding    int            // default 6
}

Hovered choices use Theme.DialogChoiceHover. Once-only choices are omitted automatically after their first pick (tracked by State.NoteTalked).

EndCard (ui.end_card.go)

A fullscreen overlay shown when Game.showEndCard(text) is called (which the ShowEnd action does). Consumes every click so nothing underneath reacts.

type EndCard struct{ Name string }
Cursor (ui.cursor.go)

The crosshair cursor (color from Theme.CursorColor). When the inventory has a selected item with a non-placeholder sprite, that sprite is drawn at the cursor position instead.

type Cursor struct{ Name string }
HotspotDebug (ui.hotspot_debug.go)

Stroke-outlines every hotspot in the current scene. F1 toggles it at runtime (override via ToggleKey).

type HotspotDebug struct {
    Name      string
    Enabled   bool
    ToggleKey ebiten.Key       // 0 → ebiten.KeyF1
}
TopBar (ui.top_bar.go)

A horizontal strip across the top with three sections:

  • Left: LeftText override or Scene.Title (falling back to Name).
  • Center: score string built from State.Var(ScoreVar). With ScoreMax > 0, formatted as "Score: X/MAX", else "Score: X".
  • Right: time string from State.Var(TimeVar).
type TopBar struct {
    Name     string
    Height   int                  // default 12
    LeftText string                // overrides scene title
    ScoreVar string                // State.Var key; "" = no score
    ScoreMax int
    TimeVar  string                // State.Var key; "" = no time
}

Empty fields are skipped, so the widget gracefully degrades to two- or one-section layouts.

CharacterPanel (ui.character_panel.go)

A floating info card showing one character's portrait, role badge and custom stat rows. Auto-hides when the character isn't an actor in the current scene — same registration works across all scenes.

type CharStat struct {
    Label  string
    VarKey string                  // State.Var(VarKey) is fmt-printed
}

type CharacterPanel struct {
    Name      string
    Bounds    Rectangle
    Character string                // Character.Name
    Title     string                // role badge ("PLAYER", "NPC", "GUIDE", …)
    Stats     []CharStat
}

The portrait reuses the placeholder rendering when no sprite is on disk (humanoid vs. quadruped picked from W vs. H).

ChatLog (ui.chat_log.go)

Renders the Game.Messages() ring buffer with per-kind colors — LogAction lines use Theme.ChatLogPrompt, LogResponse uses Theme.ChatLogResponse, LogSystem uses Theme.ChatLogSystem. Newest message at the bottom; older messages scroll out of view as the buffer fills.

type ChatLog struct {
    Name       string
    Bounds     Rectangle
    LineHeight int                 // default 10
    Padding    int                 // default 3
    ShowBorder bool                // draws a 1px border in CharacterPanelBorder
}

Set Game.MaxLogLines to bound the buffer (recommended ~64 for a small ChatLog).

10.4 The clickBlocker contract

Some widgets occupy a fixed area; clicking inside should not pop a RadialVerbs menu over them. They implement the optional library-internal interface:

type clickBlocker interface {
    BlocksClickAt(p Point) bool
}

Built-ins that implement it: VerbBar, InventoryBar, DialogBox, TopBar, CharacterPanel, ChatLog, RadialVerbs (itself, when visible). Implement it on your own widgets to mark them as solid input zones for the radial menu.

10.5 Registration helpers
// inkwell/ui.defaults.go

func RegisterDefaultUI(g *Game)                              // SCUMM-style verb bar + inventory
func RegisterRadialVerbUI(g *Game)                            // verb-coin (right-click) + wider inventory
func RegisterRichUI(g *Game, playerName, npcName string)      // top bar + character panels + chat log + verb wheel

Pass "" for any character name to skip its CharacterPanel. All three helpers register in conventional Z-order (debug overlay back, cursor front).

10.6 Custom widgets

Anything implementing Widget plugs in. The library doesn't care about widget identity beyond the name; it just calls Tick and Draw. Read state from ctx.Game, consume input via ctx.Game.Input, draw with Ebitengine primitives, and you're done.

type Minimap struct {
    Name   string
    Bounds inkwell.Rectangle
}

func (m *Minimap) GetName() string                                { return m.Name }
func (m *Minimap) Tick(ctx *inkwell.UICtx)                         {}
func (m *Minimap) Draw(dst *ebiten.Image, ctx *inkwell.UICtx) {
    // ... render scene thumbnail, mark NPCs, etc.
}

g.UIManager.Register(&Minimap{
    Name:   "minimap",
    Bounds: inkwell.Rect(220, 4, 96, 56),
})

11. Themes

// inkwell/ui.theme.go

type Theme struct {
    Name string

    // panel + status
    PanelBG    color.Color
    StatusText color.Color
    FlashText  color.Color

    // verbs
    VerbButtonBG         color.Color
    VerbButtonSelectedBG color.Color
    VerbButtonText       color.Color

    // inventory
    InventorySlotBG         color.Color
    InventorySlotSelectedBG color.Color

    // speech
    SpeechBubbleBG    color.Color
    SpeechDefaultText color.Color

    // dialog
    DialogBG          color.Color
    DialogBorder      color.Color
    DialogChoiceBG    color.Color
    DialogChoiceHover color.Color
    DialogSpeaker     color.Color
    DialogText        color.Color

    // misc overlays
    EndCardBG      color.Color
    EndCardText    color.Color
    CursorColor    color.Color
    HotspotOutline color.Color
    SceneBackdrop  color.Color

    // rich-UI widgets
    TopBarBG       color.Color
    TopBarText     color.Color
    TopBarAccent   color.Color

    ChatLogBG       color.Color
    ChatLogPrompt   color.Color
    ChatLogResponse color.Color
    ChatLogSystem   color.Color

    CharacterPanelBG     color.Color
    CharacterPanelBorder color.Color
    CharacterPanelTitle  color.Color
}
11.1 Preset themes

NewGame automatically calls RegisterPresetThemes(g) and UseTheme("classic-scumm"). The four shipped presets:

Name Mood
classic-scumm Default SCUMM-era dark blue + warm amber accents.
sierra-coin Darker purple + orange; designed for the verb-coin layout.
paper-notebook Cream paper + ink + a touch of sepia for the highlights.
terminal-green Retro phosphor green on black.
11.2 Custom themes

Register your own:

g.ThemeManager.Register(inkwell.Theme{
    Name:      "midnight-noir",
    PanelBG:   color.RGBA{6, 6, 12, 255},
    StatusText: color.White,
    // ... ~30 color fields ...
})
g.UseTheme("midnight-noir")

Switching at runtime is just g.UseTheme(name) — widgets read the active theme every frame, so the change shows up on the next draw.

12. Asset pipeline

AssetManager.Register only stores the spec (Name, Path, Kind). The first request for an image goes through loadedAssets.image(name):

  1. Look up the file from Asset.Path.
  2. If the file is missing or unreadable, generate a deterministic placeholder color from fnv32a(name). Mark the entry as a placeholder.
  3. Cache the decoded *ebiten.Image for subsequent calls.
// internal:
type loadedAssets struct {
    images       map[string]*ebiten.Image
    placeholders map[string]bool
}

func (la *loadedAssets) image(am *AssetManager, name string) *ebiten.Image
func (la *loadedAssets) isPlaceholder(name string) bool

isPlaceholder is used by widgets to decide whether to render a stylised character placeholder (humanoid / quadruped) or the real sprite.

Supported image formats: PNG and JPEG (registered via blank imports in asset.manager.go). Audio assets (AssetAudio) are decoded on demand by AudioPlayer — see §13. Fonts (AssetFont) share the same registry but are not loaded by the library at this milestone.

13. Audio

// inkwell/asset.audio.go

type AudioPlayer struct{ /* unexported */ }

func NewAudioPlayer() *AudioPlayer
func (a *AudioPlayer) PlayMusic(name string)
func (a *AudioPlayer) StopMusic()
func (a *AudioPlayer) PlaySound(name string)

Backed by Ebiten's audio package. The shared *audio.Context is created lazily on the first PlayMusic / PlaySound, at a sample rate of 48 kHz; existing audio contexts (e.g. created by a host process) are detected via audio.CurrentContext and reused. The Asset.Kind must be AssetAudio for the player to consider it.

  • Music streams from disk and loops infinitely. PlayMusic(name) on the currently-playing track no-ops, so it's safe to call from a scene's OnEnter on every visit.
  • Sound effects are decoded once, cached as raw PCM, and replayed via NewPlayerFromBytes for near-zero-latency triggering. Finished players are pruned on the next PlaySound call.

Supported formats: WAV (.wav), OGG Vorbis (.ogg), and MP3 (.mp3), picked by file extension. Anything else fails to decode and the asset is flagged so subsequent plays no-op.

Failure modes (missing file, unsupported codec, no audio device) all degrade to a debug-log line; the game keeps running with no sound. The PlayMusic / PlaySound / StopMusic actions route through the same methods, so a domain authored against the original stub still works.

14. Input

// inkwell/input.def.go

type Input struct{ /* unexported */ }

func (i *Input) Pos() (int, int)
func (i *Input) Point() Point
func (i *Input) LeftClicked() bool       // just-pressed AND not consumed
func (i *Input) RightClicked() bool
func (i *Input) ConsumeLeft()
func (i *Input) ConsumeRight()

The engine polls once per frame, snapshotting cursor position and the just-pressed state for both buttons. Widgets and the engine use the consume-on-use pattern: one click is authoritative — whoever consumes first wins, later checks see LeftClicked() == false.

Game.Input is exposed so widgets and custom actions can read it directly.

15. The game loop

// inkwell/core.dsl.go

func Run(g *Game) error                          // toplevel — same as g.Run()

Run does, in order:

  1. g.Validate() — cross-check name references between managers.
  2. If UIManager is empty, call RegisterDefaultUI(g).
  3. Place the start scene directly (no transition), bump State.NoteVisit, position registered actors, kick off music.
  4. Compose Seq(scene.OnEnter, game.OnStart) and queue it as the initial action — the first script tick runs both in order.
  5. ebiten.SetWindowSize(Width*4, Height*4), ebiten.SetWindowTitle(g.Title), then ebiten.RunGame(&engine{g}).
15.1 engine.Update
poll input
update transition
if transition fading out → return

if scriptRunner != nil:
    tick the runner
    tick characters
    return

clear hoverLabel
for w in reversed(UIManager):
    w.Tick(uictx)        // widgets consume input top-down

handleSceneInput()       // hotspot resolution + right-click reset
tick characters
15.2 engine.Draw
fill Theme.SceneBackdrop (if any)
draw scene background image
for c in characters sorted by Y:
    drawCharacter(c)
for w in UIManager (registration order):
    w.Draw(screen, uictx)
draw transition overlay
15.3 handleSceneInput

Runs only after every widget had a chance. The flow:

  1. Set hover label from the hotspot under the cursor (if any).
  2. On right-click: deselect the held item if any, otherwise reset selectedVerb to "look".
  3. On left-click:
    • If an item is selected, try hotspot.OnUseWith[item], then item.OnUseWith[hotspot]. Fail with a "Nem ehhez." flash.
    • Otherwise look up hotspot.handler(selectedVerb). Fall back to the verb's Default action. Fail with "Semmi említésre méltó."
  4. On every successful click, push a LogAction line so the ChatLog widget can display it.
15.4 Character movement

Game.tickCharacters runs every frame. For each moving character it steps the head of its waypoint queue at def.Speed pixels per second (default 60); on arrival, the waypoint is popped and the character proceeds to the next one. The character becomes idle when the queue empties.

The waypoint queue is built when Walk(name, to) runs — see §6.2 and scene.path.go for the walkbox routing. The Walk runner returns StatusRunning until characterMoving(name) reports false.

Each frame also advances the character's animation clock via tickAnimation, which auto-selects "walk" (when moving == true) or "idle" from Character.Animations. The renderer uses the active clip's source rectangle to blit a sprite-sheet frame, or falls back to the whole-sprite / placeholder draw when no clip applies.

16. Scene transitions

// inkwell/scene.transition.go (unexported)

type transition struct{ /* unexported */ }

A scene change calls Game.changeScene(name), which starts a fade-to- black overlay (duration = 0.25s). At the midpoint:

  1. prevScene.OnLeave (if any) is queued.
  2. currentScene is set to the new name.
  3. State.NoteVisit(name) bumps the visit counter.
  4. Actors are placed at their SceneActor.At positions.
  5. The new scene's Music plays.
  6. newScene.OnEnter is queued.

The fade-from-black plays after the midpoint. During the fade-out half, engine.Update returns early — input is frozen briefly.

The initial scene (from StartAt) is set without a transition so the intro script runs immediately.

17. Validation

func (g *Game) Validate() error

Run by Run before entering the Ebiten loop, and again from your tests. It cross-checks:

  • StartAt points to a registered scene.
  • Every scene has a non-empty Background referencing a registered Asset.
  • Optional Scene.Music (if non-empty) references a registered Asset.
  • Every SceneActor.CharacterName is a registered character.
  • An active theme is selected and registered.

Returns the first error wrapping one of the Err... sentinels (so callers can errors.Is against them). Duplicate-name registration is caught eagerly at Register time via panic.

18. Save and load

// inkwell/state.save.go

func (g *Game) Save(slot int) error
func (g *Game) Load(slot int) error

Slots are written as JSON files under g.SaveDir (default saves/, relative to the working directory), one file per slot named slot<N>.json. The save captures the mutable runtime state:

  • currentScene, the active verb, and the active theme.
  • Every character's position, target, and moving flag.
  • The full State: flags, vars, visited and talked counters.
  • The inventory item list plus the currently selected slot.

Static registrations (items, scenes, characters, dialogues, scripts, assets, verbs, widgets, themes) are not persisted — they are reconstructed by domain.Build() on every launch. References in the save are validated against the current managers before any runtime state is touched, so a corrupt or schema-drift save returns an error without mutating the live *Game.

What is not saved:

  • The in-flight script Runner or any active dialog. Load cancels both, so saves are effectively taken at an idle/ready boundary.
  • The animation playback state. After load, characters are placed at the saved position; the next idle frame re-derives the clip.
  • Walkbox path queues. If a character is still moving, tickCharacters rebuilds a one-step straight-line path from pos to target so the walk finishes.

Var values are JSON-marshaled as-is. Numbers round-trip through float64, strings stay strings, and any value that survives encoding/json round-tripping survives the save.

The save format is versioned (saveVersion); loading a file from a future version returns an error rather than silently truncating fields.

19. Errors

// inkwell/core.errors.go

var (
    ErrUnknownAsset           = errors.New("inkwell: unknown asset")
    ErrUnknownScene           = errors.New("inkwell: unknown scene")
    ErrUnknownItem            = errors.New("inkwell: unknown item")
    ErrUnknownCharacter       = errors.New("inkwell: unknown character")
    ErrUnknownDialogue        = errors.New("inkwell: unknown dialogue")
    ErrUnknownDialogueNode    = errors.New("inkwell: unknown dialogue node")
    ErrUnknownScript          = errors.New("inkwell: unknown script")
    ErrUnknownVerb            = errors.New("inkwell: unknown verb")
    ErrDuplicateName          = errors.New("inkwell: duplicate name")
    ErrNoStartScene           = errors.New("inkwell: StartAt not set or unknown scene")
    ErrSceneMissingBackground = errors.New("inkwell: scene has no background")
)

All wrap-able with fmt.Errorf("%w: …", err, ctx) and checkable with errors.Is. Manager.Register and MustGet use panic instead of returning these errors because they signal construction-time bugs that should crash loudly in development.

20. Testing

go build ./...

The library is single-package and has no in-tree unit tests at this milestone — the manager + action primitives are intentionally small enough that the inkwell-demo repo's build_test.go (a headless Build() + Validate() smoke test) covers the integration surface:

func TestBuildValidates(t *testing.T) {
    g := domain.Build()
    if err := g.Validate(); err != nil {
        t.Fatalf("validate: %v", err)
    }
}

Drop a similar test into any project that consumes the library — it opens no window and finishes in milliseconds, so it's a cheap CI gate.

Library-internal unit tests are not shipped yet; the building blocks are small enough to verify through smoke runs of the demo for the time being.

20.1 Useful runtime debug switches
inkwell.DebugLog = true                 // logf output to stderr (script queue, audio, scene change)
&inkwell.HotspotDebug{Enabled: true}    // start with the F1 overlay on

21. Project layout

All library source files live at the repo root; no nested package directory. The naming convention is theme.identifier.go — ls core.* or ls ui.* instantly groups related sources.

inkwell/                            # module git.teletypegames.org/games/inkwell
├── go.mod
├── go.sum
│
├── core.doc.go                    # package docs
├── core.manager.go                # Manager[T Named], Named, TypeLabel
├── core.game.go                   # Game aggregate, runtime state, helpers
├── core.engine.go                 # ebiten.Game adapter (Update/Draw/Layout)
├── core.dsl.go                    # Run()
├── core.errors.go                 # sentinel errors
│
├── util.geometry.go               # Point, Rectangle, Polygon, Shape
├── util.timer.go                  # Timer helper
├── util.log.go                    # DebugLog + logf
│
├── asset.def.go                   # Asset, AssetKind
├── asset.manager.go               # AssetManager alias + lazy loader
├── asset.audio.go                 # AudioPlayer (WAV/OGG/MP3, looping music)
├── asset.text.go                  # drawText / wrapText helpers
│
├── scene.def.go                   # Scene, SceneActor
├── scene.manager.go               # SceneManager alias
├── scene.hotspot.go               # Hotspot, CursorKind
├── scene.trigger.go               # Trigger + rising-edge engine sweep
├── scene.path.go                  # walkbox routing (BFS over polygon adjacency)
├── scene.transition.go            # fade-to-black overlay (internal)
├── scene.camera.go                # Camera (stub identity transform)
│
├── item.def.go                    # Item
├── item.manager.go                # ItemManager alias
├── item.inventory.go              # Inventory
│
├── actor.def.go                   # Character
├── actor.manager.go               # CharacterManager alias
├── actor.animation.go             # AnimationClip + tickAnimation
│
├── dialog.def.go                  # Dialogue, DialogueNode, DialogueChoice
├── dialog.manager.go              # DialogueManager alias
│
├── action.def.go                  # Action, Runner, Ctx, Status + every built-in action
├── action.condition.go            # Condition interface + combinators
├── action.script.go               # Script entity
├── action.manager.go              # ScriptManager alias
│
├── state.def.go                   # State (flags, vars, visited, talked)
├── state.save.go                  # Save/Load JSON persistence
│
├── input.def.go                   # Input (consume-on-use)
│
├── ui.widget.go                   # Widget interface, UICtx, Size, Align
├── ui.manager.go                  # UIManager alias + reversed/ordered iterators
├── ui.theme.go                    # Theme + ThemeManager
├── ui.theme_presets.go            # 4 preset themes
├── ui.defaults.go                 # RegisterDefaultUI/RadialVerbUI/RichUI
├── ui.verb.go                     # Verb + VerbManager
├── ui.verb_bar.go                 # VerbBar widget
├── ui.verb_radial.go              # RadialVerbs widget
├── ui.inventory.go                # InventoryBar widget
├── ui.status.go                   # StatusLine widget
├── ui.speech.go                   # SpeechBubble widget
├── ui.dialog_box.go               # DialogBox widget
├── ui.end_card.go                 # EndCard widget
├── ui.cursor.go                   # Cursor widget
├── ui.hotspot_debug.go            # HotspotDebug widget
├── ui.panel.go                    # Panel widget
├── ui.top_bar.go                  # TopBar widget
├── ui.character_panel.go          # CharacterPanel widget + CharStat
├── ui.chat_log.go                 # ChatLog widget
│
├── LICENSE.md                     # MIT
└── README.md                      # this file

The companion demo project (inkwell-demo) lives in its own repo at ssh://git@git.teletypegames.org:2222/games/inkwell-demo. It consumes this package via require git.teletypegames.org/games/inkwell … in its go.mod — no in-tree coupling.

22. License

MIT — see LICENSE.md. Copyright © 2026 Teletype Games.

Documentation

Overview

Package inkwell is a point-and-click adventure game library built on top of Ebitengine. Games are composed declaratively by registering plain struct literals into per-entity *Manager registries hanging off the *Game root.

See PLAN.md in the repo root for the full design notes.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnknownAsset           = errors.New("inkwell: unknown asset")
	ErrUnknownScene           = errors.New("inkwell: unknown scene")
	ErrUnknownItem            = errors.New("inkwell: unknown item")
	ErrUnknownCharacter       = errors.New("inkwell: unknown character")
	ErrUnknownDialogue        = errors.New("inkwell: unknown dialogue")
	ErrUnknownDialogueNode    = errors.New("inkwell: unknown dialogue node")
	ErrUnknownScript          = errors.New("inkwell: unknown script")
	ErrUnknownVerb            = errors.New("inkwell: unknown verb")
	ErrDuplicateName          = errors.New("inkwell: duplicate name")
	ErrNoStartScene           = errors.New("inkwell: StartAt not set or unknown scene")
	ErrSceneMissingBackground = errors.New("inkwell: scene has no background")
)
View Source 
var AssetFS fs.FS

AssetFS, when non-nil, is the filesystem asset files (images, audio) are read from instead of the OS filesystem. Set it to an embed.FS before Run to ship assets inside the binary — required for js/wasm builds, where there is no OS filesystem and every asset would fall back to a placeholder: 

//go:embed assets
var assetsFS embed.FS

func init() { inkwell.AssetFS = assetsFS }

Asset.Path values are used as-is, so they must be slash-separated and relative (e.g. "assets/bg/bedroom.png") — the same form that works with os.Open from the project root.

View Source 
var DebugLog = false

Functions

func RegisterDefaultUI 

func RegisterDefaultUI(g *Game)

RegisterDefaultUI installs the SCUMM-style HUD widgets into g.UIManager in the conventional Z-order (HotspotDebug at the back, Cursor on top). Domains that want a different layout call this and then either tweak the registered widgets in place or replace them entirely.

Layout assumes the default 320×200 internal resolution.

func RegisterPresetThemes 

func RegisterPresetThemes(g *Game)

RegisterPresetThemes installs the four built-in themes. NewGame calls this automatically and selects "classic-scumm".

func RegisterRadialVerbUI 

func RegisterRadialVerbUI(g *Game)

RegisterRadialVerbUI installs an alternative HUD that swaps the permanent verb-bar for a verb-coin (right-click radial menu). Inventory, dialog, speech and cursor stay the same.

func RegisterRichUI 

func RegisterRichUI(g *Game, playerName, npcName string)

RegisterRichUI installs a "story-rich" HUD that matches the layout of the screenshot used as the reference: top bar with title/score/time, floating character panels for the player and a single NPC, a chat-log strip at the bottom-left, a tiny inventory at the bottom-right and a permanent verb-wheel on the right edge.

The HUD assumes the default 320×200 internal resolution and that PlayerName / NPCName correspond to registered characters. Pass "" for NPCName to skip the NPC panel.

func Run 

func Run(g *Game) error

Run validates the game, then enters the ebiten main loop. The window is sized to 4× the internal resolution.

Types

type Action 

type Action interface {
	Start() Runner
}

Action is an immutable spec of work; Start makes a fresh Runner with state. Storing an Action in a struct field (e.g. Hotspot.OnUse) is safe because the engine always calls Start before ticking, so two invocations can never share mutable state.

func ClearFlag 

func ClearFlag(name string) Action

func Custom 

func Custom(fn func(*Ctx) Status) Action

Custom wraps a user function as an Action. Returns Done on first tick unless the function itself returns StatusRunning.

func EndDialogue 

func EndDialogue() Action

func Give 

func Give(item string) Action

func GoTo 

func GoTo(scene string) Action

func GotoNode 

func GotoNode(node string) Action

func If 

func If(cond Condition, then Action, els ...Action) Action

func Par 

func Par(actions ...Action) Action

func PlayMusic 

func PlayMusic(name string) Action

func PlaySound 

func PlaySound(name string) Action

func RequireItem 

func RequireItem(item string) Action

func RunDialogue 

func RunDialogue(name string) Action

func RunScript 

func RunScript(name string) Action

func Say 

func Say(speaker, text string) Action

func Seq 

func Seq(actions ...Action) Action

func SetFlag 

func SetFlag(name string) Action

func SetVar 

func SetVar(name string, v any) Action

func ShowEnd 

func ShowEnd(text string) Action

func StopMusic 

func StopMusic() Action

func TakeAway 

func TakeAway(item string) Action

func Wait 

func Wait(seconds float64) Action

func Walk 

func Walk(character string, to Point) Action

type Align 

type Align int

Align controls horizontal text alignment for widgets that draw a single line. 

const (
	AlignLeft Align = iota
	AlignCenter
	AlignRight
)

type AnimationClip 

type AnimationClip struct {
	Frames    []Rectangle
	FrameTime float64
	Loop      bool
}

AnimationClip describes one named sprite-sheet animation. Frames are source rectangles into the character's Sprite asset; the renderer projects them onto the character's screen-space W×H footprint.

FrameTime is the time (seconds) each frame is shown; Loop=true rewinds to the first frame after the last, Loop=false freezes on the final frame. A clip with zero frames or zero FrameTime is treated as static and the renderer falls back to the whole-sprite draw path.

type Asset 

type Asset struct {
	Name string
	Path string
	Kind AssetKind
}

func (Asset) GetName 

func (a Asset) GetName() string

func (Asset) TypeLabel 

func (a Asset) TypeLabel() string

type AssetKind 

type AssetKind int
const (
	AssetImage AssetKind = iota
	AssetAudio
	AssetFont
)

type AssetManager 

type AssetManager = Manager[Asset]

type AudioPlayer 

type AudioPlayer struct {
	// contains filtered or unexported fields
}

AudioPlayer plays music and one-shot sound effects through Ebiten's audio subsystem. Music is streamed and looped infinitely; sound effects are decoded once, cached as raw PCM, and replayed via NewPlayerFromBytes for low-latency triggering.

AudioPlayer is fail-soft by design: missing asset files, decode errors and a missing audio device all degrade to no-ops with a debug log message — the game keeps running. The action constructors (PlayMusic/PlaySound/StopMusic) call through here unchanged.

func NewAudioPlayer 

func NewAudioPlayer() *AudioPlayer

func (*AudioPlayer) PlayMusic 

func (a *AudioPlayer) PlayMusic(name string)

func (*AudioPlayer) PlaySound 

func (a *AudioPlayer) PlaySound(name string)

func (*AudioPlayer) StopMusic 

func (a *AudioPlayer) StopMusic()

type Camera 

type Camera struct {
	Offset Point
}

Camera is a stub identity transform — no scrolling in this milestone.

func NewCamera 

func NewCamera() *Camera

func (*Camera) Apply 

func (c *Camera) Apply(p Point) Point

type CharStat 

type CharStat struct {
	Label  string
	VarKey string
}

CharStat is one (Label, VarKey) row rendered inside a CharacterPanel. VarKey is read from g.State.Var; the value is fmt.Sprint'd verbatim.

type Character 

type Character struct {
	Name        string
	Sprite      string // Asset.Name (placeholder if missing)
	Animations  map[string]AnimationClip
	Speed       float64
	SpeechColor color.Color
	Start       Point
	// Size hints used when the sprite is a placeholder rectangle.
	W, H float64
}

func (Character) GetName 

func (c Character) GetName() string

func (Character) TypeLabel 

func (c Character) TypeLabel() string

type CharacterManager 

type CharacterManager = Manager[Character]

type CharacterPanel 

type CharacterPanel struct {
	Name      string
	Bounds    Rectangle
	Character string // Character.Name to display
	Title     string // "PLAYER", "NPC", role badge
	Stats     []CharStat
}

CharacterPanel is a small floating panel that shows portrait + stats for one registered character. The panel auto-hides when the character isn't listed as an actor in the current scene, so the same panel registration works across scenes.

func (*CharacterPanel) BlocksClickAt 

func (c *CharacterPanel) BlocksClickAt(p Point) bool

BlocksClickAt — the panel sits on top of the scene; clicks inside it shouldn't trigger hotspots underneath.

func (*CharacterPanel) Draw 

func (c *CharacterPanel) Draw(dst *ebiten.Image, ctx *UICtx)

func (*CharacterPanel) GetName 

func (c *CharacterPanel) GetName() string

func (*CharacterPanel) Tick 

func (c *CharacterPanel) Tick(ctx *UICtx)

type ChatLog 

type ChatLog struct {
	Name       string
	Bounds     Rectangle
	LineHeight int
	Padding    int
	// ShowBorder draws a thin border around the box.
	ShowBorder bool
}

ChatLog renders the in-game message log (player commands + in-world replies) as a scrolling box. The newest message is at the bottom; older messages scroll up out of view as the buffer fills.

func (*ChatLog) BlocksClickAt 

func (c *ChatLog) BlocksClickAt(p Point) bool

BlocksClickAt — the log is non-interactive, but it sits over the bottom of the scene; treat it as opaque so RadialVerbs doesn't pop up over it.

func (*ChatLog) Draw 

func (c *ChatLog) Draw(dst *ebiten.Image, ctx *UICtx)

func (*ChatLog) GetName 

func (c *ChatLog) GetName() string

func (*ChatLog) Tick 

func (c *ChatLog) Tick(ctx *UICtx)

type Condition 

type Condition interface {
	Eval(ctx *Ctx) bool
}

func And 

func And(cs ...Condition) Condition

func Flag 

func Flag(name string) Condition

func HasItem 

func HasItem(name string) Condition

func InScene 

func InScene(name string) Condition

func Not 

func Not(c Condition) Condition

func Or 

func Or(cs ...Condition) Condition

func SelectedItem 

func SelectedItem(name string) Condition

func VarEq 

func VarEq(name string, v any) Condition

type Ctx 

type Ctx struct {
	Game    *Game
	DT      float64
	Scene   *Scene
	Hotspot *Hotspot
	Item    *Item
}

Ctx is the per-tick context passed to running actions.

type Cursor 

type Cursor struct {
	Name string
}

Cursor renders the mouse cursor. When the player has an inventory item selected, the item's sprite is drawn at the cursor instead of the default crosshair. Registered last so it draws on top.

func (*Cursor) Draw 

func (c *Cursor) Draw(dst *ebiten.Image, ctx *UICtx)

func (*Cursor) GetName 

func (c *Cursor) GetName() string

func (*Cursor) Tick 

func (c *Cursor) Tick(ctx *UICtx)

type CursorKind 

type CursorKind int
const (
	CursorDefault CursorKind = iota
	CursorLook
	CursorUse
	CursorTalk
	CursorTake
	CursorExit
)

type DialogBox 

type DialogBox struct {
	Name       string
	Bounds     Rectangle
	LineHeight int
	Padding    int
}

DialogBox renders the active conversation: one line at a time (advanced on click) followed by the player's choices. The widget is dormant unless ctx.Game.dialogueActive() — and while active it consumes input so nothing underneath reacts.

func (*DialogBox) BlocksClickAt 

func (d *DialogBox) BlocksClickAt(p Point) bool

BlocksClickAt — when a dialog is open, every click is ours.

func (*DialogBox) Draw 

func (d *DialogBox) Draw(dst *ebiten.Image, ctx *UICtx)

func (*DialogBox) GetName 

func (d *DialogBox) GetName() string

func (*DialogBox) Tick 

func (d *DialogBox) Tick(ctx *UICtx)

type Dialogue 

type Dialogue struct {
	Name  string
	Start string
	Nodes []DialogueNode
}

func (Dialogue) GetName 

func (d Dialogue) GetName() string

func (Dialogue) Node 

func (d Dialogue) Node(name string) (DialogueNode, bool)

func (Dialogue) TypeLabel 

func (d Dialogue) TypeLabel() string

type DialogueChoice 

type DialogueChoice struct {
	Text    string
	Show    Condition // nil = always
	Once    bool
	Actions []Action
}

type DialogueLine 

type DialogueLine struct {
	Speaker string
	Text    string
}

type DialogueManager 

type DialogueManager = Manager[Dialogue]

type DialogueNode 

type DialogueNode struct {
	Name    string
	Lines   []DialogueLine
	Choices []DialogueChoice
}

type EndCard 

type EndCard struct {
	Name string
}

EndCard is a fullscreen overlay shown when the ShowEnd action fires. While active it consumes every input so nothing underneath reacts.

func (*EndCard) Draw 

func (e *EndCard) Draw(dst *ebiten.Image, ctx *UICtx)

func (*EndCard) GetName 

func (e *EndCard) GetName() string

func (*EndCard) Tick 

func (e *EndCard) Tick(ctx *UICtx)

type Game 

type Game struct {
	Title         string
	Width, Height int

	ItemManager      *ItemManager
	SceneManager     *SceneManager
	CharacterManager *CharacterManager
	DialogueManager  *DialogueManager
	ScriptManager    *ScriptManager
	AssetManager     *AssetManager
	VerbManager      *VerbManager
	UIManager        *UIManager
	ThemeManager     *ThemeManager

	State     *State
	Inventory *Inventory
	Audio     *AudioPlayer
	Camera    *Camera
	Input     *Input

	MaxLogLines int // 0 = unlimited (memory grows); set per-game.

	// SaveDir overrides the on-disk directory used by Save/Load.
	// Empty falls back to "saves" relative to the working directory.
	SaveDir string
	// contains filtered or unexported fields
}

Game is the root aggregate. It carries every Manager plus the runtime state. A domain package builds one via NewGame, registers entities, optionally calls RegisterDefaultUI / UseTheme, then hands it to Run.

func NewGame 

func NewGame(title string, w, h int) *Game

NewGame initializes a game with empty entity managers, the SCUMM-style verb set, all preset themes, and "classic-scumm" selected. Widgets are NOT auto-registered — call RegisterDefaultUI(g) explicitly.

func (*Game) CharacterInScene 

func (g *Game) CharacterInScene(name string) bool

CharacterInScene reports whether a registered character is listed as an actor in the current scene. Used by the CharacterPanel widget so it auto-hides when the character isn't in view.

func (*Game) ClearSpeech 

func (g *Game) ClearSpeech()

func (*Game) DrawText 

func (g *Game) DrawText(dst *ebiten.Image, s string, x, y int, c color.Color)

DrawText is a thin wrapper that lets widgets accept a Theme-supplied color today and switch to text/v2 later without changing call sites.

func (*Game) FlashLine 

func (g *Game) FlashLine(text string)

FlashLine shows a status-line message for ~2 seconds.

func (*Game) HotspotAt 

func (g *Game) HotspotAt(p Point) *Hotspot

HotspotAt returns the topmost hotspot in the current scene whose Area contains p, or nil if none. Exposed so widgets (e.g., a verb coin that only opens over hotspots) can do their own hit-tests in their Tick — the engine's own resolution runs only after every widget had a chance, so widgets can't rely on it.

func (*Game) HoverHint 

func (g *Game) HoverHint() string

HoverHint composes the "verb + target" string used by the StatusLine.

func (*Game) HoverLabel 

func (g *Game) HoverLabel() string

func (*Game) Load 

func (g *Game) Load(slot int) error

Load replaces the runtime state with the contents of saves/slot<N>.json. Managers (items, scenes, characters, …) are left intact — Build() owns those. References in the save (scene name, theme, character names) are validated against the current managers before any state is touched.

func (*Game) LogAction 

func (g *Game) LogAction(text string)

LogAction appends a player-command line (rendered with the prompt color by ChatLog widgets).

func (*Game) LogResponse 

func (g *Game) LogResponse(speaker, text string)

LogResponse appends a reply line (rendered with the response color).

func (*Game) LogSystem 

func (g *Game) LogSystem(text string)

LogSystem appends a system/meta line (rendered with the response color).

func (*Game) Messages 

func (g *Game) Messages() []LogMessage

Messages returns the current log buffer (read-only).

func (*Game) OnStart 

func (g *Game) OnStart(a Action) *Game

func (*Game) Run 

func (g *Game) Run() error

(Game.Run is provided here for convenience; some callers prefer it.)

func (*Game) Save 

func (g *Game) Save(slot int) error

Save serialises the current session into saves/slot<N>.json (or SaveDir/slot<N>.json if set). The in-flight script and dialog are dropped — saves capture state at idle/ready boundaries.

func (*Game) SelectedVerb 

func (g *Game) SelectedVerb() string

func (*Game) SetHoverLabel 

func (g *Game) SetHoverLabel(s string)

func (*Game) SetSelectedVerb 

func (g *Game) SetSelectedVerb(s string)

func (*Game) SetSpeech 

func (g *Game) SetSpeech(speaker, text string)

SetSpeech / ClearSpeech are called by the Say action; widgets render whatever the current state says.

func (*Game) StartAt 

func (g *Game) StartAt(name string) *Game

func (*Game) Theme 

func (g *Game) Theme() Theme

func (*Game) UseTheme 

func (g *Game) UseTheme(name string)

func (*Game) Validate 

func (g *Game) Validate() error

type Hotspot 

type Hotspot struct {
	Name   string
	Area   Shape
	Label  string
	Cursor CursorKind

	OnLook Action
	OnUse  Action
	OnTalk Action
	OnTake Action
	OnGive Action

	// OnUseWith: when the player has an item selected and clicks this hotspot,
	// the engine looks up the item's Name here first.
	OnUseWith map[string]Action

	// OnVerb: custom verbs registered via g.VerbManager.
	OnVerb map[string]Action
}

type HotspotDebug 

type HotspotDebug struct {
	Name    string
	Enabled bool
	// ToggleKey, if non-zero, overrides the default F1 toggle.
	ToggleKey ebiten.Key
}

HotspotDebug overlays a colored outline on every hotspot of the current scene. F1 toggles it at runtime; the default is off.

func (*HotspotDebug) Draw 

func (h *HotspotDebug) Draw(dst *ebiten.Image, ctx *UICtx)

func (*HotspotDebug) GetName 

func (h *HotspotDebug) GetName() string

func (*HotspotDebug) Tick 

func (h *HotspotDebug) Tick(ctx *UICtx)

type Input 

type Input struct {
	// contains filtered or unexported fields
}

Input is read once per Update() and exposes a tiny "consume on use" API so that one click can be authoritative — e.g. clicking on a hotspot while a Say is active should only skip the Say, not also fire the hotspot underneath.

func (*Input) ConsumeLeft 

func (i *Input) ConsumeLeft()

func (*Input) ConsumeRight 

func (i *Input) ConsumeRight()

func (*Input) LeftClicked 

func (i *Input) LeftClicked() bool

func (*Input) Point 

func (i *Input) Point() Point

func (*Input) Pos 

func (i *Input) Pos() (int, int)

func (*Input) RightClicked 

func (i *Input) RightClicked() bool

type Inventory 

type Inventory struct {
	// contains filtered or unexported fields
}

func NewInventory 

func NewInventory() *Inventory

func (*Inventory) Add 

func (i *Inventory) Add(name string)

func (*Inventory) Has 

func (i *Inventory) Has(name string) bool

func (*Inventory) Items 

func (i *Inventory) Items() []string

func (*Inventory) Remove 

func (i *Inventory) Remove(name string)

func (*Inventory) Select 

func (i *Inventory) Select(name string)

func (*Inventory) Selected 

func (i *Inventory) Selected() string

type InventoryBar 

type InventoryBar struct {
	Name     string
	Origin   Point
	Slots    int
	Cols     int
	SlotSize int
	Gap      int

	PanelBG bool
}

InventoryBar shows the player's items as clickable slots. Left-click on a slot under the "look" verb prints the item's description; under any other verb, it toggles selection (the cursor "picks up" the item).

func (*InventoryBar) BlocksClickAt 

func (b *InventoryBar) BlocksClickAt(p Point) bool

BlocksClickAt — clickBlocker contract for the RadialVerbs widget.

func (*InventoryBar) Draw 

func (b *InventoryBar) Draw(dst *ebiten.Image, ctx *UICtx)

func (*InventoryBar) GetName 

func (b *InventoryBar) GetName() string

func (*InventoryBar) Tick 

func (b *InventoryBar) Tick(ctx *UICtx)

type Item 

type Item struct {
	Name        string
	Sprite      string // Asset.Name
	Description string

	OnUseSelf Action
	// OnUseWith: targetName -> action. Target may be a hotspot Name or another item Name.
	OnUseWith map[string]Action
}

func (Item) GetName 

func (i Item) GetName() string

func (Item) TypeLabel 

func (i Item) TypeLabel() string

type ItemManager 

type ItemManager = Manager[Item]

type LogKind 

type LogKind int

LogKind classifies a chat-log entry — UI widgets style them differently. 

const (
	LogAction   LogKind = iota // player command ("> look at door")
	LogResponse                // in-world reply / Say output
	LogSystem                  // game/system message
)

type LogMessage 

type LogMessage struct {
	Speaker string // empty for actions / system
	Text    string
	Kind    LogKind
}

LogMessage is a single line in the chat-log buffer.

type Manager 

type Manager[T Named] struct {
	// contains filtered or unexported fields
}

Manager is the single registry shape used by every entity type. Each entity kind gets a named alias (ItemManager = Manager[Item], etc.). Insertion order is preserved — Names() returns it. SortedNames() returns alphabetical.

func NewManager 

func NewManager[T Named]() *Manager[T]

func (*Manager[T]) Each 

func (m *Manager[T]) Each(fn func(T))

func (*Manager[T]) Get 

func (m *Manager[T]) Get(name string) (T, bool)

func (*Manager[T]) Has 

func (m *Manager[T]) Has(name string) bool

func (*Manager[T]) Len 

func (m *Manager[T]) Len() int

func (*Manager[T]) MustGet 

func (m *Manager[T]) MustGet(name string) T

func (*Manager[T]) Names 

func (m *Manager[T]) Names() []string

Names returns the registered names in insertion order. Use SortedNames when iteration order needs to be stable across runs.

func (*Manager[T]) Register 

func (m *Manager[T]) Register(v T)

Register adds v to the registry. Panics on empty or duplicate name — these are construction-time bugs, not runtime conditions.

func (*Manager[T]) Remove 

func (m *Manager[T]) Remove(name string)

Remove drops a registered entry. Used by hot-reload / dynamic UI changes. Silently no-ops on unknown names.

func (*Manager[T]) SortedNames 

func (m *Manager[T]) SortedNames() []string

type MouseButton 

type MouseButton int

MouseButton identifies which mouse button a widget binds to (e.g. the RadialVerbs widget uses MouseButtonRight by default). 

const (
	MouseButtonLeft MouseButton = iota
	MouseButtonRight
)

type Named 

type Named interface {
	GetName() string
}

Named is implemented by every entity that can be registered into a Manager.

type Panel 

type Panel struct {
	Name   string
	Bounds Rectangle
	// BG, if nil, falls back to the active Theme.PanelBG.
	BG color.Color
	// Border thickness in pixels (0 = no border).
	Border int
	// BorderColor, if nil, falls back to Theme.DialogBorder.
	BorderColor color.Color
}

Panel is a generic background widget — a colored rectangle. Useful as a backdrop for grouping other widgets or as a chat/notebook frame.

func (*Panel) Draw 

func (p *Panel) Draw(dst *ebiten.Image, ctx *UICtx)

func (*Panel) GetName 

func (p *Panel) GetName() string

func (*Panel) Tick 

func (p *Panel) Tick(ctx *UICtx)

type Point 

type Point struct {
	X, Y float64
}

func (Point) Add 

func (p Point) Add(q Point) Point

func (Point) Dist 

func (p Point) Dist(q Point) float64

func (Point) Sub 

func (p Point) Sub(q Point) Point

type Polygon 

type Polygon struct {
	Points []Point
}

func Poly 

func Poly(pts ...Point) Polygon

func (Polygon) Bounds 

func (g Polygon) Bounds() Rectangle

func (Polygon) Contains 

func (g Polygon) Contains(pt Point) bool

type RadialVerbs 

type RadialVerbs struct {
	Name    string
	Trigger MouseButton
	Radius  float64

	// AlwaysVisible turns the widget into a permanent verb-wheel fixed at
	// Center. The trigger button is ignored in this mode; left-click picks
	// the verb slice under the cursor.
	AlwaysVisible bool
	Center        Point

	// HotspotOnly (trigger mode only) makes the wheel open only when the
	// trigger lands on a registered hotspot in the current scene. Right-
	// clicks on empty space fall through to handleSceneInput (so the
	// SCUMM "reset verb to look" behaviour still works there).
	HotspotOnly bool

	// Labels overrides the rendered verb label per verb Name. Useful when
	// the regular Verb.Label is too long to fit inside the wheel — e.g.
	// {"use": "Tedd", "take": "Vedd"}. Falls back to Verb.Label.
	Labels map[string]string
	// contains filtered or unexported fields
}

RadialVerbs is the verb-coin alternative to VerbBar: secondary-click on the scene opens a radial menu of every registered verb, click on a slice (or close to its center) picks that verb.

To use it instead of a VerbBar, register RadialVerbs and skip VerbBar. Both can coexist if you really want.

func (*RadialVerbs) BlocksClickAt 

func (r *RadialVerbs) BlocksClickAt(p Point) bool

BlocksClickAt — when the wheel is open (or always visible), clicks on it should not pass through to the scene underneath.

func (*RadialVerbs) Draw 

func (r *RadialVerbs) Draw(dst *ebiten.Image, ctx *UICtx)

func (*RadialVerbs) GetName 

func (r *RadialVerbs) GetName() string

func (*RadialVerbs) Tick 

func (r *RadialVerbs) Tick(ctx *UICtx)

type Rectangle 

type Rectangle struct {
	X, Y, W, H float64
}

func Rect 

func Rect(x, y, w, h float64) Rectangle

func (Rectangle) Bounds 

func (r Rectangle) Bounds() Rectangle

func (Rectangle) Center 

func (r Rectangle) Center() Point

func (Rectangle) Contains 

func (r Rectangle) Contains(p Point) bool

type Runner 

type Runner interface {
	Tick(ctx *Ctx) Status
}

Runner is one in-flight execution of an Action. Tick advances it one frame and returns whether it's still running, done, or failed.

type Scene 

type Scene struct {
	Name       string
	Title      string // optional human-readable title for the TopBar widget
	Background string // Asset.Name
	Music      string // Asset.Name (optional)
	Hotspots   []Hotspot
	Walkboxes  []Polygon
	Triggers   []Trigger
	Actors     []SceneActor
	OnEnter    Action
	OnLeave    Action
}

func (Scene) GetName 

func (s Scene) GetName() string

func (Scene) TypeLabel 

func (s Scene) TypeLabel() string

type SceneActor 

type SceneActor struct {
	CharacterName string
	At            Point
}

SceneActor places a registered Character at a starting position inside a scene.

type SceneManager 

type SceneManager = Manager[Scene]

type Script 

type Script struct {
	Name    string
	Actions Action
}

func (Script) GetName 

func (s Script) GetName() string

func (Script) TypeLabel 

func (s Script) TypeLabel() string

type ScriptManager 

type ScriptManager = Manager[Script]

type Shape 

type Shape interface {
	Contains(p Point) bool
	Bounds() Rectangle
}

Shape is a hotspot area. Rectangle and Polygon both satisfy it.

type Size 

type Size struct {
	W, H int
}

Size is a {Width, Height} pair in screen-space pixels.

type SpeechBubble 

type SpeechBubble struct {
	Name      string
	MaxWidth  int
	Padding   int
	OffsetY   int
	FallbackY int
}

SpeechBubble renders the line set by the Say action above the speaking character (or at FallbackY if the speaker has no on-screen position).

func (*SpeechBubble) Draw 

func (s *SpeechBubble) Draw(dst *ebiten.Image, ctx *UICtx)

func (*SpeechBubble) GetName 

func (s *SpeechBubble) GetName() string

func (*SpeechBubble) Tick 

func (s *SpeechBubble) Tick(ctx *UICtx)

type State 

type State struct {
	// contains filtered or unexported fields
}

func NewState 

func NewState() *State

func (*State) ClearFlag 

func (s *State) ClearFlag(name string)

func (*State) Flag 

func (s *State) Flag(name string) bool

func (*State) NoteTalked 

func (s *State) NoteTalked(node string)

func (*State) NoteVisit 

func (s *State) NoteVisit(name string)

func (*State) SetFlag 

func (s *State) SetFlag(name string)

func (*State) SetVar 

func (s *State) SetVar(name string, v any)

func (*State) Talked 

func (s *State) Talked(node string) int

func (*State) Var 

func (s *State) Var(name string) any

func (*State) Visited 

func (s *State) Visited(name string) int

type Status 

type Status int

Status is the outcome of one tick of a Runner. 

const (
	StatusRunning Status = iota
	StatusDone
	StatusFailed
)

type StatusLine 

type StatusLine struct {
	Name  string
	Y     int
	Align Align
	// ScreenWidth, if 0, uses Game.Width.
	ScreenWidth int
}

StatusLine renders a single line: either the active flash message (set by FlashLine) or the hover-hint (verb + target under the cursor).

func (*StatusLine) Draw 

func (s *StatusLine) Draw(dst *ebiten.Image, ctx *UICtx)

func (*StatusLine) GetName 

func (s *StatusLine) GetName() string

func (*StatusLine) Tick 

func (s *StatusLine) Tick(ctx *UICtx)

type Theme 

type Theme struct {
	Name string

	PanelBG    color.Color
	StatusText color.Color
	FlashText  color.Color

	VerbButtonBG         color.Color
	VerbButtonSelectedBG color.Color
	VerbButtonText       color.Color

	InventorySlotBG         color.Color
	InventorySlotSelectedBG color.Color

	SpeechBubbleBG    color.Color
	SpeechDefaultText color.Color

	DialogBG          color.Color
	DialogBorder      color.Color
	DialogChoiceBG    color.Color
	DialogChoiceHover color.Color
	DialogSpeaker     color.Color
	DialogText        color.Color

	EndCardBG   color.Color
	EndCardText color.Color

	CursorColor    color.Color
	HotspotOutline color.Color

	// SceneBackdrop is painted before the scene background. Useful for
	// letterboxing or filling areas not covered by a smaller backdrop.
	SceneBackdrop color.Color

	// Rich-UI widgets (TopBar, CharacterPanel, ChatLog).
	TopBarBG     color.Color
	TopBarText   color.Color
	TopBarAccent color.Color // score / highlighted number color

	ChatLogBG       color.Color
	ChatLogPrompt   color.Color // "> look at door" lines
	ChatLogResponse color.Color // in-world reply lines
	ChatLogSystem   color.Color // system / meta lines

	CharacterPanelBG     color.Color
	CharacterPanelBorder color.Color
	CharacterPanelTitle  color.Color // "PLAYER" / "NPC" badge color
}

Theme is a registry-stored entity carrying every color the built-in widgets read. Multiple themes can be registered; the active one is addressed by name on the Game.

func (Theme) GetName 

func (t Theme) GetName() string

func (Theme) TypeLabel 

func (t Theme) TypeLabel() string

type ThemeManager 

type ThemeManager = Manager[Theme]

type Timer 

type Timer struct {
	Elapsed float64
}

Timer accumulates seconds. Tick advances it; Reset zeroes it.

func (*Timer) Done 

func (t *Timer) Done(after float64) bool

func (*Timer) Reset 

func (t *Timer) Reset()

func (*Timer) Tick 

func (t *Timer) Tick(dt float64)

type TopBar 

type TopBar struct {
	Name   string
	Height int

	// LeftText overrides the auto-discovered scene Title/Name.
	LeftText string
	// ScoreVar is a State Var key whose value is fmt-printed as the
	// center score; empty = no score shown.
	ScoreVar string
	ScoreMax int // when >0, rendered as "Score: X/MAX"

	// TimeVar is a State Var key whose value is printed at the right
	// edge (e.g. "Day 2 - 14:32"); empty = nothing on the right.
	TimeVar string
}

TopBar is a thin strip across the top of the screen with three sections: scene title on the left, a score number in the center, and a day/time string on the right. Empty fields are skipped.

func (*TopBar) BlocksClickAt 

func (t *TopBar) BlocksClickAt(p Point) bool

BlocksClickAt — the TopBar swallows clicks so the radial menu doesn't pop up under it.

func (*TopBar) Draw 

func (t *TopBar) Draw(dst *ebiten.Image, ctx *UICtx)

func (*TopBar) GetName 

func (t *TopBar) GetName() string

func (*TopBar) Tick 

func (t *TopBar) Tick(ctx *UICtx)

type Trigger 

type Trigger struct {
	Name string
	When Condition
	Do   Action
	Once bool
}

Trigger fires Do when its When condition first becomes true after the trigger arms (on scene enter). Rising-edge semantics: the Do action is queued only on a false→true transition, so a condition that becomes true and stays true fires exactly once per arming. Once=true makes the trigger fire at most once per arming regardless of further toggles.

type UICtx 

type UICtx struct {
	Game *Game
	DT   float64
}

UICtx is the per-tick context handed to widgets. Game is the root aggregate; DT is seconds since the previous frame.

type UIManager 

type UIManager = Manager[Widget]

UIManager registers Widget instances. Same shape as every other manager.

type Verb 

type Verb struct {
	Name    string
	Label   string
	Default Action
}

Verb is a registered "action word" (Look, Use, Talk, Take, …). The VerbBar / RadialVerbs widgets read the VerbManager to know which verbs to render; Hotspot.handler(name) looks up the bound action by Verb.Name.

func (Verb) GetName 

func (v Verb) GetName() string

func (Verb) TypeLabel 

func (v Verb) TypeLabel() string

type VerbBar 

type VerbBar struct {
	Name   string
	Origin Point
	Cols   int
	Button Size
	Gap    Point

	// PanelBG, if non-nil, paints a backdrop behind the buttons. nil = use Theme.PanelBG.
	PanelBG bool
}

VerbBar is the SCUMM-style permanent verb panel. It reads the VerbManager every frame so newly-registered verbs show up automatically.

func (*VerbBar) BlocksClickAt 

func (v *VerbBar) BlocksClickAt(p Point) bool

BlocksClickAt is part of the clickBlocker contract — keeps the RadialVerbs widget from popping up over the verb bar.

func (*VerbBar) Draw 

func (v *VerbBar) Draw(dst *ebiten.Image, ctx *UICtx)

func (*VerbBar) GetName 

func (v *VerbBar) GetName() string

func (*VerbBar) Tick 

func (v *VerbBar) Tick(ctx *UICtx)

type VerbManager 

type VerbManager = Manager[Verb]

type Widget 

type Widget interface {
	Named
	Tick(ctx *UICtx)
	Draw(dst *ebiten.Image, ctx *UICtx)
}

Widget is the minimal surface a HUD element must implement to participate in the per-frame loop. The library ships several built-in widgets (VerbBar, InventoryBar, DialogBox, etc.) and the domain can register arbitrary new ones — chat panels, minimaps, hotbars — as long as they satisfy this interface.

Lifecycle:

  • Tick runs once per frame in REVERSE registration order so the top-most widget gets a chance to consume input first via ctx.Game.Input.ConsumeLeft / ConsumeRight.
  • Draw runs once per frame in REGISTRATION order, so widgets registered later are painted on top.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.