# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
BullTales is a Ren'Py visual novel game built using Ren'Py 8.3.4. The game follows a branching narrative structure with multiple episodes, character routes, and outcomes based on player choices.
## Development Commands
### Running the Game
```bash
# Launch Ren'Py and run the game
# Note: Requires Ren'Py SDK installed on the system
renpy BullTales
```
### Building Distributions
```bash
# Build for PC/Mac using Ren'Py launcher
# Configuration in project.json specifies packages: ["pc", "mac"]
renpy launcher build
```
### Android Build
```bash
# Build for Android (Release mode configured in project.json)
# Uses configuration from android.json
renpy android_build
```
## Architecture Overview
### Core Game Structure
The game is organized into modular components:
1. **Episodes System** (`game/episodes/`):
- `prologue.rpy` - Initial character introductions and Nancy route
- `episode_1.rpy` - Lauren's first date storyline
- `episode_2.rpy` - Lauren's second date and relationship development
- `episode_3.rpy` - Emma route with classroom and gym scenarios
- `side_dialog.rpy` - Additional character interactions
2. **Character System** (`game/utils/characters.rpy`):
- Implements `CharState` enum for character emotions (NORMAL, ANGRY, HAPPY, SAD, AROUSED, etc.)
- Dynamic character state management through `char_states` dictionary
- Character sprites automatically update based on state
3. **Scene Management** (`game/scenes.rpy`):
- Defines all animated scenes (scene_0 through scene_23)
- Handles GIF animations and frame sequencing
- Manages scene transitions and cumulative effects
4. **Location System** (`game/locations.rpy`):
- Time-based location variations (morning, afternoon, night)
- Interactive hotspots for navigation
- Dynamic location availability based on story progression
5. **Interaction Framework** (`game/interactions.rpy`):
- Manages clickable objects and navigation points
- Handles state-dependent interactions
- Implements hover effects for interactive elements
### Key Game Variables
The game tracks player progress through several critical variables:
- **Romance Points**: `nancy_right`, `lauren_right`, `lauren_right_2`, `emma_right`
- **Failure Tracking**: `mess_ups`, `emma_mess_ups` (3+ triggers game over)
- **Route Outcomes**: `nancy_outcome_prologue`, `lauren_outcome_episode_1`, `episode_2_outcome`, `emma_date1_outcome`, `emma_date2_outcome`
- **Special Flags**: `nancy_key_question_passed`, `gym_trap_success`, `perfect_first_and_second_date`, `gemmy_kiss`
### Decision Tree System
The game follows a complex branching narrative documented in `BullTales_Decision_Tree.md`. Key mechanics:
- Point thresholds determine scene outcomes (best/good/neutral/worst)
- Critical decisions can lock/unlock entire routes
- Bull Phone acts as a meta-narrator providing guidance/consequences
- Cross-episode consequences affect future interactions
## File Organization
```
game/
├── episodes/ # Story content by episode
├── images/ # Character sprites, backgrounds, scenes
├── audio/ # Music and sound effects
├── gui/ # UI assets
├── utils/ # Helper scripts and systems
├── scenes.rpy # Scene definitions
├── locations.rpy # Location definitions
├── script.rpy # Main game entry point
└── options.rpy # Game configuration
```
## Important Development Notes
1. **Character States**: When modifying character dialogue, ensure the character state is updated appropriately using `update_character_state()` function
2. **Scene Unlocking**: Sexual content scenes are gated by outcome variables - verify point calculations when modifying choice consequences
3. **Save Compatibility**: The game uses save directory "BullTales-1743738481" - structural changes may break existing saves
4. **Translation Support**: Spanish translation files exist in `game/tl/spanish/` - update these when adding new dialogue
5. **Android Building**: Uses keystore files `android.keystore` and `bundle.keystore` for signing APKs
6. **Asset Management**: GIF animations are pre-split into frames for performance - use ImageMagick for processing new animations
## Testing Considerations
- Test all romance routes to ensure point calculations work correctly
- Verify game over conditions trigger at appropriate mess_up thresholds
- Check scene unlocks match the decision tree documentation
- Test save/load functionality after structural changes
- Validate Android builds on actual devices (orientation: sensorLandscape)