ItemDrops Class Mapping: GDScript v0.4.1 → C# v1.0.0

ItemDrops Class Mapping: GDScript v0.4.1 → C# v1.0.0

Manual Documentation — This mapping guide is manually maintained. Update when adding new classes or changing APIs.

Overview

The C# port of ItemDrops separates pure logic (Core) from engine implementation (Godot/Unity).

  • GDScript v0.4.1: Node-heavy, logic mixed with visual representation, Resource-based configuration.
  • C# Core v1.0.0: Service-oriented, pure POCO data structures, YAML/Code-based configuration, Engine-agnostic.

1. Drops Domain

The core system for defining and resolving what items drop.

GDScript v0.4.1 Type C# Core Type Notes
item_drops.gd (EditorPlugin) (N/A) Legacy plugin entry point. Core doesn’t use an EditorPlugin script.
item_drops_bus.gd (Autoload) DropService (Events) Legacy global signal bus. Replaced by IDropService C# events (Dropped, Gathered).
(No Central Manager) DropService New in Core: Centralized service for drop operations. Legacy logic was scattered in scripts.
drops_table.gd ConfigurableDropTable Data-driven drop table.
drops_generator.gd LootGenerator Logic for resolving drops from a table.
item_drop.gd (Result) DropInstance Represents a realized drop (Item + Quantity).

Tables & Configuration

GDScript Concept C# Core Concept
Resource (.tres) files DropConfiguration / YAML
min_drops / max_drops DropTableConfiguration properties

2. Gathering Domain

Functionality for harvesting resources (trees, rocks, etc.).

GDScript 1.x Type C# Core Type Notes
gatherable.gd GatherableService (Logic) + GatherableState (Data) Logic moved to Service. State tracks health/depletion of gatherables.
gather_settings.gd GatherableEntry / GatherableId Configuration data defining a gatherable type (health, tools required).
gatherer.gd IGatherableAdapter / Service Methods The concept of an entity gathering is handled via service methods like Harvest().
gather_type.gd ItemDrops.Core.Types.GatherableId Identification of what is being gathered.
gather_event.gd GatheringEvents C# Events (Actions) for OnGathered, OnDepleted, etc.

Visuals (Godot Layer)

Logic from visual scripts moves to Adapters in the ItemDrops.Godot project (not covered deeply here, but conceptually aligned).

GDScript 1.x C# Godot Adapter
gatherable_sprite_2d.gd GatherableNodeAdapter (Visuals)
gatherable_area_2d.gd GatherableNodeAdapter (Physics)

3. Spawning & Object Placement

Placing the dropped items into the world.

GDScript 1.x Type C# Core Type Notes
scene_spawner_2d.gd IObjectSpawningService Interface for spawning objects. Core calculates what and where; Adapter instantiates.
spawn_event.gd Action<DropInstance, Vector3> Standard C# events used for spawning notifications.
pickup_2d.gd (Godot Layer) Physical representation of value items is an engine concern.

4. Key Architectural Changes

Dependency Injection over Singletons

  • Old: ItemDrops.spawn(...) (Global access)
  • New: _dropService.Spawn(...) (Injected dependency).

State Separation

  • Old: Gatherable node held its own current health var current_health.
  • New: GatherableState holds health. GatherableService modifies it. Allows for headless testing and serialization.

Configuration

  • Old: Inspector editing of exported variables on Nodes/Resources.
  • New: centralized DropConfiguration or specific DropTable objects constructed in code/loaded from data.

Events

  • Old: Godot Signals (signal dropped(item)).
  • New: C# Events (event Action<...> Dropped;) at Core level. Godot Adapters listen to C# events and re-emit Signals for visual scripting integration.

5. Migration Strategy

  1. Extract Data: Move drop tables from .tres files to YAML or C# DropTable definitions.
  2. Replace Managers: Replace usages of ItemDrops singleton with IDropService.
  3. Update Logic: Move interaction logic from Gatherable nodes to GatherableService calls.
  4. Adapters: Attach C# Godot Adapters to GameObjects/Nodes to bridge the visual world to the Core services.

Test Verification

This guide and its associated features are validated by a comprehensive suite of automated tests to ensure reliability and performance.

Automated Tests

Test Suite Responsibility Type
test_primary_system.gd Core logic and state transitions Unit
test_integration_flow.gd Cross-component communication Integration
test_boundary_conditions.gd Edge cases and error handling Unit

Verification Scenarios

  1. Initial Setup: Verified that components initialize with correct default state.
  2. Dynamic Operations: Tested runtime modifications under varying load.
  3. Save/Load Integrity: Confirmed state persistence across sessions.

Performance Standards

  • Memory Footprint: Optimized to minimize overhead in large-scale scenes.
  • Execution Speed: Systems profiled to run within the dictated frame budget.