dotzuki_engine/
lib.rs

1//! # dotzuki-engine
2//!
3//! Core trait definitions for a JRPG engine framework.
4//!
5//! This crate defines the foundational abstractions that any JRPG engine
6//! implementation must provide. It has **zero dependency** on specific game
7//! data — all types are generic associated types or marker traits that
8//! the implementing crate supplies.
9//!
10//! ## Design Philosophy
11//!
12//! The traits in this crate follow these principles:
13//!
14//! - **Generic over game data**: No concrete game-specific, item, or move types.
15//!   All identifiers are associated types bounded by `Copy + Eq + Hash + Debug`.
16//! - **Provider pattern**: Data providers (tilesets, maps, palettes, tile
17//!   metadata, render data) are obtained through a single `GameData` master
18//!   trait, enabling dependency injection and testing.
19//! - **No I/O, no platform**: This crate contains only trait definitions
20//!   and simple data types. No file loading, no GPU code, no platform calls.
21//!
22//! ## Modules
23//!
24//! | Module | Contents |
25//! |--------|----------|
26//! | [`tileset`] | `TilesetTrait` and `TilesetProvider` — tileset loading and querying |
27//! | [`tile_meta`] | `CollisionType`, `TileMetaTrait`, `TileMetadata` — collision and terrain |
28//! | [`tilemap`] | `TilemapEntry`, `Tilemap` — 16-bit tilemap with per-tile metadata |
29//! | [`map`] | `MapTrait`, `MapProvider`, `MapConnection` — map data and connections |
30//! | [`palette`] | `PaletteTrait`, `PaletteProvider` — colour palette lookups |
31//! | [`render_data`] | `RenderData` — display-name and metadata lookups for moves, items, species |
32//! | [`save`] | `SaveData`, `SaveManager`, `SaveStorage`, `SaveError` — save/load with CRC16 |
33//! | [`link`] | `NetworkTransport<M>`, `TransportError`, `ChannelTransport<M>`, `LinkRole`, JSON-line `link::codec` — game-agnostic link-play transport seam (zero-I/O) |
34
35// no_std port (GBA / thumbv4t):
36// - On bare-metal targets (`target_os = "none"`) the crate builds without
37//   std; a nightly-only `prelude_import` re-injects the alloc items
38//   (`Vec`, `String`, `Box`, `vec!`, `format!`, …) plus the core prelude so
39//   the existing code needs no per-module import churn.
40// - On hosted targets the crate keeps std (stable-toolchain compatible —
41//   required for the engine-dsl build-dependency path), which is why
42//   `no_std` itself is cfg-gated rather than unconditional.
43#![cfg_attr(target_os = "none", no_std)]
44#![cfg_attr(target_os = "none", feature(prelude_import))]
45// `prelude_import` is internal to the compiler; the lint is expected noise.
46#![cfg_attr(target_os = "none", allow(internal_features))]
47
48extern crate alloc;
49
50#[allow(unused_imports)]
51mod alloc_prelude {
52    pub use core::prelude::v1::*;
53    pub use core::convert::{TryFrom, TryInto};
54    pub use alloc::borrow::ToOwned;
55    pub use core::iter::FromIterator;
56    pub use alloc::boxed::Box;
57    pub use alloc::format;
58    pub use alloc::string::{String, ToString};
59    pub use alloc::vec;
60    pub use alloc::vec::Vec;
61    pub use core::{assert_eq, assert_ne, matches, todo, unimplemented, write, writeln};
62    pub use core::debug_assert;
63}
64
65#[cfg_attr(target_os = "none", prelude_import)]
66#[allow(unused_imports)]
67use alloc_prelude::*;
68
69pub mod hash;
70pub mod battle;
71pub mod camera;
72pub mod items;
73pub mod link;
74pub mod map;
75pub mod menu;
76pub mod metatile;
77pub mod overworld;
78pub mod palette;
79pub mod party;
80pub mod render;
81pub mod render_config;
82pub mod render_data;
83pub mod save;
84pub mod text;
85pub mod tile_meta;
86pub mod tilemap;
87pub mod tileset;
88pub mod trigger_manager;
89
90use core::fmt::Debug;
91use core::hash::Hash;
92
93/// Master trait that provides access to all game data subsystems.
94///
95/// `GameData` is the central dependency-injection point for the engine.
96/// Implementations supply concrete types for tilesets, maps, palettes,
97/// tile metadata, moves, items, and species, along with provider objects
98/// that serve the corresponding data.
99///
100/// # Type Parameters
101///
102/// * `Tileset` — A [`TilesetTrait`](tileset::TilesetTrait) implementation
103///   (typically an enum of tileset IDs).
104/// * `Map` — A [`MapTrait`](map::MapTrait) implementation (typically an
105///   enum of map IDs).
106/// * `Palette` — A [`PaletteTrait`](palette::PaletteTrait) implementation
107///   (typically an enum of palette IDs).
108/// * `TileMeta` — A [`TileMetaTrait`](tile_meta::TileMetaTrait) implementation
109///   for tile collision lookups.
110/// * `Move` — The move/ability ID type (`Copy + Eq + Hash + Debug`).
111/// * `Item` — The item ID type (`Copy + Eq + Hash + Debug`).
112/// * `Species` — The species/monster ID type (`Copy + Eq + Hash + Debug`).
113///
114/// # Example
115///
116/// ```ignore
117/// struct MonsterGameData;
118///
119/// impl GameData for MonsterGameData {
120///     type Tileset = TilesetId;
121///     type Map = MapId;
122///     type Palette = PaletteId;
123///     type TileMeta = TileMetaId;
124///     type Move = MoveId;
125///     type Item = ItemId;
126///     type Species = SpeciesId;
127///
128///     fn tileset_provider(&self) -> &dyn TilesetProvider<Self::Tileset> {
129///         &MY_TILESET_PROVIDER
130///     }
131///     // ... etc
132/// }
133/// ```
134pub trait GameData {
135    /// The tileset identifier type.
136    type Tileset: tileset::TilesetTrait;
137
138    /// The map identifier type.
139    type Map: map::MapTrait;
140
141    /// The palette identifier type.
142    type Palette: palette::PaletteTrait;
143
144    /// The tile metadata identifier type.
145    type TileMeta: tile_meta::TileMetaTrait;
146
147    /// The move (ability/skill) identifier type.
148    type Move: Copy + Eq + Hash + Debug;
149
150    /// The item identifier type.
151    type Item: Copy + Eq + Hash + Debug;
152
153    /// The species (monster/character) identifier type.
154    type Species: Copy + Eq + Hash + Debug;
155
156    /// Returns a reference to the tileset data provider.
157    fn tileset_provider(&self) -> &dyn tileset::TilesetProvider<Self::Tileset>;
158
159    /// Returns a reference to the map data provider.
160    fn map_provider(&self) -> &dyn map::MapProvider<Self::Map>;
161
162    /// Returns a reference to the palette data provider.
163    fn palette_provider(&self) -> &dyn palette::PaletteProvider<Self::Palette>;
164
165    /// Returns a reference to the tile metadata provider.
166    fn tile_metadata(&self) -> &dyn tile_meta::TileMetadata<Self::TileMeta>;
167
168    /// Returns a reference to the render data provider.
169    fn render_data(
170        &self,
171    ) -> &dyn render_data::RenderData<Move = Self::Move, Item = Self::Item, Species = Self::Species>;
172}
dotzuki_engine/lib.rs

dotzuki_engine/
lib.rs
