Black Trigram Documentation English

Complete guide for Korean Traditional Martial Arts Precision Combat Simulator

GitHub Release License OpenSSF Scorecard CII Best Practices SLSA 3 Scorecard supply-chain security Test & Report Lines of Code Quality Gate Status Security Rating Maintainability Rating Reliability Rating FOSSA Status

๐Ÿ“– Game Overview

Black Trigram (ํ‘๊ด˜) is a realistic 2D precision combat game inspired by Korean martial arts philosophy and I Ching. This game teaches authentic Korean martial arts through precise anatomical targeting, featuring 70 vital points and 5 distinct combat archetypes implemented with modern web technology.

๐Ÿš€ Quick Start

๐ŸŒ Web Version (Recommended)

Instant Access

The easiest way to start is through your web browser:

1. Visit https://blacktrigram.com 2. Click "Play Now" 3. Start combat training immediately

๐Ÿ”ง Local Development

Developer Setup

For development or local hosting:

# Clone repository git clone https://github.com/Hack23/blacktrigram.git cd blacktrigram # Install dependencies npm install # Start development server npm run dev # Build for production npm run build # Run tests npm run test npm run test:combat

๐ŸŽฎ Gameplay Guide

โŒจ๏ธ Basic Controls

  • ๐Ÿƒ Movement: WASD or Arrow Keys - Tactical positioning and footwork
  • โš”๏ธ Techniques: 1โ€“8 (Eight Trigram-based combat techniques)
  • ๐Ÿ›ก๏ธ Guard: Spacebar - Defensive stance and blocking
  • ๐ŸŽฏ Vital Strikes: Mouse - Target vital point attacks
  • ๐Ÿ”„ Archetype Switch: Tab - Change between 5 combat types

๐Ÿฉธ 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

๐Ÿ“š Architecture & Documentation

Explore Black Trigram's complete architecture and technical documentation:

๐Ÿ”— Architecture & Design

๐Ÿ”— Combat & Mechanics

๐Ÿ”— Assets & Media

๐Ÿ”’ CI/CD & Security

  • ๐Ÿ”’ development.md - Comprehensive security measures and development practices
  • ๐Ÿ•ท๏ธ ZAP Security Scanning - OWASP ZAP dynamic application security testing
  • โšก Lighthouse Performance - Automated performance and accessibility audits
  • ๐Ÿ“„ SBOM Generation - Software Bill of Materials for transparency

๐ŸŽฏ Combat Philosophy

"In darkness, seek the perfect strike"

์–ด๋‘  ์†์—์„œ ์™„๋ฒฝํ•œ ์ผ๊ฒฉ์„ ์ฐพ์•„๋ผ

Each technique's focus:

๐ŸŽฎ Play Now ๐Ÿ“บ YouTube Channel ๐ŸŽต TikTok
  • ์›ํ˜• ํŠนํ™” (Archetype Specialization) - Unique approach per fighter type
  • ๐ŸŽฎ Enter the Dojang

    โš”๏ธ ๋น„์ˆ˜ (Bisu) - Lethal Technique

    Decisive unarmed combat methods for maximum effectiveness.

    Combat Mechanics

    Black Trigram implements realistic combat physics and body mechanics for authentic martial arts simulation:

    ๐Ÿฉธ Authentic Trauma System

    Realistic injury visualization and blood effects based on actual combat damage patterns.

    ๐Ÿฆด Bone Impact Audio

    Genuine bone contact and fracture sounds for realistic combat feedback.

    ๐Ÿซ Breathing Disruption

    Respiratory system targeting affects stamina and combat performance.

    โš–๏ธ Balance System

    Realistic stance and momentum physics affecting combat stability.

    ๐Ÿง  Consciousness States

    Progressive awareness impairment from successful combat techniques.

    ๐Ÿ˜ต Pain Response

    Physiological pain affecting performance and combat effectiveness.

    Combat Controls

    Master the combat input system for precise technique execution:

    ControlActionDescription
    WASD / Arrow KeysMovementTactical positioning and footwork
    1-8Trigram TechniquesExecute techniques based on Eight Trigrams
    SpacebarGuardDefensive positioning and blocks
    MouseVital StrikeTargeted vital-point attacks
    TabArchetype SwitchChange between 5 fighter types

    Training Modules

    Black Trigram offers comprehensive training modules for mastering Korean martial arts techniques:

    ๐ŸŽฏ ํ•ด๋ถ€ํ•™ ์—ฐ๊ตฌ (Anatomical Study)

    Learn 70 anatomical target points, precision striking, and advanced combat techniques.

    โš”๏ธ ๋ฌด์ˆ  ๊ธฐ๋ฒ• (Martial Techniques)

    Master fundamental techniques, Eight Trigram arts, and combination sequences.

    ๐ŸฅŠ ์‹ค์ „ ํ›ˆ๋ จ (Combat Training)

    Practice one-on-one combat, environmental fighting, and multiple opponent scenarios.

    ๐ŸŽญ ์›ํ˜• ํŠนํ™” (Archetype Mastery)

    Specialized training for each of the five fighter archetypes and their unique techniques.

    Technical Architecture

    Black Trigram is built with modern web technologies optimized for performance and realism:

    ๐ŸŽฎ Combat Physics Engine

    Built with PixiJS 8.x, React 19, and TypeScript for strict type safety and performance.

    โšก Performance Optimized

    Vite for fast development, WebGL for hardware acceleration, and Howler.js for audio.

    ๐ŸŽจ Visual Effects

    Custom particle engine, WebGL shaders, and 60fps animation for smooth combat.

    ๐ŸŽฏ Combat Components

    VitalPointTargeter, CombatTracker, TechniqueCalculator, and CombatAnalyzer systems.