Creating Your First Mod¶

A complete walkthrough of building a simple mod from scratch.

What We're Building¶

A "Double Trouble" mod where:

Players start with double the normal troops
Attacks are 50% weaker
First player to 90% territory wins

Step 1: Project Setup¶

Create your mod folder structure:

double-trouble/
├── manifest.json
├── gameplay.ts
└── config.ts

Step 2: Create the Manifest¶

manifest.json

{
  "id": "double-trouble",
  "name": "Double Trouble",
  "version": "1.0.0",
  "description": "Start strong, attack weak, dominate!",
  "author": "Your Name",
  "entry": "gameplay.ts"
}

Step 3: Create the Config¶

Override game mechanics in config.ts:

config.ts

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

export class DoubleTroubleConfig implements Partial<Config> {
  // Higher starting troops (based on max population)
  startManpower(player: Player): number {
    return this.maxPopulation(player) * 0.9;
  }

  // Weaker attacks (50% reduction)
  attackAmount(attacker: Player, defender: Player | TerraNullius): number {
    return attacker.troops() / 10; // Default is troops / 5
  }

  // Higher win threshold
  percentageTilesOwnedToWin(): number {
    return 90; // Default is 80
  }
}

Step 4: Create the Mod Class¶

Create gameplay.ts:

gameplay.ts

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

export default class DoubleTroubleMod extends Mod {
  // Attach our custom config
  static override Config = DoubleTroubleConfig;

  onGameInit(game: Game, executor: Executor): void {
    console.log('🎮 Double Trouble mode activated!');

    // Track player stats
    this.modState.set('stats', {});
  }

  onPlayerAdded(player: Player): void {
    console.log(`⚔️ ${player.name()} joined with ${player.troops()} troops!`);

    // Initialize player stats
    const stats = this.modState.get('stats') || {};
    stats[player.id()] = {
      joinedAt: Date.now(),
      peakTroops: player.troops(),
    };
    this.modState.set('stats', stats);
  }

  onGameEnd(game: Game, winnerId: PlayerID, stats: unknown): void {
    const winner = game.player(winnerId);
    console.log(`🏆 ${winner?.name()} wins Double Trouble!`);
  }
}

Step 5: Build Your Mod¶

pnpm nx build-mods mod-sdk

Your mod will be bundled to dist/mods/double-trouble.js.

Step 6: Test It¶

Upload to a Lands.io server or use the local dev environment.

What's Next?¶

Now that you've built a basic mod, try: