Build Mercante: A Complete Ludus Game Tutorial
What You’ll Build
Section titled “What You’ll Build”By the end of this tutorial, you’ll have a complete, production-ready game that integrates every layer of the Ludus platform:
| Chapter | What You Build | Package |
|---|---|---|
| 1 | Game logic — trades, swaps, lending, betting | @ludus/game-engine |
| 2 | AI opponents with distinct personalities | @ludus/agent-sdk |
| 3 | A Florentine town crier commentating the action | @ludus/commentator |
| 4 | Live spectator viewer with price charts | @ludus/game-engine-react |
| 5 | Merchant wallets for on-chain identity | @ludus/wallet |
| 6 | DeFi-powered trading mechanics | @ludus/defi-bridge |
| 7 | Prediction markets on game outcomes | @ludus/prediction-markets |
| 8 | Packaging, quality gates, and catalog listing | @ludus/game-protocol |
Each chapter adds one package. Each chapter is self-contained — your game compiles and tests pass at every step.
The Game: Mercante
Section titled “The Game: Mercante”Setting: Florence, 1470. You are a merchant in the age of the Medici. Six goods flow through the market — Silk, Spice, Wine, Wool, Gold, and Art — each with its own volatility and base price.
Actions per turn:
| Action | What it does |
|---|---|
| Trade | Buy or sell goods at current market prices |
| Swap | Exchange one good for another via DeFi (better rates, fees apply) |
| Invest | Supply goods to a lending pool for yield |
| Withdraw | Pull goods from the lending pool with accrued interest |
| Bet | Wager florins on who will win the game |
| Pass | Skip your turn |
Win condition: After 15 turns, the merchant with the highest total portfolio value (florins + goods + lending positions + bet winnings) wins.
Prerequisites
Section titled “Prerequisites”- Node.js 20+
- TypeScript experience
- The Ludus monorepo cloned and built (
npm install && npm run build) - A code editor with TypeScript support
How to Follow Along
Section titled “How to Follow Along”The tutorial walks through the Mercante source code in packages/mercante/. You can:
- Read and reference — Follow the chapters while reading the existing code
- Build from scratch — Create the files yourself, chapter by chapter
- Copy and modify — Use Mercante as a template for your own game
Each chapter includes:
- An explanation of the concepts
- The complete code for that chapter’s addition
- Tests to verify your implementation
- A “What you should see” section
Let’s begin.