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

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

package main

import (
    "log"
    "git.teletypegames.org/engines/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; Run calls it if no widgets are registered
    if err := inkwell.Run(g); err != nil {
        log.Fatal(err)
    }
}

// core.manager.go

type Named interface {
    GetName() string
}

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

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]

func (i Item) GetName() string   { return i.Name }
func (i Item) TypeLabel() string { return "item" }

// core.game.go

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

    SceneRect Rectangle          // az ablak azon része, amit a kép elfoglal
    ExitLook  func(Exit) Action  // alap nézés-válasz a generált kijáratokhoz
    ExitTake  func(Exit) Action  // alap elvétel-válasz a generált kijáratokhoz

    MaxLogLines int
}

g := inkwell.NewGame("Real World", 640, 380)
g.SceneManager = mySceneManager
g.AssetManager = myAssetManager

func (g *Game) StartAt(name string) *Game     // entry scene
func (g *Game) OnStart(script string) *Game    // script run after the scene's OnEnter
func (g *Game) OnFinale(script string) *Game  // closing script, queued after OnStart
func (g *Game) Validate() error               // cross-check name references
func (g *Game) Run() error                    // same as inkwell.Run(g)

func (g *Game) CurrentScene() string          // ahol a játékos van
func (g *Game) PreviousScene() string         // ahonnan jött; ide vezet a Back()
func (g *Game) SceneArea() Rectangle          // SceneRect, vagy a teljes ablak
func (g *Game) SceneHotspots(name string) []Hotspot

func (g *Game) Theme() Theme
func (g *Game) UseTheme(name string)          // runtime switch, next frame uses it

g.StartAt(start)
g.OnStart(ScriptOpening)
if finale {
    g.OnFinale(ScriptFinale)
}

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

func (g *Game) CharacterInScene(name string) bool   // CharacterPanel auto-hide
func (g *Game) DrawText(dst *ebiten.Image, s string, x, y int, c color.Color)

type LogKind int
const (
    LogAction   // "> look at door" — player commands
    LogResponse // in-world replies, Say output
    LogSystem   // 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

// 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

// asset.def.go

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

type Asset struct {
    Name string  // logical id, "bg/kitchen"
    Path string  // "assets/bg/kitchen.png"
    Kind AssetKind
}

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

// scene.def.go

type Scene struct {
    Name       string
    Title      string         // human-readable, read by TopBar
    Background string         // Asset.Name
    Music      string         // Asset.Name, optional
    Hotspots   []Hotspot
    Exits      []Exit         // kapcsolatok más jelenetekhez
    Walkboxes  []Polygon
    Triggers   []Trigger
    Actors     []SceneActor
    OnEnter    Action
    OnLeave    Action
}

type SceneActor struct {
    CharacterName string
    At            Point
}

// scene.exit.go

type Exit struct {
    To      string      // a céljelenet; üresen "vissza, amerről jöttél"
    Label   string      // ahogy az állapotsor nevezi
    Side    ExitSide    // hol helyezkedik el, ha az Area nil
    Area    Shape       // felülírja a Side adta élsávot
    Needs   string      // zászló, aminek állnia kell, mielőtt kinyílik
    Blocked Action      // ami addig történik, amíg nem áll
    OnLook  Action      // felülírja a Game.ExitLook-ot erre a kijáratra
    OnTake  Action      // felülírja a Game.ExitTake-et erre a kijáratra
}

type ExitSide int
const (
    ExitLeft  ExitSide = iota // a bal szélen ki
    ExitRight                 // a jobb szélen ki
    ExitBack                  // a kép mélyébe
    ExitNear                  // a kamera felé kifelé
)

func ExitName(to string) string

Scene{
    Name: "alley",
    Exits: []Exit{
        {To: "noodle_house", Label: "vissza az utcára", Side: ExitLeft},
        {To: "", Label: "a tűzlétra", Side: ExitBack,
         Needs: "has_ladder", Blocked: Say("paul", "Nem érem el.")},
    },
}

// scene.hotspot.go

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

    OnLook Action
    OnUse  Action
    OnTalk Action
    OnTake Action
    OnGive Action

    OnUseWith map[string]Action   // item Name -> action
    OnVerb    map[string]Action   // custom verb Name -> action
}

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

