Skip to main content

Crate rust_pixel

Crate rust_pixel 

Source
Expand description

RustPixel is a lightweight, glyph-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:

  • Glyph / 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 or SDL2, rendering PETSCII and custom symbol sets.
  • Graphics mode (web): Same core logic compiled to WASM, rendered via WebGL + 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.

Re-exports§

pub use init::get_game_config;
pub use init::get_pixel_texture_data;
pub use init::init_game_config;
pub use init::GameConfig;
pub use init::PixelTextureData;
pub use init::GAME_CONFIG;
pub use init::PIXEL_TEXTURE_DATA;
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
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.
init
Unified asset initialization for RustPixel applications.
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§

app
Macro app! to scaffold a RustPixel application entry.
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
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