@scm-js/plugin-api 1.10.0 → 1.12.0

package/index.d.ts

@@ -1639,6 +1639,13 @@ export interface DoodadPlacementOptions {
 	/** Keep the left column on an even tile, as StarEdit always does. */
 	snapToGrid: 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 {
 	changes: UnitChange[];
@@ -1840,8 +1847,9 @@ export interface Disposable {
  * builders (`document.edit` and `document.update`) are the exception, and deliberately
  * so: their operations apply as they are called and one commit closes the transaction
  * when the builder returns, so an `async` builder would commit the part of its work that
- * ran before the first `await` and leave the rest to land outside the entry, breaking
- * undo without an error. Do the awaiting *before* the call:
+ * ran before the first `await` and leave the rest with nowhere to land: the transaction
+ * is closed once the builder returns, and every call on it throws from then on. Do the
+ * awaiting *before* the call:
  *
  * ```ts
  * await api.tileset.load();                       // the async part, first
@@ -2091,7 +2099,11 @@ export interface DocumentApi {
 	 * Returns an all-zero result with `changed: false` when no map is open.
 	 *
 	 * `build` is synchronous — see `Sync`. Await what you need (graphics, a pick, a
-	 * fetch) before the call, then write in one go.
+	 * fetch) before the call, then write in one go. The transaction is closed when
+	 * `build` returns; a call on it after that throws.
+	 *
+	 * A builder that throws is rolled back: what it had applied is taken off the map
+	 * again, nothing reaches the history or the modified flag, and the error reaches you.
 	 *
 	 * @example
 	 * // One undo entry called "Fill", however many operations it takes.
@@ -2108,7 +2120,11 @@ export interface DocumentApi {
 	 * transaction, the way a settings dialog's OK applies its whole form at once.
 	 * Operations apply as they are called; the commit marks the map modified and bumps
 	 * what the chrome reads. There is no undo entry: keep your own if you need one.
-	 * `build` is synchronous, as `edit`'s is.
+	 * `build` is synchronous, as `edit`'s is, and closed when it returns.
+	 *
+	 * There is nothing to roll an update back with, so a builder that throws leaves what
+	 * it wrote: the sections it touched are committed — the map is modified and the
+	 * chrome re-reads — and the error reaches you.
 	 *
 	 * @example
 	 * api.document.update("Rename", (tx) => {
@@ -2724,6 +2740,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. */
@@ -3376,6 +3400,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.10.0",
+  "version": "1.12.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",