README.md

Core Philosophy

⭐ Killer App: MDPT

A Markdown-first presentation toolkit with a self-rendered TUI(no terminal emulator needed).

MDPT demonstrates RustPixel's unique capability: rendering a full-featured terminal UI in a native GPU window, completely independent of any terminal emulator.

cargo pixel r mdpt g -r # WGPU mode (native)
cargo pixel r mdpt t -r # Term mode (native)
cargo pixel r mdpt w -r # Web mode (browser)

Key Features

Why MDPT?

Unlike terminal-based presenters (presenterm, slides), MDPT:

• No terminal emulator — Runs in a native window with GPU rendering
• Consistent rendering — Same look across all platforms
• Rich transitions — GPU shader effects impossible in terminals
• True graphics — Not limited by terminal cell constraints

AI-Powered Slide Generation

The gen-mdpt Claude Code skill can automatically generate complete MDPT presentations from any topic or document — including code blocks, charts, tables, column layouts, and animations. Below is a Rust tutorial generated by gen-mdpt:

⭐ Tetris — Play Against AI

Two-player Tetris with AI opponent, attack flight animations, and sweep clear effects.

cargo pixel r tetris g -r  # WGPU mode (native)
cargo pixel r tetris t -r   # Terminal mode
cargo pixel r tetris w -r   # Web mode (browser)

Unified Texture Architecture

Texture2DArray with 3-level mipmaps (4096×4096 layers), containing Sprite, TUI, Emoji, and CJK symbols. Single texture binding, instanced rendering, one draw call.

Mipmaps = precomputed lower-resolution versions of the same texture, auto-selected based on render size.

Pix resources (assets/pix/) are loaded with fallback: app-specific first, then shared root. Workspace apps share root assets/pix/; standalone projects need their own copy. See Architecture for details.

Showcase and games

PETSCII art gallery with Matrix rain, GPU transitions, and 2000+ artworks. Fullscreen screensaver mode supported.

cargo pixel r petview g -r    # WGPU mode (native)
cargo pixel r petview w -r     # Web mode (browser)

Quick Start

Install

cargo install rust_pixel         # Install cargo-pixel CLI
cargo pixel                      # First run clones workspace to ~/rust_pixel_work
cd ~/rust_pixel_work

Run Demo Games

cargo pixel r snake t            # Snake - Terminal mode
cargo pixel r snake g           # Snake - WGPU mode (native window)
cargo pixel r tetris w           # Tetris - Web mode (localhost:8080)
cargo pixel r petview g -r      # Petview - WGPU mode (release)

Create Your Own Game

cargo pixel c mygame             # Create in ./apps/mygame
cargo pixel r mygame t           # Run it!

# Or create standalone project
cargo pixel c myapp ..           # Create in ../myapp
cd ../myapp && cargo pixel r myapp g

Write Games in BASIC

RustPixel includes pixel_basic - a built-in BASIC interpreter perfect for beginners or quick prototyping!

cargo pixel r basic_snake t      # Run BASIC Snake game

Write game logic in familiar BASIC syntax (apps/basic_snake/assets/game.bas):

10 REM SNAKE GAME
20 X = 20: Y = 10
30 DIM BX(100): DIM BY(100)
40 YIELD
50 GOTO 40

1000 REM ON_INIT
1010 BOX 0, 0, 60, 24, 1
1020 RETURN

2000 REM ON_TICK
2010 IF KEY("W") THEN DY = -1: DX = 0
2020 X = X + DX: Y = Y + DY
2030 RETURN

3500 REM ON_DRAW
3510 PLOT X, Y, "@", 10, 0
3520 RETURN

pixel_basic features:

• Classic BASIC syntax with line numbers
• Game hooks: ON_INIT (1000), ON_TICK (2000), ON_DRAW (3500)
• Graphics: PLOT x, y, char, fg, bg / BOX / CLS
• Input: KEY("W"), KEY("SPACE")
• Arrays: DIM arr(100)
• Control flow: GOTO, GOSUB/RETURN, FOR/NEXT, IF/THEN
• Math: RND(), INT(), ABS()
• Strings: STR$(), LEN(), MID$()

See pixel_basic/ for the interpreter source code.

Architecture

┌─────────────────────────────────────────────────────────┐
│                         Game                            │
│  ┌─────────────────────┐  ┌─────────────────────────┐  │
│  │       Model         │  │        Render           │  │
│  │  ├─ init()          │  │  ├─ init()              │  │
│  │  ├─ handle_input()  │  │  ├─ draw()              │  │
│  │  ├─ handle_auto()   │  │  └─ Panel               │  │
│  │  └─ handle_timer()  │  │      └─ Sprites[]       │  │
│  └─────────────────────┘  │          └─ Buffer      │  │
│                           │              └─ Cells[] │  │
│                           └─────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Demo Games

cargo pixel r snake g -r   # WGPU (native)
cargo pixel r snake t -r    # Terminal
cargo pixel r snake w -r    # Web

cargo pixel r tetris g -r  # WGPU (native)
cargo pixel r tetris t -r   # Terminal
cargo pixel r tetris w -r   # Web

cargo pixel r tower g -r   # WGPU (native)
cargo pixel r tower w -r    # Web

cargo pixel r poker t -r
cargo pixel r gin_rummy t -r

Tools

Palette - Color Tool

Terminal UI for color manipulation

cargo pixel r palette t -r

Edit - Character Art Editor

cargo pixel e t . assets/logo.txt    # Terminal mode
cargo pixel e g . assets/logo.pix   # WGPU mode

Petii - Image to PETSCII Converter

cargo pixel p assets/lion.png 40 40 > lion.pix
cargo pixel e g . lion.pix

GIF to PETSCII Animation

cargo pixel cg input.gif output.ssf 40 25
cargo pixel ssf . output.ssf    # Preview

FFI & WASM

RustPixel algorithms can be exported for other languages:

# C++/Python FFI
cd apps/poker/ffi && make run

# JavaScript WASM
cd apps/poker/wasm && make run

Installation Guide

Requirements:

• Nerd Font (for terminal mode)
• Rust 1.71+
• wasm-pack (for web mode)

Features

• app! macro - One-line game scaffolding with cross-platform entry points
• Model/Render pattern - Clean separation of logic and presentation
• Event/Timer system - Built-in messaging mechanism
• Unified adapter trait - Same code for all rendering backends
• WGPU shaders - Modern GPU rendering pipeline (native + WebGL2/WebGPU)
• Game algorithms - Pathfinding, object pools, utilities
• Audio support - Sound effects and music playback

Roadmap

Three Pillars

AI Integration

• AI-friendly API — Refine APIs for better AI code generation compatibility
• AIGC for MDPT — Auto-generate slide illustrations (converted to pixel art)
• PETSCII/ASCII Art Generation — Explore AI-generated low-resolution, high-quality character art

BASIC Enhancement

• Richer Game Capabilities — Expand BASIC to support more complex games and TUI apps
• Unified Script Template — init / update / draw / on_key pattern for all apps

Toolchain

• Editor Improvements — Enhanced character art editor with more features
• Asset Pipeline — Charset/Palette/Pack import/export, versioning, hot reload
• Cross-Platform Consistency — Unified input and rendering across all backends

See Roadmap 2026 for detailed plans.