Crate rust_pixel

RustPixel is a lightweight 2D game engine and rapid‑prototyping toolkit that supports both text and graphics rendering modes. It is well‑suited for building pixel‑style games, terminal applications, and for isolating, benchmarking, and shipping CPU‑intensive core algorithms.

Rendering modes:

• Text mode: Runs in a terminal via crossterm, drawing with ASCII and Unicode/Emoji.
• Graphics mode (native): Uses wgpu or SDL2, rendering PETSCII and custom symbol sets.
• Graphics mode (web): Same core logic compiled to WASM, rendered via WebGL + JavaScript (see rust-pixel/web-template/pixel.js).

Core concepts:

• Cell: Smallest renderable unit (a character in text mode, or a fixed‑size glyph/sprite 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.

Re-exports

pub use paste;

Modules

algorithm

Algorithms and data structures used by demos and utilities (e.g., disjoint‑set/union‑find, A* pathfinding). Here integrates some common algorithms e.g. disjoint-set data structure, A*.

asset

Resource/asset manager with optional asynchronous loading for better compatibility with WASM. Asset module provides the resource manager. It supports async loading. It calls JavaScript methods to load resources asynchronously when running in WASM mode. https://www.reddit.com/r/rust/comments/8ymzwg/common_data_and_behavior/

audio

Audio playback utilities and abstractions. Audio module provides sound playback functionality for RustPixel games.

context

Runtime context, including the active rendering adapter and other shared state. Context encapsulates several public variables including stage, state, input events, etc. For simplicity, state is set to u8 type, you can create your own states using enums in your games. Context also integrates an RNG for user’s convenience. A render adapter is also provided to make it compatible with web, SDL, or terminal modes. Finally, an asset_manager is included as well.

event

Event system for input, timers, and custom user events. This event module provides a global event center and a global timer center. For comparison testing: thread_local! + Rc<RefCell> vs Mutex + lazy_static

event_mutex

Alternative event implementation used for benchmarking and mutex‑based comparisons. Mutex + lazy_static implementation for comparison This is the original implementation using Mutex

game

Game orchestration: integrates model and renderer, encapsulating the main loop. Game encapsulates Model and Render classes and implements the main loop. Be aware that all the Game, Model and Render instances have the same lifetime.

log

Logging facilities tailored for demos and examples. Log module provides various log functions, reference https://docs.rs/log4rs

render

Rendering subsystem supporting both text and graphics modes.

ui

UI framework for building character‑based interfaces, including widgets, layouts, events, and themes for rapid development.

util

Common utilities and data structures such as object pools, RNG, matrices, circles, and dots. Utilities for random, rect, PointU16… and a simple object pool: objpool.rs Some primitive algorithms: shape.rs

Macros

asset2sprite

Used to simplify the call to set_content_by_asset method

asset2sprite_raw

New macro specifically for handling raw paths (no path processing)

impl_widget_base

Helper macro for widget boilerplate

only_graphics_mode

only_terminal_mode

pixel_game

Macro pixel_game to scaffold a RustPixel application entry.

ui_event_handler

Helper macro for creating event handlers

Constants

GAME_FRAME

Target frames per second for the main game loop. Keep this moderate to conserve CPU.

LOGO_FRAME

Frame cadence used by the splash/logo animation in text mode, tuned for comparable perceived duration with lighter terminal rendering.