BreakEscape/docs/SPRITE_SYSTEM.md

# Sprite System Documentation

## Overview

The game now supports two sprite formats:
1. **Legacy Format** - 64x64 frame-based sprites (old system)
2. **Atlas Format** - 80x80 JSON atlas sprites (new PixelLab characters)

## Available Characters

### New Atlas-Based Characters (80x80)

All atlas characters support 8-directional animations with the following types:
- **breathing-idle** - Idle breathing animation
- **walk** - Walking animation  
- **cross-punch** - Punch attack
- **lead-jab** - Quick jab
- **falling-back-death** - Death animation
- **taking-punch** - Getting hit (some characters)
- **pull-heavy-object** - Pushing/pulling (some characters)

#### Female Characters

| Key | Description | Animations |
|-----|-------------|-----------|
| `female_hacker_hood` | Hacker in hoodie (hood up) | 48 animations, 256 frames |
| `female_hacker` | Hacker in hoodie | 37 animations, 182 frames |
| `female_office_worker` | Office worker (blonde) | 32 animations, 152 frames |
| `female_security_guard` | Security guard | 40 animations, 208 frames |
| `female_telecom` | Telecom worker (high vis) | 24 animations, 128 frames |
| `female_spy` | Spy in trench coat | 40 animations, 208 frames |
| `female_scientist` | Scientist in lab coat | 30 animations, 170 frames |
| `woman_bow` | Woman with bow in hair | 31 animations, 149 frames |

#### Male Characters

| Key | Description | Animations |
|-----|-------------|-----------|
| `male_hacker_hood` | Hacker in hoodie (obscured face) | 40 animations, 208 frames |
| `male_hacker` | Hacker in hoodie | 40 animations, 208 frames |
| `male_office_worker` | Office worker (shirt & tie) | 40 animations, 224 frames |
| `male_security_guard` | Security guard | 40 animations, 208 frames |
| `male_telecom` | Telecom worker (high vis) | 37 animations, 182 frames |
| `male_spy` | Spy in trench coat | 40 animations, 208 frames |
| `male_scientist` | Mad scientist | 30 animations, 170 frames |
| `male_nerd` | Nerd (red t-shirt, glasses) | 40 animations, 208 frames |

### Legacy Characters (64x64)

| Key | Description |
|-----|-------------|
| `hacker` | Original hacker sprite |
| `hacker-red` | Red variant hacker |

## Using in Scenarios

### Atlas Character Configuration

```json
{
  "id": "npc_id",
  "displayName": "NPC Name",
  "npcType": "person",
  "position": { "x": 4, "y": 4 },
  "spriteSheet": "female_hacker_hood",
  "spriteTalk": "assets/characters/custom-talk.png",
  "spriteConfig": {
    "idleFrameRate": 8,
    "walkFrameRate": 10
  }
}
```

### Legacy Character Configuration

```json
{
  "id": "npc_id",
  "displayName": "NPC Name", 
  "npcType": "person",
  "position": { "x": 4, "y": 4 },
  "spriteSheet": "hacker",
  "spriteConfig": {
    "idleFrameStart": 20,
    "idleFrameEnd": 23
  }
}
```

## Configuration Options

### Atlas Format (`spriteConfig`)

- `idleFrameRate` - Frame rate for idle animations (default: 8)
- `walkFrameRate` - Frame rate for walk animations (default: 10)
- `attackFrameRate` - Frame rate for attack animations (default: 8)

### Legacy Format (`spriteConfig`)

- `idleFrameStart` - Starting frame for idle animation (default: 20)
- `idleFrameEnd` - Ending frame for idle animation (default: 23)
- `idleFrameRate` - Frame rate for idle animation (default: 4)
- `walkFrameRate` - Frame rate for walk animation (default: 10)
- `greetFrameStart` - Starting frame for greeting animation
- `greetFrameEnd` - Ending frame for greeting animation
- `talkFrameStart` - Starting frame for talking animation
- `talkFrameEnd` - Ending frame for talking animation

## Technical Details

### How It Works

