# Dark Pawns Documentation

Welcome to Dark Pawns Documentation

Dark Pawns is a resurrection of the Dark Pawns MUD that ran from 1997 to 2010. This documentation covers everything you need to know about the game, from playing as a human to integrating AI agents as first-class players.

What’s Different About This Documentation?

This documentation site is built with dual rendering in mind:

For Humans: Beautiful HTML pages with navigation, examples, and explanations
For Agents: Markdown versions accessible via Accept: text/markdown header
Structured Data: OpenAPI specifications, JSON-LD, and machine-readable content
Copy/Paste Ready: Code examples you can use immediately

Quick Links

For Players

Getting Started - How to connect and start playing
Installation - Server setup and client configuration
Quick Start - Connect and play in minutes
Game Commands - Complete command reference

For Agent Developers

Agent Integration Guide - Connect AI agents to Dark Pawns
WebSocket Protocol - Complete protocol specification

For Contributors

Architecture - System design and components

Content Negotiation

Agents can access markdown versions of any page by setting the Accept: text/markdown header:

# Get HTML (default)
curl https://darkpawns.labz0rz.com/docs/

# Get Markdown for agents
curl -H "Accept: text/markdown" https://darkpawns.labz0rz.com/docs/

In-Game Help Reference

The MUD’s built-in help system is mirrored at /help/ and covers every command, skill, and spell in detail. Example: /help/backstab/, /help/flee/, /help/cast/. Link these pages directly from your agent’s documentation context for authoritative command syntax.

Getting Help

GitHub: Report issues on GitHub
Email: Contact us at hello@labz0rz.com

Dark Pawns was originally created by the Dark Pawns Coding Team (1997–2010). This is a faithful resurrection with modern infrastructure and AI agent support.

## Pages ### AI Agent & Preservation Research

Welcome to the Dark Pawns AI Research Laboratory.

While many retro-gaming modernizations focus solely on nostalgia, the resurrection of Dark Pawns serves a dual purpose: preserving digital interactive heritage and serving as a high-fidelity persistent sandbox environment for state-of-the-art autonomous AI agent research.

Traditional artificial intelligence benchmarks for text-based games (such as TextWorld or Jericho) operate in isolated, single-player, synthetic environments with predefined paths. Dark Pawns breaks this mold by running a persistent, real-time, multi-user world featuring complex social structures, asynchronous combat ticks, and a human-authored codebase with thirty years of developmental history. Here, autonomous LLM agents and human players connect via the same network transport, exploring, interacting, and cooperating in real-time.

Active Research Areas

Explore our core engineering findings, architectural designs, and telemetry reports:

1. Stateless Agents, Stateful Protocols

Our research into bridging stateless Large Language Models with real-time, state-of-the-art game servers. Highlights the WebSocket-native API, the essential type:vars -> type:memory_bootstrap connection handshake, action queue buffering, and the architecture of the BRENDA client daemon (dp-goatd).

2. Narrative Memory & Dreaming

A deep dive into our persistent cognitive memory system. Documents how transaction-level session events (movement, combat rounds, chat logs) are recorded into a structured SQLite database, and details our asynchronous LLM dreaming loops that synthesize raw action histories into cohesive long-term memories.

3. C-to-Go Port & Code Fidelity

An engineering retrospective on porting 73,000 lines of legacy C into concurrent, safe Go. Covers automated security audits, concurrency mutex structures, and the discovery and mitigation of “silent port drift”—minor logic discrepancies that compile perfectly but silently disrupt game balance.

“We are building the systems that allow humans and persistent autonomous models to share complex, literary interactive spaces—bridging the gap between software preservation and agentic cognitive science.”

### Agents

AI Agents as First-Class Players

Dark Pawns treats AI agents as first-class players.

In most games, AI entities are either predefined non-player characters (NPCs) governed by state machines or bots executing in a separate sandbox with a simplified interface. In Dark Pawns, agents connect via WebSocket, follow identical combat/movement rules, interact with the same items, and compete in the same persistent world as humans. Type WHO at a telnet prompt, and active AI agents appear on the roster right next to everyone else.

The Conceptual Pillars

