@scm-js/plugin-api 1.11.0 → 1.13.0

package/index.d.ts

@@ -1638,6 +1638,15 @@ export interface DoodadPlacementOptions {
 	placeAnywhere: boolean;
 	/** Keep the left column on an even tile, as StarEdit always does. */
 	snapToGrid: boolean;
+	/** Place as plain terrain: the tiles (both sections) and any overlay sprite, no DD2 record — a placement and a conversion in one. */
+	asTerrain: boolean;
+}
+export interface DoodadVerdict {
+	ok: boolean;
+	/** The footprint leaves the map (never allowed). */
+	outOfBounds: boolean;
+	/** Cell indices (row-major) whose ground fails the check, for the ghost to mark red. */
+	bad: number[];
 }
 export type StartLayout = "ring" | "corners";
 export interface StartPlacementResult {
@@ -2337,6 +2346,13 @@ export interface EditTransaction {
 	/** Stamp a doodad (a `dddata.bin` id) at a tile; returns its record index, or -1 when unknown or off the map. */
 	placeDoodad(doodadId: number, tx: number, ty: number, owner?: number): number;
 	removeDoodads(indices: number[]): number;
+	/**
+	 * Make doodads plain terrain: their records go, their tiles stay (in TILE as well as
+	 * MTXM, so the cells are ground to every tool from here on) and an overlay stays as an
+	 * ordinary sprite. The way to touch up a ramp or a cliff piece tile by tile.
+	 * Returns records converted.
+	 */
+	convertDoodads(indices: number[]): number;
 	/** A location in the lowest free slot (pixel bounds); returns the slot, or -1 when the table is full. */
 	addLocation(bounds: Bounds, name?: string, elevationFlags?: number): number;
 	editLocation(index: number, patch: LocationPatch): boolean;
@@ -2733,6 +2749,14 @@ export interface QueryApi {
 	startLocations(): StartLocation[];
 	/** Whether a unit type may be placed centred there, and what stops it; null with no map. */
 	placement(unitId: number, x: number, y: number): PlacementVerdict | null;
+	/**
+	 * StarEdit's ground check for a doodad with its top-left tile at (tx, ty): `ok`, or the
+	 * cells (row-major) whose ground is not what `DoodadInfo.required` asks for. It reads the
+	 * map as it is right now — inside a `document.edit` that is the map with the transaction's
+	 * earlier changes in — so a plugin can paint a cliff and then look for where a ramp fits.
+	 * Null with no map or without the tileset graphics.
+	 */
+	doodadPlacement(doodadId: number, tx: number, ty: number): DoodadVerdict | null;
 	/** The MASK bits at a tile: bit n set = player n + 1 starts fogged there (every bit when the map has no MASK). */
 	fogAt(tx: number, ty: number): number;
 	/** The string table as it stands (index 0 is nothing); empty with no map. */
@@ -3385,6 +3409,19 @@ export interface DoodadInfo {
 	/** Footprint in tiles. */
 	width: number;
 	height: number;
+	/**
+	 * A ramp: a doodad with the VF4 ramp bit, filed under a cliff category with no name of
+	 * its own. Ramps fit only on the cliff shape they were drawn for (see `required`), and
+	 * a tileset has them for a few terrain pairs only.
+	 */
+	ramp: boolean;
+	/**
+	 * Per cell (row-major, `width` × `height`): the CV5 tile group that must already lie
+	 * under it for StarEdit to allow the placement, or 0 for "anything". A flat terrain's
+	 * pair is its `TerrainType.group` (even) and `group + 1`; the other numbers are cliff
+	 * and shore pieces. `query.doodadPlacement` applies the rule.
+	 */
+	required: number[];
 }
 export interface PaletteApi {
 	active(): PaletteChoice;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-js/plugin-api",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",