blacktrigram

v0.7.50

Published

16 hours ago

Black Trigram (흑괘) - Korean Martial Arts Combat Simulator. Reusable game systems, combat mechanics, animation framework, and Korean martial arts data built with React, Three.js, and TypeScript.

🎯 Why This Exists

"어둠 속에서 완벽한 일격을 찾아라" — "In darkness, seek the perfect strike."

Authentic Korean martial arts deserve more than a flashy combo system. Black Trigram (흑괘) is the cultural-tech sister project to Riksdagsmonitor and EU Parliament Monitor in the Hack23 portfolio: where those projects apply structured intelligence tradecraft to democratic transparency, Black Trigram applies the same engineering rigor to combat simulation — turning the I Ching's Eight Trigrams (☰☱☲☳☴☵☶☷), 70 anatomically-precise vital points (급소) across 4 body regions and 14 TCM meridians, and 51 traditional techniques into a typed, testable, deterministic, accessible, browser-first Korean martial arts simulator.

It is a complete 13/13 combat-realism platform — body-part health, vital-point targeting, enhanced anatomy, visual feedback, pain response, consciousness levels, breathing disruption, trauma visualization, balance/vulnerability, combat-readiness HUD, injury-based movement, bone-impact audio, and counter-attack AI with limb-exposure detection — running at 60fps on desktop and 55fps+ on mobile, validated across 518 tests (372 unit + 146 new), with 75%+ coverage, WCAG 2.1 AA accessibility, and full OWASP / OSSF / SLSA 3 supply-chain hardening.

| Pillar | What it means in this project | |---|---| | 🥋 Cultural Authenticity | Hangul + Revised Romanization + meaning for every term. 51 techniques sourced from Hapkido, Taekwondo, Taekkyeon, Kuk Sool Won, Tang Soo Do, Hwa Rang Do, Gumdo, Ssireum, Subak, Yudo, Gongkwon Yusul. 127 medical references underpin the 70 vital points. | | 🎯 Anatomical Precision | 70/70 vital points, 4 body regions, 5 severity levels, 14 TCM meridians, 28-bone skeletal animation, 7 hand poses, 4 grappling states. Counter-attack AI with limb-exposure detection. | | ⚙️ Engineering Rigor | TypeScript strict mode, React 19, Three.js 0.184, R3F 9, Drei 10, Vite 8 — 60fps desktop, 55fps+ mobile, 75%+ test coverage, 518 tests, deterministic combat math. | | 🔐 Radical Transparency | Frontend-only · zero backend · zero PII · public ISMS · CodeQL · ZAP DAST · Lighthouse · OSSF Scorecard · SLSA 3 attestations · CycloneDX SBOM. |

📊 Production-readiness snapshot (v0.7.32) — see game-status.md and ARCHITECTURE.md:

| Metric | Value | Source | |---|---|---| | Product version | 0.7.32 | package.json | | Overall quality | 9.4 / 10 — Production-Ready | game-status.md | | Combat realism systems | 13 / 13 (100%) | game-status.md | | Vital points | 70 / 70 (4 regions · 5 severity · 14 TCM meridians · 127 medical refs) | game-status.md | | Trigram stances | 8 / 8 | game-status.md | | Player archetypes | 5 / 5 | game-status.md | | Techniques | 51 across 4 categories | game-status.md | | Skeletal animation | 28 bones · 7 hand poses · 4 grappling states | game-status.md | | Tests passing | 518 (372 + 146 new) | game-status.md | | Test coverage | ~75% (target 80%+) | game-status.md | | Performance | 60fps desktop · 55fps+ mobile (validated) | performance-testing.md | | Accessibility | WCAG 2.1 AA | accessibility-test.yml | | Last architecture review | 2026-04-21, Architecture v2.1 | ARCHITECTURE.md |

🌐 Explore the Platform

The published game is the audience-facing companion to this open-source TypeScript / React Three Fiber package. Bookmark these entry points:

⚡ Combat Pipeline — at a Glance

The combat loop is fully deterministic, frame-accurate, and side-effect-isolated. Player input is normalised, fed through the active trigram stance, validated against vital-point geometry, scored for damage, and rendered in Three.js — all within a single 16.6 ms frame budget.

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

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:

🎮 Rendering Engine

⚡ Build & Performance

🧪 Quality & Testing

🎨 3D Visual Effects

🎯 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

System Architect · Pattern Recognition Expert · Philosopher-Engineer View Agent Profile

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

Developer · Repository Inspector · Code Archaeologist View Agent Profile

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.

📚 Full Hack23 Blog — 50+ posts on cybersecurity, ISMS policy, and software architecture through radical transparency.

"Code is reality made computational. If it doesn't work, nothing else matters." — George Dorn

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

| System | Status | Notes | |---|---|---| | Body-Part Health | ✅ | 8-part damage tracking | | Vital-Point Targeting | ✅ | 70 authentic Korean vital points | | Enhanced Anatomy | ✅ | Polygon-based zone detection | | Visual Feedback | ✅ | Damage numbers, hit effects, combos | | Pain Response | ✅ | Realistic pain accumulation (production-tested) | | Consciousness Levels | ✅ | 4-level awareness system | | Breathing Disruption | ✅ | Respiratory targeting affects stamina/accuracy | | Trauma Visualization | ✅ | Injury rendering, bruising progression | | Balance / Vulnerability | ✅ | Stance-based weakness windows | | Combat-Readiness HUD | ✅ | Real-time multi-system status display | | Injury-Based Movement | ✅ | Damage constrains mobility and stance access | | Bone-Impact Audio | ✅ | Bone-contact and fracture sounds | | Counter-Attack AI | ✅ | Limb-exposure detection · archetype-aware ripostes |

📊 Detailed Status Report → · 🗺️ v1.0 Roadmap → · ⚔️ Combat Architecture →

🚀 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

📦 Use as a Library

npm install blacktrigram

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

🔐 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.

🌟 Ready to Master Korean Martial Arts?

🎮 Play → blacktrigram.com · 📘 API Docs · 📦 npm · 🤖 DeepWiki

Experience authentic Korean combat techniques with anatomical precision across 5 unique fighting archetypes, 8 trigram stances, and 70 vital points.

Built with 🎯 Combat Precision · 🇰🇷 Cultural Authenticity · 🔐 Radical Transparency

🥋 흑괘의 길을 걸어라 — Walk the Path of the Black Trigram 🥋