%%{init:{"theme":"dark"}}%% flowchart LR A[🎮 Input<br/>Keyboard · Touch · Gesture] --> B[☯️ Trigram Stance<br/>건태리진손감간곤] B --> C[🦴 Skeletal Pose<br/>28 bones · 7 hand poses] C --> D[🎯 Vital-Point Targeter<br/>70 points · 4 regions · 14 meridians] D --> E[⚔️ Damage Calculator<br/>severity · accuracy · archetype bonus] E --> F[🩸 Body-Part Health<br/>pain · consciousness · breathing · balance] F --> G[🤖 Counter-Attack AI<br/>limb-exposure detection] G --> H[🎨 Three.js Render<br/>60fps · trauma · particles · shaders] F --> I[🔊 Audio Engine<br/>bone impact · breath · 국악] H --> J[♿ WCAG 2.1 AA HUD<br/>combat readiness · haptics] I --> J

classDef korean fill:#000000,stroke:#FFD700,color:#FFD700,stroke-width:2px
classDef tech fill:#001a1a,stroke:#00FFFF,color:#00FFFF,stroke-width:2px
classDef combat fill:#1a0000,stroke:#FF6B6B,color:#FF6B6B,stroke-width:2px
class A,J tech
class B,C,D korean
class E,F,G,H,I combat</div><div class="mermaid light">%%{init:{"theme":"default"}}%%

flowchart LR A[🎮 Input<br/>Keyboard · Touch · Gesture] --> B[☯️ Trigram Stance<br/>건태리진손감간곤] B --> C[🦴 Skeletal Pose<br/>28 bones · 7 hand poses] C --> D[🎯 Vital-Point Targeter<br/>70 points · 4 regions · 14 meridians] D --> E[⚔️ Damage Calculator<br/>severity · accuracy · archetype bonus] E --> F[🩸 Body-Part Health<br/>pain · consciousness · breathing · balance] F --> G[🤖 Counter-Attack AI<br/>limb-exposure detection] G --> H[🎨 Three.js Render<br/>60fps · trauma · particles · shaders] F --> I[🔊 Audio Engine<br/>bone impact · breath · 국악] H --> J[♿ WCAG 2.1 AA HUD<br/>combat readiness · haptics] I --> J

classDef korean fill:#000000,stroke:#FFD700,color:#FFD700,stroke-width:2px
classDef tech fill:#001a1a,stroke:#00FFFF,color:#00FFFF,stroke-width:2px
classDef combat fill:#1a0000,stroke:#FF6B6B,color:#FF6B6B,stroke-width:2px
class A,J tech
class B,C,D korean
class E,F,G,H,I combat</div><pre><code class="language-mermaid">flowchart LR
A[🎮 Input&lt;br/&gt;Keyboard · Touch · Gesture] --&gt; B[☯️ Trigram Stance&lt;br/&gt;건태리진손감간곤]
B --&gt; C[🦴 Skeletal Pose&lt;br/&gt;28 bones · 7 hand poses]
C --&gt; D[🎯 Vital-Point Targeter&lt;br/&gt;70 points · 4 regions · 14 meridians]
D --&gt; E[⚔️ Damage Calculator&lt;br/&gt;severity · accuracy · archetype bonus]
E --&gt; F[🩸 Body-Part Health&lt;br/&gt;pain · consciousness · breathing · balance]
F --&gt; G[🤖 Counter-Attack AI&lt;br/&gt;limb-exposure detection]
G --&gt; H[🎨 Three.js Render&lt;br/&gt;60fps · trauma · particles · shaders]
F --&gt; I[🔊 Audio Engine&lt;br/&gt;bone impact · breath · 국악]
H --&gt; J[♿ WCAG 2.1 AA HUD&lt;br/&gt;combat readiness · haptics]
I --&gt; J

classDef korean fill:#000000,stroke:#FFD700,color:#FFD700,stroke-width:2px
classDef tech fill:#001a1a,stroke:#00FFFF,color:#00FFFF,stroke-width:2px
classDef combat fill:#1a0000,stroke:#FF6B6B,color:#FF6B6B,stroke-width:2px
class A,J tech
class B,C,D korean
class E,F,G,H,I combat</code></pre></div>

