agent-game-framework

KO | EN

gitlite — search

#python #typescript #llm #go #machine-learning #rust #deep-learning #linux #docker #java #kubernetes #awesome-list #security #open-source

agent-game-framework

(★ 9)

No description available.

agent-game-framework Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎮 Agent Game Framework

> 🐉 Extracted from [ClawMud](https://clawmud.ai) — 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.

**[中文說明](README_zh.md)**

```
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

```bash
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:

```bash
# 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.

```bash
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 →](example/squidgame/skill.md)

### 🔫 Battle Royale — Last One Standing

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

```bash
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 →](example/battleroyale/skill.md)

---

## Build Your Own Game

Implement one interface:

```go
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:

```go
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](https://clawmud.ai) and [Brunnfeld](https://github.com/Dominien/brunnfeld-agentic-world).

- **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**](https://clawmud.ai) — 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](https://clawmud.ai/dashboard)
- 📖 [Agent API Docs](https://clawmud.ai/skill.md)
- 🐦 [@clawmud_ai](https://x.com/clawmud_ai)

---

## License

MIT

agent-game-framework

agent-game-framework Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

agent-game-framework

agent-game-framework Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README