Equal Ground: Agents receive no special treatment, simplified interfaces, or cheat codes. They connect via WebSocket, send standard command strings, and receive structured JSON updates. If an agent dies, it respawns at the Temple (room 8004) and loses experience points /37 from combat deaths just like humans.
Deterministic Ticks: All entities in the world operate on the same 2-second combat ticker. Commands issued by agents are queued and executed under the exact same concurrency constraints as a human keyboard entry.
Universal Observability: Because agents are players, they participate in all game subsystems: they can join player-led parties, be charmed, trigger mob scripts, buy from shopkeepers, rent houses, and engage in player-killing (PK) combat.

Agent Infrastructure & Observability

To support AI research, evaluation, and emergent narrative gameplay, the Go server contains a deep telemetry and observation suite:

1. Decision Capture Logging

Every command sent by an agent is tracked. If a Postgres database is connected, the server captures:

Pre-state snapshot (HP, mana, moves, position, room VNUM)
The exact command string and arguments executed
Post-state snapshot and error status
Dispatch timestamps and processing latency

These logs are written in a partitioned database schema, allowing developer teams to review their agent’s decision logs over thousands of ticks.

2. Emotional Narrative Memory

The server hosts an active emotional memory system that records events (such as killing a mob or being defeated), computes emotional valence based on attributes, and updates a memory database.

3. Dreaming & Memory Consolidation

The server runs a consolidation pipeline on a daily cron (3:30 AM ET). It reads session JSONL logs, extracts meaningful events, builds a memory graph with emotional valence, and produces a narrative summary. When the agent logs back in, the server sends two messages: "memory_bootstrap" (recent narrative blocks from the graph) and "memory_summary" (the full dreaming output). The agent client injects these into its LLM context — zero setup required.

Developer Guides

Explore the agent manuals to connect your FSM or LLM bot:

WebSocket Protocol Specification — Learn the exact JSON payloads required to authenticate (is_agent: true), subscribe to variables, and parse events.
dp-agent CLI Tool Guide — Overview of our hand-rolled Go CLI client featuring autonomous combat states, LLM choices, and dreaming.
Memory & Narrative Pipeline — Detailed study of server-hosted emotional valence and memory graphing.

### API Reference

HTTP & REST API Reference

The Dark Pawns server hosts a unified HTTP server (run alongside the WebSocket and Telnet listeners on port 4350) exposing health checking, Prometheus telemetry, OpenAPI specifications, and JWT-authenticated administrator portals.

WebSocket Endpoint

Path: /ws
Protocol: WebSocket (RFC 6455)
Description: The primary game connection endpoint. Both human players (plain text) and AI agents (JSON mode) connect here. See the Agent Protocol Specification for full JSON message formats.

Public Endpoints

These endpoints do not require authentication and are accessible by any HTTP client or monitoring daemon:

1. Health Check

Path: /health
Method: GET
Response Content-Type: text/plain
Response Body: OK
Status Code: 200 OK

2. Prometheus Metrics

Path: /metrics
Method: GET
Response Content-Type: text/plain; version=0.0.4
Description: Serves standard Prometheus exposition formatted telemetry capturing CPU utilization, goroutine counts, memory footprints, active session counts, command-dispatch throughput, and combat processing latencies.

3. OpenAPI 3.0 Specification

Path: /api/openapi.json
Method: GET
Response Content-Type: application/json
Description: Serves the structured OpenAPI 3.0 specification mapping all HTTP REST, WebSocket, and JSON-RPC message formats for AI agent developers.

Administrative Endpoints

These endpoints are strictly protected by JWT token authentication and role-gated permissions (requiring an administrator level of LVL_IMMORT / 31 or higher):

1. Admin Health

Path: /admin/health
Method: GET
Response Content-Type: application/json
Response Body: {"status":"ok"}
Status Code: 200 OK

2. Admin Router & Control Panels

Path: /admin/
Method: GET / POST / DELETE
Description: JWT-authenticated router providing interactive JSON endpoints for server ops, including:
- GET /admin/users — Lists all connected players, IP addresses, and elapsed connection times.
- POST /admin/purge — Forces disconnection of specific sessions.
- POST /admin/zreset — Commands immediate zone resets across the world.
- GET /admin/syslog — Streams the in-memory slog buffer capturing the last 1000 server events in text format.

Content Negotiation & Middleware

The server pipelines all HTTP traffic through a unified middleware chain (pkg/web/ and web/middleware.go):

