aafe527d51
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5.8 KiB
PRD: Card Evolution System
Document Status: Draft v4.0 — Phase 0 complete, Phase 1 in progress Author: Atlas (Principal Software Architect) Date: 2026-03-10 (last updated 2026-03-17) Issue Reference: Gitea #46 (Evolution), #49 (Crafting) Stakeholder: Cal
Implementation Status
| Phase | Status | Notes |
|---|---|---|
| Phase 0 — Render Pipeline | ✅ Mostly complete | Browser persistence + lifespan hooks in main (2026.3.17). Self-hosted fonts (PR #96) and benchmark script (PR #95) still in next-release. |
| Phase 1 — Foundation | 🔄 In progress | Season stats models, formula engine, track catalog API, seed data all in main. SQL migration + Peewee models (PR #84) and evaluate endpoint (PR #98) pending on card-evolution branch. |
| Phase 2 — Rating Boosts | ⬜ Not started | |
| Phase 3 — Static Cosmetics | ⬜ Not started | |
| Phase 4 — Animated Cosmetics | ⬜ Not started |
Active branch: card-evolution (paper-dynasty-database repo)
Open PRs targeting card-evolution: #84 (SQL migration + models), #98 (evaluate endpoint)
Revision History
v4.0 (2026-03-11): Added animated card support (APNG) and render pipeline optimization. Persistent browser instance replaces per-request Chromium launch (~3x per-card speedup). Concurrent upload pipeline with
asyncio.gather(~10-20x total run speedup). Self-hosted fonts eliminate CDN dependency. APNG pipeline uses deterministic--anim-progressCSS custom property for reproducible frame capture. New Phase 0 (render optimization) added as pre-requisite. See 02-architecture.md and 08-display.md § 8.6.v3.0 (2026-03-10): Variant system redesigned to use deterministic hash-based variant numbering.
card.variant(nullable) added to card table.image_urladded tobattingcard/pitchingcardfor variant-specific rendered images with cosmetics baked in. Trading resets evolution (team-scoped progress). Card images rendered once per variant creation.v2.0 (2026-03-10): Major design pivot from opt-in enrollment model to passive, automatic, free evolution. Every card always evolves; currency sinks are cosmetics choice, not activation fees. Slot limits and abandonment mechanics removed.
Table of Contents
| Chapter | Section | File |
|---|---|---|
| — | Executive Summary | README.md (below) |
| 1 | Business Objectives and Success Metrics | 01-objectives.md |
| 2 | System Architecture + Render Pipeline Optimization | 02-architecture.md |
| 3 | Evolution Track Design | 03-tracks.md |
| 4 | Milestone Challenge System | 04-milestones.md |
| 5 | Rating Boost Mechanics | 05-rating-boosts.md |
| 6 | Database Schema | 06-database.md |
| 7 | Card Model Changes and Variant System | 07-variant-system.md |
| 8 | Discord Display, Visual Identity, and Animated Cards | 08-display.md |
| 9 | System Integrations (Crafting, Existing Systems) | 09-integrations.md |
| 10 | Economy Design and Currency Sinks | 10-economy.md |
| 11 | Anti-Abuse Safeguards | 11-safeguards.md |
| 12 | API Endpoints | 12-api.md |
| 13 | Implementation Phases and Checklists | 13-implementation.md |
| 14 | Risk Register and Open Questions | 14-risks.md |
Related files:
- Card Cosmetics Playground — Interactive visual explorer for cosmetic options
Executive Summary
Project Overview
Card Evolution is a passive, automatic progression system that permanently upgrades cards as players use them in games. Every card a team owns is always evolving — there is no opt-in, no activation cost, and no slot limit. Players build attachment to specific cards by simply playing games with them. When enough milestones accumulate, the card tiers up automatically and its ratings improve.
The system takes direct inspiration from EA FC's Evolutions mechanic and adapts it to Paper Dynasty's D20 probability engine, Discord-native UX, and PostgreSQL/Peewee architecture. The v2.0 pivot strips away the management overhead (slots, activation fees, abandonment) that would have made evolution feel like a second job and instead makes it feel like a natural reward for playing the game.
Core Design Philosophy
- Passive and automatic: Evolution happens in the background. Players do not enroll cards or manage slots. They play games; cards evolve.
- Free to evolve: Rating boosts cost nothing. Currency is spent on customization and cosmetics, not on unlocking basic progression.
- Visible progress: Players can always check any card's current evolution tier and milestone progress. The system rewards curiosity.
- Premium expression layer: Players who want to customize their card's visuals (frames, themes, animated effects) spend currency to do so. Flex culture is the monetization hook, not gatekeeping.
Scope
This PRD covers:
- Passive evolution track structure and milestone types
- Lazy evaluation architecture against existing game data tables
- D20-safe rating boost calculations
- Premium cosmetic system
- Animated card rendering pipeline (APNG) for premium cosmetics
- All new database tables and changes to existing tables
- Discord embed design for evolved cards
- Interplay with the planned Crafting (#49) system
- Economy balance (cosmetics-based, not activation-based)
- A phased implementation plan
Out of Scope
- The Crafting / Duplicate Merging system itself (covered in its own PRD, #49)
- Ranked mode (separate project)
- Mobile or web frontend