wisp

type AnimationSettings struct {
	// CullOffscreen stops an entity outside the view from advancing its
	// animation. It saves work in a crowded world, and it means an enemy walks
	// on screen mid-stride instead of from frame zero.
	CullOffscreen bool
	// FrameCount is how many frames a grid sheet puts in one row.
	FrameCount int
	// FrameDuration is how long one frame lasts, in milliseconds.
	FrameDuration float64
}

type AudioSettings struct {
	// MusicVolume scales the music, on top of Volume.
	MusicVolume float64
	// PitchJitter randomises playback speed by up to this fraction, so the
	// same hit sound does not sound identical twenty times in a row.
	PitchJitter float64
	// SfxVolume scales the sound effects, on top of Volume.
	SfxVolume float64
	// Voices is how many copies of one sound may play at once. One copy means
	// three monsters dying together make one sound.
	Voices int
	// Volume scales everything.
	Volume float64
}

type CameraSettings struct {
	// DeadzoneHeight is how far the target may move up or down before the
	// camera follows, in pixels.
	DeadzoneHeight float64
	// DeadzoneWidth is the same across.
	DeadzoneWidth float64
	// Lookahead pushes the camera this many pixels ahead of the way the target
	// is moving, so you see where you are going.
	Lookahead float64
	// Smoothing is how fast the camera catches up with its target, per
	// second: 0 snaps to it, 8 is a soft follow, 30 is almost a snap. The
	// engine closes the gap by 1-exp(-Smoothing*dt), so the feel does not
	// change between a 60 Hz screen and a 144 Hz one.
	Smoothing float64
	// Snap rounds the camera to whole pixels. Off, tile edges show seams.
	Snap bool
}

type Config struct {
	// FullscreenKey toggles fullscreen. Empty means "f". [KeyNone] leaves
	// fullscreen out, so a game may use F for itself.
	FullscreenKey string
	// Height of the drawing surface, in pixels. 0 means 360.
	Height int
	// MenuKey opens and closes the tuning menu. Empty means "m". [KeyNone]
	// leaves the menu out, which is what a shipped game wants: with no menu
	// the engine also stops reading and writing the browser's storage.
	MenuKey string
	// Mount is the CSS selector the canvas is appended to. Empty means
	// "main", falling back to the document body.
	Mount string
	// Width of the drawing surface, in pixels. 0 means 640. 640x360 scales to
	// 1080p and 4K by whole numbers, so nothing blurs.
	Width int
}

type DebugSettings struct {
	// ShowHitBoxes outlines every entity's hit box, the rectangle
	// [Engine.BoundingBox] returns, over the scene. It is where the rules have
	// the entity rather than where its sprite is drawn, so with
	// [RenderSettings.Interpolate] on the box runs up to a tick ahead of the
	// sprite — that gap is the blend made visible. An invisible entity's box
	// is drawn too, because an unseen collider is what somebody switching this
	// on is looking for.
	ShowHitBoxes bool
	// ShowMetrics draws the frame-time and memory overlay.
	ShowMetrics bool
}

type Direction uint8

