@rpgm-tools/neo-angband-core 0.10.0

package/src/visuals/glyph-table.ts

@@ -0,0 +1,191 @@
+/**
+ * The runtime attr/char override tables, ported from reference/src/ui-prefs.c
+ * (Angband 4.2.6): the `monster_x_attr` / `monster_x_char` /
+ * `kind_x_attr` / `kind_x_char` / `feat_x_attr[LIGHTING_MAX]` /
+ * `feat_x_char[LIGHTING_MAX]` / `trap_x_attr[LIGHTING_MAX]` /
+ * `trap_x_char[LIGHTING_MAX]` / `flavor_x_attr` / `flavor_x_char` globals
+ * (ui-prefs.c L46-56), their allocation (textui_prefs_init, L1427-1452) and
+ * their (re)initialisation from gamedata (reset_visuals, L1352-1421).
+ *
+ * WHY THIS IS A SEPARATE LAYER FROM THE GAMEDATA. Upstream never draws a
+ * monster with `race->d_attr`: every draw goes through the x_attr/x_char
+ * table, which merely STARTS at the gamedata default. Three things write to it
+ * after that - a pref file (`process_pref_file`'s parse_prefs_monster and
+ * friends, L602-928), the knowledge browser's glyph picker (`glyph_command`,
+ * ui-knowledge.c L597-752), and the graphics pref of the active tile mode -
+ * and four things read it back out (the map, the knowledge screens, the
+ * monster-list sidebar, and the `dump_*` pref writers). A port that reads
+ * `race.dAttr` at the draw site cannot express any of that, which is why the
+ * glyph picker and the four "Save ... attr/chars" rows were both absent.
+ *
+ * RELATIONSHIP TO TileMap (tile-prefs.ts). Upstream keeps ONE set of arrays
+ * and lets a graf-*.prf write high-bit values into them, so in graphics mode
+ * the very same slot holds an atlas (row, col) instead of an (attr, glyph).
+ * This port splits the two: TileMap holds the graphics mapping, this table
+ * holds the ASCII one. That is behaviourally equivalent because upstream only
+ * ever has one of the two interpretations live at a time (`use_graphics`
+ * gates it, and display_knowledge picks the tile picker or the glyph picker on
+ * the same flag, ui-knowledge.c L1052-1070) - but it means the glyph picker
+ * edits this table and the tile picker edits the TileMap, rather than both
+ * editing one array.
+ *
+ * ATTR NORMALISATION. Upstream's `d_attr` is already a uint8_t COLOUR_* code
+ * for every entity type. The port's compiled gamedata keeps the source text's
+ * spelling instead: a colour CHAR for features / kinds / traps (`"w"`), a
+ * colour NAME for flavours (`"Light Green"`), and an already-numeric attr for
+ * monster races. resetVisuals normalises all four to the numeric attr, so from
+ * here on the table is uniform exactly as the C's arrays are.
+ *
+ * Determinism: no RNG anywhere in this module.
+ */
+
+import { colorCharToAttr, colorTextToAttr } from "../color.js";
+import type { Flavor, ObjectKind } from "../obj/types.js";
+import type { MonsterRace } from "../mon/types.js";
+import type { Feature } from "../world/feature.js";
+import type { TrapKind } from "../world/trap.js";
+import { LIGHTING } from "./tile-prefs.js";
+
+/** One (attr, char) pair - upstream's parallel uint8_t/wchar_t slot pair. */
+export interface GlyphPair {
+  attr: number;
+  char: string;
+}
+
+/** The gamedata reset_visuals reads its defaults out of. */
+export interface GlyphTableDeps {
+  /** f_info, indexed by fidx (FEAT_MAX slots upstream). */
+  features: readonly Feature[];
+  /** k_info in kidx order. */
+  kinds: readonly ObjectKind[];
+  /** r_info in ridx order. */
+  races: readonly MonsterRace[];
+  /** trap_info in tidx order; null when the pack binds no traps. */
+  traps: readonly TrapKind[] | null;
+  /** The flavor list (upstream walks the `flavors` linked list by fidx). */
+  flavors: readonly Flavor[];
+}
+
+/**
+ * The x_attr/x_char arrays as one object. Sparse-safe: a read for an index the
+ * gamedata never bound falls back to the caller's default rather than
+ * throwing, because upstream's arrays are FEAT_MAX / r_max / k_max long and
+ * simply hold the zeroed slot for an unbound entry.
+ */
+export class GlyphTable {
+  /** monster_x_attr / monster_x_char[ridx]. */
+  private readonly monster: GlyphPair[] = [];
+  /** kind_x_attr / kind_x_char[kidx]. */
+  private readonly kind: GlyphPair[] = [];
+  /** feat_x_attr / feat_x_char[lighting][fidx]. */
+  private readonly feat: GlyphPair[][] = [[], [], [], []];
+  /** trap_x_attr / trap_x_char[lighting][tidx]. */
+  private readonly trap: GlyphPair[][] = [[], [], [], []];
+  /** flavor_x_attr / flavor_x_char[fidx]. */
+  private readonly flavor: GlyphPair[] = [];
+
+  constructor(private readonly deps: GlyphTableDeps) {
+    this.reset();
+  }
+
+  /**
+   * reset_visuals(false) (ui-prefs.c L1352): re-extract every default
+   * attr/char from the gamedata, discarding any pref-file or picker override.
+   * The `load_prefs` half of the C's signature is the caller's job here (the
+   * front end re-runs its own pref load, exactly as reset_visuals(true) then
+   * calls process_pref_file("font.prf") or the tile mode's graphics pref).
+   *
+   * WART KEPT: upstream resets flavours from the CURRENT flavor list, which is
+   * the shuffled per-game one, not a canonical order - so a reset restores the
+   * glyphs this savefile was born with, not the file order.
+   */
+  reset(): void {
+    for (const f of this.deps.features) {
+      const pair = { attr: colorCharToAttr(f.dAttr), char: f.dChar };
+      for (let j = 0; j < LIGHTING.MAX; j++) {
+        this.feat[j]![f.fidx] = { ...pair };
+      }
+    }
+    for (const k of this.deps.kinds) {
+      this.kind[k.kidx] = { attr: colorCharToAttr(k.dAttr), char: k.dChar };
+    }
+    for (const r of this.deps.races) {
+      this.monster[r.ridx] = { attr: r.dAttr, char: r.dChar };
+    }
+    for (const t of this.deps.traps ?? []) {
+      const pair = { attr: colorCharToAttr(t.color), char: t.glyph };
+      for (let j = 0; j < LIGHTING.MAX; j++) {
+        this.trap[j]![t.tidx] = { ...pair };
+      }
+    }
+    for (const f of this.deps.flavors) {
+      this.flavor[f.fidx] = { attr: colorTextToAttr(f.dAttr), char: f.dChar };
+    }
+  }
+
+  /* ----- reads (the draw sites and the dump writers) ----- */
+
+  monsterGlyph(ridx: number): GlyphPair | undefined {
+    return this.monster[ridx];
+  }
+
+  kindGlyph(kidx: number): GlyphPair | undefined {
+    return this.kind[kidx];
+  }
+
+  featGlyph(lighting: number, fidx: number): GlyphPair | undefined {
+    return this.feat[lighting]?.[fidx];
+  }
+
+  trapGlyph(lighting: number, tidx: number): GlyphPair | undefined {
+    return this.trap[lighting]?.[tidx];
+  }
+
+  flavorGlyph(fidx: number): GlyphPair | undefined {
+    return this.flavor[fidx];
+  }
+
+  /* ----- writes (the pref parser and the glyph picker) ----- */
+
+  setMonsterGlyph(ridx: number, pair: GlyphPair): void {
+    this.monster[ridx] = { ...pair };
+  }
+
+  setKindGlyph(kidx: number, pair: GlyphPair): void {
+    this.kind[kidx] = { ...pair };
+  }
+
+  /**
+   * parse_prefs_feat (ui-prefs.c L798-849): a `*` lighting field writes every
+   * variant, which is why this takes LIGHTING.MAX as "all".
+   */
+  setFeatGlyph(lighting: number, fidx: number, pair: GlyphPair): void {
+    if (lighting === LIGHTING.MAX) {
+      for (let j = 0; j < LIGHTING.MAX; j++) this.feat[j]![fidx] = { ...pair };
+      return;
+    }
+    const row = this.feat[lighting];
+    if (row) row[fidx] = { ...pair };
+  }
+
+  /** set_trap_graphic (ui-prefs.c L733-743), with the same `*` convention. */
+  setTrapGlyph(lighting: number, tidx: number, pair: GlyphPair): void {
+    if (lighting === LIGHTING.MAX) {
+      for (let j = 0; j < LIGHTING.MAX; j++) this.trap[j]![tidx] = { ...pair };
+      return;
+    }
+    const row = this.trap[lighting];
+    if (row) row[tidx] = { ...pair };
+  }
+
+  setFlavorGlyph(fidx: number, pair: GlyphPair): void {
+    this.flavor[fidx] = { ...pair };
+  }
+
+  /* ----- enumeration (the dump_* writers walk the whole table) ----- */
+
+  /** The gamedata this table was built from, for the dump writers' names. */
+  get gamedata(): GlyphTableDeps {
+    return this.deps;
+  }
+}

