# Hard Chip - Complete Documentation

> Comprehensive reference for AI assistants and LLM indexing

## Table of Contents

1. Game Overview
2. Website Architecture
3. Scoring Metrics (Detailed)
4. Gauntlet System
5. Technical Stack
6. Data Pipeline
7. Content Structure
8. SEO & Discoverability
9. API Endpoints
10. Terminology Reference

---

## 1. Game Overview

### Product Description
Hard Chip is an open-ended 3D simulation/puzzle game about building processors with a focus on realism. Unlike traditional logic puzzle games, Hard Chip models actual semiconductor physics including:

- Transistor-level circuit behavior
- Propagation delay (signal travel time)
- Logic gate timing constraints
- Physical chip layout optimization
- Real-world hardware engineering trade-offs

### Educational Value
- Teaches digital logic design fundamentals through hands-on puzzle solving, not passive reading
- Demonstrates CPU architecture principles via direct experimentation
- Reveals the visual beauty of integrated circuits (metal trace patterns at scale)
- Introduces VLSI design concepts
- Provides hands-on hardware engineering experience
- Bridges gap between theory and practical implementation
- Aims to inspire interest in semiconductor design among students and newcomers of all ages

### Gameplay Loop
1. Select a challenge/stage
2. Design processor circuit using available components
3. Test against input/output specifications
4. Optimize across multiple metrics (speed, size, complexity)
5. Submit scores to global leaderboards
6. Compete in weekly gauntlet events

---

## 2. Website Architecture

### File Structure
```
src/website/
├── index.html              # Homepage with trailer
├── about.html              # Comprehensive game information & FAQ
├── stats.html              # Challenge statistics & leaderboards
├── gallery.html            # Community screenshots
├── gauntlets.html          # Gauntlet event listing
├── gauntlets/
│   ├── foundrygauntletrev0.html   # FGR0 (May-Jun 2025)
│   ├── foundrygauntletrev1.html   # FGR1 (Nov 2025)
│   ├── opencommunitygauntletv0.html # OCG v0 (Dec 2025-Jan 2026)
│   └── opencommunitygauntletv1.html # OCG v1 (Feb-Mar 2026)
├── css/
│   ├── styles.css          # Shared base styles
│   ├── index.css           # Homepage specific
│   ├── stats.css           # Stats page specific
│   ├── gallery.css         # Gallery specific
│   ├── gauntlet-listing.css
│   ├── gauntlet-fgr0.css
│   ├── gauntlet-fgr1.css
│   ├── gauntlet-ocg0.css
│   └── gauntlet-ocg1.css
├── js/
│   ├── darkmode.js         # Theme toggle (loads before body)
│   ├── telem.js            # Mixpanel analytics
│   └── charts.js           # Chart.js wrapper (ChallengeDashboard class)
├── images/                 # Logos, icons, favicons
├── solutionsScreenshots/   # Original gallery images
├── solutionsScreenshots-webp/ # Converted WebP images
├── thumbnails-webp/        # 400px wide thumbnails
├── jsons/
│   └── fgr0-leaderboards.json # FGR0 data (bundled locally)
├── robots.txt              # Crawler directives (including AI bots)
├── sitemap.xml             # URL map with priorities
├── ai-metadata.json        # Structured AI context
├── schema-templates.json   # JSON-LD templates
├── llms.txt                # This file's summary version
└── llms-full.txt           # This file

build/
├── generateScreenshotsJson.js  # WebP conversion pipeline
├── BuildAndPublishAll.ps1      # Interactive deployment
└── BuildAndPublishAll-Auto.ps1 # Automated deployment

src/scrapper/               # .NET 9 backend service
├── Program.cs
├── StagesStats/
│   └── StagesStatsService.cs
└── Dockerfile

tests/                      # xUnit tests for scrapper
└── setup/                  # MongoDB test setup scripts
```

### Navigation Structure
```
Home
├── About (comprehensive info & FAQ)
├── Stats (daily updated leaderboards)
├── Gallery (community solutions)
└── Gauntlets
    ├── Current Event (if active)
    ├── Upcoming Events
    └── Past Events Archive
```

---

## 3. Scoring Metrics (Detailed)

