A production-ready, declarative game engine framework for building trading card games (TCGs) and turn-based strategy games.
Note
This project is currently in Phase 1: Stabilization & Polish. See the Roadmap for details.
TCG Engines is a monorepo containing a complete TypeScript framework (@tcg/core) for building trading card games, along with reference implementations, development tools, and comprehensive documentation. It empowers developers to build sophisticated card games by focusing on game-specific rules rather than infrastructure concerns.
To become the definitive TypeScript framework for TCG development, empowering developers to build sophisticated card games by focusing on game-specific rules rather than infrastructure concerns.
Read the full Mission Statement | Learn about our Design Philosophy
- Indie Game Developers - Building their first or second TCG, want to focus on game design
- TCG Platform Builders - Creating platforms to support multiple card games
- Game Studio Engineers - Professional developers building commercial TCGs
- Open Source Contributors - Interested in game engine architecture
- Educational Users - Learning game development or TCG mechanics
A production-ready, declarative game engine framework providing:
- Declarative Game Definitions - Define your game rules, zones, and cards through configuration, not boilerplate
- Immutable State Management - Powered by Immer, ensuring safe state updates and easy undo/redo
- Type Safety - Built with TypeScript 5.8+ for a fully type-safe development experience
- Deterministic Gameplay - Seeded RNG ensures replays and validations are always consistent
- Network Synchronization - Efficient delta-based state synchronization using Immer patches
- Time-Travel Debugging - Built-in support for undo, redo, and history replay
- Player Views - Automatic information hiding for multiplayer games
- Flow Orchestration - Optional turn/phase/segment management
- Zone Management - Comprehensive zone operations for card locations
- Targeting System - Complex targeting requirements and validation
- Card Filtering DSL - Query cards with a fluent API
- Logging & Telemetry - Production-grade logging and event tracking
- Testing Utilities - Complete TDD toolkit with assertions and factories
- Validation System - Type guards and runtime validators for data integrity
Read the Core Framework Documentation
Complete, production-ready game engines demonstrating best practices:
-
@tcg/lorcana- Disney Lorcana TCG implementation- Complete game rules and mechanics
- Card definitions and abilities
- Phase and turn management
- Lorcana Engine README
-
@tcg/gundam- Gundam Card Game implementation- Full game rules implementation
- Card definitions for all sets
- Tooling for card management (scraper, parser, generator)
- Gundam Engine README
-
@tcg/template- Template for creating new engines- Minimal working example
- Follows @tcg/core best practices
- Fully tested with TDD approach
- Template Engine README
Supporting packages for building and maintaining game engines:
-
@tcg/component-library- Svelte-based UI component library- Reusable components for TCG interfaces
- Storybook integration
- Internationalization support
-
@tcg/shared- Shared utilities and types- Common utilities across packages
- Shared type definitions
-
@tcg/typescript-config- Shared TypeScript configurations- Consistent TypeScript settings across packages
- Base, library, Next.js, React, and strict configs
Comprehensive documentation and coding standards:
- Product Documentation - Mission, roadmap, tech stack
- Coding Standards - Frontend, backend, library, and testing guidelines
- Integration Guides - How to build game engines with @tcg/core
- API Documentation - Complete API reference
- Examples - Integration examples and patterns
This project is organized as a monorepo using Turborepo for efficient task orchestration and caching.
tcg-engines/
├── packages/
│ ├── core/ # Core framework (@tcg/core)
│ │ ├── src/ # Framework source code
│ │ │ ├── engine/ # RuleEngine - Main orchestration
│ │ │ ├── game-definition/ # GameDefinition types and validation
│ │ │ ├── moves/ # Move system and execution
│ │ │ ├── flow/ # Turn/phase/segment management
│ │ │ ├── zones/ # Zone management system
│ │ │ ├── cards/ # Card instances and modifiers
│ │ │ ├── filtering/ # Card query DSL
│ │ │ ├── targeting/ # Targeting system
│ │ │ ├── rng/ # Seeded random number generation
│ │ │ ├── logging/ # Structured logging system
│ │ │ ├── telemetry/ # Event-based telemetry
│ │ │ ├── testing/ # Testing utilities
│ │ │ ├── validation/ # Type guards and validators
│ │ │ └── types/ # Branded types and utilities
│ │ └── docs/ # Comprehensive documentation
│ │
│ ├── engines/
│ │ └── core-engine/ # Large reference implementation (4443+ files)
│ │
│ ├── gundam-engine/ # Gundam Card Game implementation
│ │ ├── src/
│ │ │ ├── cards/ # Card definitions organized by set
│ │ │ ├── game-definition.ts
│ │ │ ├── moves/ # Move implementations
│ │ │ ├── phases/ # Phase definitions
│ │ │ └── zones/ # Zone configurations
│ │ └── tools/ # Card management tools (scraper, parser, generator)
│ │
│ ├── lorcana-engine/ # Disney Lorcana TCG implementation
│ │ ├── src/
│ │ │ ├── game-definition/ # Game definition and configuration
│ │ │ ├── moves/ # Move handlers
│ │ │ ├── cards/ # Card definitions and abilities
│ │ │ ├── types/ # TypeScript type definitions
│ │ │ └── operations/ # Game operations
│ │
│ ├── template-engine/ # Template for creating new engines
│ │ └── src/ # Minimal working example
│ │
│ ├── component-library/ # Svelte-based UI components
│ │ └── src/ # Component library source
│ │
│ ├── shared/ # Shared utilities and types
│ │ └── src/ # Common utilities
│ │
│ └── typescript-config/ # Shared TypeScript configurations
│
├── agent-os/ # Project documentation and standards
│ ├── product/ # Product documentation
│ │ ├── mission.md # Product mission statement
│ │ ├── roadmap.md # Development roadmap
│ │ └── tech-stack.md # Technical stack details
│ └── standards/ # Coding standards and guidelines
│ ├── frontend/ # Frontend standards
│ ├── backend/ # Backend standards
│ ├── library/ # Library standards
│ ├── testing/ # Testing standards
│ └── global/ # Global standards
│
├── package.json # Root package.json with workspace configuration
├── turbo.json # Turborepo configuration
└── README.md # This file
┌─────────────────────────────────────────────────────────┐
│ Game Engines │
│ (lorcana-engine, gundam-engine, template-engine) │
└────────────────────┬────────────────────────────────────┘
│
│ depends on
▼
┌─────────────────────────────────────────────────────────┐
│ @tcg/core │
│ (Core Framework) │
└────────────────────┬────────────────────────────────────┘
│
│ uses
▼
┌─────────────────────────────────────────────────────────┐
│ Shared & Config Packages │
│ (shared, typescript-config, component-library) │
└─────────────────────────────────────────────────────────┘
- Bun (v1.2.18) - Primary package manager and JavaScript runtime
- This project uses Bun as the package manager (specified in
package.json) - Bun provides fast package installation, testing, and bundling
- Install:
curl -fsSL https://bun.sh/install | bash
- This project uses Bun as the package manager (specified in
- Node.js (v24.x) - For compatibility with some tools
- fnm (optional) - Fast Node.js version manager
- This repository includes a
.node-versionfile for automatic Node.js version switching - If you're using fnm, it will automatically switch to Node.js v24.x when you enter this directory
- This repository includes a
- Git - Version control
Quick Setup (Recommended for macOS/Linux):
Run the automated setup script:
git clone https://github.com/the-card-goat/tcg-engines.git
cd tcg-engines
chmod +x setup.sh
./setup.shManual Setup (macOS/Linux):
git clone https://github.com/the-card-goat/tcg-engines.git
cd tcg-engines
bun installWindows Setup:
The automated setup script (setup.sh) is designed for macOS/Linux. On Windows, please follow these steps:
-
Install Node.js 24.x
- Download from nodejs.org or use a version manager like fnm for Windows
- Verify:
node -vshould show v24.x
-
Install Bun
- Use PowerShell:
powershell -c "irm bun.sh/install.ps1 | iex" - Or download from bun.sh
- Verify:
bun -vshould show 1.2.18 or later
- Use PowerShell:
-
Install Dependencies
git clone https://github.com/the-card-goat/tcg-engines.git cd tcg-engines bun install
For AI Agents: See agents.md for detailed setup instructions and environment configuration.
Common Setup Issues:
- fnm not found after installation: Restart your terminal or manually source your shell config (
source ~/.bashrcorsource ~/.zshrc) - Node.js version incorrect: Run
fnm use 24(if using fnm) or ensure Node.js 24.x is active - Bun not found after installation: Restart your terminal or add to PATH:
export PATH="$HOME/.bun/bin:$PATH" - Package installation fails: Ensure you're using
bun install(not npm/yarn/pnpm) and check thatpackage.jsonspecifies"packageManager": "bun@1.2.18"
For more detailed troubleshooting, see the Troubleshooting section in agents.md.
If you want to use @tcg/core to build your own game:
-
Read the Core Documentation
# Explore the core framework cat packages/core/README.md -
Use the Template Engine
# Copy the template as a starting point cp -r packages/template-engine packages/my-game-engine cd packages/my-game-engine # Follow the template README to customize
-
Study Reference Implementations
- Review
packages/lorcana-enginefor a complex TCG example - Review
packages/gundam-enginefor another implementation pattern - Review
packages/template-enginefor a minimal example
- Review
-
Read Integration Guides
If you want to contribute to the framework or engines:
-
Set Up Development Environment
# Install dependencies bun install # Run type checking bun run check-types # Run tests bun test # Run linting bun run lint # Format code bun run format
-
Run All Checks
# Run format, lint, type check, and tests bun run ci-check -
Work on Specific Packages
# Navigate to a package cd packages/core # Run package-specific commands bun test bun run check-types
Build all packages:
bun run buildRun tests for all packages:
bun testRun tests for a specific package:
cd packages/core
bun testType check all packages:
bun run check-typesLint all packages:
bun run lintFormat all packages:
bun run formatThis project uses Turborepo for task orchestration. All commands are run from the root:
bun run build- Build all packagesbun test- Run tests for all packagesbun run lint- Lint all packagesbun run format- Format all packagesbun run check-types- Type check all packagesbun run ci-check- Run format, lint, type check, and tests
Each package can be developed independently:
# Navigate to package
cd packages/core
# Install dependencies (if needed)
bun install
# Run package scripts
bun test # Run tests
bun run check-types # Type check
bun run lint # Lint
bun run format # Format- Test-Driven Development (TDD) - Write tests first
- Behavior-Driven Testing - Test observable behavior, not implementation
- Real Engine Instances - Integration tests with actual engine
- 95%+ Coverage Target - Comprehensive test coverage
- Biome - Fast linting and formatting (replaces ESLint + Prettier)
- TypeScript Strict Mode - Full type safety, no
anytypes - Turborepo Boundaries - Enforced package dependencies
All code follows strict standards documented in agent-os/standards/:
- Type Safety - No
anytypes, proper type guards - Immutable State - All state changes via Immer
- Pure Functions - Prefer pure, testable functions
- Comprehensive Documentation - JSDoc comments for public APIs
- Test Coverage - 95%+ coverage requirement
- Core Framework README - Complete framework overview
- Engine Integration Guide - How to build game engines
- Logging Guide - Structured logging system
- Telemetry Guide - Event-based telemetry
- Zone Operations Guide - Zone management utilities
- Testing Utilities Guide - TDD workflow and patterns
- Card Tooling Guide - Building card management pipelines
- Validation Guide - Type guards and runtime validation
- Move Enumeration Guide - AI and UI move discovery
- Product Mission - Full mission statement and vision
- Design Philosophy - Core design principles and philosophy
- Development Process - Development approach and implementation strategy for contributors
- Technical Stack - Complete technical stack details
- Roadmap - Development roadmap and phases
- Global Coding Style - General coding guidelines
- Frontend Standards - Frontend-specific standards
- Backend Standards - Backend-specific standards
- Library Standards - Library development standards
- Testing Standards - Testing guidelines
- Lorcana Engine README - Disney Lorcana implementation
- Gundam Engine README - Gundam Card Game implementation
- Template Engine README - Template for new engines
- Integration Examples - Complete integration examples
- Zone management examples
- Test patterns examples
- Card parser extensions
- Custom validators
- Move enumeration demos
- Language: TypeScript 5.8+
- Package Manager & Runtime: Bun 1.2.18
- Fast package installation (30x faster than npm)
- Built-in test runner (Jest-compatible)
- Built-in bundler
- Node.js-compatible runtime
- State Management: Immer 10.0.0+
- Validation: Zod 3.22.0+
- RNG: seedrandom 3.0.5+
- IDs: nanoid 5.0.0+
- Build System: Turborepo
- Code Quality: Biome 2.0.4
- Testing: Bun Test (Jest-compatible)
View the full Tech Stack Documentation
- Performance optimization
- Enhanced error messages
- Tutorial documentation
- Test utilities enhancement
- Reference implementation completion
- Plugin system
- React/Vue/Svelte integrations
- WebSocket transport layer
- AI move enumeration
- VSCode extension
- Horizontal scaling support
- Tournament system
- Analytics dashboard
- Enterprise features
We welcome contributions! Here's how to get started:
-
Read the Documentation
- Understand our Development Process and approach
- Review Coding Standards
- Understand Testing Standards
- Check the Roadmap for priorities
-
Set Up Development Environment
bun install bun run ci-check # Ensure everything passes -
Make Changes
- Follow TDD approach (write tests first)
- Maintain 95%+ test coverage
- Follow coding standards
- Update documentation as needed
-
Submit Changes
- Create a pull request
- Ensure all checks pass
- Request review
- Type Safety - No
anytypes, use proper TypeScript types - Test Coverage - 95%+ coverage required
- Documentation - Update docs for public API changes
- Code Style - Follow Biome formatting and linting rules
- Commit Messages - Use conventional commits format
MIT © The Card Goat Team
Built with ❤️ for trading card game developers
