1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
//! Inventory serialisation and deserialisation to/from JSON files on disk.
//!
//! This module provides two free functions — [`save_inventory`] and
//! [`load_inventory`] — that convert an [`crate::items::inventory::Inventory`]
//! to and from a human-readable JSON file. The format is intentionally simple
//! and hand-editable.
//!
//! # File format
//!
//! The JSON file is a single object with two top-level fields:
//!
//! ```json
//! {
//! "capacity": 36,
//! "slots": [
//! null,
//! { "item_byte": 2, "count": 7 },
//! null
//! ]
//! }
//! ```
//!
//! * `capacity` — the maximum slot count of the original inventory.
//! * `slots` — one entry per slot; `null` for empty slots, or an object with
//! `item_byte` (the value returned by [`crate::items::inventory::ItemType::to_byte`])
//! and `count`.
//!
//! # Save / load contract
//!
//! * [`save_inventory`] creates the file and any missing parent directories.
//! * [`load_inventory`] restores the inventory with the same `capacity` and
//! slot layout. Unknown `item_byte` values are silently replaced with
//! `I::default()` (the empty-slot sentinel), ensuring forward compatibility.
//! * Both functions propagate I/O and JSON errors as `Box<dyn std::error::Error>`.
use ;
use ;
// ─── On-disk format ──────────────────────────────────────────────────────────
/// Serialisable representation of an [`InventorySlot`].
/// Serialisable representation of an [`Inventory`].
// ─── save_inventory ───────────────────────────────────────────────────────────
/// Writes `inventory` to a pretty-printed JSON file at `path`.
///
/// Creates the file and any missing parent directories. If the file already
/// exists it is overwritten atomically (via [`std::fs::write`]).
///
/// # Parameters
///
/// * `inventory` — the [`crate::items::inventory::Inventory`] to serialise.
/// * `path` — filesystem path for the output file (e.g. `"saves/inventory.json"`).
///
/// # Errors
///
/// Returns a boxed error if:
/// * A parent directory cannot be created ([`std::io::Error`]).
/// * The JSON cannot be serialised ([`serde_json::Error`]).
/// * The file cannot be written ([`std::io::Error`]).
///
/// # Examples
///
/// ```rust,no_run
/// use voxel_framework::items::{DefaultItem, Inventory, save_inventory};
///
/// let mut inv = Inventory::<DefaultItem>::new(36);
/// inv.add(DefaultItem::IronOre, 5);
/// save_inventory(&inv, "saves/player.json").expect("failed to save inventory");
/// ```
// ─── load_inventory ───────────────────────────────────────────────────────────
/// Reads and deserialises an [`crate::items::inventory::Inventory`] from the
/// JSON file at `path`.
///
/// Unknown `item_byte` values in the file are decoded as `I::default()` (the
/// empty-slot sentinel), so save files from newer game versions load without
/// errors — the unknown items simply become empty slots.
///
/// # Parameters
///
/// * `path` — filesystem path of the JSON file written by [`save_inventory`].
///
/// # Errors
///
/// Returns a boxed error if:
/// * The file does not exist or cannot be read ([`std::io::Error`]).
/// * The file contents are not valid JSON or do not match the expected schema
/// ([`serde_json::Error`]).
///
/// # Examples
///
/// ```rust,no_run
/// use voxel_framework::items::{DefaultItem, load_inventory};
///
/// let inv = load_inventory::<DefaultItem>("saves/player.json")
/// .expect("failed to load inventory");
/// println!("iron ore: {}", inv.count_of(DefaultItem::IronOre));
/// ```
// ─── Tests ───────────────────────────────────────────────────────────────────