@lands.io/mod-sdk

@lands.io/mod-sdk¶

Lands.io Mod SDK

This SDK provides everything you need to create mods for Lands.io.

Example

import { Mod, Config } from '@lands.io/mod-sdk';

// Optional: Override specific game mechanics
class MyConfig implements Partial<Config> {
  attackAmount(attacker, defender) {
    return attacker.troops() / 10; // Half the normal attack
  }
}

// Export a single class extending Mod
export default class TeamMod extends Mod {
  // Attach config class (optional)
  static override Config = MyConfig;

  onGameInit(game, executor) {
    this.modState.set('teams', { blue: [], red: [] });
  }

  onPlayerAdded(player) {
    console.log(`${player.name()} joined!`);
  }

  registerActions(executor) {
    executor.registerAction(new MyCustomAction());
  }
}

Table of contents¶

Enumerations¶

Classes¶

Interfaces¶

Type Aliases¶

Variables¶

Functions¶

Type Aliases¶

AttackType¶

Ƭ AttackType: "normal" | "breakthrough"

ClientID¶

Ƭ ClientID: string

Client connection identifier

ConfigClass¶

Ƭ ConfigClass: (gameConfig: GameConfig) => PartialConfig

Config class constructor type. Used for the static Config property on Mod classes.

Type declaration¶

• (gameConfig): PartialConfig

Parameters¶

Name	Type
`gameConfig`	`GameConfig`

Returns¶

PartialConfig

Gold¶

Ƭ Gold: number

Gold currency amount

JsonPrimitive¶

Ƭ JsonPrimitive: null | boolean | number | string

JSON primitive value

JsonValue¶

Ƭ JsonValue: JsonPrimitive | JsonValue[] | { [key: string]: JsonValue; }

JSON-serializable value

LobbyRpcMethod¶

LobbyRpcResultMessage¶

Ƭ LobbyRpcResultMessage: { id: string ; ok: true ; result: unknown ; type: "rpcResult" } | { error: LobbyRpcError ; id: string ; ok: false ; type: "rpcResult" }

ModClientAction¶

Ƭ ModClientAction: { baselineId: string ; patch?: { modConfig?: JsonValue } ; type: "prewarm_singleplayer_engine_baseline" } | { baselineId: string ; patch?: { modConfig?: JsonValue } ; type: "reset_singleplayer_engine" } | { type: "leave_lobby" } | { type: "requeue_regular_game" } | { key: string ; type: "set_local_progress_flag" ; value: boolean }

ModHudActionVariant¶

ModHudPanelVariant¶

Ƭ ModHudPanelVariant: "default" | "glass_tactical" | "boost_pick" | "dev_grid"

ModHudV1Media¶

Ƭ ModHudV1Media: ModHudV1MediaVideo

ModPlayerBoostsV1¶

Ƭ ModPlayerBoostsV1: Record\<string, ModBoostBarV1Item[]>

Maps player ID → their active boost bar items.

ModPlayerLevelsV1¶

Ƭ ModPlayerLevelsV1: Record\<string, number>

Maps player ID → their current level.

PartialConfig¶

Ƭ PartialConfig: Partial\<Config>

Partial config type for mods. Mods only need to implement the methods they want to override. The rest will fall back to DefaultConfig.

PlayerID¶

Ƭ PlayerID: string

Unique player identifier string

SkinGridColor¶

Ƭ SkinGridColor: "blue" | "red"

Tick¶

Ƭ Tick: number

Game tick counter - increments each game update cycle

TileRef¶

Ƭ TileRef: number

Map tile reference - an encoded coordinate

Variables¶

AllPlayers¶

• Const AllPlayers: "AllPlayers"

MOD_BOOST_BAR_STATE_KEY_V1¶

• Const MOD_BOOST_BAR_STATE_KEY_V1: "__landsio_mod_boost_bar_v1"

MOD_HUD_STATE_KEY_V1¶

• Const MOD_HUD_STATE_KEY_V1: "__landsio_mod_hud_v1"

MOD_LEVEL_BAR_STATE_KEY_V1¶

• Const MOD_LEVEL_BAR_STATE_KEY_V1: "__landsio_mod_level_bar_v1"

MOD_PLAYER_BOOSTS_STATE_KEY_V1¶

• Const MOD_PLAYER_BOOSTS_STATE_KEY_V1: "__landsio_mod_player_boosts_v1"

MOD_PLAYER_LEVELS_STATE_KEY_V1¶

• Const MOD_PLAYER_LEVELS_STATE_KEY_V1: "__landsio_mod_player_levels_v1"

PlayerModifiers¶

• Const PlayerModifiers: Object

Well-known modifier keys read by the engine from per-player modifiers. Mods set these via player.setModifier(key, value). All values are numeric multipliers (1.0 = no change) unless noted.

Type declaration¶

Name	Type	Description
`ATTACK_SPEED`	`"core.attackSpeed"`	Multiplier on normal attack speed. Default: 1
`BREAKTHROUGH_RADIUS`	`"core.breakthroughRadius"`	Additive bonus to breakthrough corridor radius. Default: 0
`BREAKTHROUGH_SPEED`	`"core.breakthroughSpeed"`	Multiplier on breakthrough speed. Default: 1
`POP_GROWTH`	`"core.popGrowth"`	Multiplier on population growth rate. Default: 1
`TROOP_LOSS`	`"core.troopLoss"`	Multiplier on attacker troop loss per tile. Default: 1 (lower = less loss)

SDK_VERSION¶

• Const SDK_VERSION: "0.1.0"

SDK version for feature detection

Functions¶

assertNever¶

▸ assertNever(x): never

TypeScript exhaustiveness check helper

Parameters¶

Name	Type
`x`	`never`

Returns¶

never

setModBoostBar¶

▸ setModBoostBar(modState, bar): void

Parameters¶

Name	Type
`modState`	`ModState`
`bar`	`null` \| `ModBoostBarV1`

Returns¶

void

setModHud¶

▸ setModHud(modState, hud): void

Parameters¶

Name	Type
`modState`	`ModState`
`hud`	`null` \| `ModHudV1`

Returns¶

void

setModLevelBar¶

▸ setModLevelBar(modState, bar): void

Parameters¶

Name	Type
`modState`	`ModState`
`bar`	`null` \| `ModLevelBarV1`

Returns¶

void

setModPlayerBoosts¶

▸ setModPlayerBoosts(modState, boosts): void

Parameters¶

Name	Type
`modState`	`ModState`
`boosts`	`null` \| `ModPlayerBoostsV1`

Returns¶

void

setModPlayerLevels¶

▸ setModPlayerLevels(modState, levels): void

Parameters¶

Name	Type
`modState`	`ModState`
`levels`	`null` \| `ModPlayerLevelsV1`

Returns¶

void

setPublicApiUrl¶

▸ setPublicApiUrl(url): void

Set the public API URL at runtime. Called by the lobby client and worker when receiving init messages. Sets both module-level variable and global variable to handle bundled mod-sdk copies.

Parameters¶

Name	Type	Description
`url`	`string`	The public API URL for the current environment

Returns¶

void

within¶

▸ within(value, min, max): number

Clamp a value between min and max

Parameters¶

Name	Type
`value`	`number`
`min`	`number`
`max`	`number`

Returns¶

number