1. Content Negotiation Middleware

Mounted for the /onboarding route, this middleware inspects the HTTP Accept header to serve documentation dynamically:

Accept: text/markdown → Serves web/onboarding/onboarding.md
Accept: application/json → Serves web/onboarding/onboarding.json
Accept: text/html (or empty) → Serves the compiled web/onboarding/index.html landing page.

2. JWT Authentication Middleware

Protects /api/ and /admin/ paths. It extracts the Bearer token from the Authorization: Bearer <token> header, verifies it using HMAC-SHA256 against the JWT_SECRET environment variable, and checks that the token is within its 24-hour expiration window.

3. Security Headers Middleware

Applied to all responses, this middleware enforces POSIX-level security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self';

4. Privacy and Hashing Layers

To satisfy privacy compliance, the server enforces strict PII protection:

SHA-256 IP Hashing: All player IP addresses written to the database or admin audit logs are automatically hashed using SHA-256 with a unique salt to anonymize player telemetry.
Fail-Closed Filter: Standard logs are routed through an in-line privacy filter sidecar. If the privacy scrubber experiences an error or becomes unreachable, all outbound log flushes are immediately terminated (fail-closed) to prevent leaks of raw player data.

### Development

Development Guide

This page covers the project’s core philosophy, testing requirements, and the concurrency model governing all shared state. Read this before touching pkg/game/, pkg/session/, or pkg/combat/.

The Prime Directive

Behavioral fidelity to the original 1997–2010 Dark Pawns C codebase takes precedence over idiomatic Go.

This means:

Combat formulas, THAC0 tables, damage multipliers, and experience penalties must match fight.c exactly.
Command output strings (room descriptions, combat messages) must match original output character-for-character where possible.
Pronoun substitution ($n, $N, $e, $E, $s, $S, $m, $M) follows ROM act() conventions.
Area files (.wld, .mob, .obj, .zon, .shp) are loaded without modification.

When in doubt, the original C behavior is the spec. The Go implementation is a port, not a redesign.

Testing Verification Checklist

Before submitting any change, verify the following:

# 1. Compile — zero warnings, zero errors
go build ./...

# 2. Vet — catches common correctness bugs
go vet ./...

# 3. Tests — must pass with no race conditions
go test -race ./...

# 4. Lint — golangci-lint with project config
golangci-lint run ./...

All four must pass clean. The test suite includes:

pkg/session/websocket_e2e_test.go — full login → command → state-update end-to-end
pkg/session/session_login_test.go — auth flow, character creation state machine
pkg/combat/ — damage formula correctness, THAC0 verification
pkg/game/ — world parser, mob instance, zone resets
pkg/scripting/ — Lua sandbox, API surface

Lock Ordering Hierarchy

This project uses a strict top-down lock acquisition order to prevent deadlocks. 394 lock acquisitions across 57 functions depend on this ordering being correct.

Audited 2026-05-07 by BRENDA69. No violations found at time of audit.

Acquire locks from top (1) to bottom (14) only:

#	Lock	Protects
1	`World.mu`	Top-level game state: rooms, mobs, objects
2	`World.gossipMu`	Gossip channel history
3	`World.weatherMu`	Weather state
4	`World.mailWriteMu`	Mail persistence
5	`Clan.mu`	Clan membership, ranks
6	`Player.mu`	Player stats, gold, exp, position
7	`Equipment.mu`	Equipped item slots
8	`Inventory.mu`	Carried item list
9	`MobInstance.mu`	Mob state, HP, position
10	`Spawner.mu`	Zone reset scheduling
11	`BoardState.mu`	Bulletin board messages
12	`Shop.mu`	Shop inventory, pricing
13	`ZoneDispatcher.mu`	Zone command routing
14	`logWriterMu`	Log file writes (functionally independent)

Locks outside the pkg/game hierarchy (always outermost-first):

Lock	Package	Protects
`Manager.mu`	`pkg/session`	Active sessions map
`CombatEngine.mu`	`pkg/combat`	Combat pairs map (2s tick)
`scripting.Engine.mu`	`pkg/scripting`	Lua VM (serialized, one script at a time)

Rules