See COMBAT_ARCHITECTURE.md for the full pipeline (3,300+ lines), FLOWCHART.md for business / combat process flows, and STATEDIAGRAM.md for the complete state machine.

---

🥋 Combat Disciplines

Black Trigram is a realistic Korean martial arts simulator that teaches authentic vital-point combat through precise anatomical targeting. Master traditional techniques via modern 3D combat mechanics across 5 distinct fighter archetypes.

🎯 정격자 Jeonggyeokja Precision Striker Every strike targets anatomical weak points

⚔️ 비수 Bisu Lethal Technique Decisive unarmed combat methods

🥷 암살자 Amsalja Shadow Assassin Silent takedown techniques

💀 급소격 Geupsogyeok Vital Point Strike 70 anatomical targets for incapacitation

---

🎭 Player Archetypes

Master combat through 5 distinct fighting philosophies — each with unique vital-point bonuses, archetype-specific techniques, and signature visual effects:

---

☯️ Eight Trigrams (팔괘) — Combat Stance System

Master 70 authentic vital points (급소) distributed across the I Ching's eight trigrams. Each stance shapes the active hitbox geometry, technique pool, defensive posture, and audio profile:

💪 Realistic Body Mechanics (13/13 systems · 100% complete)

• 🩸 Authentic Trauma — Realistic injury visualization, blood, bruising progression
• 🦴 Bone-Impact Audio — Genuine bone-contact and fracture sounds
• 🫁 Breathing Disruption — Respiratory targeting affects stamina and accuracy
• ⚖️ Balance System — Stance- and momentum-physics-driven vulnerability windows
• 🧠 Consciousness Levels — 4-level progressive awareness impairment
• 😵 Pain Response — Physiological pain accumulation affecting performance
• 🦵 Injury-Based Movement — Damage to limbs constrains mobility and stance access
• 🎯 Vital-Point Targeter — 70 points · 4 regions · 5 severity tiers · 14 TCM meridians
• 🤖 Counter-Attack AI — Limb-exposure detection triggers archetype-aware ripostes

---

📸 Concept

---

🚀 Technical Stack

Built for combat realism, 60fps performance, and production-grade engineering:

🎯 Core Combat Components

• VitalPointTargeter — Interactive 70-point anatomical targeting with polygon-based zone detection
• CombatTracker — Real-time damage, pain, consciousness, breathing, and balance monitoring
• TechniqueCalculator — Deterministic damage / accuracy / counter-attack math (51 techniques)
• CombatAnalyzer — Post-match technique-effectiveness analysis
• ThreeJSRenderer — Hardware-accelerated 3D combat visualization with skeletal animation (28 bones)
• CounterAttackAI — Archetype-aware riposte system with limb-exposure detection

---

🎮 Combat Controls

📖 Full reference: CONTROLS.md — single source of truth for all keyboard, mouse, touch, gesture, and haptic controls.

⌨️ Desktop (currently implemented)

• 🏃 Movement — WASD / Arrow Keys — 8-directional tactical positioning
• ☯️ Stances — 1–8 (Eight Trigrams)
  • 1 ☰ Geon (Heaven) — bone-striking force
  • 2 ☱ Tae (Lake) — joint manipulation
  • 3 ☲ Li (Fire) — precise nerve strikes
  • 4 ☳ Jin (Thunder) — stunning techniques
  • 5 ☴ Son (Wind) — continuous pressure
  • 6 ☵ Gam (Water) — adaptive counters
  • 7 ☶ Gan (Mountain) — defensive mastery
  • 8 ☷ Gon (Earth) — ground control
• 🛡️ Guard — B — defensive positioning and blocks
• ⚡ Attack — Space — execute current stance technique
• 🎯 Vital Strike — V — toggle 70-point anatomical targeting overlay
• ⏸️ Pause — ESC / M — pause menu / return to intro

📱 Mobile Touch (auto-displayed on screens < 768px)