// scene.trigger.go

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

// item.def.go

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

    OnUseSelf Action
    OnUseWith map[string]Action         // target: hotspot Name or item Name
}

// item.inventory.go

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

// actor.def.go

type Character struct {
    Name        string
    Sprite      string                       // Asset.Name
    Animations  map[string]AnimationClip
    Speed       float64                      // px/sec, default 60
    SpeechColor color.Color
    Start       Point
    W, H        float64                      // placeholder size hint
}

type AnimationClip struct {
    Frames    []Rectangle                    // source rects in the sprite sheet
    FrameTime float64
    Loop      bool
}

// dialog.def.go

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

type DialogueNode struct {
    Name    string
    Lines   []DialogueLine              // one per 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 the first pick
    Actions []Action
}

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

// action.script.go

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

// ui.verb.go

type Verb struct {
    Name    string                      // canonical id, "look"
    Label   string                      // display label, "Nézd"
    Default Action                      // runs when the hotspot has no handler
}

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

// action.def.go

type Action interface {
    Start() Runner
}

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

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
    Item    *Item
}

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
    }
    return StatusRunning
}

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
})

// action.condition.go

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

// state.def.go

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 a Once pick

// 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
)

// ui.panel.go — colored rectangle, optional border; backdrop for other widgets
type Panel struct {
    Name        string
    Bounds      Rectangle
    BG          color.Color    // nil -> Theme.PanelBG
    Border      int            // 0 = none
    BorderColor color.Color    // nil -> Theme.DialogBorder
}

// ui.status.go — one line: the active flash message, else the hover hint
type StatusLine struct {
    Name        string
    Y           int
    Align       Align          // default AlignCenter
    ScreenWidth int            // 0 -> Game.Width
}

// ui.verb_bar.go — SCUMM verb panel, Cols x ceil(N/Cols) grid from VerbManager.Names()
type VerbBar struct {
    Name    string
    Origin  Point
    Cols    int               // default 2
    Button  Size
    Gap     Point
    PanelBG bool
}

// ui.verb_radial.go — verb coin or permanent wheel
type RadialVerbs struct {
    Name    string
    Trigger MouseButton       // default MouseButtonRight
    Radius  float64           // default 40

    AlwaysVisible bool        // permanent wheel at Center; Trigger ignored
    Center        Point

    Labels map[string]string  // shorten a label so it fits the disk
}

// ui.inventory.go — item slots; hover sets the description, click toggles selection
type InventoryBar struct {
    Name     string
    Origin   Point
    Slots    int
    Cols     int             // 0 -> Slots (single row)
    SlotSize int
    Gap      int
    PanelBG  bool
}

// ui.speech.go — draws whatever Game.SetSpeech last set, above the speaker's head
type SpeechBubble struct {
    Name      string
    MaxWidth  int                // wrap width, default 200
    Padding   int                // default 3
    OffsetY   int                // lift above head
    FallbackY int                // anchor when the speaker is unknown
}

// ui.dialog_box.go — dormant unless a dialogue runs; then consumes every click
type DialogBox struct {
    Name       string
    Bounds     Rectangle      // default Rect(0, 140, Width, 60)
    LineHeight int            // default 14
    Padding    int            // default 6
}

// ui.end_card.go — fullscreen overlay from ShowEnd; consumes every click
type EndCard struct{ Name string }

// ui.cursor.go — crosshair, or the selected item's sprite when it has one
type Cursor struct{ Name string }

// ui.hotspot_debug.go — outlines every hotspot in the scene
type HotspotDebug struct {
    Name      string
    Enabled   bool
    ToggleKey ebiten.Key       // 0 -> ebiten.KeyF1
}

