ItemDrops Documentation

Welcome to the documentation for the ItemDrops plugin. This folder contains comprehensive documentation for developers using and extending the ItemDrops system.

📚 Documentation Structure

Getting Started ⭐ New Users Start Here

Quick Start Guide - 5-minute setup and first drops
Installation & Setup - Detailed installation instructions
Basic Concepts - Core concepts and terminology

Configuration Guides 🔧 Essential Reading

Data-Driven Drop Tables ⭐ Recommended Approach
Resource-Based Configuration ⚠️ Legacy Support
Migration Guide - Converting from Resources to Data-Driven
Configuration Schema - Complete JSON/YAML reference

Integration Guides

Godot Integration - Godot-specific implementation guide
Unity Integration - Unity-specific implementation guide

Advanced Topics 🚀 For Power Users

Conditions & Modifiers - Advanced drop logic
Custom Drop Logic - Extending the system
Performance Optimization - Best practices and benchmarks
Testing & Validation - Comprehensive testing strategies

API Reference

Core API - Pure C# library reference
Godot API - Godot integration API
Unity API - Unity integration API

Architecture & Design

Architecture Overview - POCS design and decisions
Testing Guide - Testing strategies and guidelines
Performance Guide - Performance optimization

Examples & Tutorials

Examples - Working code examples
Tutorials - Step-by-step tutorials
Benchmarks - Performance data and analysis

Maintenance

Improvements - Planned enhancements and roadmap
Troubleshooting - Common issues and solutions

🎯 Quick Recommendations

For New Projects

👉 Use Data-Driven Configuration with JSON/YAML files

✅ Superior editor experience with custom plugin
✅ Better maintainability and version control
✅ Runtime performance benefits
✅ Centralized configuration management

Start here: Data-Driven Drop Tables

For Existing Projects

👉 Use HybridDropTable for gradual migration

✅ Backward compatibility with existing Resources
✅ Conversion tools for smooth transition
✅ No breaking changes

Start here: Migration Guide

🔥 Why Data-Driven is Superior

Aspect	Resource Arrays	Data-Driven
Editor Experience	❌ Click-heavy, scattered files	✅ Single view, searchable
Validation	❌ Runtime only	✅ Compile-time + runtime
Performance	❌ Multiple resource loads	✅ Single parse, cached
Maintainability	❌ File fragmentation	✅ Centralized configuration
Version Control	❌ Noisy diffs	✅ Clean, meaningful changes
Backup/Export	❌ Complex file collection	✅ Single file export

🚀 Quick Start (5 Minutes)

1. Create a Drop Table

{
  "minDrops": 1,
  "maxDrops": 3,
  "dropChance": 0.8,
  "drops": [
    {
      "itemId": "health_potion",
      "weight": 50,
      "minQuantity": 1,
      "maxQuantity": 2
    },
    {
      "itemId": "gold_coin",
      "weight": 100,
      "minQuantity": 10,
      "maxQuantity": 50
    }
  ]
}

2. Use in Code

// Load the drop table
var dropTable = DataDrivenDropTable.LoadFromJson("res://data/drops/goblin_loot.json");

// Generate drops
var context = new LootContext { Level = 10, Luck = 0.5f };
var drops = new DropCalculator().GenerateDrops(dropTable, context);

// Spawn in world
foreach (var drop in drops)
{
    var node = SpawnDrop(drop, globalPosition);
    AddChild(node);
}

Next: Read the Quick Start Guide for complete setup instructions.

📖 Documentation Philosophy

Principles

Living Documents - Regularly updated with new features
Example-Driven - Working code examples for every concept
Engine-Specific - Separate guides for Godot and Unity
Performance-Focused - Optimization guides and benchmarks
Migration-Friendly - Clear upgrade paths from legacy approaches

Conventions

Code Examples - All examples are tested and functional
Version Tracking - Each document notes compatibility versions
Priority Marking - Features marked by implementation priority
Status Indicators - Current status of each feature/improvement

🔍 Finding Information

By Experience Level

🟢 Beginners: Quick Start → Basic Concepts → Data-Driven Configuration
🟡 Intermediate: Advanced Topics → API Reference → Examples
🔴 Advanced: Architecture → Performance → Custom Logic

By Use Case

🎮 Game Developers: Integration guides → Examples → Troubleshooting
🔧 Plugin Developers: API reference → Architecture → Testing
🏗️ System Architects: Design decisions → Performance → Migration

📞 Support & Feedback

Getting Help

Issues: Report bugs and feature requests in the main repository
Discussions: Use GitHub Discussions for questions and ideas
Documentation Issues: Report documentation problems separately

Contributing Feedback

Documentation Errors: Create issue with “Documentation” label
Missing Information: Suggest additions via discussions
Example Requests: Request specific examples or tutorials
Improvement Ideas: Add suggestions to improvements document

Documentation maintained alongside plugin development
Last Updated: November 2025
Plugin Version: 2.0
Recommended: Data-Driven Configuration