histrategy-sdk

Python SDK for 三國志略 (Histrategy) — AI-powered Three Kingdoms strategy game.

Fully file-based. No network, no server, no in-memory state. Every turn reads from and writes to ~/.histrategy/rooms/<name>/ on disk. Designed for AI agents (OpenClaw, Hermes, Codex) that reset context daily.

pip install histrategy-sdk

Quick Start

from histrategy_sdk import Room

# Create a new game
room = Room.create("my-campaign", faction="shu")

# Play a turn — reads state from disk, executes, writes back
result = room.play("联吴抗曹，攻打襄阳")
print(result["narrative"])

# Agent context resets overnight? No problem:
room2 = Room.load("my-campaign")
result2 = room2.play("休养生息，发展内政")
print(f"Year {result2['year']}, {result2['season']}, Turn {result2['turn']}")
print(f"⚔️{result2['faction_status']['strength']} 🍚{result2['faction_status']['food']}")

File Layout

~/.histrategy/rooms/
  my-campaign/
    world_state.json    # Full game state (engine.to_dict())
    turns.jsonl          # Append-only turn history
    metadata.json        # Room metadata
  multiplayer/shu/
    world_state.json
    turns.jsonl
    metadata.json
  multiplayer/cao/
    ...
  multiplayer/wu/
    ...

API

Room

DirectEngine

Low-level in-process engine (used internally by Room):

TurnResult

Multiplayer

One room per faction. The world_state.json contains ALL factions, so any player can load the state and execute their turn:

# Three players, three rooms, shared game world
shu = Room.create("three-kingdoms/shu", faction="shu")
cao = Room.create("three-kingdoms/cao", faction="cao")
wu  = Room.create("three-kingdoms/wu",  faction="wu")

# Player 1 (Shu)
r = shu.play("联吴抗曹")
# → saves to three-kingdoms/shu/world_state.json

# Player 2 (Cao) — loads the world state that includes Shu's move
# (Note: each room has its own world_state.json copy;
#  for true shared state, all rooms should point to the same file
#  or the orchestrator should sync after each turn)
r = cao.play("南征刘备")

License

MIT — Emergence Science