rust_pixel 2.4.0

2d pixel-art game engine & rapid prototype tools support terminal, wgpu and web...
Documentation 
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

// RustPixel
// copyright zipxing@hotmail.com 2022～2026

//! **RustPixel** is a lightweight, tile-based 2D game engine and rapid-prototyping toolkit.
//!
//! It provides a unified abstraction for both **terminal** and **graphic** rendering modes
//! (including WebAssembly), allowing developers to build pixel-style games, tools, and
//! simulation prototypes with minimal boilerplate.
//!
//! RustPixel supports **TUI both with and without a real terminal environment**, thanks to its
//! built-in glyph atlas and software-rendered text engine. This enables rich UI overlays on
//! top of game layers even in pure graphic mode.
//!
//! Designed for clarity, portability, and fast iteration, RustPixel is ideal for:
//! - Tiles / PETSCII / ASCII / emoji-based pixel games
//! - Terminal applications & hybrid TUI-over-graphics UIs
//! - Rapid prototyping of gameplay ideas
//! - Cross-platform rendering (Desktop, Web, Mobile, Mini-Game platforms)
//!
//! RustPixel's architecture emphasizes simplicity and composability, making it a practical
//! foundation for building both experimental and production-ready pixel-driven experiences.
//!
//! Rendering modes:
//! - Text mode: Runs in a terminal via `crossterm`, drawing with ASCII and Unicode/Emoji.
//! - Graphics mode (native): Uses `wgpu`, rendering PETSCII and custom symbol sets.
//! - Graphics mode (web): Same core logic compiled to WASM, rendered via wgpu + JavaScript
//!
//! Core concepts:
//! - Cell: Smallest renderable unit (a character in text mode, or a fixed‑size glyph in graphics mode).
//! - Buffer: A collection of cells representing the screen state, with diff‑friendly updates.
//! - Panel/Sprite/Style: Higher‑level drawing abstractions that work uniformly across backends.
//!
//! Modules overview:
//! - `algorithm`, `event`, `util`: Always available; form the minimal runtime.
//! - `asset`, `audio`, `context`, `game`, `log`, `render`, `ui`: Enabled when not in `base` mode.
//!
//! Minimal build (base mode): Only `algorithm`, `event`, and `util` are compiled, reducing
//! dependencies for shipping as FFI or WASM libraries. This is ideal when you only need the
//! engine’s core data structures and event system.

// ============================================================================
// Asset Initialization Module
// ============================================================================

#[cfg(not(feature = "base"))]
pub mod init;

// Re-export commonly used items from init module
#[cfg(not(feature = "base"))]
pub use init::{
    get_game_config, init_game_config, GameConfig,
    GAME_CONFIG,
    get_pixel_layer_data, PixelLayerData, PIXEL_LAYER_DATA,
};

#[cfg(all(graphics_mode, not(target_arch = "wasm32")))]
pub use init::init_layered_pixel_assets;

#[cfg(target_arch = "wasm32")]
pub use init::wasm_init_pixel_assets;

#[cfg(not(feature = "base"))]
pub use init::{get_wasm_app_data, set_wasm_app_data};

/// Target frames per second for the main game loop. Keep this moderate to conserve CPU.
pub const GAME_FRAME: u32 = 60;

#[cfg(not(graphics_mode))]
pub const LOGO_FRAME: u32 = GAME_FRAME / 4 * 2;

#[cfg(graphics_mode)]
pub const LOGO_FRAME: u32 = GAME_FRAME / 4 * 3;

/// Re‑export the `paste` crate so downstream crates can use it in macros generated by this crate.
#[cfg(not(feature = "base"))]
pub use paste;

// ============================================================================
// Application Macro Module
// ============================================================================

/// Macros for scaffolding RustPixel applications.
///
/// Provides `app!` macro for generating
/// cross-platform game entry points.
#[cfg(not(feature = "base"))]
mod macros;

/// Algorithms and data structures used by demos and utilities (e.g., disjoint‑set/union‑find,
/// A* pathfinding).
pub mod algorithm;

/// Resource/asset manager with optional asynchronous loading for better compatibility with WASM.
#[cfg(not(feature = "base"))]
pub mod asset;

/// Event system for input, timers, and custom user events.
pub mod event;

// /// Alternative event implementation used for benchmarking and mutex‑based comparisons.
// pub mod event_mutex;

/// Common utilities and data structures such as object pools, RNG, matrices, circles, and dots.
pub mod util;

/// Audio playback utilities and abstractions.
#[cfg(not(feature = "base"))]
pub mod audio;

/// Runtime context, including the active rendering adapter and other shared state.
#[cfg(not(feature = "base"))]
pub mod context;

/// Game orchestration: integrates model and renderer, encapsulating the main loop.
#[cfg(not(feature = "base"))]
pub mod game;

/// Logging facilities tailored for demos and examples.
pub mod log;

/// Rendering subsystem supporting both text and graphics modes.
///
/// Components:
/// - Adapter: Rendering adapter interface (crossterm; winit + wgpu; wgpu-web).
/// - Cell: Base drawing unit (character in text mode; glyph/small bitmap in graphics mode).
/// - Buffer: Screen buffer built from cells, with efficient updates.
/// - Sprite: Higher‑level drawing primitive built on top of buffers.
/// - Layer: Collection of sprites managed as a group.
/// - Style: Foreground/background colors and other attributes.
/// - Scene: Unified drawing surface that works in both modes.
///
/// In text mode a cell is a Unicode character. In graphics mode a cell can be a fixed‑size dot
/// matrix image, a PETSCII character, or a custom texture. Graphics mode also supports per‑sprite
/// pixel offsets to improve expressiveness.
#[cfg(not(feature = "base"))]
pub mod render;

/// UI framework for building character‑based interfaces, including widgets, layouts, events,
/// and themes for rapid development.
#[cfg(not(feature = "base"))]
pub mod ui;