Skip to content

Quick Start

Create your first Lands.io mod in under 5 minutes.

1. Create Your Mod Class

Create gameplay.ts - the main entry point:

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

export default class MyFirstMod extends Mod {
  onGameInit(game: Game, executor: Executor) {
    // Called when the game starts
    console.log('Game initialized!');

    // Set up initial state
    this.modState.set('scores', {});
  }

  onPlayerAdded(player: Player) {
    // Called when a player joins
    console.log(`${player.name()} joined the game!`);

    // Initialize player score
    const scores = this.modState.get('scores') || {};
    scores[player.id()] = 0;
    this.modState.set('scores', scores);
  }

  onGameEnd(game: Game, winnerId: string, stats: unknown) {
    // Called when the game ends
    console.log(`Player ${winnerId} won!`);
  }
}

2. Add Configuration (Optional)

Override game mechanics in config.ts:

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

export class MyConfig implements Partial<Config> {
  // Reduce attack power
  attackAmount(attacker: Player, defender: Player | TerraNullius): number {
    return attacker.troops() / 10;
  }

  // Increase starting troops (relative to max population)
  startManpower(player: Player): number {
    return this.maxPopulation(player) * 0.9;
  }
}

Then attach it to your mod:

import { MyConfig } from './config';

export default class MyFirstMod extends Mod {
  static override Config = MyConfig;

  // ... rest of your mod
}

3. Build Your Mod

pnpm nx build-mods mod-sdk

4. Test It

Upload your built mod to a Lands.io game server or use the local development environment.

Next Steps