Black Trigram (흑괘) is a 3D precision Korean martial arts combat simulator built as a Progressive Web Application. This wiki documents the technical architecture, systems, and implementation details of the codebase located at https://github.com/Hack23/blacktrigram.
This Overview page provides a high-level introduction to the project's core philosophy, technology stack, and system architecture. For detailed information about specific systems, refer to the child pages:
Black Trigram is built on three foundational principles:
70 Vital Points System (급소 체계): Anatomical targeting system with authentic Korean martial arts vital points mapped to Traditional Chinese Medicine (TCM) meridians. The system categorizes targets by severity (Lethal, Critical, Major, Moderate, Minor) and anatomical type (Neurological, Skeletal, Joint, Organ, Muscular, Vascular, Respiratory).
8 Trigram Stances (팔괘 자세): Combat stance system based on I Ching philosophy, with each stance representing a natural force: ☰ 건 (Heaven), ☱ 태 (Lake), ☲ 리 (Fire), ☳ 진 (Thunder), ☴ 손 (Wind), ☵ 감 (Water), ☶ 간 (Mountain), ☷ 곤 (Earth). Each stance provides unique combat bonuses and tactical advantages.
Physics-First Design: All combat calculations use meters as the base unit, with pixel conversion only at render time. Movement physics, collision detection, and knockback calculations operate in real-world units to ensure realistic combat behavior.
Sources: game-design.md1-89 COMBAT_ARCHITECTURE.md1-76 README.md56-65
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Frontend Framework | React | 19.2.4 | UI component system |
| Language | TypeScript | 5.9.3 | Type-safe development |
| 3D Rendering | Three.js | 0.182.0 | WebGL-based graphics |
| React 3D Integration | @react-three/fiber | 9.5.0 | React renderer for Three.js |
| 3D Helpers | @react-three/drei | 10.7.7 | Pre-built 3D components |
| Build Tool | Vite | 7.x | Fast bundling and HMR |
| Audio | Howler.js | - | Spatial audio engine |
| Tool | Version | Purpose |
|---|---|---|
| Unit Testing | Vitest | 4.0.16 |
| E2E Testing | Cypress | 15.8.2 |
| Component Testing | @testing-library/react | 16.3.0 |
| Coverage | @vitest/coverage-v8 | 4.0.8 |
Sources: development.md33-56 package.json (inferred), performance-testing.md59-102
The application initializes through docs/index.html1-332 which loads the service worker docs/sw.js1-115 for offline capability. The service worker implements a network-first caching strategy (lines 56-114), ensuring users always receive the latest version when online while maintaining offline functionality. The root React application mounts at <div id="root"> and is bootstrapped by src/App.tsx1-588
Sources: docs/index.html1-332 docs/sw.js1-115 src/App.tsx1-50
The application uses a layered architecture with clear separation of concerns. App.tsx orchestrates game modes and screen transitions (lines 39-588), managing state for gameMode, selectedArchetype, combatPlayers, and screen navigation. Each screen component integrates with core systems through React hooks.
Sources: src/App.tsx39-588 README.md178-213 Diagram 1 from provided context
The combat loop runs at 60 FPS target (16.67ms frame budget). User input flows through CombatScreen3D to physics systems for movement validation, then to CombatSystem.resolveAttack() for attack resolution. The vital point system calculates damage based on anatomical target and stance effectiveness. Audio feedback provides context-specific sound effects through the AudioManager.
Sources: src/App.tsx193-346 Diagram 3 from provided context
| System | Primary Files | Purpose | Importance |
|---|---|---|---|
| Combat System | src/systems/CombatSystem.ts | Damage resolution, technique execution | Core gameplay |
| Vital Point System | src/systems/VitalPointSystem.ts | 70 anatomical targets, TCM meridian integration | 143.26 |
| Trigram System | src/systems/TrigramSystem.ts | 8 I-Ching stances, effectiveness calculation | 143.26 |
| Physics Systems | src/systems/physics/ | Movement, collision, knockback in meters | Physics-first |
| AI Systems | src/systems/ai/ | Decision tree, personality, adaptive difficulty | 114.97 |
| Animation | src/systems/animation/ | 112 animations, 28-bone rig, state machine | 233.31 |
| Audio System | src/audio/AudioManager.ts | LRU cache (30MB), variant selection | 67.96 |
| Rendering | React Three Fiber integration | WebGL via Three.js, 3D scene management | 68.13 |
| PWA | docs/sw.js, manifest.json | Offline capability, caching | 353.56 |
The importance scores indicate file edit frequency and system criticality. The PWA layer has the highest importance (353.56) as it manages application delivery and offline functionality. Core game systems (Combat, VitalPoint, Trigram) cluster around 143.26, while supporting systems (AI, Animation, Audio) provide gameplay depth.
Sources: README.md178-213 Diagram 1 analysis from provided context, docs/sw.js1-115
The development pipeline implements rigorous quality assurance with three parallel CI/CD gates that must all pass before deployment. The build process uses Vite 7 with TypeScript strict mode, generating Software Bill of Materials (SBOM) and cryptographic attestations for supply chain security. Testing infrastructure includes 4,000+ unit tests via Vitest and comprehensive E2E tests via Cypress with WebGL validation.
Sources: development.md1-75 README.md513-639 Diagram 2 from provided context
Black Trigram integrates authentic Korean martial arts and cultural elements throughout the codebase:
Bilingual System: All user-facing text appears in both Korean and English. Example: "흑괘 (Black Trigram)", "무사 (Musa/Warrior)". Typography uses Noto Sans KR for Korean characters and Orbitron for cyberpunk English text.
Martial Arts Authenticity: Techniques derive from traditional Korean martial arts (태권도 Taekwondo, 합기도 Hapkido, 택견 Taekkyeon) with Korean names preserved: "천둥벽력 (Thunder Wall Strike)", "유수연타 (Flowing Water Strike)".
I Ching Philosophy: The 8 trigram stances map directly to I Ching hexagrams with Korean names and elemental associations. Each stance provides unique combat characteristics aligned with its philosophical meaning.
Traditional Audio: The audio system integrates Korean traditional instruments (가야금 gayageum, 장구 janggu) blended with cyberpunk electronic elements to create a distinctive atmosphere.
Sources: docs/index.html1-35 game-design.md1-89 COMBAT_ARCHITECTURE.md150-241
Black Trigram optimizes for smooth combat gameplay through several techniques:
Object Pooling: ThreeObjectPools prewarms pools to eliminate ~1,344 allocations per frame, initialized in src/App.tsx105-108
Animation Precomputation: All 112 animations are precomputed at 60fps during app initialization src/App.tsx111-123 achieving 90%+ cache hit rate.
Physics-First Design: All movement and collision calculations use meters, converting to pixels only at render time. This ensures consistent behavior across devices.
Audio Caching: AudioManager implements a 30MB LRU cache with critical asset protection and object pooling for frequently used sounds.
Lazy Loading: Non-critical screens like TrainingScreen are lazy loaded src/App.tsx28-32 to reduce initial bundle size.
Sources: src/App.tsx93-147 README.md178-213 Diagram 6 from provided context
The project follows Hack23 AB's Information Security Management System (ISMS) policies:
Supply Chain Security: OSSF Scorecard analysis (target ≥7.0), dependency review, and SBOM generation with cryptographic attestations.
Security Testing: CodeQL SAST scanning, OWASP ZAP DAST scanning, and automated dependency vulnerability checks.
CI/CD Hardening: All GitHub Actions pinned to SHA hashes, runner hardening with audit logging, and parallel security gates that must pass before deployment.
Performance Security: Lighthouse CI enforces performance budgets defined in budget.json, ensuring security controls don't degrade user experience.
The service worker docs/sw.js2 includes version tracking (APP_VERSION = "0.6.54") for cache invalidation and security updates.
Sources: development.md1-75 SECURITY.md1-104 performance-testing.md1-337
This Overview introduces the Black Trigram architecture. For detailed information:
Sources: Table of Contents from provided context
Refresh this wiki