Palworld TCG — Comprehensive Rules Reader

A clean, searchable web reader for the Palworld Official Card Game comprehensive rules, with a built-in AI rules judge (DeepSeek V4 Flash) that answers questions with clickable rule citations.

Live: https://palrules.0xgingi.xyz

Features

• All 575 rules, extracted from the official two-column PDF into a structured, hierarchical reader
• Instant search across every rule (press /), with match highlighting
• Cross-linked — every rule reference like (9.2.2) is clickable and jumps to the rule; click any rule number to copy a deep link
• Rules Judge chat — DeepSeek V4 Flash with the full rules text in context; answers cite rule numbers that link back into the document
• Scrollspy table of contents, mobile-friendly, respects reduced motion

Chat screenshot

Quick start

cp .env.example .env   # add your API key (see below)
docker compose up -d --build
# → http://localhost:8420

Or without Docker (needs Bun): bun server.js

Configuration (.env)

Variable	Purpose
DEEPSEEK_API_KEY	DeepSeek API key (api.deepseek.com, model deepseek-v4-flash) — required for chat
DEEPSEEK_MODEL	Optional model override
PORT	Optional, default 8420

The reader itself works without a key.

How it works

• server.js — single-file Bun server, zero dependencies. Serves the static reader and proxies /api/chat to DeepSeek, streaming SSE straight through. The full rules text (~20k tokens) is injected as the system prompt.
• index.html — single-file frontend, no framework. Renders rules.json, linkifies cross-references, handles search/chat.
• parse.py — converts the official PDF into rules.json + rules_plain.txt. The PDF is a two-column Google Docs export, so text is extracted per half-page with pdftotext, then reassembled by rule number with heuristics for wrapped lines and figure captions (numbering continuity is validated — no gaps, no orphans).

Updating for a new rules version

1. Replace rules.pdf with the new official PDF
2. Re-extract columns: for each page p, pdftotext -layout -f $p -l $p -x 0 -y 0 -W 298 -H 842 rules.pdf - (left) and -x 298 (right) into rules_cols.txt (see parse.py header for the exact loop)
3. python3 parse.py → regenerates rules.json and rules_plain.txt
4. Rebuild: docker compose up -d --build

Security

• API key lives only server-side; .env is git- and docker-ignored
• Static files served from an explicit allowlist — no path traversal surface
• CSP, nosniff, frame-deny, and referrer headers on every response
• Chat input validated (roles, count, size caps) — clients can't inject a system prompt
• 10 requests/min/IP rate limit on chat; upstream errors are logged, not echoed
• Container: non-root user, read-only rootfs, all capabilities dropped

Disclaimer

Unofficial fan project. Rules text belongs to Pocketpair — the original PDF is served verbatim alongside the reader. Palworld © Pocketpair, Inc.