Change Log | Principle | Coding | FAQ | TODO
RustPixel is a 2D game engine & rapid prototyping tools, supporting both text and graphics rendering modes. It is suitable for creating 2D pixel-style games and developing terminal applications. It can be compiled into FFI for front-end and back-end use, and into WASM for web projects.
- Text Mode: Built with crossterm, runs in the terminal, and uses ASCII & Unicode Emoji for drawing.
- Graphical Mode: Built with wgpu & glow & sdl2, using PETSCII/ASCII & custom graphics symbols for rendering.
Here is a petscii art painting browser made with rust_pixel. Special thanks to x.com/PETSCIIWORLD for the character painting and the transition shader provided by gltransition. Click here for online demo。
https://github.com/user-attachments/assets/4758f2b6-66c2-47ed-997d-a9066be449aa
Features
- Game loops & Model/Render design pattern (game.rs)
- Event/Timer messaging mechanism (event.rs)
- Unified render adapter trait for text & graphics mode( adapter.rs )
- Support text render mode (crossterm) (cross_adapter.rs)
- OpenGL mode supports sdl and wasm (glow & sdl2 | winit) (sdl_adapter.rs, winit_glow_adapter.rs, web_adapter.rs)
- Wgpu drawing mode (winit & wgpu) (winit_wgpu_adapter.rs)
- 3 core OpenGl shaders for gl & web graphics mode: (gl/)
- 3 core Wgpu shaders for wgpu graphics mode: (wgpu/)
- instance rendering shader for draw mainbuffer (render_symbols.rs)
- transition shader for transition effect (render_transition.rs)
- general 2d shader for draw render texture (render_general2d.rs)
- Some common game algorithms (algorithm.rs, algorithm/, util.rs, util/)
- audio & log support (audio.rs, log.rs)
- Demo games: tetris, tower, poker... (apps/)
- Demo terminal ui app: palette... (apps/)
- Examples of wrapping core algorithms into FFI and WASM (apps/poker/ffi, apps/poker/wasm)
- Cargo style cli tool: cargo-pixel
Installation Guide
The main steps of the installation process are as follows:
- Install DroidSansMono Nerd Font & setup terminal (for text render mode)
- Install dependent libraries and softwares
- Install Rust and Wasm-pack
The detailed steps for each operating system: MacOS | Linux | Windows
Starting from version 0.5.3, you can deploy cargo-pixel directly from crates.io:
cargo install rust_pixel # use crates.io rust_pixel crate deploy cargo-pixel
cargo pixel # first run cargo-pixel will clone rust_pixel to <homedir>/rust_pixel_work automatic
cd ~/rust_pixel_work # cd to workspace
cargo pixel r petview s # run demo game...
To use the newest code, you should clone RustPixel and deploy cargo-pixel tool:
git clone https://github.com/zipxing/rust_pixel
cd rust_pixel
cargo install --path . --force
If you have installed an old version of cargo-pixel, you may get an error when running it. git update is required and the new version of cargo-pixel is deployed manually:
cd rust_pixel
git pull
cargo install --path . --force
Usage Instructions
cd rust_pixel
cargo pixel run snake term #Run the snake game in terminal mode
cargo pixel r snake t #Run the snake game in terminal mode - shorthand
cargo pixel r tetris s #Run the Tetris game in SDL window mode
cargo pixel r tower w #Run tower in web,visit http://localhost:8080/ in your browser
cargo pixel r tower w --webport 8081 #Change web server port
cargo pixel r tower w -r #Run with release mode
cargo pixel r petview g -r #Run the petview game in winit+glow mode
cargo pixel r petview wg -r #Run the petview game in winit+wgpu mode
You can also use cargo pixel to create your own game or app:
cargo pixel c mygame #Create mygame in ./apps using apps/template as a template
Creat a standalone app in some directory:
cargo pixel c myapp .. #Create a standalone crate in ../myapp
cd ../myapp
cargo pixel r myapp t
cargo pixel r myapp s
RustPixel also includes several tools:
- palette: A terminal-ui tool to generate, analyze, convert and manipulate colors.
cargo pixel r palette t -r
- tedit: Used to edit character art assets, example:
#term mode
cargo pixel r pixel_edit term . assets/logo.txt
#graphics mode
cargo pixel r pixel_edit sdl . assets/logo.pix
- tpetii: Used to convert regular images into PETSCII character art, example:
cargo pixel r pixel_petii t assets/a.png -r > assets/a.pix
cargo pixel r pixel_edit s . assets/a.pix
cargo pixel r pixel_petii t assets/lion.png 40 40 -r > assets/lion.pix
cargo pixel r pixel_edit s . assets/lion.pix
- Script to automatically convert gif images into PETSCII animations (.ssf)
cargo pixel cg assets/sdq/fire.gif assets/sdq/fire.ssf 40 25
cargo pixel r pixel_ssf wg -r . assets/sdq/fire.ssf # preview ssf
Demo games
- snake: A snake game with a cool PETSCII animations
#graphics mode
cargo pixel r snake s -r
#term mode
cargo pixel r snake t -r
#web mode
cargo pixel r snake w -r
#and visit http://localhost:8080/ in your browser
- tetris: A Tetris game where you can play against AI
#term mode
cargo pixel r tetris t -r
#graphics mode
cargo pixel r tetris s -r
#web mode
cargo pixel r tetris w -r
#and visit http://localhost:8080/ in your browser
- poker: Includes the core algorithms for Texas Hold'em and Gin Rummy
cargo pixel r poker t -r
cargo pixel r gin_rummy t -r
The poker/ffi directory demo how to wrap Rust algorithms into CFFI for use with other languages, showcasing C++ and Python calling poker_ffi
cd apps/poker/ffi
make run
The poker/wasm directory demo how to wrap Rust algorithms into wasm for JS calling
cd apps/poker/wasm
make run
- tower: A tower defense game prototype demonstrating the use of objpool and pixel_sprite for pixel-perfect sprite movement
#graphics mode
cargo pixel r tower s -r
#web mode
cargo pixel r tower w -r
#and visit http://localhost:8080/ in your browser
and so on ... ...