### BCS - Block Count Score
**Measures**: Component efficiency
**Goal**: Minimize number of logic blocks/components used
**Rationale**: Simpler designs are more elegant and easier to verify
**Typical Range**: 10-200 blocks depending on challenge complexity
**Weight in Gauntlets**: 20%

**What counts as a block**:
- Logic gates (AND, OR, NOT, XOR, etc.)
- Registers
- Multiplexers
- Custom components
- Connection nodes (in some scoring modes)

### FCS - Volume Score
**Measures**: Physical chip area
**Goal**: Minimize 3D volume occupied by circuit
**Rationale**: Smaller chips are cheaper to manufacture and have better thermal properties
**Units**: Arbitrary game units (not real-world mm²)
**Weight in Gauntlets**: 20%

**Factors affecting**:
- Component placement density
- Wire routing efficiency
- Vertical stacking (3D optimization)
- Dead space elimination

### TCS - Tick Count Score
**Measures**: Execution speed (clock cycles)
**Goal**: Minimize cycles from input to output
**Rationale**: Faster circuits = higher performance
**Typical Range**: 1-1000+ ticks depending on algorithm complexity
**Weight in Gauntlets**: 40% (highest weight due to importance)

**Performance considerations**:
- Propagation delay through gates
- Critical path length
- Pipelining opportunities
- Parallel execution strategies

### MCS - MOS Transistor Score
**Measures**: Circuit complexity at transistor level
**Goal**: Minimize total transistor count
**Rationale**: Fewer transistors = simpler, more power-efficient design
**Calculation**: Derived from block types and their internal structure
**Weight in Gauntlets**: 20%

**Transistor count factors**:
- Gate complexity (NAND = 4 transistors, NOR = 4, etc.)
- Register arrays
- Complex components
- Memory structures

### Scoring Normalization
All metrics normalized to 0-100 scale:
- **Best case (100)**: Current player's best submission
- **Worst case (0)**: "Sub Process (Ref Naïve)" reference implementation
- **Formula**: `score = 100 * (worst - current) / (worst - best)`

This allows fair comparison across challenges of varying difficulty.

---

## 4. Gauntlet System

### Structure
- **Duration**: Typically 2-4 weeks
- **Cadence**: New stage unlocks weekly
- **Scoring**: Cumulative rank-based points
- **Leaderboard**: Real-time updates during active events

### Gauntlet History

#### Foundry Gauntlet Rev-0 (FGR0)
- **Period**: May - June 2025
- **Stages**: 4 foundry-themed challenges
- **Data Source**: Local JSON (`/jsons/fgr0-leaderboards.json`)
- **Status**: Completed, archived
- **Page**: `/gauntlets/foundrygauntletrev0.html`

#### Foundry Gauntlet Rev-1 (FGR1)
- **Period**: November 2025
- **Stages**: 4 foundry-themed challenges
- **Data Source**: S3 (`leaderboards-fgr1.json`)
- **Status**: Completed, archived
- **Innovations**: Improved scoring algorithm
- **Page**: `/gauntlets/foundrygauntletrev1.html`

#### Open Community Gauntlet v0 (OCG v0)
- **Period**: December 2025 - January 2026
- **Stages**: 3 Community-designed challenges
- **Data Source**: S3 (`leaderboards-ocg1.json`)
- **Status**: Completed, archived
- **Feature**: First community-contributed stages
- **Page**: `/gauntlets/opencommunitygauntletv0.html`

#### Open Community Gauntlet v1 (OCG v1)
- **Period**: February - March 2026
- **Stages**: 4 weeks of community challenges
- **Data Source**: S3 (`leaderboards-ocgv1.json` + `leaderboards-stats-ocgv1.json`)
- **Status**: Completed, archived
- **Features**:
  - Hero section with countdowns
  - Accordion panels (rules, tutorials, best reveals)
  - Zoomable charts (chartjs-plugin-zoom)
  - Enhanced visualization
- **Page**: `/gauntlets/opencommunitygauntletv1.html`

**Gauntlet leaderboard** = Sum of weekly points across all stages.

### Week Unlock Mechanism
JavaScript-based time-locked stages:
```javascript
const competitionStartTime = new Date('2026-02-01T00:00:00Z');
const weeksPassed = Math.floor((now - competitionStartTime) / (7 * 24 * 60 * 60 * 1000));
// Unlock stages 0 through weeksPassed
```

