api.tileset

TilesetApi

The loaded tileset graphics: whether they are there, and the decoded files behind them.

id
name
isLoaded
load
raw

Members

id

id(): TilesetId | null;

name

name(): string;

isLoaded

isLoaded(): boolean;

load

load(tileset?: TilesetId): Promise<boolean>;

Fetch and decode the graphics — the open map's tileset's, or tileset's — and keep them in memory; resolves false when they were never extracted. Loading another tileset changes nothing about the map: it is for graphics.renderClip drawing a clip that came from a map on that tileset (a stamp, a recording), which answers null until its tileset's graphics are loaded.

if (!(await api.tileset.load())) {
  api.ui.toast({ kind: "warn", title: "No tileset graphics", detail: "Install them from Help ▸ Game Data…" });
}

Try it

raw

raw(): LoadedTileset | null;

Types

Declarations only this group names.

Cv5Groupinterface

interface Cv5Group

`index: number`	Doodad groups store 1 here; terrain groups store a group type.
`flags: number`	The full u16 flag word; see GroupFlag.
`buildability: number`	Low byte of `flags`: walkability, creep and the unbuildable bit.
`groundHeight: number`	High byte of `flags`: view-blocking and the ground-height bits.
`edges: { left: number; top: number; right: number; bottom: number; }`	ISOM link on each side: values up to 48 are "soft" links shared with whatever terrain borders this piece, higher ones are "hard" links that pair pieces of the same edge set. Flat ground has the same soft link on all four sides.
`stack: { left: number; top: number; right: number; bottom: number; }`	How cliff pieces stack vertically: a group whose `top` equals the `bottom` of the group above it continues that cliff face. Zero means nothing stacks that way.
`megatiles: Uint16Array`	VX4 megatile index for each of the 16 slots in the group.
`doodad?: Cv5Doodad`	Set on doodad groups (`index` 1), which store a different record in the edge/stack bytes.

Cv5Doodadinterface

interface Cv5Doodad

What a doodad group stores where terrain groups keep their ISOM links. A doodad spans one group per row: row r of the doodad whose first group is g is group g + r, with column c in megatile slot c (so its MTXM id is ((g + r) << 4) | c). Every group of the doodad repeats the same ddData, width and height.

`overlay: number`	sprites.dat id (DoodadFlag.SpriteOverlay) or units.dat id (DoodadFlag.UnitOverlay) drawn over the tiles.
`nameIndex: number`	1-based `rez\stat_txt.tbl` index of the palette category ("Trees", "Cliff", …); 0 for the unlisted ones.
`ddData: number`	Index into `tileset\<name>\dddata.bin`, and what DD2 records store.
`width: number`
`height: number`

Tilesetinterface

interface Tileset

`palette: Uint8Array`	256 RGBA entries, 4 bytes each.
`minitiles: Uint8Array`	VR4: `minitiles[i * 64 + n]` is a palette index.
`megatileRefs: Uint32Array`	VX4 refs, 16 per megatile: bit 0 is horizontal flip, the rest is the minitile index.
`megatileCount: number`
`extended: boolean`	True when the source was .vx4ex (Remastered, 32-bit refs).
`megatileFlags: Uint16Array`	VF4 flags, 16 per megatile.
`groups: Cv5Group[]`

PaletteBandinterface

interface PaletteBand

One rotating run of palette entries, min..max inclusive.

`min: number`
`max: number`

HdTileFileinterface

interface HdTileFile

A parsed .dds.vr4: where each megatile's compressed pixels start in bytes.

`bytes: Uint8Array`
`count: number`
`offsets: Uint32Array`	Offset of megatile N's DXT1 data (past its DDS header).

HdTilesinterface

interface HdTiles

The 2x pictures of one tileset, decoded as they are asked for.

`file: HdTileFile`
`tileSize: number`	Source pixels per megatile.
`pages: HTMLCanvasElement[]`
`slot: Int32Array`	Megatile → slot across the pages, or -1 while it has not been drawn.
`used: number`
`scratch: ImageData \| null`	One cell's pixels, reused for every decode.
`effects?: HdEffects \| null`	The tileset's moving water or lava, where the data set has the files for it.

GrpPictureinterface

interface GrpPicture

One picture of a .dds.grp: its size, and where its DXT1 blocks start.

`width: number`
`height: number`
`data: number`
`size: number`	The blocks' length in bytes — what a compressed upload to the graphics card takes whole.

HdEffectKindtype

type HdEffectKind = "water" | "heat";

How a tileset's masked ground moves: ripples over water, or shimmer over lava.

PictureSequenceinterface

interface PictureSequence

A sequence of pictures in one file, for the graphics card: the bytes and where each picture's blocks are.

