BreakEscape/planning_notes/player_preferences/FILE_MANIFEST.md

# Player Preferences - File Manifest

Complete list of files to be created or modified during implementation.

## Files to CREATE

### Database

```
db/migrate/YYYYMMDDHHMMSS_create_break_escape_player_preferences.rb
```

### Models

```
app/models/break_escape/player_preference.rb
```

### Controllers

```
app/controllers/break_escape/player_preferences_controller.rb
```

### Policies

```
app/policies/break_escape/player_preference_policy.rb
```

### Views

```
app/views/break_escape/player_preferences/show.html.erb
```

### Helpers

```
app/helpers/break_escape/player_preferences_helper.rb
```

### JavaScript

```
public/break_escape/js/ui/sprite-grid.js
```

### CSS

```
public/break_escape/css/player_preferences.css
```

**Note**: Break Escape uses `public/break_escape/css/` for all styles (not Rails asset pipeline).

### Tests - Models

```
test/models/break_escape/player_preference_test.rb
```

### Tests - Controllers

```
test/controllers/break_escape/player_preferences_controller_test.rb
```

### Tests - Policies

```
test/policies/break_escape/player_preference_policy_test.rb
```

### Tests - Integration

```
test/integration/sprite_selection_flow_test.rb
```

### Fixtures

```
test/fixtures/break_escape/player_preferences.yml
```

### Documentation

```
docs/PLAYER_PREFERENCES.md
```

---

## Files to MODIFY

### Routes

```
config/routes.rb
  + get 'configuration', to: 'player_preferences#show', as: :configuration
  + patch 'configuration', to: 'player_preferences#update'
```

### Models - DemoUser

```
app/models/break_escape/demo_user.rb
  + has_one :preference, as: :player, class_name: 'BreakEscape::PlayerPreference', dependent: :destroy
  + def ensure_preference!
```

### Models - Game

```
app/models/break_escape/game.rb
  + def inject_player_preferences(scenario_data)
  
  Modify:
  - generate_scenario_data (add call to inject_player_preferences)
```

### Controllers - GamesController

```
app/controllers/break_escape/games_controller.rb
  
  Modify:
  - create action (add sprite validation before starting game)
```

### Documentation

```
README.md
  + Section on Player Configuration

.github/copilot-instructions.md
  + Add player preferences to architecture section

CHANGELOG.md
  + Entry for player preferences feature
```

---

## File Count Summary

| Category          | Create | Modify | Total |
|-------------------|--------|--------|-------|
| Database          | 1      | 0      | 1     |
| Models            | 1      | 2      | 3     |
| Controllers       | 1      | 1      | 2     |
| Policies          | 1      | 0      | 1     |
| Views             | 1      | 0      | 1     |
| Helpers           | 1      | 0      | 1     |
| JavaScript        | 1      | 0      | 1     |
| CSS               | 1      | 0      | 1     |
| Routes            | 0      | 1      | 1     |
| Tests             | 4      | 0      | 4     |
| Fixtures          | 1      | 0      | 1     |
| Documentation     | 1      | 3      | 4     |
| **TOTAL**         | **14** | **7**  | **21**|

---

## Implementation Phases

### Phase 1: Core Backend (4 files)
1. Migration
2. PlayerPreference model
3. Update DemoUser model
4. Routes

**Checkpoint**: Run migration, verify model can be created

### Phase 2: Controller & Policy (3 files)
1. PlayerPreferencesController
2. PlayerPreferencePolicy
3. Helper

**Checkpoint**: Routes accessible, authorization works

### Phase 3: Frontend (3 files)
1. View (show.html.erb)
2. JavaScript (sprite-grid.js)
3. CSS (player_preferences.css)

**Checkpoint**: Configuration page renders with animated Phaser sprites

### Phase 4: Game Integration (2 files)
1. Update Game model (inject_player_preferences)
2. Update GamesController (validation flow)

**Checkpoint**: Preferences inject into game, validation redirects work

### Phase 5: Testing (5 files)
1. Model tests
2. Controller tests
3. Policy tests
4. Integration tests
5. Fixtures

**Checkpoint**: All tests pass

### Phase 6: Documentation (4 files)
1. README.md
2. copilot-instructions.md
3. CHANGELOG.md
4. PLAYER_PREFERENCES.md

**Checkpoint**: Documentation complete, feature ready for release

---

## Dependencies

### New Gems Required
- None (uses existing Rails/Phaser stack)

### Existing Assets Used
- `/break_escape/assets/characters/*.png` (16 sprite sheets)
- `/break_escape/assets/characters/*.json` (16 sprite atlases)
- `/break_escape/assets/icons/padlock_32.png` (lock overlay)

### External Libraries
- Phaser 3.60.0 (loaded via CDN in configuration view)

### External Libraries Used
- Phaser.js (already loaded in game)
- Rails 7 (ActiveRecord, ActionView, Pundit)

---

## Hacktivity Integration Notes

When mounted in Hacktivity, one additional file modification is required:

### Parent App: Hacktivity

```
app/models/user.rb
  + has_one :break_escape_preference, 
      as: :player, 
      class_name: 'BreakEscape::PlayerPreference', 
      dependent: :destroy
  + def ensure_break_escape_preference!
```

This is NOT part of the Break Escape codebase but should be documented for integration.

---

## Git Workflow

### Branch Name
```
feature/player-preferences-system
```

### Commit Strategy

1. **Migration & Models**:
   ```
   feat: Add PlayerPreference model with polymorphic player association
   ```

2. **Controller & Policy**:
   ```
   feat: Add PlayerPreferences controller with sprite selection UI
   ```

3. **Frontend**:
   ```
   feat: Add sprite preview grid with Phaser animations
   ```

4. **Game Integration**:
   ```
   feat: Integrate player preferences into game scenario data
   ```

5. **Validation Flow**:
   ```
   feat: Add scenario-based sprite validation before game start
   ```

6. **Tests**:
   ```
   test: Add comprehensive test coverage for player preferences
   ```

7. **Documentation**:
   ```
   docs: Document player preferences system
   ```

### Pull Request Title
```
Add Player Preferences System (Sprite & Name Customization)
```

---

End of File Manifest