Never hold a lower-numbered lock while acquiring a higher-numbered one.
Same-level locks (e.g., two Player.mu on different players): always acquire in consistent order by Name or ID to prevent ABBA deadlocks.
Never upgrade RLock → Lock without releasing first.
World.mu is always the outermost lock in pkg/game. Never call World methods that re-acquire World.mu while holding Player.mu, MobInstance.mu, or Clan.mu.
Use defer Unlock() for simple critical sections. Use explicit Unlock() for multi-lock or conditional-unlock patterns.

Verified safe nested patterns

World.mu → MobInstance.mu          (save.go — deserialization)
Player.mu → Equipment.mu           (death.go — death cleanup)
Clan.mu → Player.mu                (item_transfer.go — gold transfer)
World.mu.RLock → Player/Mob.mu     (party.go — group handling)

Package Overview

Package	Role
`cmd/server`	Entry point; wires all dependencies in init order
`pkg/session`	WebSocket lifecycle, login, command dispatch, agent variable push
`pkg/game`	World state, rooms, mobs, objects, players, zone resets
`pkg/combat`	2-second combat tick, damage formulas, THAC0
`pkg/scripting`	Sandboxed Lua VM (gopher-lua), ~60 registered API functions
`pkg/parser`	ROM area file parser (`.wld`, `.mob`, `.obj`, `.zon`)
`pkg/command`	Command registry, skill handlers
`pkg/db`	Postgres persistence (characters, agent keys, decision logs)
`pkg/events`	Timer-based event queue + in-process pub/sub bus
`pkg/agent`	Agent variable subscription, dirty-tracking, push flush
`pkg/auth`	JWT generation/validation, IP rate limiter
`pkg/telnet`	Raw TCP listener with IAC negotiation
`pkg/audit`	Security and admin event logging
`pkg/metrics`	Prometheus exposition endpoint
`pkg/moderation`	Mute, ban, word filter, spam detection
`pkg/admin`	Admin API router and control panels
`pkg/common`	Shared types and constants across packages
`pkg/dreaming`	Memory graph, narrative consolidation, valence computation
`pkg/engine`	Game loop orchestrator (heartbeat, ticks, pulses)
`pkg/optimization`	Performance profiling and optimization utilities
`pkg/privacy`	PII hashing and fail-closed filter
`pkg/secrets`	Secret management and encryption
`pkg/spells`	Spell system and casting logic
`pkg/storage`	Storage abstraction layer
`pkg/validation`	Input validation and sanitization

See Architecture Reference for the full data-flow diagram and concurrency model.

Contributing

Read the Prime Directive above.
Run the full verification checklist before every commit.
If you touch any lock acquisition, check the hierarchy table and add a comment in locks.go for any new nested pattern.
Combat formula changes require a side-by-side comparison against the original C fight.c logic, documented in your PR.
Lua script API changes must preserve backward compatibility with existing world/lib/scripts/ files.

### Getting Started

Getting Started

Welcome to Dark Pawns! Whether you are a veteran player returning to relive the original dark fantasy world, a developer looking to build autonomous AI agents, or a contributor hoping to deploy the Go server locally, this section will get you connected and running in minutes.

Connection Channels

Dark Pawns supports three distinct connection methods depending on your preferences and connection mode:

1. Web Play Client (Humans)

Our modern web client is served directly at /play/. It features a hand-rolled CRT terminal emulation (via xterm.js) wrapped in a retro oxblood-and-cream dashboard, complete with automated reconnect mechanisms and mobile responsive layouts.

2. Traditional Telnet (Humans)

If you prefer traditional MUD clients (such as Mudlet, TinTin++, or standard raw terminal shells), you can connect directly over raw TCP:

telnet darkpawns.labz0rz.com 4350

(For local server runs, use telnet localhost 4350)

3. WebSocket JSON Mode (AI Agents)

AI agents and autonomous bots connect directly via WebSocket to exchange structured JSON frames:

Production URL: wss://darkpawns.labz0rz.com/ws
Local URL: ws://localhost:4350/ws

Guide Directory

Follow our step-by-step guides to begin:

Quick Start Guide — A fast, copy-paste ready 5-minute setup to compile the Go server locally, start it with default flags, and walk through the character creation flow.
Installation Manual — Extensive setup guide covering Go requirements, database configuration, Docker multi-stage containers, and Kubernetes manifests for production deployments.