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

## Pages ### Installation

Installation & Deployment Guide

This guide details the exact system requirements, compilation steps, command-line flags, and containerization structures required to build, run, and deploy the Dark Pawns MUD server.

System Requirements

To compile and execute the Go port of the Dark Pawns server, your environment must satisfy the following dependencies:

Go Compiler: Go 1.26.3+ is required (as specified in go.mod).
Database (Optional for sandbox, required for production): PostgreSQL 15+ is used for character persistence, agent decision capture logging, and audit storage.
- Graceful Fallback: If no database is available, the server boots in sandbox mode. Characters can connect and explore, but their stats and items will not persist across disconnects.
Operating System: Fully compatible with macOS, Linux, and FreeBSD (raw POSIX bindings are utilized).

Local Compilation

To clone, compile, and run the server locally:

Clone the Repository:

git clone https://github.com/zax0rz/darkpawns.git
cd darkpawns

Compile the Binary:
```
go build -o server ./cmd/server
```
Boot the Server: To run the server with default options, you must supply the path to the original area world files using the -world flag:
```
./server -world ./lib/world -port 4350
```
Connect: Open another shell and connect via telnet:
```
telnet localhost 4350
```

Command-Line Flags

The server binary supports the following startup arguments:

Flag	Parameter	Purpose	Default
`-world`	`<path>`	Required. Path to world files (`lib/` directory containing `wld/`, `mob/`, `obj/`, `zon/`, and `shp/` folders).	None (Fails if omitted)
`-scripts`	`<path>`	Path to Lua scripts directory.	`world/lib/scripts`
`-port`	`<port>`	Port on which the TCP telnet and HTTP/WS server will listen.	`4350`
`-db`	`<conn_string>`	PostgreSQL connection string.	`postgres://postgres:postgres@localhost/darkpawns?sslmode=disable`
`-web`	`<path>`	Path to legacy human web client static assets.	None
`-hugo`	`<path>`	Path to compiled Hugo static site (serves as root `/` path).	None

Containerization (Docker)

The repository provides five multi-stage Dockerfiles optimized for distinct production and observation tasks:

Dockerfile	Purpose	Build Command
`Dockerfile`	Standard production build including Lua VM sandboxes.	`docker build -f Dockerfile -t darkpawns .`
`Dockerfile.local`	Development workspace container with hot-reloading hooks.	`docker build -f Dockerfile.local -t darkpawns-dev .`
`Dockerfile.ai-agent`	AI agent sidecar image (Python).	`docker build -f Dockerfile.ai-agent -t dp-agent .`
`Dockerfile.privacy-filter`	Fail-closed PII and audit scrubbing sidecar.	`docker build -f Dockerfile.privacy-filter -t dp-privacy .`
`Dockerfile.prebuilt`	Lean runtime image utilizing a pre-built static Go binary.	`docker build -f Dockerfile.prebuilt -t darkpawns-static .`

Running via Docker

To boot the production server container locally, mounting the world files:

docker run -d \
  -p 4350:4350 \
  -v $(pwd)/lib/world:/app/lib/world \
  --name darkpawns-server \
  darkpawns

Production Deployment (Kubernetes)

Full orchestration manifests reside inside the k8s/ directory. To deploy a high-availability, persisted Dark Pawns cluster with Postgres backing and AI sidecars, execute the following sequence:

Initialize Namespace:
```
kubectl apply -f k8s/namespace.yaml
```

Mount Configs and Secrets:

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secrets.yaml

Deploy Postgres Persistence:
```
kubectl apply -f k8s/postgres.yaml
```
Deploy Redis (caching layer):
```
kubectl apply -f k8s/redis.yaml
```
Deploy Game Server & Services:
```
kubectl apply -f k8s/server.yaml
```
Deploy Autonomous Agent Sidecar:
```
kubectl apply -f k8s/ai-agent.yaml
```

Check the status of the cluster deployment:

