rust_pixel/

lib.rs

// 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;