03_WAND_ENTITY - NoitaModSDK/NoitaWandTemplate GitHub Wiki

3. Wand Entity

This chapter focuses on defining the wand as an entity in the game using XML. We'll break down the key components of the wand entity file and explain their roles.

The Wand Entity File (custom_wand.xml)

This XML file defines the wand as an entity in the game. Here's a typical structure with explanations:

<Entity tags="wand">
    <Base file="data/entities/base_item.xml">
        <ItemComponent
            item_name="Custom Wand"
            remove_on_death="1"
            collect_nondefault_actions="1"
            play_hover_animation="1">
        </ItemComponent>
    </Base>

    <AbilityComponent
        sprite_file="mods/your_mod_name/files/wands/custom_wand_gfx.xml"
        ui_name="Custom Wand"
        mana_max="200"
        mana_charge_speed="60"
        use_gun_script="1">
        <gun_config 
            shuffle_deck_when_empty="1"
            deck_capacity="8"
            actions_per_round="1"
            reload_time="20">
        </gun_config>
        <gunaction_config 
            spread_degrees="4"
            speed_multiplier="1">
        </gunaction_config>
    </AbilityComponent>

    <HotspotComponent 
        _tags="shoot_pos" 
        offset.x="8" 
        offset.y="0.5">
    </HotspotComponent>

    <LuaComponent
        execute_on_added="1"
        remove_after_executed="1"
        script_source_file="mods/your_mod_name/files/wands/custom_wand_setup.lua">
    </LuaComponent>

    <!-- Optional: Particle effect for floating wands -->
    <SpriteParticleEmitterComponent
        sprite_file="data/particles/ray.xml" 
        delay="0"
        lifetime="1.5"
        color.r="1" color.g="0.5" color.b="1" color.a="1"
        color_change.r="0" color_change.g="0" color_change.b="0" color_change.a="-0.5"
        velocity.x="0" velocity.y="0"
        gravity.x="0" gravity.y="10"
        velocity_slowdown="0"
        rotation="0"
        angular_velocity="0"
        scale.x="1" scale.y="0"
        scale_velocity.x="0" scale_velocity.y="4"
        emission_interval_min_frames="3"
        emission_interval_max_frames="6"
        count_min="1" count_max="1"
        randomize_position.min_x="-2"
        randomize_position.max_x="2"
        randomize_position.min_y="-2"
        randomize_position.max_y="2"
        randomize_velocity.min_x="-10"
        randomize_velocity.max_x="10"
        randomize_velocity.min_y="-10"
        randomize_velocity.max_y="10"
        velocity_always_away_from_center="1">
    </SpriteParticleEmitterComponent>
</Entity>

Key Components Explained

Base Properties

<Base file="data/entities/base_item.xml">
    <ItemComponent
        item_name="Custom Wand"
        remove_on_death="1"
        collect_nondefault_actions="1"
        play_hover_animation="1">
    </ItemComponent>
</Base>

This section defines basic item properties. The play_hover_animation attribute determines whether the wand floats (1) or not (0).

Ability Component

<AbilityComponent
    sprite_file="mods/your_mod_name/files/wands/custom_wand_gfx.xml"
    ui_name="Custom Wand"
    mana_max="200"
    mana_charge_speed="60"
    use_gun_script="1">
    <gun_config 
        shuffle_deck_when_empty="1"
        deck_capacity="8"
        actions_per_round="1"
        reload_time="20">
    </gun_config>
    <gunaction_config 
        spread_degrees="4"
        speed_multiplier="1">
    </gunaction_config>
</AbilityComponent>

This component defines the wand's core properties, including mana capacity, charging speed, and basic gun configurations.

Hotspot Component

<HotspotComponent 
    _tags="shoot_pos" 
    offset.x="8" 
    offset.y="0.5">
</HotspotComponent>

This component defines where spells are cast from. Adjust the offset.x and offset.y values to change the spell origin point relative to the wand's center.

Lua Component

<LuaComponent
    execute_on_added="1"
    remove_after_executed="1"
    script_source_file="mods/your_mod_name/files/wands/custom_wand_setup.lua">
</LuaComponent>

This component loads and executes the Lua script that sets up the wand's properties when it's created.

Particle Effect Component (Optional)

<SpriteParticleEmitterComponent
    sprite_file="data/particles/ray.xml" 
    delay="0"
    lifetime="1.5"
    color.r="1" color.g="0.5" color.b="1" color.a="1"
    ...
</SpriteParticleEmitterComponent>

This optional component adds a particle effect to the wand, which can be useful for floating wands or to add visual flair.

In the next chapter, we'll dive into the graphics configuration for your wand, including how to set up the sprite and any animations.

⚠️ **GitHub.com Fallback** ⚠️