Competition Engine

Framework for structured competitive play: seasons, leagues, rankings, and events.

Purpose

The Competition module provides the data structures, lifecycle management, and on-chain settlement patterns for organized competitive play. It handles:

Seasons — time-bounded competitive periods with tracked rankings
Leagues — skill-based tiers that segment the player population
Leaderboards — real-time and historical ranking systems
Events — one-off or recurring competitions outside the seasonal structure

All matchmaking and gameplay resolution happens off-chain on the game server. The competition module defines how results are structured, tracked, and settled when economic finality is needed.

Module Architecture

┌─────────────────────────────────────────────────────────────┐
│                     GAME SERVER                             │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ Season   │  │ League   │  │ Leader-  │  │  Event    │  │
│  │ Manager  │  │ System   │  │ board    │  │  Manager  │  │
│  │          │  │          │  │ Tracker  │  │           │  │
│  │ start/   │  │ promote/ │  │ ELO/     │  │create/    │  │
│  │ end/     │  │ relegate/ │  │ points/  │  │finalize/  │  │
│  │ finalize │  │ place    │  │ rank     │  │schedule   │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬──────┘  │
│       │              │              │              │         │
│       └──────────────┴──────────────┴──────────────┘         │
│                              │                               │
│                   settlement payload                         │
└──────────────────────────────┼───────────────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   Settlement Chain  │
                    │                     │
                    │  • Prize pool       │
                    │    distribution     │
                    │  • Achievement      │
                    │    minting          │
                    │  • Season results   │
                    │    recording        │
                    └─────────────────────┘

Components

Component	Description	Doc
Seasons & Leagues	Time-bounded competitive periods with tiered skill brackets	Seasons & Leagues →
Leaderboards	Real-time and historical ranking systems with multiple scoring models	Leaderboards →
Events	One-off competitions, tournaments, and special formats	Events →

Key Properties

Property	Detail
Server-authoritative	All match results determined by game server, not blockchain
Off-chain tracking	Leaderboards and rankings maintained in server database
On-chain settlement	Only season-end distributions, prizes, and achievements go on-chain
Configurable formats	Supports any competitive structure — round-robin, Swiss, bracket, etc.
Token-agnostic	Entry fees and prizes can use any ERC-20 or native token

Data Flow: Season Lifecycle

1. Season configured (parameters set by game operator)
       │
       ▼
2. Season opens (players begin competing)
       │ matches played, results recorded off-chain
       ▼
3. Season ends (server stops accepting matches)
       │
       ▼
4. Server calculates final standings
       │
       ▼
5. Server submits results to chain
       │ (ranked list, achievement qualifiers)
       ▼
6. Prize pool distributes rewards
       │ (winners call claim())
       ▼
7. Achievement NFTs minted for qualifiers
       │ (server signs, player mints)
       ▼
8. New season configured → repeat

When to Use This Module

Your Situation	Use Competition?
Multiplayer skill-based game with seasons	✅ Full module
Casual game with occasional tournaments	✅ Events only
Game with ranked matchmaking	✅ Leagues + Leaderboards
Single-player game with no competitive element	❌ Not needed
PvE game with leaderboards only	✅ Leaderboards only

Purpose​

Module Architecture​

Components​

Key Properties​

Data Flow: Season Lifecycle​

When to Use This Module​