project-overview.txt

Discord RPG Bot Project Documentation

Project Overview

A Discord bot for running a text-based RPG game with features including character creation, inventory management, travel system, and combat. The bot uses Redis for data storage and supports multiple servers through Discord's sharding system.

Directory Structure

project_root/
├── config/
│   ├── __init__.py
│   ├── settings.py          # Constants, env vars, guild configs
│   └── logging_config.py    # Logging setup
├── utils/
│   ├── __init__.py
│   ├── rate_limiter.py     # Rate limiting functionality
│   ├── redis_manager.py    # Redis connection management
│   ├── game_loader.py      # Game data loading utilities
│   ├── shard_manager.py    # Sharding utilities
│   ├── items/
│   │   ├── __init__.py
│   │   ├── manager.py      # Item management system
│   │   └── item.py         # Item class definitions
│   ├── character/
│   │   ├── __init__.py
│   │   ├── constants.py    # Character creation constants
│   │   ├── validators.py   # Validation functions
│   │   ├── session.py      # Character creation session management
│   │   ├── ui/
│   │   │   ├── __init__.py
│   │   │   ├── views.py    # UI view classes
│   │   │   ├── modals.py   # Modal classes
│   │   │   ├── buttons.py  # Button classes
│   │   │   └── embeds.py   # Embed creators
│   │   └── callbacks/
│   │       ├── __init__.py
│   │       ├── ability.py  # Ability score callbacks
│   │       ├── character.py # Character info callbacks
│   │       └── equipment.py # Equipment selection callbacks
│   └── world/
│       ├── __init__.py
│       ├── world.py        # World class
│       ├── continent.py    # Continent class
│       ├── region.py       # Region class
│       ├── location.py     # Location class
│       ├── area.py         # Area class
│       └── loaders.py      # World data loaders
├── cogs/
│   ├── __init__.py
│   ├── events/
│   │   ├── __init__.py
│   │   ├── bot_events.py   # Core bot events
│   │   ├── error_handler.py # Error handling
│   │   └── message_handler.py # Message processing
│   ├── character/
│   │   ├── __init__.py
│   │   └── creation.py     # Character creation commands
│   └── travel.py           # Travel system commands
└── main.py                 # Bot initialization

Redis Databases

DB 0 (Game Data):
Global game data (areas, items, actions)
Key format: 'items', 'areas', 'actions'
Hash storage for items and areas
String storage for actions (pickle serialized)

DB 1 (Player Data):
Character data
Key format: "character:{guild_id}:{user_id}"
Pickle serialized Character objects

DB 2 (Server Data):
Server-specific configurations and overrides
Key format: "server:{guild_id}:config"
Key format: "server:{guild_id}:area:{area_name}"
Key Naming Conventions

DB Management Classes
Level 1 (Lowest): ShardAwareRedisDB (utils/redis_manager.py)
  - Basic Redis operations
  - Shard awareness
  - Connection pooling

Level 2: DatabaseManager Cog (cogs/database.py)
  - High-level database operations
  - Game-specific operations
  - Uses ShardAwareRedisDB

Level 3: Game Loader (utils/game_loader.py)
  - Game data initialization
  - Data relationship resolution
  - Uses DatabaseManager for operations

Characters: character:{guild_id}:{user_id}
Server Config: server:{guild_id}:config
Server Areas: server:{guild_id}:area:{area_name}
Global Areas: areas (hash)
Global Items: items (hash)
Actions: actions (string, pickle serialized)
Area Connections Cache: area_connections_cache (24h TTL)
Party: party:{guild_id}:{user_id}

Core Systems
Character System
Character creation uses a session-based system
Point-buy ability score system
Class-based starting equipment
Inventory system with weight limits
Equipment slots system
Travel System
Area-based movement
Weather effects on travel
Travel time calculations
Party travel support
Encounter generation

World Structure
Hierarchy: World -> Continent -> Region -> Location -> Area
Session Management
Character creation sessions
Travel sessions
Party sessions
Important Classes
Item System
Base Item class
Weapon, Armor, Shield subclasses
ItemManager for handling item operations

Character Classes
Character base class
InventoryMixin for inventory management
Equipment management system

World Classes
Area class with NPC and item support
Location class for area grouping
Region and Continent classes for world structure

Configuration

