magic-building/CLAUDE.md

# Fantasy Universe Visual Generation Framework

## Project Overview

This repository contains a comprehensive fantasy universe with parallel worlds, locations, and characters. The system is designed to generate consistent visual representations using Gemini Flash Image (Nano Banana) through Claude Code and the Nano-Banana-MCP integration.

## Project Structure

```
/
├── CLAUDE.md                     # This file
├── PROJECT_STANDARDS.md          # Quality and style requirements
├── cities/
│   └── {city-name}/
│       ├── description.md        # City overview and lore
│       ├── images/              # Generated city views
│       ├── prompts/             # Successful prompts archive
│       └── locations/
│           └── {location-name}.md
├── locations/
│   └── {location-name}/
│       ├── description.md        # Location details and lore
│       ├── images/              # Generated location images
│       └── prompts/             # Successful prompts archive
├── heroes/
│   └── {hero-name}/
│       ├── description.md        # Character details and traits
│       ├── photos/              # Character portraits and scenes
│       └── prompts/             # Character-specific prompts
├── worlds/
│   └── {world-name}/
│       ├── description.md        # World rules and aesthetics
│       └── style-guide.md       # Visual style requirements
├── items/
│   └── {item-name}/
│       ├── description.md        # Item properties and lore
│       ├── images/              # Item visualizations
│       └── prompts/             # Item-specific prompts
├── creatures/
│   └── {creature-name}/
│       ├── description.md        # Creature details and abilities
│       ├── images/              # Creature visualizations
│       └── prompts/             # Creature-specific prompts
├── settings/
│   ├── clothing/
│   │   └── {style-name}/
│   │       ├── description.md   # Style specifications and usage
│   │       ├── images/          # Reference style images
│   │       └── prompts/         # Style-specific prompts
│   ├── transportation/
│   │   └── {transport-type}/
│   │       ├── description.md   # Transportation style details
│   │       ├── images/          # Reference images
│   │       └── prompts/         # Transportation prompts
│   ├── weapons/                 # Weapon styles and designs
│   ├── environments/            # Environmental style references
│   ├── architecture-styles/     # Architectural design patterns
│   └── magical-effects/         # Magical visual effect styles
└── scenes/
    └── {scene-name}/
        ├── description.md        # Scene context and story
        └── images/              # Generated scene images
```

## Entity Relationship System

### Cross-Reference Links
Each entity can reference other entities through standardized linking syntax in their description.md files:

- **Characters**: `[Character:name]` - Links to heroes/{name}/description.md
- **Locations**: `[Location:name]` - Links to locations/{name}/description.md or cities/{city}/locations/{name}.md
- **Worlds**: `[World:name]` - Links to worlds/{name}/description.md
- **Items**: `[Item:name]` - Links to items/{name}/description.md
- **Creatures**: `[Creature:name]` - Links to creatures/{name}/description.md
- **Cities**: `[City:name]` - Links to cities/{name}/description.md
- **Settings**: `[Setting:category/name]` - Links to settings/{category}/{name}/description.md

### Relationship Types
Define relationships between entities using these markers:

- **Ownership**: `[Item:sword-of-power] (owned by this character)`
- **Combat History**: `[Creature:ice-dragon] (defeated by this character)`
- **Location Associations**: `[Location:library] (frequent visitor)`
- **World Origin**: `[World:winter-world] (native to this world)`
- **Character Relationships**: `[Character:camelot] (father of this character)`
- **Item Interactions**: `[Item:mystical-staff] (can be wielded by this character)`
- **Style Preferences**: `[Setting:clothing/ancient-mage-robes] (typical attire for this character)`

## Settings System - Style and Visual References

### Purpose
The `settings/` directory contains reusable visual style references that can be applied across multiple characters, worlds, and scenarios. These are **thematic style guides** rather than specific entities.

### Categories

#### Clothing Settings
- **ancient-mage-robes**: Traditional high-status magical practitioner attire
- **modern-tactical-gear**: Contemporary military/security equipment
- **medieval-noble-attire**: Royal and aristocratic clothing styles
- **casual-modern-wear**: Contemporary everyday clothing

#### Transportation Settings
- **magical-mounts**: Fantasy creature transportation (dragons, unicorns, etc.)
- **modern-vehicles**: Contemporary cars, motorcycles, aircraft
- **medieval-horses**: Traditional horseback transportation
- **futuristic-transport**: Advanced sci-fi transportation methods