• 🕹️ Virtual D-Pad (bottom-left, 140×140 px, 48 px buttons exceeding the 44 px iOS guideline) — 8-directional movement with Korean arrows (↑ ↗ → ↘ ↓ ↙ ← ↖)
• ⚡ Action Buttons (bottom-right) — 80×80 px gold Attack ⚡, 70×70 px blue Block 🛡️
• ☯️ Stance Wheel (bottom-center, 200 px diameter) — 8 trigrams with hangul: 건 태 리 진 손 감 간 곤
• All controls are safe-area aware (34 px bottom inset for notched devices)

👆 Gesture & Haptic Feedback

• Swipe → advance · ← retreat · ↑ high attack · ↓ low attack · two-finger tap toggles vital-point mode
• Haptics: 10 ms light (movement / stance), 50 ms medium (attack), 100 ms heavy (vital-point hits)

---

🎭 Training Modules

🎯 해부학 연구 (Anatomical Study)

• 📚 급소학습 — 70 anatomical target points
• 🎯 정밀타격 — accurate targeting techniques
• ⚫ 고급기법 — professional combat methods
• 🥋 실전응용 — combat-effectiveness training

⚔️ 무술 기법 (Martial Techniques)

• 🥋 기본기 — fundamentals: striking and positioning
• 🔢 팔괘술 — Eight Trigram Arts: traditional Korean combat philosophy
• 🔗 연계기법 — combination techniques: flowing technique sequences
• 🎯 정밀술 — precision arts: exact targeting and timing

🥊 실전 훈련 (Combat Training)

• 👤 일대일 — single-opponent simulation
• 🏢 환경전투 — environmental combat (using surroundings tactically)
• 🧘 정신수양 — mental cultivation: psychological combat preparation
• 🏃 연속대전 — continuous combat: multiple-opponent scenarios

🎭 원형 특화 (Archetype Mastery)

• 🏯 무사도 — traditional warrior discipline · 🥷 암영술 — shadow arts · 💻 사이버전 — cyber warfare · 🕵️ 정보전 — intelligence warfare · ⚡ 거리술 — street arts

---

📝 Architecture & Development Insights

In-depth technical and cultural analysis from the Hack23 development team.

⭐ Simon Moon — Architecture Chronicles

Simon Moon reveals the hidden structures and sacred geometry in Black Trigram's architecture through the Law of Fives and numerological patterns.

🥋 Black Trigram Architecture Five Fighters, Sacred Geometry Five fighter archetypes discovered through combat-domain analysis. Cultural authenticity meeting mechanical depth — with zero backend architecture.

⚔️ Black Trigram Combat System 70 Vital Points & Physics Traditional Korean martial arts mapped to 70 biomechanical vital points. Five collision systems with anatomical precision and respect for cultural tradition.

🥽 Black Trigram Future Vision VR Martial Arts & Immersive Combat Five-year evolution roadmap from immersive 3D fighter to VR martial arts training platform. Korean martial arts preservation through immersive technology.

🔍 George Dorn — Code Analysis

George Dorn provides repository deep-dives based on actual code inspection, not assumptions. Each analysis includes cloned repositories, file counts, dependency reviews, and verified metrics.

💻 Black Trigram Code Analysis Repository Deep-Dive Stack: TypeScript 6.0.3 · React 19 · Three.js 0.184 · Vite 8 Metrics: 132+ TypeScript files · 70 vital points · 5 archetypes · 28-bone skeletal animation · 51 techniques Examined package.json dependencies, explored src/ structure, verified combat-system implementation, and reviewed AI integrations.

🎮 Black Trigram Implementation Reality Combat Code: TypeScript vs. Martial Arts Physics George's technical commentary on collision-detection challenges, performance optimization for 60fps combat, and Easter eggs hidden throughout the codebase. Easter Eggs: land exactly 23 hits → FNORD victory screen · Konami code unlocks "Hagbard Mode" · health at 23% → UI pulses urgently.

---

🩸 Combat Realism Systems — 13 / 13 Complete (100%)

---

🚀 Quick Start

📋 Prerequisites

• Node.js 26+ — download
• npm 11+ (bundled with Node 26)
• Modern browser with WebGL 2.0 support

🌐 Play Now