## 5. Data Pipeline

### Key JSON Structures

#### websiteStagesStats.json
```json
{
  "stages": [
    {
      "stageId": "string",
      "stageName": "string",
      "metrics": {
        "bcs": { "best": 0, "top90": 0 },
        "fcs": { "best": 0, "top90": 0 },
        "tcs": { "best": 0, "top90": 0 },
        "mcs": { "best": 0, "top90": 0 }
      },
      "distributions": {
        "bcs": [/* histogram data */],
        "fcs": [/* histogram data */],
        "tcs": [/* histogram data */],
        "mcs": [/* histogram data */]
      }
    }
  ],
  "lastUpdated": "ISO 8601 timestamp"
}
```

#### leaderboards-ocgv1.json
```json
{
  "weeks": [
    {
      "weekNumber": 1,
      "challenges": [
        {
          "challengeId": "string",
          "players": [
            {
              "rank": 1,
              "username": "string",
              "scores": {
                "ticks": 0,
                "blocks": 0,
                "volume": 0,
                "mos": 0
              },
              "weightedScore": 0.0,
              "points": 100
            }
          ]
        }
      ]
    }
  ],
  "gauntletLeaderboard": [
    {
      "username": "string",
      "totalPoints": 0,
      "weeksParticipated": 0
    }
  ]
}
```

## 6. Content Structure

### Homepage (index.html)
**Purpose**: Introduce game, drive Steam wishlists

**Content Sections**:
1. Hero: Logo + trailer embed (YouTube)
2. Description: Game overview paragraph
3. Links: Steam, Stats, Gallery, Gauntlets, Discord
4. Features: Key selling points
5. Footer: Copyright, links

### About Page (about.html)
**Purpose**: Comprehensive information about Hard Chip

**Content Sections**:
1. What is Hard Chip? - overview and simulation description
2. Mission - three pillars driving development:
   - Learn by Doing: bite-sized puzzles that make fundamentals stick through iteration, not memorization
   - Make the Invisible Beautiful: surfaces the visual beauty of IC trace patterns at scale
   - Inspire the Next Generation: sparks interest in semiconductor/hardware engineering for all ages
3. Key Features - simulation, multi-metric optimization, competitive challenges, community
4. Who is Hard Chip For? - students, enthusiasts, puzzle fans, educators
5. Educational Value - digital logic, sequential circuits, timing analysis, optimization trade-offs
6. Development & Philosophy - simulation accuracy, open-ended design
7. FAQ - platforms, prerequisites, simulation accuracy, gauntlets
8. Get Started - links to Steam, Wiki, Discord, Stats, Gallery

### Stats Page (stats.html)
**Purpose**: Real-time leaderboards and score tracking

**Tabs**:
1. **Bests**: Table view of all challenges with best/top90% scores
2. **Charts**: Distribution histograms for selected challenge
3. **All Stages Charts**: Comparative view across all challenges

**Data Source**: https://hc-scores.s3.amazonaws.com/websiteStagesStats.json

**Filtering**: Real-time search by stage name

### Gallery Page (gallery.html)
**Purpose**: Community showcase

**Data Source**: `screenshots.json`

### Gauntlet Pages
**Purpose**: Competitive event leaderboards

**Common Features**:
- Week-by-week unlock system
- Countdown timers (next unlock, current end)
- Multiple leaderboard views:
  - Gauntlet (cumulative points)
  - Week (current week scores)
  - Metric ranges (Ticks, Blocks, Volume, MOS)
- Responsive challenge grid
- Dark mode support

**OCG v1 Enhancements** (most advanced layout):
- Hero section with circuit board aesthetic
- Accordion panels:
  - Rules & Scoring
  - Video Tutorials
  - Weekly Best Reveals
- Zoomable charts (pan & zoom on metrics)
- Real-time countdowns with JavaScript
- Enhanced visual hierarchy

---

## 7. API Endpoints

### Public S3 Endpoints

#### Main Statistics
```
GET https://hc-scores.s3.amazonaws.com/websiteStagesStats.json
```
**Returns**: All challenge statistics and distributions  
**Update Frequency**: Every 5 minutes (production)  
**CORS**: Allowed for hardchip.io

