README

Flexible turn order tracking library for tabletop RPG combat systems

PHP Turn Tracker is a zero-dependency PHP library that provides robust turn order management for tabletop RPG combat encounters. It supports all major RPG systems through configurable timeline profiles, handling everything from D&D's individual initiative to Shadowrun's pass-based combat.

Features

• 🎲 Universal RPG Support: D&D all editions, Pathfinder, Shadowrun, GURPS, Savage Worlds, Genesys, Marvel Heroic, OSR, and more
• ⚡ Zero Dependencies: Pure PHP 8.1+ implementation using only stdlib
• 🔄 Multiple Turn Order Models: Round-based individual/side, pass-based with decay, slot-based, popcorn initiative
• 📊 State Tracking: Automatic tracking of acted/unacted actors per round/pass
• 🎯 Dynamic Management: Add reinforcements, remove defeated actors, change initiative mid-combat
• 🧪 100% Test Coverage: Comprehensive PHPUnit test suite with 90%+ coverage
• 📦 PSR-12 Compliant: Modern PHP coding standards

Installation

composer require codryn/phpturntracker

Requirements: PHP 8.1 or higher

Quick Start

Basic D&D-Style Combat

use Codryn\PhpTurnTracker\Encounter;
use Codryn\PhpTurnTracker\Actor;
use Codryn\PhpTurnTracker\TimelineProfile;
use Codryn\PhpTurnTracker\TurnOrderType;

// 1. Create a timeline profile for your RPG system
$profile = new TimelineProfile(
    type: TurnOrderType::ROUND_INDIVIDUAL,
    minInitiative: 1,
    maxInitiative: 30
);

// 2. Create an encounter
$encounter = new Encounter($profile);

// 3. Add participants
$encounter->addActor(new Actor('fighter', 'Conan', 18));
$encounter->addActor(new Actor('wizard', 'Gandalf', 15));
$encounter->addActor(new Actor('orc', 'Orc Warrior', 12));

// 4. Start combat
$encounter->start();

// 5. Run turns
while ($encounter->isActive()) {
    $current = $encounter->getCurrentActor();
    echo "It's {$current->getName()}'s turn! (Round {$encounter->getCurrentRound()})\n";
    
    // ... resolve actor's actions ...
    
    $encounter->advanceTurn();
}

Dynamic Combat Management

// Add reinforcements mid-combat
$encounter->addActor(new Actor('troll', 'Cave Troll', 20));

// Remove defeated enemies
$encounter->removeActor('orc');

// Handle delays
$encounter->delayActor('wizard', 10);  // Wizard delays to initiative 10

// Apply initiative modifiers
$encounter->changeInitiative('fighter', 25);  // Haste spell!

Supported RPG Systems

Configuration Examples

D&D 5e with Dexterity Tie-Breaker

$profile = new TimelineProfile(
    type: TurnOrderType::ROUND_INDIVIDUAL,
    minInitiative: 1,
    maxInitiative: 30,
    tieBreakerAttribute: 'dexterity'
);

$encounter->addActor(new Actor('ranger', 'Legolas', 18, ['dexterity' => 16]));
$encounter->addActor(new Actor('rogue', 'Garrett', 18, ['dexterity' => 14]));
// Legolas acts first (higher dexterity)

Shadowrun 4e Multi-Pass Combat

$profile = new TimelineProfile(
    type: TurnOrderType::PASS,
    passesPerRound: 4,
    decayEnabled: true,
    decayAmount: 10
);

$encounter->addActor(new Actor('sam', 'Street Samurai', 28));  // 3 passes
$encounter->addActor(new Actor('mage', 'Mage', 15));           // 2 passes
$encounter->addActor(new Actor('grunt', 'Grunt', 8));          // 1 pass

// Pass 1: sam(28), mage(15), grunt(8) all act
// Pass 2: sam(18), mage(5) act (decay -10)
// Pass 3: sam(8) acts
// Round 2: All reset to original initiative

Genesys Slot-Based Initiative

$profile = new TimelineProfile(
    type: TurnOrderType::SLOT,
    slotConfiguration: [
        ['type' => 'PC', 'initiative' => 3],
        ['type' => 'NPC', 'initiative' => 2],
        ['type' => 'PC', 'initiative' => 2],
        ['type' => 'NPC', 'initiative' => 1]
    ]
);

// Any PC can fill PC slots, any NPC can fill NPC slots
// Players choose which character acts in each slot

Popcorn Initiative (Marvel Heroic)

$profile = new TimelineProfile(
    type: TurnOrderType::POPCORN,
    allowRepeatPopcorn: false  // Can't designate someone who already acted
);

$encounter->start();
// Current actor designates who goes next
$encounter->designateNext('hero2');

OSR Side-Based Initiative

$profile = new TimelineProfile(
    type: TurnOrderType::ROUND_SIDE
);

$encounter->addActor(new Actor('fighter', 'Fighter', 15, ['side' => 'players']));
$encounter->addActor(new Actor('cleric', 'Cleric', 12, ['side' => 'players']));
$encounter->addActor(new Actor('goblin1', 'Goblin', 10, ['side' => 'monsters']));

// All players act, then all monsters act

State Tracking

// Check current round/pass
$round = $encounter->getCurrentRound();
$pass = $encounter->getCurrentPass();  // For pass-based systems

// Query actor status
$acted = $encounter->getActedActors();
$waiting = $encounter->getUnactedActors();

// Check if encounter is active
if ($encounter->isActive()) {
    // Combat ongoing
}

Documentation

• Quick Start Guide - Complete tutorial with examples
• API Documentation - Detailed API reference
• Examples - Complete code examples for each RPG system

Testing

# Run tests
composer test

# Generate coverage report
composer coverage

# Check code style
composer cs-check

# Fix code style
composer cs-fix

Requirements

• PHP 8.1 or higher
• No external dependencies (production)
• PHPUnit 10+ (development)
• php-cs-fixer 3+ (development)

Performance

• Encounters with 20 actors: Complete 10 rounds in <100ms
• State queries: <1ms response time
• Concurrent encounters: Multiple independent encounters without performance degradation

Architecture

The library uses the Strategy Pattern for turn order calculation:

• Encounter - Main coordinator class
• Actor - Represents a participant in combat
• TimelineProfile - Configuration for turn order rules
• TurnOrderInterface - Strategy interface for turn order models
• Strategies: RoundBasedIndividual, RoundBasedSide, PassBased, SlotBased, Popcorn

Contributing

Contributions are welcome! Please ensure:

• All tests pass (composer test)
• Code follows PSR-12 (composer cs-fix)
• Test coverage remains ≥90%
• PHPDoc comments on all public methods

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history.

Credits

Developed by Codryn

Need help? Check out the Quick Start Guide or open an issue on GitHub.