Required Environment Variables

DISCORD_BOT_TOKEN=your_bot_token
OPENAI_API_KEY=your_openai_key
DISCORD_APP_ID=your_app_id

REDIS_CONFIG = {
    'url': 'redis://localhost',
    'player_db': 0,
    'game_db': 1,
    'server_db': 2
}

Critical Implementations to Maintain

Multi-server support
Character separation by guild
Shard awareness
Caching mechanisms
Proper error handling
Data consistency
Rate limiting

Dependencies

py-cord 2.6.1
redis.asyncio
aiofiles
openai

Development Notes

Always maintain guild_id context for operations
Consider cross-shard implications
Cache frequently accessed data
Handle Redis connection failures gracefully
Use proper serialization for complex objects
Maintain backwards compatibility
Consider rate limits in all operations

Testing Considerations

Use connection pooling
Implement proper caching
Batch operations where possible
Monitor memory usage
Handle concurrent access
Consider TTL for cached data

Security Considerations

Proper data segregation between guilds
Secure Redis connections
Input validation
Rate limiting
Error message sanitization

i'm going to start with the highest level directories so we can look through those, make sure all necessary imports are there, and then an init file for that directory (if one is needed). then down to the next level, since so far it seems like things are "pulled down" the structure, i.e. files lower in the folder draw on functions found in higher level files more than vice versa. is that accurate?  we should probably also start a list of files and the classes and functions in each so we can start creating documentation for the project. let's not make any changes, unless a true error is found in which case we can address it. i haven't actually run the code since dividing it up, i know it won't work. i want to parse through the code now with your help and get it as right as i can before i run it again and start addressing errors. does that sound like the best course of action? or is there a better way to approach this?

For documentation, I suggest we create a running "module map" as we go. We can use this format:

File: [filepath]
Classes:
  - ClassName: Brief description
    - Methods
    - Attributes
Functions:
  - function_name(): Brief description
Dependencies:
  - What this file imports
Exported by:
  - What components should be available to importers
  

Documentation:

File: config/settings.py
Classes: None
Functions: None
Constants:
  - DISCORD_BOT_TOKEN: Discord bot authentication token from env
  - OPENAI_API_KEY: OpenAI API key from env
  - DISCORD_APP_ID: Discord application ID from env
  - REDIS_CONFIG: Dictionary containing Redis connection settings
  - GUILD_CONFIGS: Dictionary containing per-guild configuration settings
  - FILE_PATHS: Dictionary mapping data type names to their JSON file paths
  - DEFAULT_STARTING_AREA: Default starting area for new characters
  - GLOBAL_COOLDOWN: Global cooldown time in seconds
  - CACHE_DURATION: Cache duration in seconds
Dependencies:
  - os: For environment variable access
  - dotenv: For loading .env file
  - pathlib.Path: For path handling
Exported by:
  - All constants should be available for import
  
  
File: utils/rate_limiter.py
Classes:
  - RateLimit: Manages rate limiting for different operations
    Methods:
      - __init__(): Initializes rate limit tracking
      - check_rate_limit(bucket: str) -> float: Checks wait time needed for a bucket
      - update_rate_limit(bucket: str, reset_after: float, is_global: bool): Updates rate limits
      - clear_bucket(bucket: str): Removes rate limit for specific bucket
      - clear_all(): Clears all rate limits
    Attributes:
      - rate_limits: Dict[str, float] - Stores bucket-specific rate limits
      - global_rate_limit: float - Stores global rate limit
      - lock: asyncio.Lock - Thread-safe access to rate limits
Dependencies:
  - asyncio: For async operations and Lock
  - time: For timestamp operations
  - logging: For logging (note: currently imported but not used)
  - typing.Dict: For type hints
Exported by:
  - RateLimit class should be exposed
  

