api.query

QueryApi

Reading the open map: what is under a point, what lies in a rectangle, and the editor's own analyses — Check Map's issues, Tools ▸ Statistics, the Ctrl+F search and the string usage map the String Editor is built on.

Everything here is a read: nothing changes the map, and nothing throws without one (an empty list, or null).

unitAt
unitsIn
unitsOf
spriteAt
spritesIn
doodadAt
locationAt
locationsIn
startLocations
placement
fogAt
strings
validate
statistics
find
stringUsage
unusedStrings

Members

unitAt

unitAt(px: number, py: number): number;

The topmost unit whose sprite box covers a map pixel, or -1.

unitsIn

unitsIn(rect: Rect): number[];

Every unit whose centre lies in a tile rect.

unitsOf

unitsOf(owner: number): number[];

Units owned by a player (0-based).

spriteAt

spriteAt(px: number, py: number): number;

spritesIn

spritesIn(rect: Rect): number[];

doodadAt

doodadAt(tx: number, ty: number): number;

The doodad covering a tile, or -1.

locationAt

locationAt(px: number, py: number): number;

The smallest location covering a map pixel (never Anywhere), or -1.

locationsIn

locationsIn(rect: Rect): number[];

Locations wholly inside a tile rect (never Anywhere).

startLocations

startLocations(): StartLocation[];

The map's start locations, by player.

placement

placement(unitId: number, x: number, y: number): PlacementVerdict | null;

Whether a unit type may be placed centred there, and what stops it; null with no map.

fogAt

fogAt(tx: number, ty: number): number;

The MASK bits at a tile: bit n set = player n + 1 starts fogged there (every bit when the map has no MASK).

strings

strings(): (string | null)[];

The string table as it stands (index 0 is nothing); empty with no map.

validate

validate(): Issue[];

Check Map: every issue the editor knows how to spot, with a target to go to.

statistics

statistics(): MapStatistics | null;

Tools ▸ Statistics: tile, unit, resource and player counts. Null without a map.

find

find(options: FindOptions): FindResult[];

The Ctrl+F search over units, locations, sprites, strings and triggers.

stringUsage

stringUsage(): Map<number, StringUsage[]>;

Every record that refers to each string index.

unusedStrings

unusedStrings(): number[];

String slots nothing refers to.

Types

Declarations only this group names.

IssueLeveltype

type IssueLevel = "error" | "warn" | "info";

IssueTargettype

type IssueTarget = {
	kind: "location";
	index: number;
} | {
	kind: "unit";
	index: number;
} | {
	kind: "trigger";
	index: number;
} | {
	kind: "dialog";
	id: DialogId;
};

Issueinterface

interface Issue

`level: IssueLevel`
`text: string`
`where: string`
`target?: IssueTarget`

PlayerStatisticsinterface

interface PlayerStatistics

`slot: number`
`type: string`
`race: string`
`units: number`
`buildings: number \| null`	Null when units.dat is not loaded.
`startLocations: number`

MapStatisticsinterface

interface MapStatistics

`width: number`
`height: number`
`tileset: string`
`revision: string`
`sections: number`
`strings: { slots: number; set: number; extended: boolean; }`
`players: PlayerStatistics[]`
`unownedUnits: number`	Units whose owner byte is past the twelve slots.
`units: { total: number; buildings: number \| null; top: { id: number; name: string; count: number; }[]; }`
`resources: { minerals: number; gas: number; fields: number; geysers: number; }`
`doodads: number`
`sprites: { pure: number; unit: number; }`
`locations: number`
`triggers: { count: number; conditions: number; actions: number; preserved: number; disabled: number; }`
`briefings: { count: number; actions: number; }`	MBRF: the briefing's records and the actions in them.
`switchesNamed: number`
`sounds: number`
`terrain: { name: string; tiles: number; }[] \| null`	Tiles per terrain type ("Edges and cliffs" for the unnamed edge sets), most common first; null without the tileset graphics.

FindKindtype

type FindKind = "units" | "locations" | "sprites" | "doodads" | "strings" | "triggers" | "briefing";

FindResultinterface

interface FindResult

`kind: FindKind`
`index: number`	Index into the list the kind names (unit / sprite / trigger index, location slot, string index).
`label: string`
`detail: string`
`x?: number`	Tile coordinates to centre on, where the thing has a position.
`y?: number`

FindOptionsinterface

interface FindOptions

`kind: FindKind`
`query: string`
`matchCase?: boolean`
`spriteName?: (r: SpriteRecord) => string`	Display name of a sprite record (needs the game data); the id when omitted.
`doodadName?: (r: DoodadRecord) => string`	Display name of a doodad record (needs the tileset); the id when omitted.
`limit?: number`

StringUsageKindtype

type StringUsageKind = "name" | "description" | "force" | "location" | "unit" | "switch" | "trigger" | "briefing" | "wav";

StringUsageinterface

interface StringUsage

`kind: StringUsageKind`
`ref: number`	What the kind indexes: force / slot / unit id / switch / trigger index / WAV slot; 0 for name and description.
`label: string`

PlacementProblemtype

type PlacementProblem = "terrain" | "collision";

PlacementVerdictinterface

interface PlacementVerdict

`problem: PlacementProblem \| null`
`blocker: number`	The unit in the way, for collision problems.
`reason: string \| null`	The problem as a sentence fragment — "the ground is unwalkable", "it overlaps Terran Marine" — null when it fits.

StartLocationinterface

interface StartLocation

A start location on the map: the record's index, its owner and where it sits.

`index: number`
`owner: number`
`x: number`	Map pixels.
`y: number`
`tx: number`	The tile it is centred on.
`ty: number`