FAQ

March 3, 2026 · View on GitHub

Installation

How to install on Windows?

Use WSL2 with Windows 11. RustPixel's terminal mode and WGPU mode both work well under WSL2.

What's the minimum Rust version?

Rust 1.71+. The engine uses features stabilized in that version.

How to install cargo-pixel?

cargo install rust_pixel
cargo pixel          # First run clones repo to ~/rust_pixel_work

Or from local source:

cargo install --path . --force

As of v2.1, SDL2 and Glow (OpenGL) backends have been removed. WGPU provides a modern, unified GPU API (Vulkan/Metal/DX12/WebGPU) that covers all platforms including web. This simplifies the codebase significantly — one GPU pipeline instead of three.

How does web rendering work without a separate backend?

Web mode uses the same WGPU pipeline as desktop. When compiled to WASM, wgpu automatically falls back to WebGL2 if WebGPU is unavailable in the browser. No separate adapter code needed.

What's the difference between `term` and `wgpu` mode?

term: Renders directly to a terminal emulator using crossterm. Characters are Unicode text, colors are ANSI. Works over SSH.
wgpu: Opens a native window with GPU rendering. Characters are tiles from Texture2DArray with mipmaps. Supports scaling, rotation, alpha blending, shader effects.

Both modes share the same Model code. Only the Render implementation differs.

How does the texture system work?

RustPixel uses GPU Texture2DArray with multiple 4096×4096 layers. All symbol types (Sprite, TUI, Emoji, CJK) are packed into the array with 3-level mipmaps (mip0/mip1/mip2). The engine auto-selects the appropriate mipmap level based on actual render size, ensuring crisp rendering at any scale. Single texture binding, instanced rendering, one draw call.

What is the 4-stage GPU pipeline?

Data → RenderBuffer: Collect cells from Buffer/Sprites into Vec<RenderCell>
RenderBuffer → RenderTexture: Draw to off-screen textures (RT0-RT3)
RT Operations: Blend/copy between textures (for transitions)
RT → Screen: Composite final output

RT convention: RT0/RT1 = transition sources, RT2 = main scene, RT3 = overlay/effects.

How do GPU transitions work?

Slide transitions use the RT pipeline: previous frame goes to RT0, current frame to RT1, a shader blends them into RT3 based on progress (0.0→1.0). Seven GPU effects are available: squares, heart, noise, rotate, bounce, dissolve, ripple. Five CPU effects also exist (slide, wipe, dissolve) that operate on cell buffers directly.

Application Development

How is an app structured?

Every app has a Model (game logic) and a Render (drawing). The app! macro generates scaffolding:

use rust_pixel::app;
app!(MyGame);

This creates MyGameGame struct, init_game(), run(), and WASM exports.

How do I differentiate graphics vs terminal code?

#[cfg(any(feature = "wgpu", target_arch = "wasm32"))]
{
    // GPU-only code: set_graph_sym, set_alpha, etc.
}

#[cfg(not(any(feature = "wgpu", target_arch = "wasm32")))]
{
    // Terminal-only code: load .txt assets, etc.
}

How do Model and Render communicate?

Use events for loose coupling:

// Model side
event_emit("MyApp.ScoreChanged");

// Render side (in handle_event)
if event_check("MyApp.ScoreChanged", "update_score") {
    // redraw score display
}

How do command line arguments work?

cargo pixel r myapp wg -r <project_path> <extra_args...> translates to:

cargo run -p myapp --features wgpu --release -- <project_path> <extra_args...>

args[1] = project/asset directory path (used by get_project_path())
args[2]+ = app-specific arguments

If only one arg is passed, it's the project path. If none, uses CARGO_MANIFEST_DIR or ..

How do I create a standalone project?

cargo pixel c myapp ..
cd ../myapp
cargo pixel r myapp wg -r

The standalone project depends on rust_pixel as a crate and has its own Cargo.toml.

MDPT (Markdown Presentation Tool)

How is MDPT different from terminal presenters like presenterm?

MDPT renders a complete TUI in a GPU window — no terminal emulator needed. This gives consistent rendering across platforms, GPU shader transitions, and true graphics capabilities not limited by terminal cells.

How do I run a presentation?

cargo pixel r mdpt wg -r apps/mdpt/ demo.md

What markdown features does MDPT support?

Headings, paragraphs, lists (nested, ordered/unordered)
Code blocks with syntax highlighting (100+ languages)
Dynamic code highlighting with {1-4|6-10|all} syntax
Tables with column alignment
Block quotes with GitHub alert types ([!note], [!caution], etc.)
Column layouts ()
Incremental display ()
Text animations (spotlight, wave, fadein, typewriter)
Charts (line, bar, pie) and Mermaid flowcharts
Image support (.pix, .ssf)
CJK text and emoji

FAQ