File: utils/redis_manager.py
Classes:
  - ShardAwareRedisDB: Manages Redis connections with Discord shard awareness
    Methods:
      - __init__(bot): Initializes Redis connection management
      - init_pools(): Creates Redis connection pools for each shard
      - get_key(guild_id, key): Generates shard-specific Redis keys
      - get_pool(guild_id): Gets appropriate Redis pool for a guild
      - set(key, value, guild_id, expire): Stores data in Redis
      - get(key, guild_id): Retrieves data from Redis
      - delete(key, guild_id): Removes data from Redis
      - save_character(character): Saves Character object
      - load_character(user_id, guild_id): Loads Character object
      - save_area(area): Saves Area object
      - load_area(area_name): Loads Area object
      - save_all_characters(characters): Batch saves characters
      - migrate_from_json(characters_file): Migrates data from JSON to Redis
    Attributes:
      - bot: Discord bot instance
      - redis_pools: Dict of Redis connections per shard
      - default_ttl: Default time-to-live for Redis entries
      - lock: asyncio.Lock for thread safety
Dependencies:
  - redis.asyncio: For Redis operations
  - aioredis: Imported but not used (can be removed)
  - pickle: For object serialization
  - logging: For error logging
  - asyncio: For async operations
  - typing: For type hints
  - ..config.settings: REDIS_CONFIG, CHARACTERS_FILE
  
  
File: utils/game_loader.py
Functions:
  Game Data Loading:
    - load_game_data(bot): Main function to load all game data into Redis
    - load_items(redis_db, filename): Loads items from JSON to Redis
    - load_npcs(redis_db, item_lookup, filename): Loads NPCs from JSON to Redis
    - load_areas(redis_db, item_lookup, filename): Loads areas from JSON to Redis
    - load_characters(redis_db, filename, area_lookup, shard_id, bot): Loads characters with shard awareness
    - load_actions_redis(redis_db): Loads/caches actions in Redis
  
  Area Management:
    - resolve_area_connections_and_npcs(redis_db, area_lookup, npc_lookup): Links areas and NPCs
    - invalidate_area_connections_cache(redis_db): Clears area connection cache
    - get_area_by_name(area_name, area_lookup): Retrieves specific area
  
  World Structure Loading:
    - load_locations(area_lookup, npc_lookup, item_lookup, filename): Loads location data
    - load_regions(location_lookup, filename): Loads region data
    - load_world(continent_lookup, filename): Loads world data

Dependencies:
  Imports:
    - json: For JSON file handling
    - logging: For logging operations
    - aiofiles: For async file operations
    - typing: For type hints
    - .redis_manager: ShardAwareRedisDB
    - ..config.settings: FILE_PATHS (needs fixing like redis_manager)
  
  Class Dependencies (imported elsewhere):
    - Item class (with from_dict method)
    - NPC class (with from_dict method)
    - Area class (with from_dict method)
    - Character class (with from_dict method)
    - Location class (with from_dict method)
    - Region class (with from_dict method)
    - World class (with from_dict method)


File: utils/game_objects/base.py
Classes:
  - InventoryMixin: Base class for objects that can hold items
    Methods:
      - __init__(inventory, capacity): Initialize inventory system
      - add_item_to_inventory(item): Add item to inventory with checks
      - remove_item_from_inventory(item_name): Remove and return item
      - can_add_item(item): Check if item can be added
      - calculate_total_weight(): Get total inventory weight
      - transfer_item(from_entity, to_entity, item_name): Transfer items between entities
    Attributes:
      - inventory: List[Item] - List of held items
      - capacity: Optional[float] - Maximum weight capacity
  
  - Entity: Base class combining InventoryMixin with basic entity properties
    Methods:
      - __init__(name, stats, inventory, **kwargs): Initialize entity
    Attributes:
      - name: Optional[str] - Entity name
      - stats: Dict[str, Any] - Entity statistics
    Inherits:
      - InventoryMixin

Dependencies:
  - typing: For type hints
  - .items.Item: For item manipulation


