usulpro
/
magic-building
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
magic-building/CLAUDE.md

15 KiB
Raw Blame History

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.