type Engine struct {
	Settings

	// Alpha is the opacity, 0 to 1.
	Alpha []float64
	// FrameOffset is the animation frame showing now.
	FrameOffset []int
	// FrameTime is the milliseconds spent on the current frame.
	FrameTime []float64
	// ImageColumn is the sheet column of the sprite's first frame.
	ImageColumn []int
	// ImageIndex is which loaded image, in [Engine.LoadImages] order.
	ImageIndex []int
	// ImageRow is which animation is playing: a row on the grid convention, a
	// tag's index when the image has a [Sheet]. RowForState overwrites it for
	// entities whose state has a bit in RowMask, and [Engine.Play] writes the
	// tag it looked up.
	ImageRow []int
	// PrevX is where the entity was when the tick running now began, and
	// PrevY the same. [Engine.DrawPos] is what reads them, to place a sprite
	// between two ticks; [Engine.Place] is how a game writes them, for an
	// entity that jumps somewhere rather than travelling there.
	PrevX []float64
	PrevY []float64
	// ScreenSpace draws the entity in canvas pixels, past the camera.
	ScreenSpace []bool
	// SpeedFactor multiplies World.Speed for this entity.
	SpeedFactor []float64
	// SpriteHeight is the drawn height in pixels.
	SpriteHeight []float64
	// SpriteWidth is the drawn width in pixels.
	SpriteWidth []float64
	// State is the entity's state bits. The engine reads the ones it knows; a
	// game adds its own above bit 15.
	State []uint64
	// X is the world x of the sprite's centre.
	X []float64
	// Y is the world y of the sprite's centre.
	Y []float64
	// Z is the draw layer. Lower draws first.
	Z []int

	// Facing is how many ways [Engine.Move] turns an entity: 2, 4 or 8, and 0
	// means 2. At 2 only the horizontal axis turns it, which is what a sheet
	// with a left row and a right row wants, and what every game had until
	// now. At 4 a move sets one of the four facing bits; at 8 a diagonal sets
	// two, one from each axis, so the eight rotations of a top-down sprite
	// key a RowForState map through [MaskPose]. Both halves of a networked
	// game set the same value, because the server is what turns a player.
	Facing int
	// RowForState maps a state, masked by RowMask, to the sheet row that draws
	// it. A game fills it once; the engine only looks things up, so it never
	// has to know what an "attack" is.
	RowForState map[uint64]int
	// RowMask picks the bits RowForState is keyed by. Start it with [MaskPose]
	// and add the game's own action bits.
	RowMask uint64

	// Sheets describes the loaded images: one entry per image, in the order
	// [Engine.LoadImages] took them. A game fills it once, from [ParseSheet]
	// or [GridSheet]. An image with no entry — or a zero Sheet, or one with no
	// tags — draws on the grid convention instead, so a game that never had a
	// sheet never needs one. See [Sheet].
	Sheets []Sheet

	// CamTarget is the entity the camera follows, or -1 for none.
	CamTarget int
	// InputTarget is the entity the movement keys drive, or -1 for none.
	InputTarget int

	// CamX is the world x of the view's left edge, before the shake. Read it
	// for parallax; writing it lasts until the next frame.
	CamX float64
	// CamY is the world y of the view's top edge, before the shake.
	CamY float64
	// CamShakeX is the shake offset used when drawing, in pixels. It does not
	// move the world, so a hit box never moves with a shake.
	CamShakeX float64
	// CamShakeY is the vertical shake offset.
	CamShakeY float64

	// Height of the drawing surface in pixels. Read it; do not write it.
	Height float64
	// Width of the drawing surface in pixels. Read it; do not write it.
	Width float64

	// Input is the keyboard and the mouse. Ask it Down, JustPressed or
	// JustReleased; nothing here ever needs clearing by hand.
	Input Input

	// Paused holds the world still. The scene still draws and the game still
	// gets its update with a dt of 0, so it can show a menu and read the keys
	// that leave it, but nothing moves and no animation advances.
	Paused bool

	// RenderUI draws screen-space content after the entities: a HUD, a score,
	// a menu. Use [Engine.Rect] and [Engine.Text]. The engine's own tuning
	// menu draws after this, so it stays on top.
	RenderUI func()

	// Simulate moves the game's own world, and runs at the fixed rate
	// [TimeSettings.TickRate] sets rather than once per frame. Put movement,
	// physics and anything a rule depends on here: it is called with the same
	// dt every time, so the same input twice gives the same answer twice,
	// which is what a replay — and one day a rollback — needs.
	//
	// Read held keys here with [Input.Down]. An edge belongs in the update
	// given to [Engine.Run], which runs once per frame: a frame can carry two
	// ticks or none, so a JustPressed read here fires twice or not at all.
	Simulate func(dt float64)
	// contains filtered or unexported fields
}

type FeelSettings struct {
	Heavy  ImpactSettings
	Light  ImpactSettings
	Medium ImpactSettings
	Shake  ShakeSettings
}

type Frame struct {
	// Duration is how long this frame shows, in milliseconds.
	Duration float64
	// H is the frame's height on the image.
	H float64
	// W is the frame's width on the image.
	W float64
	// X is the frame's left edge on the image.
	X float64
	// Y is the frame's top edge on the image.
	Y float64
}

type ID uint64

type ImpactSettings struct {
	// HitStopDuration is how long the world holds still, in milliseconds.
	HitStopDuration float64
	// HitStopScale is how fast time runs while it holds: 0 is a freeze, 0.1 is
	// slow motion, 1 does nothing.
	HitStopScale float64
	// ShakeDuration is how long the shake lasts, in milliseconds.
	ShakeDuration float64
	// ShakeMagnitude is how far the camera may be thrown, in pixels.
	ShakeMagnitude float64
}

