โก Black Trigram (ํ๊ด) โ Performance Testing & Benchmarks
Comprehensive Performance Validation & Monitoring Framework
๐ Lighthouse Audits โข ๐ Performance Budgets โข ๐ฎ 60fps Combat Rendering
**๐ ISMS Alignment:** This document follows [Hack23 Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md) performance testing and monitoring requirements.
**๐ Document Owner:** CEO | **๐
Last Updated:** February 2026
**๐ Review Cycle:** Quarterly | **โฐ Next Review:** May 2026
---
## ๐ฏ Purpose & Scope
This document establishes the **comprehensive performance testing strategy, benchmarks, and optimization practices** for the Black Trigram Korean martial arts combat simulator, ensuring optimal gameplay experience and rendering performance aligned with **Hack23 ISMS [Secure Development Policy ยง8](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md#-performance-testing--monitoring-framework)**.
**Performance validation ensures:**
- โ
Smooth 60fps combat rendering on desktop (55fps+ mobile)
- โ
Optimal bundle sizes within performance budgets (<500KB initial, <2MB total)
- โ
Lighthouse scores meeting quality standards (90+ performance)
- โ
Continuous performance monitoring and regression prevention
- โ
Three.js scene optimization (instancing, LOD, culling)
- โ
**ISO/IEC 27001:2022 (A.8.6)** compliance for capacity management
- โ
**NIST CSF (ID.AM-1)** compliance for asset performance characteristics
---
## ๐ Related Documentation
| Document | Description |
|----------|-------------|
| [๐ ARCHITECTURE.md](ARCHITECTURE.md) | High-level C4 architecture and component views |
| [โ๏ธ COMBAT_ARCHITECTURE.md](COMBAT_ARCHITECTURE.md) | Combat system performance requirements |
| [๐งช UnitTestPlan.md](UnitTestPlan.md) | Unit testing strategy with coverage targets |
| [๐ฏ E2ETestPlan.md](E2ETestPlan.md) | End-to-end testing including performance scenarios |
| [๐ง WORKFLOWS.md](WORKFLOWS.md) | CI/CD pipeline with performance gates |
| [๐ก๏ธ SECURITY_ARCHITECTURE.md](SECURITY_ARCHITECTURE.md) | Security architecture and performance implications |
| [๐ game-status.md](game-status.md) | Current performance metrics and quality scores |
---
## ๐ Performance Standards & Current Metrics
### ๐ฏ Lighthouse Audit Targets
| Metric | Target Score | Status | Description |
|--------|-------------|--------|-------------|
| **Performance** | 90+ | ๐ฏ Target | Core Web Vitals and rendering speed |
| **Accessibility** | 95+ | ๐ฏ Target | ARIA labels, contrast, keyboard navigation |
| **Best Practices** | 95+ | ๐ฏ Target | Security headers, HTTPS, modern APIs |
| **SEO** | 90+ | ๐ฏ Target | Meta tags, structured data, crawlability |
### ๐ฎ Game Rendering Targets
| Metric | Desktop Target | Mobile Target | Description |
|--------|---------------|--------------|-------------|
| **Frame Rate** | 60fps | 55fps+ | Three.js scene rendering |
| **Frame Budget** | <16.67ms | <18.18ms | Per-frame processing time |
| **Draw Calls** | <100 | <50 | WebGL draw call budget |
| **Triangle Count** | <100K | <50K | Scene geometry budget |
| **Texture Memory** | <256MB | <128MB | GPU texture allocation |
| **Scene Load** | <2s | <3s | Initial scene loading time |
### โก Page Load Time Targets
| Metric | Target | Measurement Point |
|--------|--------|-------------------|
| **Initial Load** | <2 seconds | GitHub Pages / S3 deployment |
| **Time to Interactive (TTI)** | <3 seconds | Lighthouse audit |
| **First Contentful Paint (FCP)** | <1.5 seconds | Core Web Vitals |
| **Largest Contentful Paint (LCP)** | <2.5 seconds | Core Web Vitals |
| **Cumulative Layout Shift (CLS)** | <0.1 | Core Web Vitals |
| **Three.js Canvas Ready** | <1.5 seconds | WebGL context creation |
### ๐ฆ Bundle Size Analysis
**Build Output (Current):**
```
Bundle Analysis (gzipped):
โโโ index.js ~15 KB โ
Core app shell
โโโ react-vendor.js ~60 KB ๐ฆ React 19 + ReactDOM runtime
โโโ three-vendor.js ~150 KB ๐ฎ Three.js core
โโโ fiber-drei.js ~80 KB โ๏ธ @react-three/fiber + drei
โโโ game-components.js ~40 KB ๐ฅ Combat system components
โโโ audio-vendor.js ~25 KB ๐ต Howler.js audio engine
โโโ CSS Assets ~10 KB ๐จ Styles
โโโ Total Bundle ~380 KB โ
Within 500 KB budget
```
**Performance Status:**
- โ
**Initial Bundle**: Under 500 KB budget
- โ
**Three.js Optimized**: Tree-shaking applied
- โ
**Code Splitting**: Lazy-loaded non-critical components
- โ
**Asset Optimization**: WebM/Opus audio, compressed textures
### ๐ฏ Performance Budget
Performance budgets are defined in [`budget.json`](budget.json) and enforced via Lighthouse CI:
```json
[
{
"path": "/*",
"timings": [
{ "metric": "interactive", "budget": 6000 },
{ "metric": "first-contentful-paint", "budget": 3500 },
{ "metric": "largest-contentful-paint", "budget": 4000 },
{ "metric": "total-blocking-time", "budget": 1600 },
{ "metric": "cumulative-layout-shift", "budget": 0.1 },
{ "metric": "speed-index", "budget": 5000 }
],
"resourceSizes": [
{ "resourceType": "script", "budget": 180 },
{ "resourceType": "image", "budget": 200 },
{ "resourceType": "stylesheet", "budget": 50 },
{ "resourceType": "document", "budget": 20 },
{ "resourceType": "font", "budget": 50 },
{ "resourceType": "total", "budget": 500 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 59 }
]
}
]
```
---
## ๐งช Performance Testing Framework
### Overview
The performance testing framework ensures the application meets both web performance and game rendering requirements:
1. **Lighthouse Audits** โ Web performance, accessibility, best practices, SEO
2. **Three.js Rendering Profiling** โ Frame rate, draw calls, memory usage
3. **Bundle Size Monitoring** โ Build output analysis via `budget.json`
4. **E2E Performance Testing** โ Cypress-based interaction and load testing
5. **CI Integration** โ Automated performance testing in GitHub Actions
### Key Components
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#2979FF','primaryTextColor':'#fff','primaryBorderColor':'#0D47A1','lineColor':'#00C853','secondaryColor':'#FFD600','tertiaryColor':'#FF3D00'}}}%%
graph TB
A[๐จโ๐ป Code Changes] --> B[๐จ Build Application]
B --> C{๐ฆ Bundle Size Check}
C -->|โ
Within Budget| D[๐ Deploy to Staging]
C -->|โ Over Budget| E[โก Optimize & Rebuild]
E --> B
D --> F[๐ Lighthouse Audit]
F --> G{๐ Scores >90?}
G -->|โ Below Target| H[๐ง Performance Optimization]
G -->|โ
Pass| I[๐ฎ Three.js Profiling]
I --> J{๐ฏ 60fps Stable?}
J -->|โ Frame Drops| H
J -->|โ
Pass| K[โ
Deploy to Production]
H --> F
style A fill:#e3f2fd
style K fill:#c8e6c9
style H fill:#ffcdd2
style C fill:#fff9c4
style G fill:#fff9c4
style J fill:#fff9c4
```
---
## ๐ฌ Performance Testing Procedures
### 1. Lighthouse Audit Execution
**Local Testing:**
```bash
# Install Lighthouse CLI
npm install -g lighthouse
# Run Lighthouse audit
lighthouse https://blacktrigram.com/ --view
# Run with budget validation
lighthouse https://blacktrigram.com/ \
--budget-path=./budget.json \
--output=html \
--output-path=./lighthouse-report.html
```
### 2. Bundle Size Analysis
```bash
# Build application and analyze
npm run build
# Check build output sizes
npm run build:analyze
# View detailed build output
du -sh build/assets/*
```
### 3. Three.js Performance Profiling
**In-Game Profiling:**
```typescript
import { useFrame } from '@react-three/fiber';
import { Stats } from '@react-three/drei';
// Add Stats component in development
{process.env.NODE_ENV === 'development' && }
// Monitor frame time in useFrame
useFrame((state, delta) => {
// delta should be ~0.0167 (60fps) or less
if (delta > 0.02) {
console.warn('Frame drop detected:', (1/delta).toFixed(1), 'fps');
}
});
```
**Key Metrics to Monitor:**
- **Frame Time**: Target <16.67ms (60fps)
- **Draw Calls**: Monitor via `renderer.info.render.calls`
- **Triangles**: Monitor via `renderer.info.render.triangles`
- **Textures**: Monitor via `renderer.info.memory.textures`
- **Geometries**: Monitor via `renderer.info.memory.geometries`
### 4. E2E Performance Testing with Cypress
```bash
# Run all E2E tests including performance checks
npm run test:e2e
# Run specific performance-related tests
npx cypress run --spec "cypress/e2e/**/performance*"
```
---
## ๐ฎ Three.js Optimization Best Practices
### Rendering Optimization
- โ
**Instanced Rendering**: Use `` for repeated geometry (particles, indicators)
- โ
**LOD (Level of Detail)**: Use `` for distance-based mesh complexity
- โ
**Frustum Culling**: Enabled by default in Three.js, ensure meshes are properly bounded
- โ
**Object Pooling**: Reuse Three.js objects instead of creating/destroying per frame
- โ
**Geometry Merging**: Combine static geometry with `BufferGeometryUtils.mergeGeometries()`
### Memory Management
- โ
**Dispose Resources**: Always call `.dispose()` on geometries, materials, textures in `useEffect` cleanup
- โ
**Memoize Objects**: Use `useMemo` for geometries and materials that don't change
- โ
**Texture Compression**: Use KTX2/Basis Universal for compressed GPU textures
- โ
**Avoid Frame Allocations**: Never create `new THREE.Vector3()` inside `useFrame`
### React/Three.js Integration
- โ
**Minimize Re-renders**: Use `React.memo()` for Three.js components
- โ
**useFrame Efficiency**: Keep `useFrame` callbacks lightweight (<5ms)
- โ
**Ref-based Updates**: Mutate refs directly instead of using React state for animations
- โ
**Lazy Loading**: Use `React.lazy()` for non-critical scene components
---
## ๐ Performance Regression Prevention
### Automated Monitoring
**GitHub Actions Integration:**
- โ
Bundle size monitoring with `budget.json`
- โ
Lighthouse CI checks via workflow
- โ
Performance assertions in E2E tests
- โ
Build time monitoring
### Testing Checklist
**Before Release:**
- [ ] Lighthouse audit scores >90 (all categories)
- [ ] Bundle size within budget (<500 KB initial)
- [ ] Core Web Vitals pass (LCP <2.5s, CLS <0.1)
- [ ] 60fps stable on desktop (Chrome, Firefox, Safari)
- [ ] 55fps+ on mobile devices
- [ ] No memory leaks in Three.js scene (30-minute stress test)
- [ ] Draw calls within budget (<100 desktop, <50 mobile)
- [ ] E2E performance tests pass
- [ ] No performance regressions detected
---
## ๐ Compliance & Standards Alignment
**ISO/IEC 27001:2022:**
- **A.8.6 (Capacity Management)**: Performance budgets and monitoring ensure adequate capacity for business requirements
- **A.8.9 (Configuration Management)**: Performance monitoring ensures system stability during configuration and system changes
**NIST Cybersecurity Framework:**
- **ID.AM-1 (Asset Management)**: Performance characteristics documented as part of asset inventory
- **PR.IP-2 (Information Protection)**: Performance testing ensures security controls don't degrade UX
**CIS Controls:**
- **16.12 (Application Software Security)**: Performance testing validates security controls
- **16.13 (Application Performance Monitoring)**: Continuous monitoring ensures availability
**Hack23 ISMS:**
- [Secure Development Policy ยง8](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md) โ Performance Testing & Monitoring Framework
- [Classification Framework](https://github.com/Hack23/ISMS-PUBLIC/blob/main/CLASSIFICATION.md) โ Business impact of performance degradation
---
## ๐ Performance Evidence & Reports
### Live Performance Resources
- ๐ [Test & Report Workflow](https://github.com/Hack23/blacktrigram/actions/workflows/test-and-report.yml) โ CI/CD performance metrics
- ๐ฆ [Performance Budget](./budget.json) โ Resource size and timing budgets
- ๐ [Live Application](https://blacktrigram.com/) โ Production deployment for testing
- ๐ [SonarCloud Dashboard](https://sonarcloud.io/summary/new_code?id=Hack23_blacktrigram) โ Code quality metrics
- ๐ก๏ธ [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/Hack23/blacktrigram) โ Supply chain security
---
**๐ Document Owner:** CEO | **๐
Last Updated:** February 2026
**๐ Review Cycle:** Quarterly | **โฐ Next Review:** May 2026