magic module structure

Guide for magic module structure

Magic System Module Structure

Overview

This document describes the implementation of the Magic System in src/systems/magic/, which provides spell casting, Bija consumption, and projectile mechanics.

Module Organization

src/systems/magic/
├── mod.rs           # Core definitions, plugin, events
├── cast_system.rs   # Spell loading and casting logic
└── projectile.rs    # Visual projectile movement and collision

Core Components

mod.rs - Core Definitions

Data Structures:
  • BijaCost: Represents required Bija items and quantities
  • SpellDefinition: Matches mantras.json schema (spell_id, name, level_req, bijas, max_hit, xp, spell_tier, effect fields)
  • MantrasJson: Root structure for loading mantras.json (combat_spells, utility_spells)
  • SpellDatabase: Resource storing HashMap<String, SpellDefinition>
Events:
  • CastSpellEvent: Triggered when player attempts to cast (caster, spell_id, target)
  • SpawnProjectileEvent: Triggered after successful cast (spell_id, source, target, max_hit)
Components:
  • ActiveSpell: Tracks currently selected spell (spell_id, autocast, last_cast_time)
Plugin:
  • MagicPlugin: Registers resources, events, and systems

cast_system.rs - Spell Casting Logic

Systems:

load_spells (Startup)

  • Reads data/mantras.json
  • Parses into MantrasJson structure
  • Populates SpellDatabase resource with combat and utility spells
  • Logs loaded spell count

cast_spell_system (Update)

  • Listens for CastSpellEvent
  • Validates:
    1. Magic level requirement (checks Skills component)
    2. Bija availability in Inventory
  • Consumes Bijas via RemoveItemEvent
  • Grants Magic XP via XpGainEvent
  • Spawns projectile via SpawnProjectileEvent (for combat spells)
  • Logs cast success/failure
Key Implementation Details:
  • Uses crate::systems::data::string_to_id() to convert Bija IDs to ItemId
  • Checks inventory.get_item_count() for each required Bija
  • Sends RemoveItemEvent for each consumed Bija
  • Grants base XP from spell definition (spell.xp)

projectile.rs - Visual Effects

Components:
  • MagicProjectile: Tracks projectile state (spell_id, target, speed, damage, start_pos)
Systems:

magic_projectile_movement (Update)

  • Spawns new projectiles from SpawnProjectileEvent:
    • Creates blue sphere mesh (0.2 radius)
    • Emissive material for glow effect
    • Positioned at source + Y offset (1.5)
  • Moves existing projectiles:
    • Calculates direction to target
    • Moves at constant speed (15.0 units/sec)
    • Checks distance for collision (< 0.5 threshold)
  • On collision:
    • Rolls damage (0 to max_hit)
    • Sends DamageDealtEvent
    • Despawns projectile
  • Despawns if target lost/dead

projectile_collision

  • Placeholder (collision handled in movement for simplicity)

Integration Points

Dependencies

  • crate::systems::player::inventory::{Inventory, RemoveItemEvent}
  • crate::systems::player::skills::{Skills, SkillType, XpGainEvent}
  • crate::systems::combat::DamageDealtEvent
  • crate::systems::data::{ItemId, string_to_id}

Registration

The MagicPlugin must be registered in src/systems/mod.rs:
app.add_plugins(MagicPlugin);

Data Flow

  1. Spell Selection (UI) → CastSpellEvent
  2. Validation (cast_system) → Level check, Bija check
  3. Consumption (cast_system) → RemoveItemEvent for Bijas
  4. XP Grant (cast_system) → XpGainEvent
  5. Projectile Spawn (cast_system) → SpawnProjectileEvent
  6. Visual Movement (projectile) → Moves toward target
  7. Collision (projectile) → DamageDealtEvent, despawn

Testing Considerations

  • test_cast_spell_success: Has level + bijas → Success
  • test_cast_spell_no_bijas: Has level, no bijas → Fail
  • test_cast_spell_low_level: Low level → Fail
  • test_bija_consumption: Verify correct quantities removed

Manual Testing

  1. Grant player Bijas (e.g., 100x air_bija, 100x chandra_bija)
  2. Open Spellbook UI
  3. Click "Air Pulse"
  4. Verify:
    • Bijas decrease by correct amount
    • Magic XP increases
    • Projectile spawns and travels
    • Damage applied on hit

Future Enhancements

  • Cooldown system (last_cast_time tracking)
  • Spell animations (particle effects)
  • Utility spell effects (healing, buffs)
  • Teleportation implementation
  • Auto-cast toggle functionality