🥋 Black Trigram (흑괘)

어둠의 무예로 완벽한 일격을 추구하라

"Master the dark arts through the pursuit of the perfect strike" 🎮 Enter the Dojang

📚 Documentation:

📋 Test Documentation:

🔐 ISMS Framework Compliance:

An immersive 3D precision combat game powered by Three.js, inspired by Korean martial arts philosophy and the I Ching

---

⚡ Combat Mastery

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

🎯 Combat Disciplines

🎯 정격자 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

---

📸 Concept

---

🌟 Authentic Combat Features

🥋 Player Archetypes

Master combat through 5 distinct fighting philosophies:

Archetype	Name	Combat Philosophy	Special Focus
🏯	무사 (Musa) Traditional Warrior	Honor through strength	Military discipline, overwhelming force
🥷	암살자 (Amsalja) Shadow Assassin	Efficiency through invisibility	Stealth approaches, instant takedowns
💻	해커 (Hacker) Cyber Warrior	Information as power	Environmental manipulation, tech-assisted strikes
🕵️	정보요원 (Jeongbo Yowon) Intelligence Operative	Knowledge through observation	Psychological manipulation, precise timing
⚡	조직폭력배 (Jojik Pokryeokbae) Organized Crime	Survival through ruthlessness	Dirty fighting, improvised weapons

🎯 Anatomical Targeting System

Master 70 authentic vital points for combat effectiveness:

Trigram	Name	Combat Focus	Combat Effects
☰	건 (Geon) – Heaven	Bone-striking force	Fractures, structural damage
☱	태 (Tae) – Lake	Joint manipulation	Dislocations, mobility loss
☲	리 (Li) – Fire	Precise nerve strikes	Temporary paralysis, numbness
☳	진 (Jin) – Thunder	Stunning techniques	Disorientation, knockouts
☴	손 (Son) – Wind	Continuous pressure	Gradual incapacitation
☵	감 (Gam) – Water	Blood flow restriction	Circulation disruption
☶	간 (Gan) – Mountain	Defensive counters	Counter-attacks, blocks
☷	곤 (Gon) – Earth	Ground techniques	Throws, takedowns

💪 Realistic Body Mechanics

• 🩸 Authentic Trauma – Realistic injury visualization and blood
• 🦴 Bone Impact Audio – Genuine bone contact and fracture sounds
• 🫁 Breathing Disruption – Respiratory system targeting
• ⚖️ Balance System – Realistic stance and momentum physics
• 🧠 Consciousness States – Progressive awareness impairment
• 😵 Pain Response – Physiological pain affecting performance

🎯 Combat Specializations

• 🎯 Anatomical Precision – 70 target points for tactical advantage
• 🇰🇷 Traditional Korean Arts – Authentic techniques from 태권도, 합기도, 택견
• ⚫ Advanced Techniques – Professional combat methods from 5 distinct archetypes
• 🥋 Combat Application – Real martial arts effectiveness

---

🚀 Technical Excellence

Built for combat realism and authentic simulation:

🎮 Rendering Engine

⚡ Performance Optimized

🎨 3D Visual Effects

🎯 Combat Components

• VitalPointTargeter – Interactive anatomical targeting system
• CombatTracker – Real-time damage and status monitoring
• TechniqueCalculator – Precise combat effectiveness calculations
• CombatAnalyzer – Post-match technique analysis
• ThreeJS Renderer – Hardware-accelerated 3D combat visualization

---

🎮 Combat Controls

📖 Complete Control Reference: See CONTROLS.md for comprehensive control documentation

⌨️ Desktop Input System (Currently Implemented)

• 🏃 Movement: WASD or Arrow Keys – 8-directional tactical positioning and footwork
• ⚔️ Stances: 1–8 (Eight Trigram-based combat stances)
  • 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 or M – Pause menu / Return to intro

📱 Mobile Touch Controls (375x667+ screens)

Virtual Controls (Auto-displayed on screens < 768px width):

• 🕹️ Virtual D-Pad (Bottom-Left) – 8-directional movement control

  • 140x140px touch-optimized size
  • 48px minimum button targets (exceeds iOS 44px guideline)
  • Tap directional buttons for tactical positioning
  • Korean arrow indicators (↑ ↗ → ↘ ↓ ↙ ← ↖)
  • Safe area aware positioning (34px from bottom)

• ⚡ Action Buttons (Bottom-Right)

  • Attack Button (80x80px, Gold ⚡) – Execute current stance technique
  • Block Button (70x70px, Blue 🛡️) – Activate defensive guard
  • Safe area aware positioning (34px from bottom)

• ☯️ Stance Wheel (Bottom-Center)

  • Tap to expand circular selector (200px diameter)
  • 8 trigram stances (☰ ☱ ☲ ☳ ☴ ☵ ☶ ☷)
  • Korean names: 건 태 리 진 손 감 간 곤
  • Safe area aware positioning

Gesture Controls:

• Swipe Right → – Advance toward opponent
• Swipe Left ← – Retreat from opponent
• Swipe Up ↑ – High attack execution
• Swipe Down ↓ – Low attack execution
• Two-Finger Tap 🤞 – Toggle vital point targeting mode

Haptic Feedback:

• Light vibration (10ms) on D-pad movement and stance selection
• Medium vibration (50ms) on attack execution
• Heavy vibration (100ms) on critical hits and vital point strikes

🩸 Combat Feedback

• 💥 Impact Effects: Bone contact sounds and visual trauma
• 🩸 Injury System: Realistic bleeding and damage progression
• 😵 Incapacitation: Visual indicators of combat effectiveness
• ⚖️ Balance: Physical stance and vulnerability windows

---

🎭 Training Modules

🎯 해부학 연구 (Anatomical Study)

• 📚 급소학습 (Vital Point Study) – 70 anatomical target points
• 🎯 정밀타격 (Precision Striking) – Accurate targeting techniques
• ⚫ 고급기법 (Advanced Techniques) – Professional combat methods
• 🥋 실전응용 (Practical Application) – Combat effectiveness training

⚔️ 무술 기법 (Martial Techniques)

• 🥋 기본기 (Fundamentals) – Basic striking and positioning
• 🔢 팔괘술 (Eight Trigram Arts) – Traditional Korean combat philosophy
• 🔗 연계기법 (Combination Techniques) – Flowing technique sequences
• 🎯 정밀술 (Precision Arts) – Exact targeting and timing

🥊 실전 훈련 (Combat Training)

• 👤 일대일 (One-on-One) – Single opponent combat simulation
• 🏢 환경전투 (Environmental Combat) – Using surroundings tactically
• 🧘 정신수양 (Mental Cultivation) – Psychological combat preparation
• 🏃 연속대전 (Continuous Combat) – Multiple opponent scenarios

🎭 원형 특화 (Archetype Mastery)

