api.graphics

ready

ready(): { tileset: boolean; units: boolean; };

Whether the tileset graphics and the unit tables are in memory.

load

load(): Promise<{ tileset: boolean; units: boolean; }>;

Fetch both; resolves with what is available afterwards.

unitImage

unitImage(unitId: number, options?: { owner?: number; }): PluginImage | null;

A unit type in its editor pose, in a player's colours (owner 0 by default).

spriteImage

spriteImage(kind: SpriteKind, id: number, options?: { owner?: number; flipped?: boolean; }): PluginImage | null;

A THG2 sprite: a sprites.dat image for "pure", a unit for "unit".

tileImage

tileImage(tileId: number): PluginImage | null;

One 32 × 32 megatile of the open map's tileset.

doodadImage

doodadImage(doodadId: number): PluginImage | null;

A doodad drawn from its own tiles.

renderRect

renderRect(rect: Rect, options?: Partial<MapImageOptions>): Promise<Blob | null>;

Part of the map as File ▸ Export ▸ Image draws it — the same render, cropped to a tile rect. Everything it needs is loaded first; null without a map or a canvas.

renderClip

renderClip(clip: Clip, options?: RenderClipOptions): PluginImage | null;

A Clip drawn as the clipboard layer's paste ghost draws it: the picture (its own tiles, or the catalogue's for a doodad-only clip), then units, sprites and doodad overlays with the viewport's own graphics, then location boxes — a thumbnail for a list of clips, or the ghost under the pointer while a plugin stamps one. It is drawn with the graphics of the clip's own tileset (clip.era), which are in memory for the open map once loaded; a clip from another tileset answers null until tileset.load(id) has fetched that one. So does a missing tileset or a page with no canvas. Synchronous and uncached: keep the result while the clip and the tileset stay the same.

playerColor

playerColor(owner: number): string;

The colour a player's units are drawn in, #rrggbb.

requestUnit

requestUnit(unitId: number): boolean;

Start fetching the GRPs a unit type needs, and say whether they are already in memory. Graphics load lazily, so the first unitImage for a type is often null — ask for it here, redraw on onImageLoaded, and the list fills in.

requestSprite

requestSprite(kind: SpriteKind, id: number): boolean;

icon

icon(kind: IconKind, id: number, options?: { look?: IconLook; }): PluginImage | null;

The game's own button picture for a unit type, an upgrade or a technology — the icon its command card shows — 36 × 34 at most and transparent round the edges. look colours it as the game does: "normal" yellow (the default), "disabled" grey, "selected" white. It does not depend on the map or its tileset. Null for an id with no picture (a unit type past 227, a turret) and until requestIcons has the pictures; null for good from a game data copy made before the editor kept them (installing the game data again brings them). The canvas is the editor's own cached one: draw from it.

// A row of what a player researched, as the game's icons, with the names where there are no pictures.
const show = () => list.replaceChildren(...done.map((r) => {
  const icon = api.graphics.icon(r.kind, r.id);
  if (!icon) return api.ui.el("span", {}, r.kind === "tech" ? api.names.tech(r.id) : api.names.upgrade(r.id));
  const canvas = api.ui.el("canvas", { width: icon.width, height: icon.height });
  canvas.getContext("2d")?.drawImage(icon.image, 0, 0);
  return canvas;
}));
api.graphics.requestIcons();
api.graphics.onImageLoaded(show);
show();

requestIcons

requestIcons(): boolean;

Start fetching the icon pictures (one sheet holds them all), and say whether they are in memory. onImageLoaded fires when they arrive.

onImageLoaded

onImageLoaded(listener: () => void): Disposable;

A GRP finished loading: anything drawn from one may look different now.

type IconKind = "unit" | "upgrade" | "tech";

type IconLook = "normal" | "disabled" | "selected";

interface PluginImage

interface RenderClipOptions