api.view
ViewApi
The map view: where the viewport is looking, how far in, and what it draws over the terrain. A plugin that finds something needs this to show the user where it is.
Members
zoom
zoom(): number;reveal
reveal(rect: Rect, options?: RevealOptions): Promise<boolean>;Bring a tile rect onto the screen, gliding there by the shortest way rather than
jumping, and leaving the view alone when the rect is already visible. With fit the
view zooms out (never in) as far as the rect needs. Resolves once the view is there;
false when the user, or another request, moved it first — a plugin that follows its
own work around the map takes that as its cue to stop.
const shown = await api.view.reveal({ x0: 0, y0: 0, x1: 16, y1: 16 }, { fit: true });
if (!shown) api.log("the user moved the view first");goTo
goTo(target: GoTo): void;Scroll to an object (and select it, for a unit, sprite or location).
// Player 1's start location, selected and in the middle of the view.
const start = api.query.startLocations().find((s) => s.owner === 0);
if (start) api.view.goTo({ kind: "unit", index: start.index });cursorTile
cursorTile(): { x: number; y: number; };The tile under the pointer, as the status bar shows it.
setFlags
setFlags(patch: Partial<ViewFlags>): void;api.view.setFlags({ grid: !api.view.flags().grid });setGridSize
setGridSize(size: 8 | 16 | 32 | 64 | 128): void;flash
flash(target: FlashTarget): void;Highlight something on the map for a moment: the rect an edit filled, the units it placed, the location it moved. Fades by itself; several may run at once. Nothing to clean up.
// Mark the top-left corner for Player 1's fog, and show where that was.
const rect = { x0: 0, y0: 0, x1: 8, y1: 8 };
const r = api.document.edit("Fog a corner", (tx) => tx.setFog(rect, 0b1, "fog"));
if (r.changed) api.view.flash({ rect });Types
Declarations only this group names.
ViewFlagsinterface
interface ViewFlagsgrid: boolean | |
|---|---|
locations: boolean | |
locationNames: boolean | |
units: boolean | |
sprites: boolean | |
doodads: boolean | Off draws the ground under the doodads (TILE) instead of the picture (MTXM). |
fog: boolean | |
elevation: boolean | Ground height per minitile, tinted (mid amber, high red). |
buildability: boolean | Unbuildable tile groups, hatched in blue. |
startLocations: boolean | |
animateWater: boolean | Cycle the palette so water and lava animate as they do in game. |
animateUnits: boolean | Run the units' iscript idle animations (turrets, pulsing buildings, fires, smoke). |
hdGraphics: boolean | Draw terrain and sprites from StarCraft: Remastered's 2x pictures, where the data set in use has them. |
GoTotype
type GoTo = {
kind: "tile";
x: number;
y: number;
} | {
kind: "unit";
index: number;
} | {
kind: "sprite";
index: number;
} | {
kind: "location";
index: number;
}
/** Opens the Trigger Editor (or, with `briefing`, the Mission Briefing) on that trigger. */
| {
kind: "trigger";
index: number;
briefing?: boolean;
};Where view.goTo should take the user. Issues from query.validate carry one.
RevealOptionsinterface
interface RevealOptionsHow view.reveal brings a rect on screen.
fit?: boolean | Zoom out to the zoom control's nearest step that fits the rect (plus the margin); never zooms in. Off by default. |
|---|---|
animate?: boolean | Glide rather than jump. On by default. |
margin?: number | Tiles kept clear between the rect and the viewport's edge when the view has to move. 1 by default. |
FlashTargettype
type FlashTarget = {
rect: Rect;
kind?: FlashKind;
ms?: number;
} | {
units: number[];
kind?: FlashKind;
ms?: number;
} | {
locations: number[];
kind?: FlashKind;
ms?: number;
} | {
tiles: {
x: number;
y: number;
}[];
kind?: FlashKind;
ms?: number;
};What view.flash highlights: a tile rect, or units / locations by index. The
highlight fades over ms (600 by default) and never blocks or takes the pointer; it is
the shared way to say "this just changed" or "look here", so every plugin's flash looks
the same. kind picks the colour: "change" (gold, the default) or "attention" (teal).