Deathwalker

A cooperative zombie RPG turn-based board game running on Board Game Arena (BGA).

Project Status: Early Development (template-based start)

Game Overview

Deathwalker is a cooperative board game inspired by pen & paper RPGs like Dungeons & Dragons. Players work together to survive zombie outbreaks in a post-apocalyptic world. The game features:

• 2-4 players (configurable, with potential for 6)
• 30-60 minute missions
• Easy-to-learn rules with RPG elements
• Theme: Post-apocalyptic zombie survival

Project Structure

deathwalker/                  # Root synced to BGA Studio via SFTP
├── _ide_helper.php           # PHP IDE type hints (local only, not synced)
├── bga-framework.d.ts        # TypeScript definitions (local only, not synced)
├── gameinfos.inc.php         # Game metadata (name, players, duration, colors)
├── dbmodel.sql               # Database schema extensions
├── gameoptions.json          # Game options configuration (empty = defaults)
├── gamepreferences.json      # Player preferences (empty = defaults)
├── stats.json                # Statistics configuration (empty = defaults)
├── deathwalker.css           # Game UI styling
├── modules/
│   ├── php/
│   │   ├── Game.php          # Main game logic
│   │   └── States/           # State machine implementations
│   │       ├── PlayerTurn.php
│   │       ├── NextPlayer.php
│   │       └── EndScore.php
│   └── js/                   # Compiled output (generated from src/)
│       └── Game.js           # Frontend game UI (built from TypeScript)
├── src/                      # TypeScript source files
│   ├── Game.ts               # Main UI controller
│   ├── PlayerTurn.ts         # PlayerTurn state handler
│   └── types.d.ts            # TypeScript type definitions
├── img/                      # Game artwork (not committed to git)
├── misc/                     # Dev notes (local only, not synced to BGA)
├── docs/                     # Game documentation
│   └── README.md             # Game ruleset concept
└── node_modules/             # Development dependencies (local only)

.vscode/
└── sftp.json                 # FTP sync config (not synced to BGA)

Architecture

Backend (PHP)

The PHP backend uses the new BGA Framework architecture with:

• Game.php - Main game class extending \Bga\GameFramework\Table

  • Global variables, player counters, card types
  • setupNewGame() - Initialize game state
  • getAllDatas() - Return data visible to current player
  • upgradeTableDb() - Database migrations

• State Classes - Each game state is a class in modules/php/States/

  • Extend \Bga\GameFramework\States\GameState
  • Use #[PossibleAction] attributes for player actions
  • Return next state class or state ID at the end of actions
  • Support zombie mode for disconnected players

Frontend (TypeScript → JavaScript)

The UI code is written in TypeScript in src/ and compiled to modules/js/:

• src/Game.ts - Main UI controller

  • setup() - Initialize game interface from gamedatas
  • setupNotifications() - Handle server notifications
  • movePlayerToken() - Update player position on board

• State Classes (e.g., src/PlayerTurn.ts)

  • onEnteringState() - UI setup when entering state
  • onLeavingState() - Cleanup when leaving state
  • onPlayerActivationChange() - Handle active player changes

Build Process:

src/Game.ts ──(tsc)──> modules/js/Game.js

Communication Pattern

1. Player clicks button → JS calls bga.actions.performAction("actionName", args)
2. PHP validates and processes → returns next state
3. PHP sends notifications via $this->bga->notify->all() or notifyPlayer()
4. JS handles notifications via notif_* methods

Development Workflow

Prerequisites

• BGA Studio account (for testing on the platform)
• Local PHP 8.x environment (for syntax checking)
• Node.js (for TypeScript compilation and code formatting)
• VS Code with SFTP extension (for syncing to BGA)

Deployment: Local Git + BGA FTP Sync

This project uses a dual versioning workflow:

┌─────────────────┐     git commit      ┌─────────────────┐
│   Local Git     │ ──────────────────> │  Local Backup   │
│   Repository    │                     │  (GitHub/etc)   │
└─────────────────┘                     └─────────────────┘
        │
        │ VS Code SFTP
        │ (auto-sync on save)
        ▼
┌─────────────────┐                    ┌─────────────────┐
│  BGA Studio     │ <─── SVN ────────  │  BGA SVN        │
│  (FTP upload)   │                    │  (production)   │
└─────────────────┘                    └─────────────────┘

Important: The .vscode/sftp.json configures automatic upload to BGA on save, but excludes several files and folders.

Deployment Steps

1. Code locally with git for version control
2. Save files - SFTP automatically syncs to studio.boardgamearena.com:/deathwalker/
3. Test on BGA Studio - Use the Studio sandbox to playtest
4. BGA handles SVN - Their system commits to their version control

Note: The misc/ folder contains development notes and is excluded from BGA sync. Keep your working notes there.

Building TypeScript

npm run build     # Compile TypeScript to modules/js/
npm run watch     # Watch mode for development

Code Formatting

The project uses Prettier with PHP plugin:

npm run format    # Format all PHP files

Running on BGA Studio

1. Zip the project directory
2. Upload to BGA Studio
3. Test in the Studio sandbox environment
4. Use the Debug panel to jump to specific states

Key Development Links

• BGA Studio Cookbook ⭐ Common patterns & recipes
• BGA Developer Documentation - Full documentation index
• Game States & Game Logic
• Notifications
• Database Schema
• Game UI
• Zombie Mode

Framework Components (Available)

The BGA framework provides many components. See _ide_helper.php and bga-framework.d.ts:

• Counters - PlayerCounter, TableCounter for tracking values
• Deck - Card deck management
• Notifications - notify->all(), notifyPlayer() with i18n support
• Player Management - activeNextPlayer(), giveExtraTime()
• Scoring - playerScore->inc(), etc.

License

See LICENCE_BGA for Board Game Arena licensing terms.