# Module: utils/game_objects/items.py
File: utils/game_objects/items.py
Classes:
  1. Item (Base Item Class):
    Properties:
      - Name: str - Item name
      - Weight: float - Item weight
      - Type: str - Item type
      - Description: str - Item description
      - Effect: Dict - Parsed effects
      - Proficiency_Needed: Optional[str] - Required proficiency
      - Average_Cost: float - Item cost
      - Is_Magical: bool - Magic item flag
      - Rarity: str - Item rarity

    Methods:
      Serialization:
        - to_dict(): Dict[str, Any] - Convert item to dictionary
        - from_dict(data: Dict): Item - Create item from dictionary
        
      Effect Handling:
        - _parse_effect(effect): Parse and compile effect data
        - get_ac_bonus(): int - Get armor class bonus
        - get_damage(): Optional[Dict] - Get weapon damage info
        - get_healing(): int - Get healing amount
        
      Equipment:
        - can_be_equipped(slot: str): bool - Check slot compatibility
        - check_proficiency(character): bool - Check proficiency requirements
        - calculate_stat_changes(): Dict - Calculate stat modifications
        - apply_equip_effects(character): bool - Apply equipment effects
        - remove_equip_effects(character): Remove equipment effects
        
      Usage:
        - use_consumable(character): Tuple[bool, str] - Use consumable item
        - roll_damage(): Tuple[int, Optional[str]] - Roll weapon damage
        - update(**kwargs): Update item attributes

  2. Weapon(Item):
    Additional Properties:
      - damage_amount: str - Damage dice expression
      - damage_type: str - Type of damage
      - equip: bool - Equipment status

    Additional Methods:
      - to_dict(): Dict - Extended serialization
      - from_dict(data: Dict): Weapon - Create weapon from dictionary

  3. Armor(Item):
    Additional Properties:
      - ac_value: int - Base armor class
      - max_dex_bonus: int - Maximum DEX bonus
      - equip: bool - Equipment status

    Additional Methods:
      - to_dict(): Dict - Extended serialization
      - from_dict(data: Dict): Armor - Create armor from dictionary

  4. Shield(Item):
    Additional Properties:
      - ac_value: int - Shield bonus
      - equip: bool - Equipment status

    Additional Methods:
      - to_dict(): Dict - Extended serialization
      - from_dict(data: Dict): Shield - Create shield from dictionary

Dependencies:
  - typing: Optional, Dict, Any
  - .base: InventoryMixin (circular import warning)
  - logging: For error handling
  - random: For damage rolls

Key Features:
  - Comprehensive effect system supporting code execution
  - Equipment slot system
  - Proficiency checks
  - Stat modification tracking
  - Damage rolling system
  - Serialization support
  - Equipment management

  
File: utils/game_objects/character.py
Classes:
  - Character: Core player character class in the game
    Inherits from:
      - InventoryMixin: For inventory management
    
    Attributes:
      Base Info:
        - user_id: str - Discord user ID
        - name: Optional[str] - Character name
        - species: Optional[str] - Character race/species
        - char_class: Optional[str] - Character class
        - gender: Optional[str] - Character gender
        - pronouns: Optional[str] - Preferred pronouns
        - description: Optional[str] - Character description

      Game Stats:
        - stats: Dict[str, int] - Core ability scores (STR, DEX, etc.)
        - skills: Dict[str, Any] - Character skills
        - level: int - Character level (default: 1)
        - xp: int - Experience points
        - ac: int - Armor Class
        - max_hp: int - Maximum hit points
        - curr_hp: int - Current hit points
        - movement_speed: int - Base movement speed (default: 30)

      Equipment & Resources:
        - inventory: Dict[str, Item] - Character's items
        - equipment: Dict[str, Union[Item, List[Optional[Item]]]] - Equipped items
        - currency: Dict[str, int] - Character's money
        - capacity: float - Maximum carry weight
        - spells: Dict[str, Any] - Known spells
        - spellslots: Optional[Dict] - Available spell slots
        - abilities: Dict[str, Any] - Special abilities

      Location & Travel:
        - is_traveling: bool - Current travel status
        - travel_end_time: Optional[float] - Travel completion time
        - current_area: Optional[Area] - Current area
        - current_location: str - Current location name
        - current_region: str - Current region name
        - current_continent: str - Current continent name
        - current_world: str - Current world name
        - last_travel_message: Optional[Message] - Last travel update
        - last_interaction_guild: Optional[int] - Last Discord guild ID

    Methods:
      Serialization:
        - to_dict(): Convert character to dictionary
        - from_dict(data, user_id, area_lookup): Create character from dictionary
        
      Combat & Stats:
        - get_stat_modifier(stat): Calculate ability modifier
        - attack(target, weapon): Perform attack action
        - calculate_max_carry_weight(): Get carrying capacity
        
      Equipment:
        - equip_item(item, slot): Equip an item
        - unequip_item(slot): Remove equipped item
        - use_item(item): Use a consumable item
        
      Travel & Movement:
        - move_to_area(new_area): Change current area
        - move_to_location(new_location): Change current location
        - move_to_region(new_region): Change current region
        - move_to_continent(new_continent): Change current continent

