canvas

Documentation

Overview

Package canvas owns the fixed 80x24 cell grid that the lobby and every game render into. The Cell type and the Grid type are defined here and aliased by the game SDK; a single shared definition governs every composed frame.

Index

• Constants
• Variables
• func GridToASCII(g Grid) string
• type Attr
• type Cell
• type Color
  • func Default() Color
  • func Gray(v uint8) Color
  • func RGB(r, g, b uint8) Color
  • func (c Color) Equal(o Color) bool
  • func (c Color) IsSet() bool
  • func (c Color) RGB() (uint8, uint8, uint8)
• type Grid
  • func New() Grid
  • func (g *Grid) ClearRow(row int)
  • func (g *Grid) Fill(r0, c0, r1, c1 int, cell Cell)
  • func (g *Grid) Set(row, col int, cell Cell)
  • func (g *Grid) SetRune(row, col int, r rune, st Style)
  • func (g *Grid) Text(row, col int, s string, st Style) int
  • func (g *Grid) TextRight(row, end int, s string, st Style)
• type Style

Constants

const (
	Cols = 80
	Rows = 24
)

The fixed drawable canvas. This is a system-wide invariant in v1.

Variables

var (
	White   = RGB(0xff, 0xff, 0xff)
	Black   = RGB(0x00, 0x00, 0x00)
	Red     = RGB(0xff, 0x55, 0x55)
	Green   = RGB(0x55, 0xff, 0x55)
	Yellow  = RGB(0xff, 0xff, 0x55)
	Blue    = RGB(0x55, 0x99, 0xff)
	Cyan    = RGB(0x55, 0xff, 0xff)
	Magenta = RGB(0xff, 0x77, 0xff)
	DimGray = Gray(0x6c)
)

Some shared palette entries used by the lobby and games.

Functions

func GridToASCII

func GridToASCII(g Grid) string

GridToASCII renders g as a deterministic, color-independent text block: every cell's rune (rune 0 → space), trailing spaces trimmed per row, and the 24 rows joined with "\n" (no trailing newline). It is stable across runs for identical grid content — color and attribute differences do not affect the output — so it is suitable for before/after snapshot artifacts and golden tests.

Types

type Attr

type Attr uint8

Attr is a bitset of text attributes applied to a cell.

const (
	AttrBold Attr = 1 << iota
	AttrDim
	AttrUnderline
	AttrReverse
)

type Cell

type Cell struct {
	Rune rune
	Cp2  rune // second grapheme code point (0 = unused)
	Cp3  rune // third grapheme code point (0 = unused)
	FG   Color
	BG   Color
	Attr Attr
	Cont bool // continuation column of a wide rune to the left
}

Cell is a single drawable position: a rune plus foreground/background color and attributes. A double-width rune occupies two columns; the trailing column is a continuation cell (Cont == true, Rune == 0).

In ABI v2 a cell may carry up to three code points of a grapheme cluster: Rune is the base, Cp2/Cp3 the extra code points (0 = unused; e.g. a VS16 selector, a skin-tone modifier, a ZWJ piece, or a keycap U+20E3). Renderers emit base+Cp2+Cp3 as one contiguous UTF-8 burst. Single-code-point cells leave Cp2/Cp3 zero by zero-value, so existing content is unchanged.

type Color

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

Color is a truecolor source value. The renderer downgrades it per the session's color depth at encode time; the canvas itself only stores the authoritative RGB (or "default / unset").

func Default

func Default() Color

Default is the unset color (terminal default fg/bg).

func Gray

func Gray(v uint8) Color

Gray is a convenience for an equal-channel gray.

func RGB

func RGB(r, g, b uint8) Color

RGB constructs a truecolor value.

func (Color) Equal

func (c Color) Equal(o Color) bool

Equal reports color equality (used by the cell diff).

func (Color) IsSet

func (c Color) IsSet() bool

IsSet reports whether the color is set (vs. terminal default).

func (Color) RGB

func (c Color) RGB() (uint8, uint8, uint8)

RGB returns the color's red/green/blue channels (the renderer downgrades these per session color depth).

type Grid

type Grid struct {
	Cells [Rows][Cols]Cell
}

Grid is the fixed Rows x Cols cell grid. It is intrinsically 80x24, so a game can never accidentally exceed the canvas. It is passed by value as a Frame.

func New

func New() Grid

New returns a grid filled with blank cells.

func (*Grid) ClearRow

func (g *Grid) ClearRow(row int)

ClearRow blanks an entire row.

func (*Grid) Fill

func (g *Grid) Fill(r0, c0, r1, c1 int, cell Cell)

Fill sets every cell in the inclusive rectangle to cell (clamped).

func (*Grid) Set

func (g *Grid) Set(row, col int, cell Cell)

Set writes a single cell, clamping (silently dropping) out-of-bounds writes.

func (*Grid) SetRune

func (g *Grid) SetRune(row, col int, r rune, st Style)

SetRune writes one rune with a style. Out-of-bounds is dropped. Width is treated as 1 (v1 corpus is ASCII); callers wanting wide-rune handling should pre-account for the continuation column.

func (*Grid) Text

func (g *Grid) Text(row, col int, s string, st Style) int

Text blits a string starting at (row, col), left to right, clamping any portion that would exceed the grid. Returns the column just past the written text (may be off-canvas). Tabs/newlines are not interpreted.

func (*Grid) TextRight

func (g *Grid) TextRight(row, end int, s string, st Style)

TextRight blits a string so that it ends at column end-1 (right-aligned), clamping on the left if needed.

type Style

type Style struct {
	FG   Color
	BG   Color
	Attr Attr
}

Style bundles the styling applied when writing text into the grid.