Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zipxing/rust_pixel

Rust 2d game engine, ideal for developing mini-games&app, support terminal, sdl, web modes.
https://github.com/zipxing/rust_pixel

Last synced: 4 days ago
JSON representation

Rust 2d game engine, ideal for developing mini-games&app, support terminal, sdl, web modes.

Awesome Lists containing this project

README 

        
![logo](./screen-shot/logo.png)



![License] [![Latest Version]][crates.io] ![Downloads] [![API Documentation]][docs.rs] ![MSRV]



[License]: https://img.shields.io/badge/license-Apache2.0-blue.svg

[Latest Version]: https://img.shields.io/crates/v/rust_pixel.svg

[crates.io]: https://crates.io/crates/rust_pixel

[Downloads]: https://img.shields.io/crates/d/rust_pixel.svg

[API Documentation]: https://docs.rs/rust_pixel/badge.svg

[docs.rs]: https://docs.rs/rust_pixel

[MSRV]: https://img.shields.io/badge/rust-1.71+-brightgreen.svg?&logo=rust



[Change Log]  |  [Principle]  |  [Coding]  |  [FAQ]  |  [TODO]



[Change Log]: doc/change.md

[Principle]: doc/principle.md

[Coding]: doc/coding.md

[FAQ]: doc/faq.md

[TODO]: doc/todo.md



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 (SDL2 & WEB): Built with **glow** & **sdl2**, using **PETSCII & custom graphics symbols** for rendering.



[online demo]: https://zipxing.github.io/rust_pixel



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/8e9e0837-43fd-4f18-a5ad-265a06ddb47e



### Features



- Game loops & Model/Render design pattern (game.rs)

- Event/Timer messaging mechanism (event.rs)

- Support text render mode (crossterm) (adapter.rs, cross.rs)

- Unified OpenGL drawing mode supports sdl and wasm (glow & sdl2) (adapter.rs, sdl.rs, web.rs)

- 3 core OpenGl shaders for sdl2 & web graphics mode: (gl/) 

    - gl instance rendering shader for draw mainbuffer (render_symbols.rs) 

    - gl transition shader for transition effect (render_transition.rs)

    - gl 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... (games/)

- Demo terminal ui app: palette... (apps/)

- Examples of wrapping core algorithms into FFI and WASM (games/poker/ffi, games/poker/wasm)



### Installation Guide



The main steps of the installation process are as follows:

- Install [DroidSansMono Nerd Font] & setup terminal

- Install dependent libraries and softwares

- Install **Rust** and **Wasm-pack**



The detailed steps for each operating system:   [MacOS]   |   [Linux]   |   [Windows]



[MacOS]: doc/mac.md

[Linux]: doc/linux.md

[Windows]: doc/win.md

[DroidSansMono Nerd Font]: https://github.com/ryanoasis/nerd-fonts



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 /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

``` 



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:

1. **palette**: A terminal-ui tool to generate, analyze, convert and manipulate colors.

```

cargo pixel r palette t -r

```

 ![palette](./screen-shot/palette.gif)



2. **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

```

 ![tedit_t](./screen-shot/tedit_term.png)

 ![tedit_s](./screen-shot/tedit_sdl.png)



3. **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

```

 ![tpetii_1](./screen-shot/a.png)

 ![tpetii_2](./screen-shot/lion.png)



4. Script to automatically **convert gif images into PETSCII animations (.ssf)**

```

cargo pixel cg assets/sdq/fire.gif assets/sdq/fire.ssf 40 25 

```



### Demo games

1. snake: A snake game with a cool PETSCII animations

```

#graphics mode

cargo pixel r snake s -r

```



![graphics mode](./screen-shot/snake_sdl.gif)



``` 

#term mode

cargo pixel r snake t -r

```



```

#web mode

cargo pixel r snake w -r

#and visit http://localhost:8080/ in your browser

```



2. tetris: A Tetris game where you can play against AI

``` 

#term mode

cargo pixel r tetris t -r

```



 ![term mode](./screen-shot/tetris_term.gif)



```

#graphics mode

cargo pixel r tetris s -r

```



![graphics mode](./screen-shot/tetris_sdl.gif)



```

#web mode

cargo pixel r tetris w -r

#and visit http://localhost:8080/ in your browser

```



![web mode](./screen-shot/tetris_web.gif)



3. 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

```

 ![gin_rummy](./screen-shot/ginrummy.png)

 ![red_black](./screen-shot/redblack.png)



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 games/poker/ffi

make run

```

The poker/wasm directory demo how to wrap Rust algorithms into wasm for JS calling

```

cd games/poker/wasm

make run

```



4. 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

```

 ![tower](./screen-shot/tower_sdl.gif)



and so on ... ...