Dependencies:
  - logging: For error tracking
  - typing: For type hints
  - random: For combat calculations
  - .base: InventoryMixin
  - .items: Item class references
  - .world: Area, Location, Region classes

Exported by:
  - utils/game_objects/__init__.py


Package: utils/travel_system/
Description: A comprehensive system for managing character travel in the game world.

Directory Structure:
utils/travel_system/
├── __init__.py (Package exports)
├── conditions.py (Travel modes and weather)
├── ui.py (Discord UI components)
├── party.py (Party management)
└── core.py (Core travel logic)

Components:

1. Conditions Module (conditions.py):
   Classes:
     - TravelMode:
       Description: Defines different methods of travel
       Attributes:
         - name: str - Mode name
         - speed_multiplier: float - Speed modifier
         - emoji: str - Display emoji
       Methods:
         - as_dict(): Get dictionary representation
         
     - WeatherEffect:
       Description: Weather conditions affecting travel
       Attributes:
         - name: str - Weather name
         - description: str - Weather description
         - speed_modifier: float - Travel speed multiplier
         - danger_level: float - Encounter chance modifier
         - emoji: str - Weather emoji
   
   Constants:
     - TRAVEL_MODES: Standard travel methods
     - WEATHER_EFFECTS: Available weather conditions

2. UI Module (ui.py):
   Classes:
     - TravelView:
       Description: Discord UI for travel progress
       Methods:
         - get_embed(): Create status embed
         - _get_travel_conditions(): Get current conditions
         - _get_points_of_interest(): Generate POIs
         - _get_travel_status(): Get progress status
       
     - CancelTravelButton:
       Description: Button for canceling travel
       
     - TravelEmbed:
       Description: Helper for creating travel embeds
       Methods:
         - weather_emojis(): Get weather emoji mapping
         - random_flavor_text(): Get random descriptions
         - get_time_of_day_condition(): Get time-based text

3. Party Module (party.py):
   Classes:
     - TravelParty:
       Description: Manages group travel
       Methods:
         - leader: Get party leader
         - get_slowest_member(): Find slowest member
         - get_lowest_health(): Find weakest member
         - get_member_names(): List member names
         - to_dict(): Convert to dictionary
         - from_dict(): Create from dictionary

4. Core Module (core.py):
   Classes:
     - TravelSystem:
       Description: Main travel management system
       Methods:
         - calculate_distance(): Get distance between points
         - get_travel_time(): Calculate journey duration
         - can_travel(): Check travel possibility
         - start_travel(): Begin journey
         - complete_travel(): Finish journey
         - cancel_travel(): Cancel journey
         - process_travel(): Handle travel progress
         - handle_travel_progress(): Update travel status

Dependencies:
  - discord.py: For UI components
  - typing: For type hints
  - dataclasses: For data structures
  - logging: For error tracking
  - asyncio: For async operations
  - redis: For data persistence

External Class Dependencies:
  - Character: From character system
  - Area: From world system
  - EncounterManager: From combat system

Usage Notes:
  - The system supports both single character and party travel
  - Weather conditions affect travel speed and encounter chances
  - Travel progress is displayed through interactive Discord embeds
  - Supports cross-shard travel between Discord servers
  - Includes encounter generation during travel
  - Supports different travel modes with varying speeds
  

File: utils/game_objects/npc.py
Classes:
  - NPC: Non-player character class
    Inherits from:
      - Entity: Base game entity class
    
    Attributes:
      Base Info:
        - name: Optional[str] - NPC name
        - role: Optional[str] - NPC role/occupation
        - description: Optional[str] - NPC description
        - dialogue: List[str] - Conversation lines
        
      Combat Stats:
        - stats: Dict[str, int] - Ability scores
        - max_hp: Optional[int] - Maximum hit points
        - curr_hp: Optional[int] - Current hit points
        - ac: Optional[int] - Armor Class
        - is_hostile: bool - Combat stance
        
      Abilities & Magic:
        - abilities: Dict[str, Any] - Special abilities
        - spells: Dict[str, Any] - Known spells
        - spellslots: Optional[Dict] - Spell slots
        
      Social:
        - attitude: Optional[str] - Disposition towards players
        - faction: Optional[str] - Associated faction
        - reputation: Optional[Dict] - Standing with groups
        - relations: Dict[str, Any] - Relationships
        
      Location & Movement:
        - current_area: str - Current location
        - movement_speed: Optional[int] - Movement speed
        - travel_end_time: Optional[float] - Travel completion time

    Methods:
      Serialization:
        - to_dict(): Convert NPC to dictionary
        - from_dict(data, item_lookup): Create NPC from dictionary
        
      Actions:
        - move_to_area(new_area): Change location
        - attack(target, weapon): Perform attack
        - get_dialogue(): Get next dialogue line
        - update(**kwargs): Update attributes

Dependencies:
  - logging: For error tracking
  - random: For combat calculations
  - .base: Entity class
  - .items: Item class references


File: utils/game_objects/containers.py
Classes:
  - Container: Represents in-game containers that can hold items
    Inherits from:
      - InventoryMixin: For inventory management
    
    Attributes:
      - name: str - Container name
      - description: str - Container description
      - capacity: Optional[float] - Maximum weight capacity
      - locked: bool - Container lock status
      - inventory: List[Item] - Stored items (inherited)
    
Methods:
      Inherited from InventoryMixin:
        - add_item_to_inventory()
        - remove_item_from_inventory()
        - can_add_item()
        - calculate_total_weight()
        - transfer_item()

Dependencies:
  - .base: InventoryMixin
  - typing: For type hints
  

# World Structure Documentation
World
└── has Continents[]
    └── has Regions[]
        └── has Locations[]
            └── has Areas[]

Package: utils/game_objects/world/
Description: Hierarchical world management system for game environments

Directory Structure:
utils/game_objects/world/
├── __init__.py (Package exports)
├── area.py (Base area unit)
├── location.py (Area collections)
├── region.py (Location collections)
├── continent.py (Region collections)
└── world.py (Top-level world management)

1. Area Class (area.py):
   Description: Base unit of player interaction and navigation
   Attributes:
     - name: str - Area name
     - description: str - Area description
     - coordinates: Tuple[float, float] - Spatial position
     - inventory: List[Item] - Available items
     - npcs: List[NPC] - Present NPCs
     - connected_areas: List[Area] - Linked areas
     - channel_id: Optional[int] - Discord channel reference
     - allows_intercontinental_travel: bool - Travel hub status
     - danger_level: int (0-10) - Area difficulty
   Key Methods:
     - add_npc()/remove_npc(): NPC management
     - add_item()/remove_item(): Inventory management
     - connect_area()/disconnect_area(): Area connections
     - get_npc(): NPC lookup

2. Location Class (location.py):
   Description: Collection of connected areas
   Attributes:
     - name: str - Location name
     - description: str - Location description
     - coordinates: Tuple[float, float] - Spatial position
     - areas: List[Area] - Contained areas
     - area_names: List[str] - Area reference list
   Key Methods:
     - add_area()/remove_area(): Area management
     - get_area(): Area lookup
     - get_all_npcs(): Aggregate NPC access
     - get_all_items(): Aggregate item access

3. Region Class (region.py):
   Description: Geographical region containing locations
   Attributes:
     - name: str - Region name
     - description: str - Region description
     - coordinates: Tuple[float, float] - Spatial position
     - locations: List[Location] - Contained locations
     - location_names: List[str] - Location reference list
   Key Methods:
     - add_location()/remove_location(): Location management
     - get_location(): Location lookup
     - get_all_areas(): Aggregate area access
     - calculate_center(): Region center calculation
     - get_closest_location(): Proximity search

4. Continent Class (continent.py):
   Description: Major landmass containing regions
   Attributes:
     - name: str - Continent name
     - description: str - Continent description
     - coordinates: Tuple[float, float] - Spatial position
     - regions: List[Region] - Contained regions
     - region_names: List[str] - Region reference list
   Key Methods:
     - add_region()/remove_region(): Region management
     - get_region(): Region lookup
     - get_all_locations(): Aggregate location access
     - get_travel_hubs(): Travel point access
     - calculate_center(): Continent center calculation