package/src/visuals/grafmode-data.ts

@@ -0,0 +1,90 @@
+// Generated from reference/lib/tiles/list.txt by
+// scripts/gen-grafmode.mjs. Do not edit.
+//
+// The graphics-mode catalog METADATA (functional data) from Angband's tile
+// list. Faithful to grafmode.c's parse of name/directory/size/pref/extra.
+//
+// This file is METADATA ONLY - no tile images. The art for all five packs ships
+// with the web build at packages/web/public/tiles/, and each pack's terms differ
+// (see that directory's CREDITS.md). A front end builds file paths from
+// `directory`/`file`, and can be pointed at a pack of the player's own with
+// `?tiles=<base-url>`. ASCII is the default and the game runs fully with no tile
+// pack present.
+
+import type { GraphicsMode } from "./grafmode.js";
+
+/** Every parsed graphics mode from list.txt, in file order (grafID 1..N). */
+export const GRAPHICS_MODE_CATALOG: readonly GraphicsMode[] = [
+  {
+    grafID: 1,
+    menuname: "Original Tiles",
+    directory: "old",
+    cellWidth: 8,
+    cellHeight: 8,
+    file: "8x8.png",
+    pref: "graf-xxx.prf",
+    alphablend: 0,
+    overdrawRow: 0,
+    overdrawMax: 0,
+  },
+  {
+    grafID: 2,
+    menuname: "Adam Bolt's tiles",
+    directory: "adam-bolt",
+    cellWidth: 16,
+    cellHeight: 16,
+    file: "16x16.png",
+    pref: "graf-new.prf",
+    alphablend: 0,
+    overdrawRow: 0,
+    overdrawMax: 0,
+  },
+  {
+    grafID: 3,
+    menuname: "David Gervais' tiles",
+    directory: "gervais",
+    cellWidth: 32,
+    cellHeight: 32,
+    file: "32x32.png",
+    pref: "graf-dvg.prf",
+    alphablend: 0,
+    overdrawRow: 0,
+    overdrawMax: 0,
+  },
+  {
+    grafID: 4,
+    menuname: "Nomad's tiles",
+    directory: "nomad",
+    cellWidth: 16,
+    cellHeight: 16,
+    file: "8x16.png",
+    pref: "graf-nmd.prf",
+    alphablend: 0,
+    overdrawRow: 0,
+    overdrawMax: 0,
+  },
+  {
+    grafID: 5,
+    menuname: "Shockbolt Dark",
+    directory: "shockbolt",
+    cellWidth: 64,
+    cellHeight: 64,
+    file: "64x64.png",
+    pref: "graf-shb-dark.prf",
+    alphablend: 1,
+    overdrawRow: 27,
+    overdrawMax: 31,
+  },
+  {
+    grafID: 6,
+    menuname: "Shockbolt Light",
+    directory: "shockbolt",
+    cellWidth: 64,
+    cellHeight: 64,
+    file: "64x64.png",
+    pref: "graf-shb-light.prf",
+    alphablend: 1,
+    overdrawRow: 27,
+    overdrawMax: 31,
+  },
+];

package/src/visuals/grafmode.ts

@@ -0,0 +1,123 @@
+/**
+ * Graphics-mode catalog + lookup, ported from reference/src/grafmode.c
+ * (Angband 4.2.6).
+ *
+ * The catalog is metadata only (mode id, menu name, tile dimensions,
+ * directory + image/pref filenames, double-height rows) parsed from
+ * lib/tiles/list.txt. NO tile IMAGE assets are bundled - the art packs carry
+ * their own (partly non-commercial) licenses, so a user supplies a tile pack
+ * at runtime and the web renderer builds URLs from this metadata. ASCII stays
+ * the default and the game runs fully with no tile pack present.
+ *
+ * Ported here:
+ *  - struct graphics_mode -> GraphicsMode.
+ *  - GRAPHICS_NONE (grafmode.h) + the hardcoded "None" fallback entry the C
+ *    appends in finish_parse_grafmode (L137-146).
+ *  - get_graphics_mode (L223): find a mode by grafID.
+ *  - graphics_mode_high_id (L148): the highest catalog grafID.
+ *  - is_dh_tile (L241): double-height tile test.
+ *
+ * The list.txt parse itself is done ahead of time by
+ * scripts/gen-grafmode.mjs, which emits grafmode-data.ts.
+ */
+
+import { GRAPHICS_MODE_CATALOG } from "./grafmode-data.js";
+
+export { GRAPHICS_MODE_CATALOG } from "./grafmode-data.js";
+
+/** grafmode.h GRAPHICS_NONE: the ASCII (no-tiles) mode id. */
+export const GRAPHICS_NONE = 0;
+
+/**
+ * struct graphics_mode (grafmode.h). The C stores a fully-built absolute
+ * `path` under ANGBAND_DIR_TILES; here we keep the raw `directory` name and
+ * leave path/URL construction to the platform (no bundled assets).
+ */
+export interface GraphicsMode {
+  /** grafID: the serial number / mode id (uint on the `name` line). */
+  grafID: number;
+  /** menuname: the display name (the `name` line's str field). */
+  menuname: string;
+  /** The tile directory name (the `directory` line), e.g. "old". */
+  directory: string;
+  /** cell_width: tile width in pixels (the `size` line). */
+  cellWidth: number;
+  /** cell_height: tile height in pixels (the `size` line). */
+  cellHeight: number;
+  /** file: the tileset image filename (the `size` line's str field). */
+  file: string;
+  /** pref: the pref file name (the `pref` line), or "none". */
+  pref: string;
+  /** alphablend: whether the tileset needs alpha blending (the `extra` line). */
+  alphablend: number;
+  /** overdrawRow: first double-height tile row (the `extra` line). */
+  overdrawRow: number;
+  /** overdrawMax: last double-height tile row (the `extra` line). */
+  overdrawMax: number;
+}
+
+/**
+ * The hardcoded no-graphics fallback (grafmode.c L137-146). Appended after the
+ * parsed catalog and used as the initial current_graphics_mode.
+ */
+export const GRAPHICS_MODE_NONE: GraphicsMode = {
+  grafID: GRAPHICS_NONE,
+  menuname: "None",
+  directory: "",
+  cellWidth: 0,
+  cellHeight: 0,
+  file: "",
+  pref: "none",
+  alphablend: 0,
+  overdrawRow: 0,
+  overdrawMax: 0,
+};
+
+/**
+ * The full graphics-mode list: the parsed catalog plus the "None" entry at the
+ * end, exactly as finish_parse_grafmode builds graphics_modes[] (parsed modes
+ * followed by the hardcoded None fallback).
+ */
+export const GRAPHICS_MODES: readonly GraphicsMode[] = [
+  ...GRAPHICS_MODE_CATALOG,
+  GRAPHICS_MODE_NONE,
+];
+
+/**
+ * graphics_mode_high_id (grafmode.c L148): the highest grafID among the
+ * parsed modes (the None entry is excluded, matching the C's `max` scan which
+ * runs before None is appended).
+ */
+export const GRAPHICS_MODE_HIGH_ID: number = GRAPHICS_MODE_CATALOG.reduce(
+  (max, m) => (m.grafID > max ? m.grafID : max),
+  0,
+);
+
+/**
+ * get_graphics_mode (grafmode.c L223): the mode with the given id, or
+ * undefined (the C returns NULL) if none matches. GRAPHICS_NONE resolves to
+ * the None fallback entry.
+ */
+export function getGraphicsMode(id: number): GraphicsMode | undefined {
+  for (const mode of GRAPHICS_MODES) {
+    if (mode.grafID === id) return mode;
+  }
+  return undefined;
+}
+
+/**
+ * is_dh_tile (grafmode.c L241): whether an attr/char pair is a double-height
+ * tile under the given mode. True only for a tile attr (high bit set) whose
+ * tileset row falls in the mode's double-height band. `current` may be
+ * undefined (no mode selected), matching the C's !current_graphics_mode guard.
+ */
+export function isDoubleHeightTile(
+  current: GraphicsMode | undefined,
+  attr: number,
+): boolean {
+  if ((attr & 0x80) === 0 || !current || !current.overdrawRow) return false;
+  const tilesetRow = attr & 0x7f;
+  return (
+    tilesetRow >= current.overdrawRow && tilesetRow <= current.overdrawMax
+  );
+}

package/src/visuals/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The visuals subsystem: a platform-agnostic color-cycle + legacy flicker
+ * animation engine (engine.ts) and the graphics-mode catalog (grafmode.ts),
+ * ported from reference/src/ui-visuals.c and reference/src/grafmode.c
+ * (Angband 4.2.6).
+ *
+ * A front end owns the frame timer and the glyph/tile draw; the core returns
+ * the COLOUR_* attr to draw for a given animation frame. The tile IMAGE assets
+ * for all six graphics modes ship with the web build (packages/web/public/tiles);
+ * ASCII stays the default.
+ */
+
+export * from "./engine.js";
+export * from "./glyph-table.js";
+export * from "./grafmode.js";
+export * from "./map-text.js";
+export * from "./pref-expr.js";
+export * from "./prefs.js";
+export * from "./tile-prefs.js";

package/src/visuals/map-text.ts

@@ -0,0 +1,152 @@
+/**
+ * The monster and player arms of grid_data_as_text, ported from
+ * reference/src/ui-map.c L232-331 (Angband 4.2.6).
+ *
+ * SCOPE. Upstream resolves a whole map cell in one function: terrain from
+ * feat_x_attr, then trap, then object, then monster-or-player, all layered onto
+ * one (attr, char) pair. The port's web shell layers those four in its own
+ * render loop (main.ts render(), one index map per layer), so what needs to
+ * live in core is the part that is not simple "last writer wins": the monster
+ * branch, whose seven arms READ the glyph already under the monster, and the
+ * player branch, which takes its colour from the x_attr table's race-0 slot.
+ * Everything here is pure, so both are directly testable.
+ *
+ * What upstream does that the port's layered loop still cannot express is
+ * recorded in parity/CENSUS_PUNCHLIST.md (block O: map_info has no port, so
+ * hallucination glyphs, the multi-object pile kind and the unknown-item/gold
+ * kinds are absent) - it is measured there rather than excused here.
+ *
+ * Determinism: no RNG. ATTR_RAND's per-monster colour is rolled once at birth
+ * (mon-make.c place_new_monster_one), and the flicker/multi frame colour is the
+ * caller's animator; this module only selects between values it is handed.
+ */
+
+import { COLOUR_L_RED, COLOUR_ORANGE, COLOUR_RED, COLOUR_VIOLET, COLOUR_WHITE, COLOUR_YELLOW } from "../color.js";
+import type { GlyphPair } from "./glyph-table.js";
+
+/**
+ * The high bit upstream reserves for "this slot holds a graphics tile code,
+ * not a colour attr" (ui-map.c L246 `da & 0x80`, L275 `a & 0x80`). The port
+ * keeps tile codes in a separate TileMap (see glyph-table.ts), so in practice
+ * this is only set when a pref file wrote a high-bit attr into the ASCII
+ * table; the branches are ported anyway so that case behaves as upstream.
+ */
+const ATTR_TILE_BIT = 0x80;
+
+/** The inputs grid_data_as_text's monster branch reads. */
+export interface MonsterGlyphInput {
+  /** The (attr, char) already resolved for this grid: terrain, then trap/object. */
+  under: GlyphPair;
+  /** monster_x_attr[race->ridx] / monster_x_char[race->ridx]. */
+  desired: GlyphPair;
+  /**
+   * mon->attr: the animated colour do_animation last wrote for an
+   * ATTR_MULTI/ATTR_FLICKER monster, or the colour ATTR_RAND rolled at birth.
+   * 0 means "none set", which upstream falls back from to `da` (L259).
+   */
+  monAttr: number;
+  attrMulti: boolean;
+  attrFlicker: boolean;
+  attrRand: boolean;
+  attrClear: boolean;
+  charClear: boolean;
+  /** OPT(player, purple_uniques). */
+  purpleUniques: boolean;
+  /** monster_is_shape_unique(mon) (mon-predicate.c L100). */
+  shapeUnique: boolean;
+}
+
+/**
+ * grid_data_as_text's `g->m_idx > 0` branch (ui-map.c L232-289), in upstream's
+ * exact arm order. The returned attr is also what upstream stores back into
+ * `mon->attr` (L288), which the monster-list sidebar then reads.
+ *
+ * The arms, in order:
+ *  1. `da & 0x80` - a special (tile) code in the slot wins outright.
+ *  2. purple_uniques on a currently-unique monster: violet, monster's char.
+ *  3. ATTR_MULTI / ATTR_FLICKER / ATTR_RAND: `mon->attr` if set, else `da`.
+ *  4. Neither ATTR_CLEAR nor CHAR_CLEAR: an ordinary monster, both overridden.
+ *  5. `a & 0x80` - a bizarre (tile) grid under the monster: both overridden.
+ *  6. not CHAR_CLEAR: keep the grid's attr, take the monster's char.
+ *  7. not ATTR_CLEAR: take the monster's attr, keep the grid's char.
+ *
+ * Arms 6 and 7 are why an ATTR_CLEAR monster shows in the colour of whatever
+ * it is standing on, and a CHAR_CLEAR monster is invisible except for its
+ * colour tinting the terrain glyph.
+ */
+export function monsterGlyph(input: MonsterGlyphInput): GlyphPair {
+  const { under, desired } = input;
+
+  if (desired.attr & ATTR_TILE_BIT) {
+    return { attr: desired.attr, char: desired.char };
+  }
+  if (input.purpleUniques && input.shapeUnique) {
+    return { attr: COLOUR_VIOLET, char: desired.char };
+  }
+  if (input.attrMulti || input.attrFlicker || input.attrRand) {
+    return { attr: input.monAttr ? input.monAttr : desired.attr, char: desired.char };
+  }
+  if (!input.attrClear && !input.charClear) {
+    return { attr: desired.attr, char: desired.char };
+  }
+  if (under.attr & ATTR_TILE_BIT) {
+    return { attr: desired.attr, char: desired.char };
+  }
+  if (!input.charClear) {
+    return { attr: under.attr, char: desired.char };
+  }
+  if (!input.attrClear) {
+    return { attr: desired.attr, char: under.char };
+  }
+  /* Both flags set: upstream falls out of the if-chain leaving the grid's own
+   * attr and char untouched - a monster you cannot see at all. */
+  return { attr: under.attr, char: under.char };
+}
+
+/**
+ * grid_data_as_text's `g->is_player` branch (ui-map.c L289-331). The player's
+ * glyph is r_info[0] ("<player>" in monster.txt) read through the SAME x_attr
+ * table as every monster, so a pref file or the glyph picker can re-map the
+ * '@'. hp_changes_color recolours by HP decile, but only when the slot does
+ * not hold a tile code (L292 `!(a & 0x80)`).
+ */
+export function playerGlyph(
+  /** monster_x_attr[0] / monster_x_char[0]. */
+  desired: GlyphPair,
+  opts: { hpChangesColor: boolean; chp: number; mhp: number },
+): GlyphPair {
+  let attr = desired.attr;
+  if (opts.hpChangesColor && !(attr & ATTR_TILE_BIT)) {
+    /* Upstream's `player->chp * 10 / player->mhp` is integer division on
+     * possibly-negative chp; Math.trunc reproduces C's truncation. mhp is
+     * never 0 in a live game, but a 0 guard keeps this total for tests. */
+    const decile = opts.mhp > 0 ? Math.trunc((opts.chp * 10) / opts.mhp) : 10;
+    switch (decile) {
+      case 10:
+      case 9:
+        attr = COLOUR_WHITE;
+        break;
+      case 8:
+      case 7:
+        attr = COLOUR_YELLOW;
+        break;
+      case 6:
+      case 5:
+        attr = COLOUR_ORANGE;
+        break;
+      case 4:
+      case 3:
+        attr = COLOUR_L_RED;
+        break;
+      case 2:
+      case 1:
+      case 0:
+        attr = COLOUR_RED;
+        break;
+      default:
+        attr = COLOUR_WHITE;
+        break;
+    }
+  }
+  return { attr, char: desired.char };
+}