type Input struct {
	// Alt, Ctrl, Meta and Shift are the modifier keys, as of the last event.
	Alt   bool
	Ctrl  bool
	Meta  bool
	Shift bool

	// MouseDown is true while a mouse button is held on the canvas.
	MouseDown bool
	// MouseX and MouseY are the pointer in world coordinates.
	MouseX float64
	MouseY float64

	// Started turns true on the first key or click and stays true. Browsers
	// refuse to play sound before it, so a game waits for it.
	Started bool
	// contains filtered or unexported fields
}

type RenderSettings struct {
	// Background is the CSS colour the canvas is cleared to. Empty clears to
	// transparent and lets the page show through.
	Background string
	// Interpolate draws each entity between the tick that has run and the one
	// that has not, so a frame carrying two ticks or none does not show a pop.
	// It costs the draw a little arithmetic and shows the world up to one tick
	// in the past. Off, every sprite sits exactly where the simulation put it,
	// and moves in the steps the simulation moved it in.
	//
	// It smooths what [Engine.Simulate] moves. An entity moved from the update
	// [Engine.Run] was given is already frame-accurate, and blending drags it
	// backwards instead — which is one more reason movement belongs in a tick.
	Interpolate bool
	// PixelSnap rounds sprite positions to whole pixels.
	PixelSnap bool
	// Smoothing turns on the canvas's own interpolation. Pixel art wants it
	// off; leaving it on is what makes a scaled sprite look blurry.
	Smoothing bool
}

type Settings struct {
	Animation AnimationSettings
	Audio     AudioSettings
	Camera    CameraSettings
	Debug     DebugSettings
	Feel      FeelSettings
	Render    RenderSettings
	Time      TimeSettings
	World     WorldSettings
}

type ShakeSettings struct {
	// Decay is the shape of the fade: 1 falls off in a straight line, 2 drops
	// fast then lingers, 0.5 holds then stops.
	Decay float64
	// Frequency is how many times a second the camera is thrown somewhere new.
	// Below the frame rate it reads as a rumble, above it as noise.
	Frequency float64
	// IgnoresHitStop keeps the shake moving while a hit stop holds the world
	// still, so a freeze still feels violent.
	IgnoresHitStop bool
	// Snap rounds the shake to whole pixels, like the camera.
	Snap bool
}

type Sheet struct {
	// Frames is every frame on the image, in the order the export lists them.
	Frames []Frame
	// H is the image's height, as the export measured it. The parser checks
	// every frame against it, so a rectangle can never point off the image.
	H float64
	// Tags is the named animations. [Engine.ImageRow] indexes it.
	Tags []Tag
	// W is the image's width, as the export measured it.
	W float64
}

type Sprite struct {
	// Alpha is the opacity, 0 to 1. Because an entity added invisible is
	// almost always a mistake, 0 here means 1; set e.Alpha[i] afterwards for
	// an entity that really should start transparent.
	Alpha float64
	// Column is the sheet column the sprite starts at. The animation frame is
	// added to it, so one sheet holds every animation of every sprite.
	Column int
	// Height of the sprite in pixels. It is also the sheet's cell height.
	Height float64
	// Image is which loaded image, in [Engine.LoadImages] order.
	Image int
	// Row is the sheet row, which is one animation.
	Row int
	// ScreenSpace draws the sprite in canvas pixels, past the camera. Use it
	// for a HUD.
	ScreenSpace bool
	// SpeedFactor multiplies [WorldSettings.Speed] for this entity. 0 means 1.
	SpeedFactor float64
	// State is the entity's state bits.
	State uint64
	// Width of the sprite in pixels. It is also the sheet's cell width.
	Width float64
	// X is the world x of the sprite's centre.
	X float64
	// Y is the world y of the sprite's centre.
	Y float64
	// Z is the draw layer. Lower draws first.
	Z int
}