#### Weapon Settings
- **medieval-weapons**: Swords, shields, crossbows, traditional arms
- **modern-firearms**: Contemporary weapons and tactical equipment
- **magical-weapons**: Enchanted and mystical weapons
- **futuristic-weapons**: Advanced technology armaments

#### Environment Settings
- **magical-forests**: Enchanted woodland environments
- **urban-landscapes**: Modern city environments
- **ancient-ruins**: Historical and archaeological sites
- **winter-landscapes**: Cold weather and snow environments

#### Architecture Settings
- **medieval-castles**: Traditional fortress and castle designs
- **modern-buildings**: Contemporary architectural styles
- **magical-towers**: Fantasy magical structure designs
- **ancient-temples**: Religious and ceremonial architecture

#### Magical Effects Settings
- **elemental-magic**: Fire, water, earth, air magical visualizations
- **healing-magic**: Positive magical effect visualizations
- **dark-magic**: Shadow and necromantic magical effects
- **protective-magic**: Barrier and shielding magical effects

### Settings Integration in Prompts

#### Automatic Style Application
When generating images, Claude Code should:

1. **Identify applicable settings** based on character, world, and scenario context
2. **Load relevant style descriptions** from settings files
3. **Integrate style elements** into the generated prompt
4. **Maintain consistency** with established character and world aesthetics

#### Example Style Integration
```
Generate [Character:camelot] riding to [Location:guardian-library]

Auto-loaded styles:
- [Setting:clothing/ancient-mage-robes] for Camelot's attire
- [Setting:transportation/magical-mounts] for his transportation
- [World:camelot-world] style guide for overall aesthetic
```

### Style Prompt Template
```
[Base scene description] + [Character with Setting:clothing/style applied] + [Setting:transportation/method if applicable] + [World style context] + [Setting:environment/type for background] + [Technical specifications]
```

## Core Directives for Claude Code

### 1. Context Discovery and Assembly

When receiving image generation requests:

1. **Parse the request** to identify:
   - Characters mentioned
   - Locations referenced
   - Items involved
   - Creatures present
   - Scene context
   - Specific actions or poses

2. **Automatically gather context** by reading relevant files:
   - Character descriptions from `/heroes/{character-name}/description.md`
   - Location details from `/locations/{location-name}/description.md` or `/cities/{city-name}/locations/{location-name}.md`
   - World style guides from `/worlds/{world-name}/description.md` and `/worlds/{world-name}/style-guide.md`
   - Item specifications from `/items/{item-name}/description.md`
   - Creature details from `/creatures/{creature-name}/description.md`
   - **Style settings** from `/settings/{category}/{style-name}/description.md`
   - Reference images from appropriate directories

3. **Identify applicable settings** automatically:
   - Character clothing based on world, status, and scenario
   - Transportation methods appropriate to world and character
   - Environmental styles matching the location and world
   - Weapon styles suitable for character and scenario
   - Magical effects appropriate to character abilities

4. **Follow cross-references** by parsing linked entities:
   - When reading a character file, automatically load linked items, locations, and preferred settings
   - Resolve creature combat histories for context
   - Load world-specific style requirements for characters from different realms
   - Apply appropriate setting styles based on character preferences and world context

5. **Synthesize information** into a comprehensive understanding before prompt creation

### 2. Prompt Generation Framework

1. Learn prompting documentation in `docs/prompting-guide.md` with comprehensive guid with best practices of prompting using Gemini 2.5 Flash Image model.
2. Select the best matching case and create a prompt following templates in `docs/prompting-guide.md`, respect best practices described in this document, and adopt them to the actual user request
3. Prepare the professional prompt in English respecting all details and requirements passed by users and this project framework, aligned with documentation, selected template, and best practices

#### Settings Integration Protocol
- **Automatic Style Detection**: Identify appropriate settings based on character, world, and scenario
- **Style Consistency**: Ensure settings align with established character and world aesthetics
- **Hierarchical Application**: World styles > Character preferences > Scenario requirements
- **Style Combination**: Blend multiple settings when appropriate (clothing + transportation + environment)

