System Architecture Overview

🏗️ High-Level Architecture

The Item Drops plugin follows a layered architecture pattern that separates concerns and provides flexibility for different game types.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Godot Layer   │    │  Service Layer  │    │   Core Layer    │
│                 │    │                 │    │                 │
│ • ItemDrops     │◄──►│ • Drop Service  │◄──►│ • LootGenerator │
│   Node          │    │ • Inventory     │    │ • DropTable     │
│ • UI Components │    │   Service       │    │ • DropContext   │
│ • Physics       │    │ • Rule Service  │    │ • Modifiers     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

📦 Core Components

Loot Generation Engine

• LootGenerator - Main engine for generating drops
• DropTable - Configuration for possible drops
• DropContext - Contextual data for generation
• Modifiers - System for modifying drop behavior

Data Management

• ItemData - Item definitions and properties
• DropResult - Generated drop information
• DropInstance - Runtime drop instances

Integration Layer

• IItemProvider - Item database integration
• IInventoryIntegration - Inventory system integration
• IDropOddsResolver - Custom drop probability logic

🔗 Key Interfaces

ILootGenerator

public interface ILootGenerator
{
    string Id { get; }
    string Name { get; }
    string Description { get; }
    int Priority { get; }
    bool IsEnabled { get; }
    
    DropResult GenerateLoot(DropContext context);
    bool CanGenerate(DropContext context);
    bool IsValid();
}

IDrop

public interface IDrop
{
    string ItemId { get; }
    float Weight { get; }
    ItemRarity Rarity { get; }
    int MinQuantity { get; }
    int MaxQuantity { get; }
    
    bool CanDrop(DropContext context);
}

IItemProvider

public interface IItemProvider
{
    string Id { get; }
    string Name { get; }
    
    IItemData? GetItemData(string itemId);
    bool HasItem(string itemId);
    IEnumerable<string> GetAllItemIds();
    bool IsValid();
}

🎯 Design Patterns

Strategy Pattern

• Drop Modifiers - Different strategies for modifying drops
• Odds Resolvers - Different probability calculation strategies
• Item Providers - Different item database implementations

Builder Pattern

• DropTableBuilder - Fluent configuration of drop tables
• LootGenerationSettings - Configuration for generation

Factory Pattern

• ConditionFactory - Creates drop conditions
• ModifierFactory - Creates drop modifiers

🔄 Data Flow

1. Game Request → LootGenerator
2. Context Setup → DropContext
3. Table Selection → DropTable
4. Modifier Application → Modified Settings
5. Generation → DropResult[]
6. Post-Processing → Final Drops
7. Integration → Game Systems

Example Flow

// 1. Create generator
var generator = new LootGenerator();

// 2. Set up context
var context = new DropContext();
context.SetData("PlayerLevel", 25);
context.SetData("LuckModifier", 1.5f);

// 3. Add modifiers
generator.AddModifier(new LuckModifier(1.2f));
generator.AddModifier(new LevelBonusModifier(20, 1.3f));

// 4. Generate drops
var drops = generator.GenerateLoot(dropTable, context);

// 5. Process results
foreach (var drop in drops)
{
    inventorySystem.AddItem(drop.ItemId, drop.Quantity);
}

🧪 Testing Architecture

Unit Tests

• Core Logic Tests - Drop generation, probability calculations
• Modifier Tests - Individual modifier behavior
• Interface Tests - Contract compliance

Integration Tests

• End-to-End Tests - Complete drop generation flows
• Performance Tests - Large-scale generation scenarios
• Game Integration Tests - Real-world usage scenarios

Test Structure

Core/Tests/
├── Conditions/
├── DataDriven/
├── Drops/
├── Generation/
├── Modifiers/
└── Probability/

🔧 Configuration Architecture

Data-Driven Configuration

• YAML/JSON Support - External configuration files
• Schema Validation - Ensure configuration validity
• Hot Reloading - Runtime configuration updates

Runtime Configuration

• Drop Tables - Runtime modification support
• Modifiers - Dynamic addition/removal
• Context Data - Runtime context manipulation

🚀 Performance Considerations

Optimization Strategies

• Object Pooling - Reuse drop instances
• Lazy Loading - Load item data on demand
• Caching - Cache expensive calculations
• Batch Processing - Process multiple drops efficiently

Memory Management

• Struct Usage - Minimize heap allocations
• Disposable Pattern - Clean up resources
• Weak References - Avoid memory leaks

🔌 Extensibility Points

Custom Modifiers

public class CustomModifier : ILootModifier
{
    public string Id => "custom_modifier";
    public string Name => "Custom Drop Modifier";
    
    public LootGenerationSettings ModifySettings(LootGenerationSettings settings)
    {
        // Custom modification logic
        return settings;
    }
}

Custom Conditions

public class CustomCondition : IDropCondition
{
    public bool CanDrop(IDrop drop, DropContext context)
    {
        // Custom condition logic
        return context.GetData<bool>("CustomCondition", false);
    }
}

Custom Providers

public class CustomItemProvider : IItemProvider
{
    public IItemData? GetItemData(string itemId)
    {
        // Custom item lookup logic
        return customDatabase.GetItem(itemId);
    }
}

This architecture documentation is intended for developers extending the Item Drops plugin
For usage documentation, see the Getting Started guide