Skip to main content

Module items

Module items 

Source
Expand description

Item system — inventory, drop tables, hotbar, and persistence.

This module provides the complete lifecycle of collectible items: they are spawned as world entities when voxels break, attracted to the player through a magnet system, inserted into a slot-based inventory, displayed on a hotbar, and finally saved to disk between sessions.

§Core abstraction

ItemType is the item counterpart of VoxelType: implement it for any Copy + Hash + Default enum to make that enum usable everywhere in the item pipeline. The framework ships DefaultItem as a ready-made implementation covering common mineral pickups.

§Module overview

Sub-moduleKey typesResponsibility
dropsDropTable, DroppedItem, DropsPluginSpawn item entities on crate::world::VoxelBroken; magnet + pickup
inventoryInventory, InventorySlot, ItemPickedUpSlot-based storage resource
hotbarHotbarState, HotbarSelectionChanged, HotbarPluginSelection state and keyboard/scroll input
persistencesave_inventory, load_inventoryJSON serialisation to/from disk

§Relationship to the voxel system

Drops fire in response to crate::world::VoxelBroken messages emitted by the mining subsystem. DropsPlugin subscribes to those messages and consults a DropTable to decide which items — and how many — to spawn. Because DropsPlugin is generic over I: ItemType it cannot be bundled inside crate::VoxelPlugin; game code must add it explicitly alongside crate::generator::GeneratorPlugin.

§Usage pattern

use bevy::prelude::*;
use voxel_framework::{VoxelPlugin, prelude::*};
use voxel_framework::items::{DefaultItem, DropsPlugin, DropTable, ItemCollector};

fn main() {
    App::new()
        // Core framework (includes HotbarPlugin automatically).
        .add_plugins(VoxelPlugin::<DefaultVoxel>::new())
        // Drop system — must be added by game code because it is generic.
        .add_plugins(DropsPlugin::<DefaultItem>::new())
        .add_systems(Startup, setup)
        .run();
}

fn setup(
    mut drop_table: ResMut<DropTable<DefaultItem>>,
    mut commands: Commands,
) {
    // Register which items each voxel type drops when broken.
    drop_table.register(1, DefaultItem::RockFragment, 1, 3);
    drop_table.register(2, DefaultItem::IronOre, 1, 2);

    // Mark the player entity so the magnet system knows where to attract items.
    // (In practice the player entity is spawned by `voxel_framework::player::spawn_player`
    // and `ItemCollector` is attached to it via a separate startup system.)
    commands.spawn(ItemCollector);
}

Re-exports§

pub use drops::*;
pub use hotbar::*;
pub use inventory::*;
pub use persistence::*;

Modules§

drops
Drop table, world-entity lifecycle, and magnet pickup systems.
hotbar
Hotbar selection state, keyboard/scroll input, and the HotbarPlugin.
inventory
Slot-based inventory resource and the ItemType trait.
persistence
Inventory serialisation and deserialisation to/from JSON files on disk.