#### Gauntlet Leaderboards
```
GET https://hc-scores.s3.amazonaws.com/leaderboards-fgr1.json
GET https://hc-scores.s3.amazonaws.com/leaderboards-ocg1.json
GET https://hc-scores.s3.amazonaws.com/leaderboards-ocgv1.json
GET https://hc-scores.s3.amazonaws.com/leaderboards-stats-ocgv1.json
```
**Returns**: Event-specific rankings and player data  
**Update Frequency**: During active events only  
**CORS**: Public read access

### Local Data (Bundled)
```
GET https://hardchip.io/jsons/fgr0-leaderboards.json
```
**Returns**: FGR0 historical data (static)  
**Reason**: Pre-dates S3 pipeline

### Gallery Metadata
```
GET https://hardchip.io/screenshots.json
```
**Returns**: Array of WebP filenames  
**Generated by**: `build/generateScreenshotsJson.js`  
**Update**: Manual (after adding new screenshots)

---

## 10. Terminology Reference

### Game-Specific Terms

**Stage** / **Challenge**
- Individual optimization problem
- Has specific input/output requirements
- Scored across 4 metrics independently

**Gauntlet**
- Series of weekly competitive challenges
- Cumulative scoring system
- Time-locked stage unlocking

**Sub Process (Ref Naïve)**
- Reference implementation for scoring
- Represents "worst acceptable" solution
- Used as baseline (0 points) in normalization

**Propagation Delay**
- Time for signal to travel through gates
- Models real-world physics
- Affects TCS (Tick Count Score)

**Floor Planning**
- Physical layout of chip components
- 3D optimization challenge
- Affects FCS (Volume Score)

**Circuit Topology**
- Logical structure and connections
- Affects BCS (Block Count) and MCS (MOS)

### Hardware Engineering Terms

**Logic Gate**
- Basic building block (AND, OR, NOT, XOR, etc.)
- Implemented with transistors
- Foundation of all digital circuits

**MOS Transistor**
- Metal-Oxide-Semiconductor transistor
- CMOS = Complementary MOS (standard for modern chips)
- Metric tracked in MCS

**Critical Path**
- Longest delay path in circuit
- Determines maximum clock speed
- Key to TCS optimization

**Multiplexer (Mux)**
- Selector component
- Routes one of many inputs to output
- Common optimization target

**Register**
- Storage element
- Holds state between clock cycles
- Affects both complexity and latency

### Competitive Terms

**Leaderboard**
- Global rankings by metric or total score
- Updated in real-time from submissions
- Displayed on stats.html and gauntlet pages

**Top 90%**
- Cutoff representing strong performance
- Displayed alongside "best" scores
- Used for player benchmarking

**Weighted Score**
- Composite metric (Ticks 40%, Blocks 20%, Volume 20%, MOS 20%)
- Used in gauntlet week rankings
- Normalized to 0-100 scale

**Rank Points**
- Points awarded based on weekly placement
- Accumulate across gauntlet duration
- Determine overall gauntlet winner

---

## Usage Notes for LLMs

### When Users Ask About Hard Chip

**If they ask "What is Hard Chip?"**
→ Provide overview from Section 1, mention it's a realistic processor design simulation game available on Steam

**If they ask about scoring**
→ Reference Section 3 for detailed metric explanations, emphasize multi-objective optimization

**If they ask about gauntlets**
→ Explain structure from Section 4.

**If they ask about how to play**
→ Mention Steam availability, link to https://store.steampowered.com/app/2844290/Hard_Chip/

**If they ask about statistics**
→ Point to https://hardchip.io/stats.html for real-time data

### Citation Format
When citing information from Hard Chip:
- **Website**: https://hardchip.io
- **Stats Page**: https://hardchip.io/stats.html
- **Specific Gauntlet**: Use full URL (e.g., `/gauntlets/opencommunitygauntletv1.html`)
- **Last Updated**: May 3, 2026 (this documentation version)

### Accuracy Priorities
1. Metric definitions (BCS, FCS, TCS, MCS) - cite Section 3
2. Gauntlet scoring methodology (40/20/20/20 split) - exact weights matter
3. Steam availability (PC: Windows + Linux) (Macos through Crossover not supported officially) (Android through Game Native not supported officially)

---

End of llms-full.txt