@lands.io/mod-sdk / ScenarioSetup

Interface: ScenarioSetup¶

Init-only API for deterministic scenario setup.

All methods throw if used after scenario setup has ended (engine calls finalize() automatically).

Table of contents¶

Methods¶

claimRect¶

▸ claimRect(playerId, rect): void

Claim a rectangle of tiles (inclusive bounds).

Parameters¶

Name	Type
`playerId`	`string`
`rect`	`ClaimRectSpec`

Returns¶

void

claimRing¶

▸ claimRing(playerId, ring): void

Claim a ring of tiles centered at (cx,cy) with radii in tiles (inclusive).

Parameters¶

Name	Type
`playerId`	`string`
`ring`	`ClaimRingSpec`

Returns¶

void

claimTiles¶

▸ claimTiles(playerId, tiles): void

Claim an explicit list of tiles for a player. The engine enforces a deterministic ordering internally.

Parameters¶

Name	Type
`playerId`	`string`
`tiles`	`number`[]

Returns¶

void

createPlayer¶

▸ createPlayer(spec): string

Parameters¶

Name	Type
`spec`	`ScenarioPlayerSpec`

Returns¶

string

finalize¶

▸ finalize(): void

Optional manual finalize; engine calls automatically.

Returns¶

void

setDefaultHumanSpawn¶

▸ setDefaultHumanSpawn(tile): void

Override the default human spawn tile deterministically.

Parameters¶

Name	Type
`tile`	`number`

Returns¶

void

setHumanSpawnCandidates¶

▸ setHumanSpawnCandidates(tiles): void

Provide multiple candidates; the engine picks deterministically.

Parameters¶

Name	Type
`tiles`	`number`[]

Returns¶

void

setHumanSpawnTerritory¶

▸ setHumanSpawnTerritory(tiles): void

Override the initial territory for the next spawned human (init-only). The engine applies this once, during the next human spawn.

Parameters¶

Name	Type
`tiles`	`number`[]

Returns¶

void

setTroops¶

▸ setTroops(playerId, troops): void

Parameters¶

Name	Type
`playerId`	`string`
`troops`	`number`

Returns¶

void

spawnPlayer¶

▸ spawnPlayer(spec, spawnTile, spawnTerritoryTiles?): string

Spawn a non-human player through the normal engine spawn path. This gives bots their standard AI behavior instead of creating a static player.

Parameters¶

Name	Type
`spec`	`ScenarioPlayerSpec`
`spawnTile`	`number`
`spawnTerritoryTiles?`	`number`[]

Returns¶

string

Source Code¶

View full implementation

/**
 * Init-only API for deterministic scenario setup.
 *
 * All methods throw if used after scenario setup has ended (engine calls `finalize()` automatically).
 */
export interface ScenarioSetup {
  createPlayer(spec: ScenarioPlayerSpec): PlayerID;

  /**
   * Spawn a non-human player through the normal engine spawn path.
   * This gives bots their standard AI behavior instead of creating a static player.
   */
  spawnPlayer(
    spec: ScenarioPlayerSpec,
    spawnTile: TileRef,
    spawnTerritoryTiles?: TileRef[]
  ): PlayerID;

  setTroops(playerId: PlayerID, troops: number): void;

  /**
   * Claim an explicit list of tiles for a player.
   * The engine enforces a deterministic ordering internally.
   */
  claimTiles(playerId: PlayerID, tiles: TileRef[]): void;

  /** Claim a rectangle of tiles (inclusive bounds). */
  claimRect(playerId: PlayerID, rect: ClaimRectSpec): void;

  /** Claim a ring of tiles centered at (cx,cy) with radii in tiles (inclusive). */
  claimRing(playerId: PlayerID, ring: ClaimRingSpec): void;

  /** Override the default human spawn tile deterministically. */
  setDefaultHumanSpawn(tile: TileRef): void;

  /** Provide multiple candidates; the engine picks deterministically. */
  setHumanSpawnCandidates(tiles: TileRef[]): void;

  /**
   * Override the initial territory for the next spawned human (init-only).
   * The engine applies this once, during the next human spawn.
   */
  setHumanSpawnTerritory(tiles: TileRef[]): void;

  /** Optional manual finalize; engine calls automatically. */
  finalize(): void;
}