#### Character Consistency Protocol
- **Always reference unique identifying features** from character descriptions
- **Apply appropriate clothing settings** based on character status, world, and scenario
- **Include owned/wielded items** from character links
- **Maintain physical characteristics** across all generations
- **Use specific descriptors** rather than generic terms
- **Reference previous successful images** when available
- **Consider character relationships** for group scenes

#### Location Consistency Protocol
- **Establish architectural style** from world guidelines and architecture settings
- **Apply appropriate environmental settings** for location type
- **Include signature elements** that make locations recognizable
- **Maintain geographic and environmental logic**
- **Reference existing location images** for consistency
- **Consider location-specific creatures or items**

#### Item Integration Protocol
- **Reference visual descriptions** from item files
- **Apply appropriate weapon/item settings** for visual consistency
- **Maintain consistent appearance** across scenes
- **Consider item-character compatibility** from relationship links
- **Include magical/special effects** if specified using magical-effects settings

#### Creature Integration Protocol
- **Use detailed creature descriptions** for accurate representation
- **Consider creature-character relationships** (combat history, alliances)
- **Include creature abilities** in visual representation using appropriate effect settings
- **Maintain creature consistency** across different scenes

### 3. Settings Usage Examples

#### Clothing Application
```
"Generate Camelot in his study"
→ Auto-applies [Setting:clothing/ancient-mage-robes] based on character status
→ Result: Camelot wearing elaborate blue mage robes with golden runic embroidery
```

#### Transportation Integration
```
"Show Eliot traveling to the Guardian Library"
→ Auto-applies [Setting:transportation/magical-mounts] for fantasy world travel
→ Result: Eliot riding a magical steed appropriate to his mage status
```

#### Environmental Styling
```
"Create a scene in the winter world"
→ Auto-applies [Setting:environments/winter-landscapes] for background
→ Result: Appropriate snow, ice, and cold weather environmental details
```

### 4. Critical Prompting Guidelines

#### ALWAYS DO:
- **Use narrative descriptions** instead of keyword lists
- **Include world-specific style elements** in every prompt
- **Apply appropriate settings automatically** based on context
- **Reference character's unique identifying features** consistently
- **Integrate linked items and relationships** naturally
- **Specify lighting and atmosphere** appropriate to the scene
- **Include technical quality descriptors** for professional results
- **Maintain established visual continuity** across the universe
- **Follow cross-reference links** to gather complete context
- **Apply style settings consistently** across related generations

#### NEVER DO:
- Use disconnected keyword lists
- Ignore established character features
- Generate without consulting existing context files
- Create prompts without world style consistency
- Skip the iterative refinement process
- Forget to specify aspect ratios
- Ignore entity relationships and cross-references
- Apply inappropriate settings that conflict with character or world aesthetics

### 5. File Management Protocol

**Upon Image Approval:**
1. **Save image** to appropriate directory:
   - Character portraits → `/heroes/{character-name}/photos/`
   - Location shots → `/locations/{location-name}/images/` or `/cities/{city-name}/images/`
   - Item visualizations → `/items/{item-name}/images/`
   - Creature images → `/creatures/{creature-name}/images/`
   - Style references → `/settings/{category}/{style-name}/images/`
   - Scene compositions → `/scenes/{scene-name}/images/`

2. **Archive successful prompt** in corresponding `/prompts/` directory with descriptive filename

3. **Update cross-references** if new relationships are established in the scene

4. **Create scene description** if the image represents a specific story moment

5. **Document entity interactions** for future consistency

6. **Archive style applications** in appropriate settings `/prompts/` directories for reuse

### 6. Context Integration Commands

Use these patterns for efficient context gathering:

- `"Generate {character} in {location}"` → Auto-gather character, location, appropriate settings, and linked entity files
- `"Show {character} wielding {item}"` → Gather character and item descriptions, check compatibility, apply weapon settings
- `"Create {character} fighting {creature}"` → Load combat context from character's creature links, apply appropriate combat settings
- `"Show {location} with {creature} present"` → Gather location and creature contexts, apply environmental settings
- `"Generate scene with {character1} and {character2}"` → Load both characters and their relationship context, apply group scene settings
- `"Style {character} in {setting:category/name}"` → Apply specific style override to character
- `"Show {character} in {world} style"` → Apply world-specific styling to character appearance

This framework ensures consistent, high-quality visual generation that maintains narrative coherence, character/location integrity, proper entity relationships, and appropriate style application across the entire fantasy universe project.