PHPackages codryn/phpturntracker - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. codryn/phpturntracker ActiveLibrary[Utility & Helpers](/categories/utility) codryn/phpturntracker ===================== Flexible turn order tracking library for tabletop RPG combat systems 0.2.1(4mo ago)06[1 issues](https://github.com/codryn/phpturntracker/issues)MITPHPPHP ^8.1CI passing Since Jan 9Pushed 4mo agoCompare [ Source](https://github.com/codryn/phpturntracker)[ Packagist](https://packagist.org/packages/codryn/phpturntracker)[ RSS](/packages/codryn-phpturntracker/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (4)Versions (5)Used By (0) PHPTurnTracker ============== [](#phpturntracker) [![PHP Version](https://camo.githubusercontent.com/27d7b4f926939f3cbfbdec4ee0bf45e33457aa351e1ceb3551eddc96c195e19d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312d2d382e352d626c75652e737667)](https://www.php.net/)[![PHPStan Level 10](https://camo.githubusercontent.com/d18b9a987aa81e64470a11caecf72caa66597c9ebd6b307bd1c2cb7a752b0dff/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c25323031302d627269676874677265656e2e737667)](https://phpstan.org/)[![CI](https://github.com/codryn/phpturntracker/workflows/CI/badge.svg)](https://github.com/codryn/phpturntracker/actions)[![Latest Stable Version](https://camo.githubusercontent.com/f920c4656bf9838d5991c260f88dfad6180c8377dbb85ee653406dd34b8e05f2/68747470733a2f2f706f7365722e707567782e6f72672f636f6472796e2f7068707475726e747261636b65722f762f737461626c65)](https://packagist.org/packages/codryn/phpturntracker)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE) > Flexible turn order tracking library for tabletop RPG combat systems **PHPTurnTracker** 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 -------- [](#features) - **๐ŸŽฒ Universal RPG Support**: D&D all editions, Pathfinder, Shadowrun, GURPS, Savage Worlds, Genesys, Marvel Heroic, OSR, and more - **๐Ÿ”„ 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 - **โ— Error Handling**: Clear, specific error messages with location information - **๐Ÿ”’ Type Safe**: Full PHP 8.1+ type declarations and strict mode - **โšก Zero Dependencies**: Pure PHP 8.1+ implementation using only stdlib and json extension - **๐Ÿงช Well Tested**: Unit tests with comprehensive coverage - **๐Ÿ“ฆ PSR-12 Compliant**: Modern PHP coding standards Requirements ------------ [](#requirements) - PHP 8.1 or higher - json PHP extension enabled Installation ------------ [](#installation) ``` composer require codryn/phpturntracker ``` Quick Start and Usage --------------------- [](#quick-start-and-usage) ### Basic D&D-Style Combat [](#basic-dd-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 [](#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 --------------------- [](#supported-rpg-systems) SystemTurn Order TypeTimeline Profile**D&D 5e / Pathfinder**Individual initiative, round-based`ROUND_INDIVIDUAL`**Shadowrun 4e**Pass-based with 10-point decay`PASS` (decay: 10)**Shadowrun 5e/6e**Pass-based with 5-point decay`PASS` (decay: 5)**Genesys / Star Wars FFG**Slot-based initiative`SLOT`**Marvel Heroic / Popcorn**Narrative designation`POPCORN`**B/X D&D / OSR**Side-based initiative`ROUND_SIDE`Configuration Examples ---------------------- [](#configuration-examples) ### D&D 5e with Dexterity Tie-Breaker [](#dd-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 [](#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 [](#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) [](#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 [](#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 -------------- [](#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 } ``` State Save and Restore ---------------------- [](#state-save-and-restore) Save and restore complete encounter state for persistence, UI synchronization, or undo/rewind features: ``` use Codryn\PHPTurnTracker\State\EncounterSnapshot; // Capture current state $snapshot = $encounter->getState(); // Serialize to JSON for storage $json = $snapshot->toJson(); file_put_contents('encounter_state.json', $json); // Later: Load and restore state $json = file_get_contents('encounter_state.json'); $snapshot = EncounterSnapshot::fromJsonString($json); $newEncounter = new Encounter(new TimelineProfile(TurnOrderType::ROUND_INDIVIDUAL)); $newEncounter->restoreState($snapshot); // Continue from exact same state $encounter->advanceTurn(); ``` The state snapshot includes: - **Timeline configuration** (profile, turn order type, all settings) - **All actors** (IDs, names, initiatives, attributes) - **Actor states** (acted/unacted, passes remaining, temporary initiative changes) - **Encounter state** (active status, current round/pass, current actor) Use cases: - **Persistence**: Save state between sessions - **UI Synchronization**: Ensure UI always reflects exact game state - **Rewind/Undo**: Implement advanced undo features using state snapshots - **State Transfer**: Move encounters between different systems or implementations Documentation ------------- [](#documentation) - **[Examples](examples/)** - Complete code examples for each RPG system Development ----------- [](#development) See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines. Architecture ------------ [](#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` Performance ----------- [](#performance) - **Encounters with 20 actors**: Complete 10 rounds in <100ms - **State queries**: <1ms response time - **Concurrent encounters**: Multiple independent encounters without performance degradation Quality Standards ----------------- [](#quality-standards) - โœ… **PHPStan Level 10**: Strictest static analysis level from PHPSTan 2.1 - โœ… **PSR-12**: PHP coding standards compliance - โœ… **Strict Types**: `declare(strict_types=1)` in all files - โœ… **TDD**: Test-driven development methodology - โœ… **Type Hints**: Full type declarations on all methods - โœ… **PHPDoc**: Complete documentation blocks Contributing ------------ [](#contributing) Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for: - Development workflow - Coding standards - Testing requirements - Pull request process License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. Changelog --------- [](#changelog) See [CHANGELOG.md](CHANGELOG.md) for version history and migration guides. Support ------- [](#support) - ๐Ÿ“– [Documentation](docs/) - ๐Ÿ› [Issue Tracker](https://github.com/codryn/phpturntracker/issues) - ๐Ÿ’ฌ [Discussions](https://github.com/codryn/phpturntracker/discussions) - ๐Ÿ“ง [Email](mailto:info@codryn.com) Credits ------- [](#credits) Created and maintained by Marco for [Codryn](https://codryn.com). Special thanks to: - The PHP community - PHPUnit, PHPStan, and PHP-CS-Fixer maintainers ### Game Systems Copyright [](#game-systems-copyright) This library implements initiative and turn order mechanics from various tabletop RPG systems for non-commercial use. All game system names, mechanics, and related intellectual property remain the property of their respective copyright holders. See [GAME\_SYSTEMS\_COPYRIGHT.md](GAME_SYSTEMS_COPYRIGHT.md) for detailed copyright notices and attributions. --- Built for the tabletop RPG community ๐ŸŽฒ ### Health Score 32 โ€” LowBetter than 72% of packages Maintenance77 Regular maintenance activity Popularity4 Limited adoption so far Community8 Small or concentrated contributor base Maturity36 Early-stage or recently created project Bus Factor1 Top contributor holds 83.1% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 3 Last Release 127d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/672c6ebccd9bbdd03fda087928aa8d8f9bf64eea76423116ee328c216430003f?d=identicon)[marcowuelser](/maintainers/marcowuelser) --- Top Contributors [![marcowuelser](https://avatars.githubusercontent.com/u/10141843?v=4)](https://github.com/marcowuelser "marcowuelser (49 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (10 commits)") --- Tags dndrpgcombattabletoppathfinderturn-trackerinitiativeshadowrungame-master ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/codryn-phpturntracker/health.svg) ``` [![Health](https://phpackages.com/badges/codryn-phpturntracker/health.svg)](https://phpackages.com/packages/codryn-phpturntracker) ``` ### Alternatives [kotchuprik/yii2-sortable-widgets Implementation Rubaxa/Sortable for Yii2. Sortable grid view inside. 61132.2k6](/packages/kotchuprik-yii2-sortable-widgets)[telephantast/message-bus Thesis Message Bus 161.3k6](/packages/telephantast-message-bus) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)