// ui.top_bar.go — left: LeftText or Scene.Title | center: score | right: time
type TopBar struct {
    Name     string
    Height   int                  // default 12
    LeftText string
    ScoreVar string                // State.Var key; "" = no score
    ScoreMax int                   // >0 -> "Score: X/MAX"
    TimeVar  string                // State.Var key; "" = no time
}

// ui.character_panel.go — portrait, role badge, stat rows;
// auto-hides when the character is not an actor in the current scene
type CharStat struct {
    Label  string
    VarKey string                  // State.Var(VarKey), fmt-printed
}

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

// ui.chat_log.go — Game.Messages() with per-kind colors, newest at the bottom
type ChatLog struct {
    Name       string
    Bounds     Rectangle
    LineHeight int                 // default 10
    Padding    int                 // default 3
    ShowBorder bool
}

type clickBlocker interface {
    BlocksClickAt(p Point) bool
}

// ui.defaults.go

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

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, …
}

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

// ui.theme.go

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  color.Color

    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
}

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

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

// asset.audio.go

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

// input.def.go

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()

// core.dsl.go

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

engine.Update:
    poll input
    update transition
    if fading out -> return

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

    clear hoverLabel
    for w in reversed(UIManager): w.Tick(uictx)   # top-down input
    handleSceneInput()                            # hotspots, right-click reset
    tick characters

engine.Draw:
    fill Theme.SceneBackdrop
    draw scene background
    for c in characters sorted by Y: drawCharacter(c)
    for w in UIManager (registration order): w.Draw(screen, uictx)
    draw transition overlay

func (g *Game) Validate() error

// state.save.go

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

// 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")
)

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

inkwell.DebugLog = true                 // script queue, audio, scene change -> stderr
&inkwell.HotspotDebug{Enabled: true}    // start with the F1 overlay on

inkwell/                            # module git.teletypegames.org/engines/inkwell
├── 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
├── 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               # alias + lazy loader
├── asset.audio.go                 # AudioPlayer (WAV/OGG/MP3, looping music)
├── asset.text.go                  # drawText / wrapText
│
├── scene.def.go                   # Scene, SceneActor
├── scene.manager.go
├── scene.hotspot.go               # Hotspot, CursorKind
├── scene.exit.go                  # Exit, ExitSide + edge-strip geometry
├── scene.trigger.go               # Trigger + rising-edge sweep
├── scene.path.go                  # walkbox routing (BFS)
├── scene.transition.go            # fade overlay (internal)
├── scene.camera.go                # Camera (identity stub)
│
├── item.def.go                    # Item
├── item.manager.go
├── item.inventory.go              # Inventory
│
├── actor.def.go                   # Character
├── actor.manager.go
├── actor.animation.go             # AnimationClip + tickAnimation
│
├── dialog.def.go                  # Dialogue, DialogueNode, DialogueChoice
├── dialog.manager.go
│
├── action.def.go                  # Action, Runner, Ctx, Status + built-ins
├── action.condition.go            # Condition + combinators
├── action.script.go               # Script entity
├── action.manager.go
│
├── state.def.go                   # State (flags, vars, visited, talked)
├── state.save.go                  # Save/Load JSON
│
├── input.def.go                   # Input (consume-on-use)
│
├── ui.widget.go                   # Widget, UICtx, Size, Align
├── ui.manager.go                  # alias + ordered/reversed iterators
├── ui.theme.go                    # Theme + ThemeManager
├── ui.theme_presets.go            # 4 presets
├── ui.defaults.go                 # RegisterDefaultUI / RadialVerbUI / RichUI
├── ui.verb.go                     # Verb + VerbManager
├── ui.verb_bar.go
├── ui.verb_radial.go
├── ui.inventory.go
├── ui.status.go
├── ui.speech.go
├── ui.dialog_box.go
├── ui.end_card.go
├── ui.cursor.go
├── ui.hotspot_debug.go
├── ui.panel.go
├── ui.top_bar.go
├── ui.character_panel.go          # + CharStat
├── ui.chat_log.go
│
├── LICENSE.md                     # MIT
└── README.md