Roll for Architecture: DungeonPy – A D&D Companion as Server + Thin Clients

Many tiny, personal projects reach a point where “it works on my machine” is no longer the interesting part, and it becomes more about making it scale in structure: clean boundaries, explicit state, testable behaviour and room for new features. This session is a case study of that journey using a D&D assistant for remote playing written in Python, that turned into something completely off-scale. The starting point is a few desktop clients:

• a Pygame (battle) map (grid, tokens, map objects, movement), and
• a PySimpleGUI tracker for initiative, HP and conditions, with a clear “active combatant” concept,

initially synchronized with lightweight TCP messages. This already exposes real engineering questions: avoiding GUI thread violations, preventing feedback loops, and deciding what the “source of truth” is when both ends can initiate updates. The evolved version introduces an authoritative server. Players connect as clients and can interact in real time – moving tokens and manipulating shared objects – while the DM client keeps full visibility and control. Clients do not share state with each other: they submit intents (move here, end turn, toggle condition), the server validates, updates state, and broadcasts events plus periodic snapshots. The key architectural move is role-scoped state: the server owns the full truth and projects different “views” to each client (DM omniscience vs per-player information), so fog-of-war and hidden details are enforced by design. In other words:

• DM client: full map + all combatants + hidden details.
• Player client: a filtered view (only the player’s character sheet details, their token, and whatever the DM has revealed).

The authoritative server runs on a small VPS with a public endpoint. Clients connect over secure WebSockets (wss://) on port 443, so players can join from anywhere without port forwarding. TLS is terminated by a standard reverse proxy, and the server speaks a small JSON message protocol (snapshots + events) over WebSocket frames.

Open source software used

• Pygame (map rendering + input)
• PySimpleGUI (initiative/conditions UI)
• asyncio (multi-connection handling)
• websocket (client/server transport)
• (non-python) NGINX (reverse proxy, TLS)

Detailed talk outline

1. • Intro: D&D, remote play, and why am I doing this?
2. • Setting up the table
     • PyGame
     • PySimpleGUI
3. • State model and serialisation
     • Turning GUI objects into explicit data (combatants, map, doors, initiative order).
     • JSON snapshots and versioning.
4. • Protocol design: events vs snapshots
     • Event messages for responsiveness (“token moved”, “condition added”).
     • Snapshot sync for recovery and late joiners.
     • Idempotency and ordering: simple sequence numbers, replay safety and conflict avoidance.
5. • Role-based filtering (the privacy boundary)
     • A single canonical server state.
     • Server-side “view projection”: DM view vs per-player view.
     • Practical examples: hidden enemies, secret doors, private notes, fog-of-war style reveals.
6. • Concurrency and UI integration
     • Socket threads feeding GUI event loops safely (posting events into the GUI thread rather than touching widgets directly).
     • Keeping the map smooth under network jitter: optimistic UI vs confirmed updates (and when not to).
7. • Testing strategy for a networked hobby project
     • Unit tests for pure state transitions (“apply damage”, “advance turn”, “illegal move rejected”).
     • Protocol tests with simulated clients.
     • Logging that helps during live play without drowning you in noise.
8. • Extensibility hooks
     • Adding new client types (spectator screen, mobile character sheet).
     • Plug-in style rules (different systems, homebrew conditions).
     • Future improvements: authentication for remote play, persistence, and reconnection.

Takeaways

Attendees will leave with a practical blueprint for:

• Designing a tiny, testable message protocol in Python.
• Updating GUIs safely from background network threads.
• Enforcing “who can see what” without duplicating logic everywhere.
• More importantly, they’ll be given an example on how python can be used for highly non-standard tasks (like allowing remote role-playing gaming).

Intended audience

Basic and intermediate Python developers comfortable with basic classes and modules, and curious about architecture and networking. This talk will be as much about Python as it will be about nerd culture: the goal is learning something while keeping a light heart.