Skip to main content

voxel_framework/items/
mod.rs

1//! Item system — inventory, drop tables, hotbar, and persistence.
2//!
3//! This module provides the complete lifecycle of collectible items: they are
4//! spawned as world entities when voxels break, attracted to the player through
5//! a magnet system, inserted into a slot-based inventory, displayed on a hotbar,
6//! and finally saved to disk between sessions.
7//!
8//! # Core abstraction
9//!
10//! [`ItemType`] is the item counterpart of
11//! [`VoxelType`](crate::voxel::VoxelType): implement it for any
12//! `Copy + Hash + Default` enum to make that enum usable everywhere in the item
13//! pipeline.  The framework ships [`DefaultItem`] as a ready-made implementation
14//! covering common mineral pickups.
15//!
16//! # Module overview
17//!
18//! | Sub-module | Key types | Responsibility |
19//! |---|---|---|
20//! | [`drops`] | [`DropTable`], [`DroppedItem`], [`DropsPlugin`] | Spawn item entities on [`crate::world::VoxelBroken`]; magnet + pickup |
21//! | [`inventory`] | [`Inventory`], [`InventorySlot`], [`ItemPickedUp`] | Slot-based storage resource |
22//! | [`hotbar`] | [`HotbarState`], [`HotbarSelectionChanged`], [`HotbarPlugin`] | Selection state and keyboard/scroll input |
23//! | [`persistence`] | [`save_inventory`], [`load_inventory`] | JSON serialisation to/from disk |
24//!
25//! # Relationship to the voxel system
26//!
27//! Drops fire in response to [`crate::world::VoxelBroken`] messages emitted by
28//! the mining subsystem.  [`DropsPlugin`] subscribes to those messages and
29//! consults a [`DropTable`] to decide which items — and how many — to spawn.
30//! Because [`DropsPlugin`] is generic over `I: ItemType` it cannot be bundled
31//! inside [`crate::VoxelPlugin`]; game code must add it explicitly alongside
32//! [`crate::generator::GeneratorPlugin`].
33//!
34//! # Usage pattern
35//!
36//! ```rust,no_run
37//! use bevy::prelude::*;
38//! use voxel_framework::{VoxelPlugin, prelude::*};
39//! use voxel_framework::items::{DefaultItem, DropsPlugin, DropTable, ItemCollector};
40//!
41//! fn main() {
42//!     App::new()
43//!         // Core framework (includes HotbarPlugin automatically).
44//!         .add_plugins(VoxelPlugin::<DefaultVoxel>::new())
45//!         // Drop system — must be added by game code because it is generic.
46//!         .add_plugins(DropsPlugin::<DefaultItem>::new())
47//!         .add_systems(Startup, setup)
48//!         .run();
49//! }
50//!
51//! fn setup(
52//!     mut drop_table: ResMut<DropTable<DefaultItem>>,
53//!     mut commands: Commands,
54//! ) {
55//!     // Register which items each voxel type drops when broken.
56//!     drop_table.register(1, DefaultItem::RockFragment, 1, 3);
57//!     drop_table.register(2, DefaultItem::IronOre, 1, 2);
58//!
59//!     // Mark the player entity so the magnet system knows where to attract items.
60//!     // (In practice the player entity is spawned by `voxel_framework::player::spawn_player`
61//!     // and `ItemCollector` is attached to it via a separate startup system.)
62//!     commands.spawn(ItemCollector);
63//! }
64//! ```
65
66pub mod drops;
67pub mod hotbar;
68pub mod inventory;
69pub mod persistence;
70
71pub use drops::*;
72pub use hotbar::*;
73pub use inventory::*;
74pub use persistence::*;