• 🏯 무사도 (Warrior's Way) – Traditional warrior discipline training
• 🥷 암영술 (Shadow Arts) – Stealth and assassination techniques
• 💻 사이버전 (Cyber Warfare) – Tech-enhanced combat methods
• 🕵️ 정보전 (Intelligence Warfare) – Psychological and strategic combat
• ⚡ 거리술 (Street Arts) – Underground survival combat

---

📝 Architecture & Development Insights

Explore in-depth technical analysis and architectural insights about Black Trigram through blog posts by our development team.

⭐ Simon Moon's 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's Code Analysis

Developer | Repository Inspector | Code Archaeologist

View Agent Profile

George Dorn provides detailed 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 5.9, React 19, Three.js 0.181, Vite 7 Metrics: 132 TypeScript files, 70 vital points system, 5 fighter archetypes 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 reveals 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.

🌟 Explore More Insights

📚 Full Security Blog — 50+ posts covering cybersecurity, ISMS policies, and software architecture through radical transparency

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

---

📚 Documentation

API Reference

Complete TypeDoc API documentation with Korean martial arts context is available:

📘 View API Documentation

The API documentation includes:

• 📖 Core Types: All enums, interfaces, and type definitions with Korean-English bilingual descriptions
• 🥋 Eight Trigram System: Complete I Ching philosophy and stance mechanics
• 🎯 Vital Point System: All 70 Korean vital points with anatomical details
• ⚔️ Combat System: Combat mechanics, damage calculation, and technique execution
• 👤 Player Archetypes: Detailed descriptions of all 5 fighter types
• 🎨 UI Components: Component usage examples and props documentation
• 🔧 Utilities: Helper functions and system utilities

Key Documentation Sections

• Korean Martial Arts Concepts: Traditional philosophy integrated with modern combat
• I Ching (易經) Integration: How the Eight Trigrams influence combat flow
• Anatomical Targeting: Realistic vital point system based on Korean martial arts
• Combat Calculations: Damage, accuracy, and effectiveness algorithms
• Security Notes: Critical functions with security considerations

Documentation Coverage

• ✅ 100% of core types documented with examples
• ✅ All system classes with comprehensive JSDoc
• ✅ Korean-English bilingual terminology throughout
• ✅ Usage examples for complex functions
• ✅ Philosophy context for martial arts concepts

Validation Approach: Strict TypeDoc validation is enabled (notDocumented: true) to track documentation progress. This generates ~2,250 warnings initially, which are being addressed incrementally. The strict approach ensures all new exports are documented from the start, maintaining high documentation standards as the codebase evolves.

Building Documentation Locally

# Generate TypeDoc documentation
npm run docs

# View documentation
open docs/api/index.html

UI/UX Architecture Documentation

Comprehensive guides for developers building Korean-themed cyberpunk interfaces:

Document	Description	Topics Covered
🏗️ UI/UX Architecture	Component hierarchy and design patterns	Component hierarchy, design patterns, Three.js integration, performance optimization
🎨 Korean Theming Guide	Color palette and typography standards	Cyberpunk colors, 오방색 (Five Directional Colors), typography, bilingual patterns
🌐 Three.js UI Integration	Html overlay and 3D mesh patterns	Html vs 3D mesh decisions, Canvas setup, useFrame patterns, performance optimization
📐 Responsive Design	Mobile-first responsive system	Breakpoints, layout utilities, safe area handling, touch target standards
📱 Mobile Controls	Touch controls and gestures	Virtual D-pad, action buttons, stance wheel, haptic feedback, gesture recognition
♿ Accessibility Guide	WCAG 2.1 Level AA compliance	Color contrast, keyboard navigation, screen readers, ARIA labels, testing checklist

Key Benefits:

• ✅ Developer Onboarding: Reduced from 2-3 days to <1 day
• ✅ Design Consistency: Single source of truth for UI/UX standards
• ✅ WCAG 2.1 AA: All components meet accessibility requirements (4.5:1 contrast, 48px touch targets)
• ✅ Korean Aesthetics: Complete cyberpunk + traditional 오방색 color system
• ✅ Three.js Patterns: Clear Html overlay vs 3D mesh decision framework
• ✅ Mobile-First: Complete responsive system with virtual controls

---

🔐 Commitment to Transparency and Security

At Hack23 AB, we believe that true security comes through transparency and demonstrable practices. Our Information Security Management System (ISMS) is publicly available, showcasing our commitment to security excellence and organizational transparency.

📋 Public ISMS Repository Complete Information Security Management System documentation

🔒 Information Security Policy Enterprise-grade security framework and governance

📊 ISMS Reference Mapping: For a complete mapping of all ISMS policies referenced by Black Trigram, see ISMS_REFERENCE_MAPPING.md

🏆 Security Through Transparency

Our approach to cybersecurity consulting is built on a foundation of transparent practices:

• 🔍 Open Documentation: Complete ISMS framework available for review
• 📋 Policy Transparency: Detailed security policies and procedures publicly accessible
• 🎯 Demonstrable Expertise: Our own security implementation serves as a live demonstration
• 🔄 Continuous Improvement: Public documentation enables community feedback and enhancement

"Our commitment to transparency extends to our security practices - demonstrating that true security comes from robust processes, continuous improvement, and a culture where security considerations are integrated into every business decision."

— James Pether Sörling, CEO/Founder

---

🔧 Development Features

🎯 Anatomical Data Integration

// Authentic vital point data with combat applications
interface VitalPoint {
  name: { korean: string; english: string; technique: string };
  location: AnatomicalPosition;
  effectiveness: CombatEffectiveness;
  difficulty: PrecisionRequired;
  method: CombatTechnique[];
  archetypeBonus: ArchetypeModifier[]; // Special bonuses for different fighter types
}

🩸 Combat Mechanics System

// Realistic body mechanics for authentic combat
interface CombatState {
  health: number; // Physical condition remaining
  consciousness: number; // Awareness and responsiveness
  pain: number; // Pain levels affecting performance
  balance: CombatStability; // Physical stability in combat
  stamina: number; // Energy and endurance
  technique: number; // Skill and precision level
  archetype: PlayerArchetype; // Current fighter specialization
}

// Player archetype system
type PlayerArchetype = "musa" | "amsalja" | "hacker" | "jeongbo" | "jojik";

---

🚀 Quick Start

🌐 Enter the Dojang

🎮 Begin Combat Training

🔧 Local Development

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

# Install dependencies
npm install

# Start combat simulation
npm run dev

# Build for deployment
npm run build

# Run combat testing
npm run test
npm run test:combat

---

📚 Documentation & Further Reading

Game/frontend will be open source with commercial backend supporting multiplayer functionality, rankings and subscriptions to fund development and runtime of backend. Will enable progressions and persistent state of game.

🔗 Architecture & Design

• 📐 ARCHITECTURE.md High-level C4 models, container/component views, and system context.
• 📈 FUTURE_ARCHITECTURE.md Vision for upcoming architectural enhancements and PWA integration.
• API Docs Detailed API reference for all components, types, and functions in the application.

🔗 Combat & Mechanics

• 🥋 COMBAT_ARCHITECTURE.md In-depth battleflow, trigram integration, vital-point targeting, and damage pipeline.
• 🗺️ game-design.md Overall game mechanics, archetype breakdowns, and design decisions.
• 📊 game-status.md Current progress, feature roadmap, and milestone tracking.

🔗 Assets & Media

• 🖼️ ART_ASSETS.md Guidelines for sprite sheets, particle textures, color palettes, and UI icons.
• 🎵 AUDIO_ASSETS.md List of traditional Korean instrument loops, impact SFX, and mixing notes.
• 🎵 VIDEO_ASSETS.md Black Trigram: The Path of Shadows 🌑⚡🗡️ .Scene 1: Initiation Under Neon Skies 🌑🗡️🌆

🔒 CI/CD & Security Features

• 🔒 development.md The development implements comprehensive security measures.
• 🤖 Copilot MCP Setup Model Context Protocol servers for enhanced Copilot capabilities.
• 🛡️ Supply Chain Security - OSSF Scorecard analysis and dependency review
• 🔍 Static Analysis - CodeQL scanning for vulnerabilities
• 📦 Dependency Protection - Automated dependency vulnerability checks
• 🔐 Runner Hardening - All CI/CD runners are hardened with audit logging
• 📋 Security Policies - GitHub security advisories and vulnerability reporting
• 🏷️ Pinned Dependencies - All GitHub Actions pinned to specific SHA hashes
• 📄 SBOM Generation - Software Bill of Materials for transparency
• 🔏 Build Attestations - Cryptographic proof of build integrity
• 🏆 Artifact Verification - SLSA-compliant build provenance
• 🕷️ ZAP Security Scanning - OWASP ZAP dynamic application security testing
• ⚡ Lighthouse Performance - Automated performance and accessibility audits

---

🎯 Combat Philosophy

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

Each technique focuses on:

• 정확한 타격 (Precise Targeting) – Exact anatomical vulnerable points
• 최대 효과 (Maximum Effectiveness) – One-strike incapacitation
• 전투 심리 (Combat Psychology) – Mental preparation for combat
• 전통 지식 (Traditional Knowledge) – Authentic Korean martial arts
• 원형 특화 (Archetype Specialization) – Unique approach per fighter type

---

🏆 Combat Achievements

🎯 Combat Mastery

• 🎓 급소대가 (Vital Point Master) – Master all 70 vital-point targets
• 🩸 전투전문가 (Combat Expert) – Execute optimal combat techniques
• ⚫ 고수 (Advanced Practitioner) – Complete advanced technique training
• 🔪 완벽한 무사 (Perfect Warrior) – Achieve flawless combat records

🥋 Martial Proficiency

• 🎯 정밀타격사 (Precision Striker) – Perfect vital-point targeting accuracy
• ⚖️ 균형대사 (Balance Master) – Master all stance & footwork patterns
• 🧘 정신수양사 (Mental Cultivator) – Complete psychological combat training
• 🇰🇷 무도학자 (Martial Scholar) – Understand Korean martial arts philosophy

🎭 Archetype Mastery

• 🏯 무사완성 (Warrior Perfection) – Master traditional warrior discipline
• 🥷 그림자대사 (Shadow Master) – Perfect stealth & assassination arts
• 💻 사이버무사 (Cyber Warrior) – Tech-enhanced combat mastery
• 🕵️ 정보대가 (Intelligence Master) – Psychological warfare expertise
• ⚡ 거리왕 (Street King) – Underground combat supremacy

---

🌟 Ready to Master Korean Martial Arts?

🎮 Enter the Dojang

Experience authentic Korean combat techniques with anatomical precision across 5 unique fighting archetypes

---

Built with 🎯 Combat Precision and 🇰🇷 Traditional Authenticity

🥋 무도의 길을 걸어라 (Walk the Path of Martial Arts) 🥋

---

📚 Related Documents

🔐 Security & Compliance

• 🔐 Information Security Policy - Enterprise-grade security framework
• 🛡️ Security Architecture - Complete security implementation
• 🔮 Future Security Architecture - Planned security enhancements
• 🎯 Threat Model - STRIDE analysis and attack trees
• 📋 CRA Assessment - EU Cyber Resilience Act compliance
• 🔒 Security Policy - Vulnerability reporting and disclosure
• 🗺️ ISMS Reference Mapping - Complete ISMS policy mapping

🛠️ Development & Architecture

• 🛠️ Secure Development Policy - Security-integrated SDLC
• 📐 Architecture - High-level system design
• ⚔️ Combat Architecture - Combat system mechanics
• 🔄 Workflows - CI/CD security automation
• 🔧 Development Guide - Security features and testing
• 🏷️ Classification Framework - Business impact analysis

📊 Testing & Quality

• 🧪 Unit Test Plan - Comprehensive unit testing strategy
• 🎯 E2E Test Plan - End-to-end testing documentation
• 🎮 Screen-Specific E2E Strategy - One test per screen (3-4 min each)
• ⚡ Performance Testing - Lighthouse & load testing
• 🔍 Vulnerability Management - Security testing procedures

🎮 Game Design & Assets

• 🎮 Game Design - Overall game mechanics
• 📊 Game Status - Development progress
• 🖼️ Art Assets - Visual asset guidelines
• 🎵 Audio Assets - Sound design documentation
• 🎬 Video Assets - Cinematic content

🌐 ISMS Public Repository

• 🔓 Open Source Policy - Open source governance
• 🤖 AI Policy - AI governance framework
• 🌐 ISMS Transparency Plan - Public disclosure strategy
• 📊 Security Metrics - Performance measurement

---

🥋 Black Trigram Project Classification

🎯 Project Classification

🔒 Security Classification

⏱️ Business Continuity

💰 Business Impact Analysis Matrix

Impact Category	Financial	Operational	Reputational	Regulatory
🔒 Confidentiality
✅ Integrity
⏱️ Availability

🛡️ Security Investment Returns

🎯 Competitive Differentiation

📈 Porter's Five Forces Strategic Impact

---