`bytes: Uint8Array`
`pictures: GrpPicture[]`

HdEffectTexturesinterface

interface HdEffectTextures

The textures an effect is read from, shared by every tileset that has it.

`large?: PictureSequence`	Water: the slow, large ripples and the fine ones over them.
`fine?: PictureSequence`
`noise?: { width: number; height: number; rgba: Uint8Array; }`	Heat: the noise the shimmer follows.

HdEffectsinterface

interface HdEffects

Everything the viewport needs to animate a tileset's water or lava.

`kind: HdEffectKind`
`maskOf: Int32Array`	Megatile → picture number in `masks`, or -1 for ground that stands still.
`masks: HdTiles`	The mask pictures, decoded on first use like the tiles: white where the effect is.
`textures: HdEffectTextures`

TilesetAtlasinterface

interface TilesetAtlas

All of a tileset's megatiles rendered once into a single image, so the viewport can draw terrain with one drawImage per visible tile instead of decoding minitiles on every frame.

`image: CanvasImageSource`
`columns: number`	Megatiles per atlas row.
`tileSize: number`
`count: number`
`averages: Uint32Array`	Packed 0xRRGGBB average of each megatile, for minimap and far-zoom drawing.
`animation: AtlasAnimation \| null`	The cycling (water/lava) megatiles, or null when the tileset has none.
`hd?: HdTiles \| null`	StarCraft: Remastered's 2x pictures (`hd.ts`), when View ▸ Remastered Terrain is on and the data set has them. `atlasSource` then answers from these, at twice the source size, and nothing cycles: Remastered moves water and lava by bending the finished picture (`hd.effects`, `viewport/effectPass.ts`), so a megatile here is always the still one. `image`, `averages` and `animation` stay the classic ones — the minimap and the far zooms use the averages either way.

AtlasAnimationinterface

interface AtlasAnimation

A second, small atlas holding only the megatiles that reference cycling palette entries. It is re-rasterised with the rotated palette on every step, while the main atlas stays at step 0; atlasSource picks the right one per megatile.

`image: HTMLCanvasElement`
`columns: number`
`slot: Int32Array`	Megatile → slot in this atlas, or -1 for megatiles that do not cycle.
`megatiles: Uint32Array`
`bands: readonly PaletteBand[]`
`length: number`	Steps until the cycle repeats.
`step: number`	The step the image currently shows.
`pixels: ImageData`
`palette: Uint8Array`	Scratch palette, rotated in place each step.

DoodadDefinterface

interface DoodadDef

`id: number`	The `dddata.bin` index, which DD2 records store.
`group: number`	First CV5 group; row `r` is group `group + r`, column `c` is slot `c`.
`width: number`
`height: number`
`category: string`	Palette category, from stat_txt.tbl; "Unlisted" for groups without a name.
`flags: number`	The first group's CV5 flag word — copied onto the overlay's THG2 record, as StarEdit does.
`overlay: DoodadOverlay \| null`	The sprite (or unit) drawn over the tiles, or null.
`tiles: Uint16Array`	MTXM id per cell, row-major; 0 where the doodad leaves the ground alone.
`required: Uint16Array`	CV5 group required under each cell, row-major; 0 = no requirement.
`ramp: boolean`	Whether any of its minitiles carries the VF4 ramp bit. StarEdit files ramps under the cliff categories with no name of their own; this is the only way to tell them apart.

DoodadOverlayinterface

interface DoodadOverlay

`kind: "sprite" \| "unit"`
`id: number`	sprites.dat or units.dat id.
`flipped: boolean`

DoodadCategoryinterface

interface DoodadCategory

`name: string`
`doodads: DoodadDef[]`

DoodadCatalogueinterface

interface DoodadCatalogue

`doodads: DoodadDef[]`
`byId: Map<number, DoodadDef>`
`categories: DoodadCategory[]`	In first-appearance order, the way StarEdit's category drop-down lists them; "Unlisted" last.
`hasPlacementData: boolean`	Whether dddata.bin was available; without it nothing is ever refused for its ground.

TILESET_FILENAMESconst

const TILESET_FILENAMES: readonly [
	"badlands",
	"platform",
	"install",
	"ashworld",
	"jungle",
	"desert",
	"ice",
	"twilight"
]

TilesetFileNametype

type TilesetFileName = (typeof TILESET_FILENAMES)[number];

LoadedTilesetinterface

interface LoadedTileset

`name: TilesetFileName`
`tileset: Tileset`
`atlas: TilesetAtlas`
`doodads: DoodadCatalogue`	The doodads the CV5 holds, with their placement rules when `<name>.dddata.bin` was extracted.