api.clipboard

ClipboardApi

Cut / Copy / Paste: the clip, its parts, and pasting — what the clipboard layer does.

The Cut / Copy / Paste layer. The clip is self-contained (it outlives the map it came from and pastes into another) and shared with the user's own clipboard, so a plugin that copies here is copying for the user too.

clip
setClip
copy
cut
paste
parts
setParts
mode
setMode
pasting
setPasting
summary

Members

clip

clip(): Clip | null;

What is on the clipboard, or null.

setClip

setClip(clip: Clip | null): void;

Put a clip on the clipboard (one from copy, or built elsewhere); null clears it.

copy

copy(source?: ClipSource): Clip | null;

Copy a source — the marked area when omitted (or, on an object layer, that layer's selection, as Ctrl+C does) — with the parts ticked in parts(). Null when there is nothing to copy.

cut

cut(source?: ClipSource): Clip | null;

Copy, then remove the source's objects as one undo step (terrain and fog stay). Null when there was nothing.

paste

paste(tx: number, ty: number, options?: PasteOptionsSpec): PasteResult | null;

Stamp the clip with its top-left tile at (tx, ty), one undo step; the pasted area becomes the marked one. Null when there is no clip or no map.

parts

parts(): ClipParts;

setParts

setParts(patch: Partial<ClipParts>): void;

mode

mode(): PasteMode;

setMode

setMode(mode: PasteMode): void;

pasting

pasting(): boolean;

Whether the clipboard layer is armed: the next click on the map pastes.

setPasting

setPasting(on: boolean): void;

Arm pasting (switches to the clipboard layer) or stop.

summary

summary(clip: Clip): string;

One line for a clip: 12 × 8 tiles · 3 units · 2 doodads.

Types

Declarations only this group names.

TileChangeinterface

interface TileChange

`at: number`	Flat index into `scenario.tiles`.
`before: number`
`after: number`
`under?: number`	What `scenario.editorTiles` (TILE) held before a terrain change, when that differs from `before` (the cell was under a doodad). Filled in by `applyChanges` the first time a change is applied, so undo can put the ground back rather than the doodad tile.

LocationStringChangeinterface

interface LocationStringChange

`index: number`
`before: string \| null`
`after: string \| null`

LocationChangeinterface

interface LocationChange

`index: number`
`before: LocationRecord`
`after: LocationRecord`
`string?: LocationStringChange`	A string slot the edit adds (a name no existing string matched); removed again on undo.

SpriteChangeinterface

interface SpriteChange

`index: number`
`before: SpriteRecord \| null`
`after: SpriteRecord \| null`

DoodadChangeinterface

interface DoodadChange

`index: number`
`before: DoodadRecord \| null`
`after: DoodadRecord \| null`

HistoryEditinterface

interface HistoryEdit

The change lists of one edit; HistoryEntry adds the label.

`changes: TileChange[]`
`isom?: TileChange[]`	The isometric brush's changes to `scenario.isom`, undone together with the tiles.
`createdIsom?: Uint16Array`	Set when the edit gave a map an ISOM section it did not have (Rebuild ISOM). Undo removes the section again rather than leaving an all-zero one behind.
`units?: UnitChange[]`	Unit placements, moves and deletions (see editor/units.ts).
`doodadTiles?: TileChange[]`	Doodad tiles stamped into or lifted off MTXM alone — TILE keeps the ground beneath (see editor/doodads.ts). Applied after `changes`, so a terrain stroke that removes the doodads it painted over restores their remaining cells on top of its own edit.
`doodads?: DoodadChange[]`	DD2 record insertions, removals and replacements.
`sprites?: SpriteChange[]`	THG2 record changes: the Sprites layer's edits, and a doodad's overlay sprite coming and going with it.
`locations?: LocationChange[]`	MRGN slot replacements — create, move, resize, rename, delete (see editor/locations.ts); a rename may carry a string.
`fog?: TileChange[]`	Fog of war edits to `scenario.mask` (see editor/fog.ts); `at` indexes the MASK byte.
`createdMask?: Uint8Array`	Set when the edit gave a map a MASK section it did not have (the first fog stroke on such a map). Undo removes the section again.

ClipParttype

type ClipPart = "terrain" | "doodads" | "units" | "sprites" | "locations" | "fog";

ClipPartstype

type ClipParts = Record<ClipPart, boolean>;

PasteModetype

type PasteMode = "merge" | "replace";

Whether a paste adds to what is in the target area or clears its objects first.

ClipLocationinterface

interface ClipLocation

`left: number`	Bounds in map pixels relative to the clip's origin (an inverted box keeps its inversion).
`top: number`
`right: number`
`bottom: number`
`elevationFlags: number`
`name: string`

Clipinterface

interface Clip

`width: number`	Size in tiles.
`height: number`
`era: number`	ERA of the source map: tile ids mean nothing on another tileset.
`tiles: Uint16Array \| null`	MTXM ids, row-major, or null when terrain was not included.
`ground: Uint16Array \| null`	TILE ids (the ground under the doodads), alongside `tiles`.
`doodads: DoodadRecord[]`	Records with positions relative to the origin in map pixels.
`units: UnitRecord[]`
`sprites: SpriteRecord[]`
`locations: ClipLocation[]`
`fog: Uint8Array \| null`	MASK bytes, row-major, or null when fog was not included.

PasteCountsinterface

interface PasteCounts

`tiles: number`
`doodads: number`
`units: number`
`sprites: number`
`locations: number`
`fog: number`
`removed: number`	Objects the paste cleared out of the way (replace mode) or that a new tile stranded.

PasteResultinterface

interface PasteResult

`edit: HistoryEdit`
`counts: PasteCounts`
`notes: string[]`	Things that could not be pasted, in words.

ClipSourcetype

type ClipSource = {
	rect: Rect;
} | {
	units?: number[];
	sprites?: number[];
	doodads?: number[];
	locations?: number[];
};

What clipboard.copy / cut take: the marked area (or any tile rect), or objects by index.

PasteOptionsSpecinterface

interface PasteOptionsSpec

`parts?: Partial<ClipParts>`	Over what `clipboard.parts()` says.
`mode?: PasteMode`	Over `clipboard.mode()`.