桌面游戏AI

3. Install Python dependencies (display companion only)

The core scripts have no dependencies. The optional display companion requires:

cd display
pip3 install -r requirements.txt

Setup

1. Install OpenCode

opencode.ai — supports Anthropic, OpenAI, Google, Ollama, LM Studio, and any OpenAI-compatible endpoint.

Quick Start

Improvised campaign — GM generates world and narrative arc:

/gm new my-campaign          # generates world, factions, NPCs, optional story arc
/gm character new            # create a character
/gm load my-campaign         # start a session

Structured campaign — import a pre-written module:

/gm import module.pdf my-campaign   # extract structure and build campaign files
/gm load my-campaign                # start a session — GM enforces the arc beats

Once loaded, type naturally — no /gm prefix needed. The GM interprets all input as in-game action.

---

4. Configure OpenCode

Point OpenCode at this skill by adding the following to your OpenCode config (~/.config/opencode/opencode.json):

{
  "instructions": [
    "/path/to/open-tabletop-gm/no_think.md",
    "/path/to/open-tabletop-gm/paths.md",
    "/path/to/open-tabletop-gm/SKILL-commands.md",
    "/path/to/open-tabletop-gm/SKILL-branches.md"
  ]
}

SKILL.md (the GM persona) is not loaded at startup — it is read from disk the first time a session is loaded, keeping the standing system prompt lean (~2,300 tokens). See docs/LLM-GUIDE.md for why this matters on smaller models.

For a local model via LM Studio, add your provider config:

{
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://localhost:1234/v1"
      },
      "models": {
        "your-model-id": {
          "name": "Your Model Name"
        }
      }
    }
  }
}

Viewing options

TLS / HTTPS (optional)

HTTP is the default. Use --tls only on public or untrusted networks. When passed: - A self-signed cert is auto-generated if cert.pem is not present - A plain HTTP server starts on :8080 to serve cert.pem for download - Per-platform install instructions are printed to the terminal (iOS, Android, Mac)

For iOS: open http://<your-ip>:8080/cert.pem in Safari → tap Allow → Settings → General → VPN & Device Management → install profile → Certificate Trust Settings → enable full trust.

System plugin architecture

The framework is split into two layers:

SKILL.md                    ← GM core: pacing, NPCs, improvisation, world craft
                               Never changes. Works for any game.

systems/<your-system>/
  system.md                 ← Your game's rules: dice, stats, health, resources
                               Loaded alongside SKILL.md at session start.

SKILL.md contains everything about being a good GM. system.md contains everything about your specific game. The GM model reads both at session start — it brings the craft, your system module brings the rules.

D&D 5e ships as the reference implementation. It demonstrates what a complete system module looks like: dice conventions, ability scores, spell slots, conditions, death saves, SRD lookup, and character scripts.

Building a new system module takes one file to start — a filled-in systems/TEMPLATE.md for your game. You can start with just dice resolution and health, play a session, then iterate. Full porting guide: SYSTEM-PORTING.md.

---