1. **Loading**: Atlas characters are loaded in `game.js` using `this.load.atlas()`
2. **Detection**: The system automatically detects whether a sprite is atlas-based or legacy
3. **Animation Setup**: 
   - Atlas characters use `setupAtlasAnimations()` which reads animation metadata from JSON
   - Legacy characters use frame-based animation generation
4. **Direction Mapping**: Atlas directions (east/west/north/south) map to game directions (right/left/up/down)

### Animation Key Format

Atlas animations are automatically mapped to the game's animation key format:

**Atlas Format**: `breathing-idle_east`, `walk_north`, etc.  
**Game Format**: `npc-{npcId}-idle-right`, `npc-{npcId}-walk-up`, etc.

### 8-Directional Support

All atlas characters support 8 directions:
- **Cardinal**: north (up), south (down), east (right), west (left)
- **Diagonal**: north-east, north-west, south-east, south-west

## Portrait Images (`spriteTalk`)

The `spriteTalk` field specifies a separate larger image used in conversation scenes. This is independent of the sprite sheet format and works with both atlas and legacy sprites.

```json
"spriteTalk": "assets/characters/custom-talk-portrait.png"
```

If not specified, the system will fall back to using the sprite sheet for portraits.

## Adding New Characters

### From PixelLab

1. Export character animations from PixelLab
2. Run the conversion script:
   ```bash
   python tools/convert_pixellab_to_spritesheet.py \
       ~/Downloads/characters \
       ./public/break_escape/assets/characters
   ```
3. Add atlas loading to `public/break_escape/js/core/game.js`:
   ```javascript
   this.load.atlas('character_key',
       'characters/character_name.png',
       'characters/character_name.json');
   ```
4. Use in scenario with `"spriteSheet": "character_key"`

### Custom Sprites

For custom sprites, use the legacy format with frame-based configuration:

1. Create a sprite sheet with consistent frame size (e.g., 64x64)
2. Load in `game.js`:
   ```javascript
   this.load.spritesheet('custom_sprite', 'characters/custom.png', {
       frameWidth: 64,
       frameHeight: 64
   });
   ```
3. Configure frame ranges in scenario JSON

## Migration Guide

To migrate NPCs from legacy to atlas format:

1. Choose an appropriate atlas character from the available list
2. Update `spriteSheet` value to the atlas key
3. Replace frame-based config:
   ```json
   // Old
   "spriteConfig": {
     "idleFrameStart": 20,
     "idleFrameEnd": 23
   }
   
   // New
   "spriteConfig": {
     "idleFrameRate": 8,
     "walkFrameRate": 10
   }
   ```

## Character Assignment Examples

Based on M01 First Contact scenario:

- **Agent 0x00** (Player) → `female_hacker_hood` - Main protagonist, mysterious hacker
- **Agent 0x99** (Briefing) → `male_spy` - Handler/coordinator
- **Sarah Martinez** → `female_office_worker` - Corporate office worker
- **Kevin Park** → `male_nerd` - IT support/nerdy character
- **Maya Chen** → `female_scientist` - Research scientist
- **Derek Lawson** → `male_security_guard` - Security personnel

## Troubleshooting

### Sprite Not Loading

- Check that the atlas key matches exactly in both `game.js` and scenario
- Verify PNG and JSON files exist in `public/break_escape/assets/characters/`
- Check browser console for texture loading errors

### Animations Not Playing

- Verify `spriteConfig` uses correct format (frameRate vs frameStart/frameEnd)
- Check console for animation creation logs
- Ensure JSON atlas includes animation metadata

### Wrong Direction/Animation

- Atlas format uses automatic 8-directional mapping
- Check that the atlas JSON includes all required directions
- Verify direction mapping in `npc-sprites.js`

## Performance

Atlas sprites provide better performance:
- ✅ Single texture per character (efficient GPU usage)
- ✅ Pre-defined animations (no runtime generation)
- ✅ Optimized frame packing (2px padding prevents bleeding)
- ✅ 16 characters = 16 requests vs 2500+ individual frames