5. World Class (world.py):
   Description: Top-level world management
   Attributes:
     - name: str - World name
     - description: str - World description
     - coordinates: Tuple[float, float] - Reference position
     - continents: List[Continent] - Contained continents
     - continent_names: List[str] - Continent reference list
   Key Methods:
     - add_continent()/remove_continent(): Continent management
     - get_continent(): Continent lookup
     - get_all_regions()/locations()/areas(): Aggregate access
     - get_travel_network(): Travel connection mapping
     - get_path_between_areas(): Pathfinding

Common Features Across All Classes:
1. Serialization:
   - to_dict(): Convert to dictionary format
   - from_dict(): Create instance from dictionary
   - Proper type validation

2. Error Handling:
   - Comprehensive logging
   - Exception catching
   - Validation checks

3. Type Safety:
   - Full type hints
   - Optional handling
   - Union type support

4. Coordinate System:
   - Consistent (x, y) tuple format
   - Center calculation
   - Distance-based lookups

5. Name Management:
   - Synchronized name lists
   - Case-insensitive lookups
   - String-based removal support

Dependencies:
  - logging: Error tracking and debugging
  - typing: Type hint support
  - collections: For travel network mapping

Usage Patterns:
1. Area Navigation:
   ```python
   area1.connect_area(area2)
   path = world.get_path_between_areas(start_area, end_area)
   ```

2. Entity Management:
   ```python
   location.add_area(new_area)
   area.add_npc(new_npc)
   continent.get_travel_hubs()
   ```

3. World Traversal:
   ```python
   all_areas = world.get_all_areas()
   travel_network = world.get_travel_network()
   closest = region.get_closest_location(coordinates)
   ```

Data Flow:
World -> Continent -> Region -> Location -> Area

Each level maintains:
- Direct references to contained elements
- Name lists for lookups
- Coordinate information
- Serialization support
- Error handling
- Aggregate access methods

File: utils/items/manager.py
Description: Centralized system for managing game items with caching and persistence

Class:
  - ItemManager: Manages the creation, storage, and retrieval of game items
    
    Attributes:
      - bot: Discord bot instance for Redis access
      - items: Dict[str, Item] - Primary item storage
      - items_cache: Dict[str, Item] - Temporary item cache
      - cache_duration: int - Cache lifetime in seconds (default: 3600)
      - logger: Logger - Dedicated logging instance

    Methods:
      Initialization:
        - initialize(): 
          - Bootstraps item management system
          - Loads items from Redis or JSON fallback
          - Sets up initial cache
        
        - load_items_from_json():
          - Loads items from JSON file
          - Creates item instances
          - Populates primary storage
      
      Item Creation:
        - create_item(item_data: Dict[str, Any]) -> Optional[Item]:
          - Factory method for item instances
          - Supports: Item, Weapon, Armor, Shield
          - Handles type-specific attributes
          - Returns appropriate item subclass

      Item Management:
        - get_item(item_name: str) -> Optional[Item]:
          - Multi-level lookup (cache -> storage -> Redis)
          - Automatic cache population
          - Type-safe return

        - save_item(item: Item) -> bool:
          - Updates all storage layers
          - Redis persistence
          - Cache synchronization

        - delete_item(item_name: str) -> bool:
          - Removes from all storage layers
          - Cache cleanup
          - Redis cleanup

      Cache Management:
        - clear_cache():
          - Empties temporary cache
          - Preserves primary storage

        - reload_items() -> bool:
          - Full system refresh
          - Rebuilds from persistence
          - Resets cache

Dependencies:
  - typing: Type hints and safety
  - logging: Error tracking
  - json: JSON file handling
  - pickle: Object serialization
  - pathlib: File path management
  - .item: Item class definitions
    - Item: Base item class
    - Weapon: Combat item type
    - Armor: Defense item type
    - Shield: Defense item type

Storage Hierarchy:
1. Memory Cache (items_cache):
   - Fastest access
   - Temporary storage
   - 1-hour lifetime
   
2. Primary Storage (items):
   - In-memory dictionary
   - Full item collection
   - Runtime persistence
   
3. Redis Storage:
   - Permanent persistence
   - Cross-shard access
   - Hash storage format

Error Handling:
  - Comprehensive logging
  - Exception catching
  - Fallback mechanisms
  - Type validation

Usage Patterns:
1. Item Lookup:
   ```python
   item = await manager.get_item("sword")
   if item:
       # Item found in cache/storage/Redis