🎮 Play live → blacktrigram.com · 🎮 GitHub Pages mirror → hack23.github.io/blacktrigram

🔧 Local Development

# Clone
git clone https://github.com/Hack23/blacktrigram.git
cd blacktrigram

# Install (requires Node ≥ 26)
npm ci

# Start the dojang
npm run dev

# Production build
npm run build

# Run tests
npm run test           # Vitest unit
npm run test:systems   # combat-system focused
npm run test:e2e       # Cypress E2E

# Generate API docs (TypeDoc)
npm run docs
Copy

📦 Use as a Library

npm install blacktrigram
Copy

// ESM with strict TypeScript types
import { CombatSystem, VitalPoints } from 'blacktrigram/systems';
import type { TrigramStance, PlayerArchetype } from 'blacktrigram/types';
Copy

---

🔐 Security, Compliance & ISMS Alignment

At Hack23 AB we believe true security comes through transparency and demonstrable practices. Black Trigram is governed by the public ISMS-PUBLIC framework, aligned with ISO 27001:2022, NIST CSF 2.0, CIS Controls v8.1, EU CRA, NIS2, and GDPR.

🛡️ Supply-Chain Security (SLSA 3)

• OSSF Scorecard — automated weekly via scorecards.yml
• OpenSSF Best Practices — project ID 10777
• SLSA 3 Provenance — every release attested → /attestations
• CycloneDX SBOM — published with each GitHub Release
• CodeQL SAST — codeql.yml
• OWASP ZAP DAST — zap-scan.yml
• Lighthouse Performance — lighthouse-performance.yml
• Accessibility (WCAG 2.1 AA) — accessibility-test.yml
• Dependency Review — dependency-review.yml
• Dependabot + auto-merge for low-risk updates
• All GitHub Actions pinned to commit SHAs — see WORKFLOWS.md

📜 Hack23 ISMS Policy Anchors

Policy	Alignment
Information Security Policy	Master security governance
Secure Development Policy	SDLC, code review, testing, threat modeling
Open Source Policy	License compliance, OSSF Scorecard, SBOM
Vulnerability Management	CodeQL, ZAP, Dependabot, SLA
Cryptography Policy	TLS 1.3, SRI, no client secrets
Threat Modeling	STRIDE per trust boundary
Access Control Policy	GitHub branch protection, signed commits
Network Security Policy	CDN, WAF, CSP, HSTS, SRI
Backup & Recovery Policy	Multi-region S3 + GitHub Pages DR
Incident Response Plan	Security disclosure, runbooks
Risk Register	Project risks tracked centrally
Compliance Checklist	ISO 27001 · NIST CSF · CIS v8.1 mapping
Security Metrics	KPIs and dashboards
AI Policy	Copilot governance, EU AI Act, NIST AI RMF
Data Classification Policy	Public · no PII
ISMS Transparency Plan	Public-disclosure strategy
CLASSIFICATION.md	Business-impact analysis

📊 Full project ↔ ISMS mapping: ISMS_REFERENCE_MAPPING.md

---

🏗️ Hack23 Portfolio — Sister Projects

Black Trigram is part of the Hack23 portfolio — a connected suite of open-source platforms applying transparent engineering and structured-intelligence tradecraft to high-stakes domains:

Project	Description
🥋 Black Trigram	This repo — Korean martial arts simulator (Three.js / R3F / TypeScript)
🕵️ Citizen Intelligence Agency	Swedish political-intelligence and accountability platform
📊 CIA Compliance Manager	CIA-triad compliance dashboard with business-impact mapping
🗳️ Riksdagsmonitor	Swedish Parliament monitor — autonomous AI newsroom in 14 languages
🏛️ EU Parliament Monitor	European Parliament political-intelligence platform
🛰️ European Parliament MCP Server	TypeScript MCP server exposing EP open data to LLMs
🌐 Hack23 Homepage	Hack23 AB corporate site — radical transparency in practice
🔐 ISMS-PUBLIC	Public Information Security Management System framework

🌐 Hack23 AB — hack23.com · Blog · Security Posture

---

📚 Documentation Map

🗺️ Planning & Status

