package action

import "git.teletypegames.org/engines/inkwell/inkbase/action"

Package action holds the generic actions — the ones any Ebitengine game built on inkbase can use — and the combinators every script is built from.

Action and Runner

An inkbase.Action is an immutable spec of work, safe to keep in a field and run many times. Its Start makes an inkbase.Runner, one in-flight execution carrying whatever state it needs (elapsed time, sub-runners, a started flag). The host never ticks an Action directly; it asks for a fresh Runner every time the action runs.

A Runner's Tick is called once per frame with an inkbase.Ctx — the frame's DT in seconds, the inkbase.State, and the Game as an opaque any — and answers an inkbase.Status: StatusRunning (tick me again), StatusDone (a sequence moves on) or StatusFailed (a sequence stops here, which is how RequireItem aborts the rest of a script).

An inkwell game runs one action at a time, from a queue; parallel work goes inside one action, with Par.

The actions

An action that needs more than the State type-asserts ctx.Game to the host interface named above; a host that does not implement it gets an action that does nothing.

Custom actions

For a one-shot change, Custom is shortest: 

bump := action.Custom(func(ctx *inkbase.Ctx) inkbase.Status {
	score, _ := ctx.State.Var("score").(int)
	ctx.State.SetVar("score", score+10)
	return inkbase.StatusDone
})

Work that runs over several frames — an animation, a tween, a poll — implements Action and Runner directly: 

type fade struct{ seconds float64 }

func (f fade) Start() inkbase.Runner { return &fadeRunner{spec: f} }

type fadeRunner struct {
	spec    fade
	elapsed float64
}

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

Index

Functions

func ClearFlag

func ClearFlag(name string) inkbase.Action

ClearFlag lowers a world-state flag.

func Custom

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

Custom wraps a user function as an Action.

func Flash

func Flash(text inkbase.Text) inkbase.Action

Flash puts a line in the status strip.

func GoBack

func GoBack() inkbase.Action

GoBack shows the Stage that was showing before the current one.

func GoToStage

func GoToStage(s *stage.Stage) inkbase.Action

GoToStage shows another Stage.

func If

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

If runs then when cond holds and els otherwise. The branch is chosen once, on the frame the action starts.

func Learn

func Learn(entity inkbase.Knowable) inkbase.Action

Learn marks an entity Known.

func LoadSlot

func LoadSlot(slot int) inkbase.Action

LoadSlot restores a saved session.

func Noting

func Noting(name string, value any, inner inkbase.Action) inkbase.Action

Noting writes a world-state variable for exactly as long as the action it wraps is running, and clears it afterwards.

func Par

func Par(actions ...inkbase.Action) inkbase.Action

Par starts every action on the same frame and is done when all are.

func PlayMusic

func PlayMusic(music *inkbase.Music) inkbase.Action

PlayMusic starts a track.

func PlaySound

func PlaySound(sound *inkbase.Sound) inkbase.Action

PlaySound plays a noise once.

func Quit

func Quit() inkbase.Action

Quit closes the window at the end of the frame.

func Restart

func Restart() inkbase.Action

Restart begins a new session.

func RunScript

func RunScript(script *inkbase.Script) inkbase.Action

RunScript runs a named action sequence in place.

func SaveSlot

func SaveSlot(slot int) inkbase.Action

SaveSlot writes the session to a slot.

func Seq

func Seq(actions ...inkbase.Action) inkbase.Action

Seq runs its actions one after another. A Seq handed to another Seq is flattened.

func SetFlag

func SetFlag(name string) inkbase.Action

SetFlag raises a world-state flag.

func SetVar

func SetVar(name string, v any) inkbase.Action

SetVar writes a world-state variable.

func SetVarIfEmpty

func SetVarIfEmpty(name string, v any) inkbase.Action

SetVarIfEmpty writes a world-state variable only while nothing has written it yet.

func StopMusic

func StopMusic() inkbase.Action

StopMusic silences the music track.

func UseLang

func UseLang(lang string) inkbase.Action

UseLang switches the language every Text resolves into.

func UseTheme

func UseTheme(name string) inkbase.Action

UseTheme switches the active theme by name.

func Wait

func Wait(seconds float64) inkbase.Action

Wait holds the frame for a number of seconds.

Types

type AudioHost

type AudioHost interface {
	GameAudio() *asset.AudioPlayer
}

AudioHost provides access to the audio player.

type Flasher

type Flasher interface {
	FlashLine(text inkbase.Text)
}

Flasher is the host interface a Flash action needs.

type LifecycleHost

type LifecycleHost interface {
	Restart()
}

LifecycleHost provides restart and quit.

type Quitter

type Quitter interface {
	SetQuitting()
}

Quitter can be told to quit.

type SettingsSaver

type SettingsSaver interface {
	SaveSettings() error
}

SettingsSaver can persist settings after a change.

type SlotHost

type SlotHost interface {
	LoadLater(slot int)
	Save(slot int) error
}

SlotHost provides save and load.

type StageHost

type StageHost interface {
	GoToStage(s *stage.Stage)
	PreviousStage() *stage.Stage
}

StageHost provides stage navigation.

type ThemeHost

type ThemeHost interface {
	UseThemeByName(name string)
	SaveSettings() error
}

ThemeHost can switch themes.