type Stats struct {
	// Budget is one frame's worth of milliseconds, measured from the display
	// rather than assumed: 16.7 at 60 Hz, 8.3 at 120.
	Budget float64
	// DrawMs is how long the last frame spent drawing.
	DrawMs float64
	// Drawn is how many sprites the last frame actually painted, after the
	// camera threw the off-screen ones away.
	Drawn int
	// Dropped counts frames that took more than one and a half budgets.
	Dropped int
	// Entities is how many entities exist, drawn or not.
	Entities int
	// FPS is the frame rate over the window.
	FPS float64
	// FrameMs is the last frame, wall to wall.
	FrameMs float64
	// GoHeapBytes is what the Go heap holds. Under TinyGo this is a subset of
	// what ordinary Go reports; the overlay says so rather than guessing.
	GoHeapBytes uint64
	// GPU names the graphics card, or says why it cannot.
	GPU string
	// JSHeapBytes is the JavaScript heap. Chromium only; 0 elsewhere.
	JSHeapBytes uint64
	// Load is the share of the frame budget the main thread spent working,
	// 0 to 1 and beyond. It is the closest honest thing to processor load.
	Load float64
	// Late is the frame time, in milliseconds, at which a frame counts as
	// missed: [Stats.Budget] times a tolerance. Compare a percentile against
	// this rather than against Budget, which half of a healthy window exceeds
	// by construction. 0 when the budget is not known yet.
	Late float64
	// LongFrames counts frames the browser itself reported as too long.
	// Chromium only; -1 where the browser does not offer it.
	LongFrames int
	// P50Ms and P99Ms are the middle and the near-worst frame in the window.
	// P99 is the number that decides whether a game feels smooth; an average
	// hides exactly the frames a player notices.
	P50Ms float64
	P99Ms float64
	// SortMs is how long the last frame spent putting the entities in draw
	// order. It is separate from [Stats.DrawMs] because the two answer
	// different questions: the sort is a function of how many entities exist
	// and a different renderer would not change it, while the draw is what a
	// different renderer would replace.
	SortMs float64
	// UpdateMs is how long the last frame spent on the world.
	UpdateMs float64
	// WasmBytes is the module's own size, which is the number this engine
	// exists to keep small.
	WasmBytes int
	// WasmMemoryBytes is the WebAssembly linear memory the module holds. It
	// only ever grows, and it grows in 64 KiB pages.
	WasmMemoryBytes uint64
}

type Tag struct {
	// Direction is the play order.
	Direction Direction
	// From is the first frame of the animation.
	From int
	// Name is what the animation is called in Aseprite. [Engine.Play] takes
	// this. A grid sheet has no names, so its tags carry an empty one.
	Name string
	// To is the last frame of the animation, and it is included.
	To int
}

type Tilemap struct {
	// Height of one tile in pixels.
	Height float64
	// Image is which loaded image the tileset comes from.
	Image int
	// Rows and Cols are the shape of the map.
	Cols int
	Rows int
	// TilesetCols and TilesetRows are the shape of the tileset image, in
	// tiles. A tile index outside them leaves the cell empty.
	TilesetCols int
	TilesetRows int
	// Tiles is one tile index per cell, row by row. A negative index leaves
	// the cell empty, and a short slice fills what it can.
	Tiles []int
	// Width of one tile in pixels.
	Width float64
	// Z is the draw layer every tile lands on. A floor belongs below the
	// entities that stand on it: inside one layer the draw order is by
	// baseline, so a tile sharing a layer with an actor draws over it
	// whenever the tile sits lower down the screen.
	Z int
}

type TimeSettings struct {
	// FullscreenDebounce is the shortest gap, in milliseconds, between two
	// fullscreen toggles. Browsers refuse a burst of requests.
	FullscreenDebounce float64
	// MaxStep caps one frame's elapsed time, in milliseconds. Without it a tab
	// left in the background teleports everything when it comes back.
	MaxStep float64
	// Scale multiplies every frame's elapsed time. Below 1 is slow motion.
	Scale float64
	// TickRate is how many times a second the simulation runs, apart from the
	// frame rate. A higher rate costs more and reacts sooner; a lower one is
	// cheaper and coarser.
	//
	// Two machines simulating one world have to agree on it, so a networked
	// game sets it from the server rather than from a saved menu.
	TickRate float64
}

type WorldSettings struct {
	// HitBoxMargin shrinks every hit box by this many pixels on all four
	// sides, so sprites have to visibly overlap before they collide.
	HitBoxMargin float64
	// Speed is the base movement speed, in pixels per millisecond.
	Speed float64
}