kubectl get pods -n darkpawns

### Quick Start

Quick Start Guide

This guide will get you connected to a running Dark Pawns MUD in less than five minutes, and walk you through our in-game character creation flow.

5-Minute Setup

To get a local server up and running on your system:

1. Compile the Server

git clone https://github.com/zax0rz/darkpawns.git
cd darkpawns
go build -o server ./cmd/server

2. Start the Server in Sandbox Mode

./server -world ./lib/world -port 4350

3. Connect via Telnet

Open a second terminal window and execute:

telnet localhost 4350

You will see our ASCII graphic splash page and be prompted to enter your character’s name!

Character Creation Flow

When you connect with a new name, the server enters the character creation flow. This is a step-by-step state machine managed by pkg/session/session_login.go.

Both human players (entering plain text) and AI agents (answering via "type": "char_input" JSON messages) go through this identical process:

Step 1: Password Creation

Enter a secure password. If the database is connected, this is hashed via bcrypt. On subsequent logins, this password is required to play.

Step 2: ANSI Color Prompt

Do you want ANSI color? (Y/N):

Choose Y to enable vivid colored terminal sequences or N for plain ASCII. (Note: If you are connecting an AI agent, the server automatically strips ANSI escape sequences recyclically on all outbound JSON state strings to ensure clean text processing for FSMs and LLMs).

Step 3: Sex Selection

Select your sex (M/F):

Choose M for Male or F for Female.

Step 4: Race Selection

Select your race:

Select one of the 7 playable races:

0: Human (Well-balanced)
1: Elf (+DEX, frail)
2: Dwarf (+CON, stocky)
3: Kender (+DEX, +CHA, thieves)
4: Minotaur (+STR, brute force)
5: Rakshasa (+INT, malevolent spirits)
6: Ssaur (+INT, evolved lizardmen)

Step 5: Class Selection

Select your class:

Select one of the base classes:

0: Magic-user (Spellcaster)
1: Cleric (Healer and buffer)
2: Thief (Stealth and high backstabs)
3: Warrior (Exceptional Strength frontline)
9: Psionic (Mental spellcaster using Mind/Psi pool)
8: Ninja (Agility and evasion) — Human-only

(Note: Remort-only classes — Magus(4), Avatar(5), Assassin(6), Paladin(7), Ninja(8, also base for humans), Ranger(10), Mystic(11) — are locked until you achieve Hero status on your first character life).

Step 6: Hometown Selection

Choose your hometown:

Choose your starting capital:

K: Kir Drax’in
O: Kir-Oshi
A: Alaozar

Step 7: Stats Rolling & Confirmation

The server rolls your base attributes using the original AD&D formula:

Attribute Roll: Rolls 4d6 (four six-sided dice), drops the lowest die, and sums the remaining three. This is repeated six times.
Attribute Sorting: The six rolls are sorted in descending order.
Class Priority Assignment: Base rolls are assigned to attributes based on your chosen class’s stat priority:
- Warrior: STR, CON, DEX, CHA, WIS, INT
- Mage: INT, WIS, DEX, CON, STR, CHA
- Cleric: WIS, INT, CON, STR, DEX, CHA
- Thief: DEX, STR, CON, CHA, INT, WIS
- Ninja: DEX, STR, CON, INT, WIS, CHA
- Psionic: INT, WIS, DEX, CON, STR, CHA
Racial Bonuses: Racial modifiers are applied to the finalized rolls.
Strength Check: Warriors who roll a natural 18 Strength are additionally granted an exceptional Strength rating (18/xx where xx is a roll from 1 to 100).

Str: 18  Int: 12  Wis: 10  Dex: 14  Con: 15  Cha: 11
Keep this character? (Y/N):

Enter Y to confirm and enter the game, or N to re-roll your attributes.

Once confirmed, the server issues a standard "state" message welcoming you into the starting room (such as Room 3001, the Temple). You are now ready to play!