• 🗺️ ROADMAP.md — v1.0 release plan (Q3 2026), milestones, system tracking
• 📊 game-status.md — comprehensive metrics (9.4/10 · 13/13 combat realism · 75%+ coverage)
• 🔮 VISION_2026_2034.md — 8-year strategic vision
• 🎮 game-design.md — game mechanics, archetypes, design decisions

🏛️ Architecture (C4 Model)

• 📐 ARCHITECTURE.md — current C4 context · container · component
• ⚔️ COMBAT_ARCHITECTURE.md — full combat pipeline (3,300+ lines)
• 📊 DATA_MODEL.md — data structures and relationships
• 🔄 FLOWCHART.md — combat / business process flows
• 🎛️ STATEDIAGRAM.md — game and combat state machines
• 🧠 MINDMAP.md — conceptual relationships
• 📈 SWOT.md — strategic analysis
• 🚀 FUTURE_ARCHITECTURE.md — post-v1.0 evolution roadmap

🔐 Security & Compliance

• 🔒 SECURITY.md — vulnerability disclosure, supported versions, SLA
• 🛡️ SECURITY_ARCHITECTURE.md — implemented security design
• 🚀 FUTURE_SECURITY_ARCHITECTURE.md — planned security improvements
• 🎯 THREAT_MODEL.md — STRIDE analysis and attack trees
• 🚀 FUTURE_THREAT_MODEL.md — evolved threats
• 📋 CRA-ASSESSMENT.md — EU Cyber Resilience Act readiness
• 🗺️ ISMS_REFERENCE_MAPPING.md — repo ↔ ISMS-PUBLIC cross-reference
• 🔄 WORKFLOWS.md — CI/CD security automation
• ♻️ BCPPlan.md — Business Continuity Plan (multi-region failover)
• 🏁 End-of-Life-Strategy.md — sunset and migration plan

🛠️ Development, Testing & Assets

• 🔧 development.md — dev environment, security features, testing
• 🧪 UnitTestPlan.md — unit-testing strategy (Vitest)
• 🎯 E2ETestPlan.md — end-to-end testing (Cypress)
• ⚡ performance-testing.md — Lighthouse + load testing
• 🎮 CONTROLS.md — complete controls reference (desktop · mobile · gestures · haptics)
• 🖼️ ART_ASSETS.md — sprites, particles, palettes
• 🎵 AUDIO_ASSETS.md — Korean instruments, impact SFX, mixing
• 🎬 VIDEO_ASSETS.md — cinematic content
• 💰 FinancialSecurityPlan.md — financial-security plan

🤖 GitHub Copilot Custom Agents

• 🎯 Custom Agents Guide — specialized agents for development, testing, security, documentation, and Korean martial arts expertise
• ⚡ Agent Skills Catalog — automatic enforcement skills
• 📋 Agent Capabilities Matrix — coordination guide
• 📊 Agent Skills Implementation — implementation report

---

🥋 Project Classification

🎯 Project Type

🔒 Security Classification

⏱️ Business Continuity

The frontend is statically deployed to AWS CloudFront + S3 in multiple AWS regions with Route 53 health-checked failover to GitHub Pages as disaster-recovery — supporting the RTO/RPO commitments above with no backend dependencies. See BCPPlan.md and SECURITY_ARCHITECTURE.md.

💰 Business Impact Analysis Matrix

Impact	Financial	Operational	Reputational	Regulatory
🔒 Confidentiality	Negligible	Negligible	Low	Negligible
✅ Integrity	Negligible	Moderate	Moderate	Negligible
⏱️ Availability	Negligible	Low	Low	Negligible

🛡️ Security Investment & Strategic Position

---

🤝 Contributing

We welcome contributions in code, documentation, Korean cultural review, accessibility audits, and security research.

• 📋 CONTRIBUTING.md — contribution workflow
• 🤝 CODE_OF_CONDUCT.md — community standards
• 🔒 SECURITY.md — responsible disclosure (use the dedicated channel; do not file public issues)
• ✍️ All commits must be signed; first-time contributors sign the CLA

---

📜 License

Apache License 2.0 — see LICENSE.

---