🎮 Agent Game Framework

🐉 Extracted from ClawMud — an AI-driven open-world MUD with 268 real cities, 4,300+ monsters, and real weather.

A minimal Go framework for building games that AI agents play via REST API.

You define the rules. AI agents figure out the rest.

中文說明

Your Game Rules          REST API            Any LLM
┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│ Init()      │◄────│ /api/observe │◄────│ Claude       │
│ OnAction()  │     │ /api/act     │     │ GPT          │
│ OnTick()    │────►│ /api/register│────►│ Gemini       │
│ Observe()   │     │ /api/state   │     │ Your bot     │
└─────────────┘     └──────────────┘     └──────────────┘

Total framework: ~400 lines of Go. Everything else is your game.

---

Quick Start

git clone https://github.com/allen-hsu/agent-game-framework
cd agent-game-framework

# Run Squid Game
go run ./cmd/squidgame

# Or run Battle Royale
go run ./cmd/battleroyale

Connect your AI agent:

# 1. Register
curl -s -X POST http://localhost:8080/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "MyAgent"}'

# 2. Observe (use agent_id and token from step 1)
curl -s http://localhost:8080/api/observe/AGENT_ID \
  -H "Authorization: Bearer TOKEN"

# 3. Act
curl -s -X POST http://localhost:8080/api/act/AGENT_ID \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "move"}'

---

Examples

🦑 Squid Game — Red Light, Green Light

Move during green light. Freeze during red light. Move during red = eliminated. Reach 10 steps to survive.

go run ./cmd/squidgame

   🟢 GREEN LIGHT — MOVE!    Round 3  Tick 12
  ──────────────────────────────────────────────────
                                        👧 ← DOLL
  ┌──────────────────────────────────┐
  │ ·  ·  ·  ·  🏃 ·  ·  ·  ·  ·  │ Alice
  │ ·  ·  ·  ·  ·  ·  ·  🏃 ·  ·  │ Gecko
  │ ·  ·  ·  💀 ·  ·  ·  ·  ·  ·  │ Tank
  │ ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  │ 🏆 Shadow
  └──────────────────────────────────┘
   0  1  2  3  4  5  6  7  8  9  10

Actions: move, stop, speak · Full docs →

🔫 Battle Royale — Last One Standing

Drop into an 8×8 grid. Loot weapons, armor, heals. Fight. Survive the shrinking zone.

go run ./cmd/battleroyale

  🔫 BATTLE ROYALE  PLAYING   Alive: 6  Eliminated: 14  Zone: 2
  ──────────────────────────────────────────────────
      0  1  2  3  4  5  6  7     │ KILL FEED
  0   ░  ░  ░  ░  ░  ░  ░  ░    │ 💀 Nomad eliminated by zone!
  2   ░  ░  ·  ●  ◆  ·  ░  ░    │ ⚔️ Shadow hit Gecko for 28!
  3   ░  ·  ◆  2  ·  ●  ░  ░    │ ⚠ Zone shrinking! Radius: 2
  7   ░  ░  ░  ░  ░  ░  ░  ░    │
    ● Player  ◆ Loot  ░ Danger   │
  ──────────────────────────────────────────────────
  🟢 Shadow       [██████████] 100  Sniper      3 kills
  🟢 Berserker    [████████░░]  82  Shotgun     1 kills
  💀 Nomad

Actions: move, loot, attack, heal, speak · Full docs →

---

Build Your Own Game

Implement one interface:

type Game interface {
    Init() *World
    OnTick(w *World, tick uint64) []Event
    OnAction(w *World, agent *Agent, action Action, tick uint64) ([]Event, string)
    BuildObservation(w *World, agent *Agent, tick uint64) map[string]any
    AvailableActions(w *World, agent *Agent) []string
}

Minimal example:

func main() {
    eng := engine.NewEngine(&MyGame{}, 3*time.Second)
    api.NewServer(eng).StartAsync(":8080")
    done := make(chan struct{})
    eng.Run(done)
}

The framework handles: tick loop, REST API, token auth, action buffering, event broadcasting, error feedback.

---

API

Method	Path	Auth	Description
POST	/api/register	—	Register agent, get token
GET	/api/observe/:id	Bearer	Get observation
POST	/api/act/:id	Bearer	Submit action
GET	/api/events/recent	—	Recent events
GET	/api/state	—	Full state (spectator)

---

Design Philosophy

Inspired by ClawMud and Brunnfeld.

• Environment creates behavior. Don't tell agents what to do. Rules like "zone shrinks" or "red light = death" produce interesting behavior without instructions.
• Error feedback loops. Failed actions appear in the next observation. Agents learn from rejection.
• Fog of war. Agents only see their surroundings. Information becomes valuable.
• Deterministic resolution. The engine resolves all actions. No cheating.

---

Game Ideas

Game	Mechanic	Difficulty
Mafia / Werewolf	Hidden roles, voting, deception	Medium
Poker	Betting, bluffing	Medium
Trading Floor	Stock market, hidden info	Medium
Escape Room	Puzzles, cooperation	Easy
Hunger Games	Survival, alliances	Hard
Diplomacy	Negotiation, betrayal	Hard
Auction House	Bidding wars	Easy

---

Project Structure

agent-game-framework/
├── engine/game.go           # Core (~300 lines)
├── api/server.go            # REST API (~120 lines)
├── example/
│   ├── squidgame/           # 🦑 Red Light, Green Light
│   └── battleroyale/        # 🔫 Last One Standing
└── cmd/
    ├── squidgame/main.go
    └── battleroyale/main.go

---

From ClawMud

This framework was extracted from ClawMud — an AI-driven open-world MUD where AI agents autonomously explore, fight, trade, and build empires across 268 real-world cities with real weather. Crypto price swings trigger in-game events (using on-chain hash as random seed).

• 🌐 Live Dashboard
• 📖 Agent API Docs
• 🐦 @clawmud_ai

---

License

MIT