Trait ItemProvider 

pub trait ItemProvider {
    type Item: Copy + Eq + Hash + Debug;
    type Effect;
    type Monster;
    type CustomKind: Copy + Eq + Hash + Debug;

    // Required methods
    fn item_name(&self, item: &Self::Item) -> &str;
    fn item_description(&self, item: &Self::Item) -> &str;
    fn item_effect(&self, item: &Self::Item) -> Self::Effect;
    fn item_price(&self, item: &Self::Item) -> u32;
    fn can_use_outside_battle(&self, item: &Self::Item) -> bool;
    fn can_use_in_battle(&self, item: &Self::Item) -> bool;
    fn use_on_monster(
        &self,
        item: &Self::Item,
        monster: &mut Self::Monster,
    ) -> ItemResult;
    fn consume(&self, item: &Self::Item) -> bool;
    fn item_kind(&self, item: &Self::Item) -> ItemKind<Self::CustomKind>;

    // Provided methods
    fn on_teach_move<M: MonsterProvider>(
        &self,
        item: Self::Item,
        target: &mut MonsterInstance<M>,
    ) -> Option<ItemUseResult<Self::Item>> { ... }
    fn on_use_field(
        &self,
        item: Self::Item,
    ) -> Option<ItemUseResult<Self::Item>> { ... }
    fn usable_in(&self, item: &Self::Item) -> UsageContext { ... }
    fn apply_effect<M: MonsterProvider>(
        &self,
        provider: &M,
        item: Self::Item,
        ctx: UsageContext,
        target: Option<&mut MonsterInstance<M>>,
        rng: &mut dyn BattleRng,
    ) -> ItemUseResult<Self::Item> { ... }
}

Provider trait for item metadata, usage rules, and effects.

Game-specific crates implement this trait to supply all item data the engine needs: names, descriptions, prices, usage eligibility, and the logic for applying an item to a monster.

Associated types

• Item — The item identifier (typically an enum).
• Effect — The effect descriptor (heal amount, status cure, etc.).
• Monster — The monster / character type that items can target.

Required Associated Types

type Item: Copy + Eq + Hash + Debug

Concrete item identifier type.

type Effect

Describes what the item does when used.

type Monster

The monster / party-member type that items may be applied to.

type CustomKind: Copy + Eq + Hash + Debug

Game-specific item kind discriminant (e.g. an enum of custom sub-categories).

Required Methods

fn item_name(&self, item: &Self::Item) -> &str

Human-readable name of the item (e.g., "Potion").

fn item_description(&self, item: &Self::Item) -> &str

In-game flavour / description text.

fn item_effect(&self, item: &Self::Item) -> Self::Effect

The effect this item produces.

fn item_price(&self, item: &Self::Item) -> u32

Base purchase / sale price in the in-game currency.

fn can_use_outside_battle(&self, item: &Self::Item) -> bool

Whether the item may be used outside of battle (e.g. from the bag menu on the overworld).

fn can_use_in_battle(&self, item: &Self::Item) -> bool

Whether the item may be used during battle.

fn use_on_monster( &self, item: &Self::Item, monster: &mut Self::Monster, ) -> ItemResult

Attempt to apply the item’s effect to monster.

Returns ItemResult::Used on success, or an appropriate error variant if the item could not be applied.

fn consume(&self, item: &Self::Item) -> bool

Returns true if the item is consumed (removed from inventory) after a successful use. Permanent items (key items, reusable tools, etc.) return false.

fn item_kind(&self, item: &Self::Item) -> ItemKind<Self::CustomKind>

Classify the item into a gameplay category (Consumable, Equipment, KeyItem, Custom(...), etc.). Used by the engine for default shop/bag behaviours.

Equipment metadata (slots, stat bonuses) lives on the optional EquipProvider trait so that games without an equipment system never declare slot or stat types.

Provided Methods

fn on_teach_move<M: MonsterProvider>( &self, item: Self::Item, target: &mut MonsterInstance<M>, ) -> Option<ItemUseResult<Self::Item>>

Called when this item is used to teach a move to target. Returns None (the default) if this item is not a move-teaching item.

fn on_use_field(&self, item: Self::Item) -> Option<ItemUseResult<Self::Item>>

Called when this item is used in the field (overworld). Returns None (the default) if the item has no field effect.

fn usable_in(&self, item: &Self::Item) -> UsageContext

Where / whether this item may be used (field, battle, both, or none).

Defaults to UsageContext::FieldAndBattle. The use_item driver uses this to gate usage by the active context before dispatching the effect.

fn apply_effect<M: MonsterProvider>( &self, provider: &M, item: Self::Item, ctx: UsageContext, target: Option<&mut MonsterInstance<M>>, rng: &mut dyn BattleRng, ) -> ItemUseResult<Self::Item>

Apply the item’s effect to an optional target monster, in a context.

This is an opaque dispatch: the engine routes the call and the game owns ALL numbers — heal amounts, status cures, vitamins, level-up candy, repel steps, capture rolls, and any game-specific item bugs. The engine only reports the ItemUseResult back to use_item, which consumes from the bag on success.

provider is the game’s MonsterProvider instance, passed through so the effect implementation can query species data, stat formulas, etc.

Generic over the MonsterProvider so the engine never couples to a concrete monster model. Defaults to ItemUseResult::NoEffect so games (and tests) that only need bag/shop bookkeeping compile unchanged.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors