288 lines
8.2 KiB
Markdown
288 lines
8.2 KiB
Markdown
# Rust for Arduboy
|
||
|
||
Running Rust on the [Arduboy](https://arduboy.com/) miniature game system.
|
||
|
||
The most important first.
|
||
I didn't create this project from scratch, @Seeker14491 the legend has already done a lot in his old project [ArduboyRust](https://github.com/Seeker14491/ArduboyRust)
|
||
|
||
I just updated and completed the project.
|
||
|
||
### What do i mean by completed?
|
||
|
||
I provided all the important functions from the [Arduboy2](https://github.com/MLXXXp/Arduboy2) library in a safe Rust API.
|
||
|
||
Most of the Arduboy2 funktions can be called the same way like in C.
|
||
|
||
# How to use this Project
|
||
|
||
First clone the repo
|
||
|
||
```bash
|
||
git clone https://github.com/ZennDev1337/Rust-for-Arduboy
|
||
```
|
||
|
||
Install [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/methods/pypi.html) on your system.
|
||
I recommend the pip install if you don't want to configure a new path variable for pio.
|
||
Otherwise you will know how to do that.
|
||
|
||
The rust-analyzer will complain about a missing test crate to fix this
|
||
add the following rule to the lsp settings :
|
||
|
||
```json
|
||
{
|
||
"rust-analyzer.checkOnSave.allTargets": false
|
||
}
|
||
```
|
||
|
||
If your using Visual Studio Code: Create a folder named `.vscode` and a file named `settings.json` inside. Past the setting above in the new file. (I have excluded my `.vscode` folder because I have many different settings there that you don't need)
|
||
|
||
Your game is located in the Project/game folder. This is also the folder you are working in
|
||
|
||
Inside the game folder you will find a lib.rs file which contains the setup and loop function as you know it from a normal Arduboy C project.
|
||
|
||
You can find the Docs here:
|
||
|
||
- [arduboy-rust Crate Docs](https://zenndev1337.github.io/Rust-for-Arduboy/)
|
||
|
||
or you can use the following command to open the arduboy-rust Crate docs locally
|
||
|
||
```bash
|
||
cargo doc -p arduboy-rust --open
|
||
```
|
||
|
||
Most of the time you will use the prelude.
|
||
There is listed witch funktionality you will have.
|
||
|
||
And last but not least there are multiple examples inside of the Examples folder which shows you how to use the functions.
|
||
I will from time to time also upload my projects to the Example folder so you have as much ressurces as possible.
|
||
|
||
## Usage of the run tool
|
||
|
||
**Both run scripts** (only works if you use the given folder structure)
|
||
|
||
requirements:
|
||
|
||
- [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/methods/pypi.html) must be installed
|
||
- The Arduboy must be plugged in
|
||
- You are in the root directory of this project
|
||
|
||
All builded `.hex` files are saved inside of `arduboy-rust/Wrapper-Project/build/<GAMENAME>.hex` after you uploaded them to the Arduboy.
|
||
|
||
To upload your own game to the Arduboy use:
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
./run
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
.\run.bat
|
||
```
|
||
|
||
## Play ZennDev1337 Games
|
||
|
||
### Dr. Boy
|
||
|
||
To upload snake to the Arduboy use:
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
./run drboy
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
.\run.bat drboy
|
||
```
|
||
|
||
### Snake
|
||
|
||
To upload snake to the Arduboy use:
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
./run snake
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
.\run.bat snake
|
||
```
|
||
|
||
## Play Rust Games
|
||
|
||
### I'm now a Rustacean <3
|
||
|
||
To upload rustacean to the Arduboy use:
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
./run rustacean
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
.\run.bat rustacean
|
||
```
|
||
|
||
## Play Demo Games
|
||
|
||
### The demo games / tutorials from the official Arduboy forum [Rewritten in Rust]
|
||
|
||
- [Make Your Own Arduboy Game: Part 1 - Setting Up Your Computer](https://community.arduboy.com/t/make-your-own-arduboy-game-part-1-setting-up-your-computer/7924/1)
|
||
- [demo2] [Make Your Own Arduboy Game: Part 2 - Printing Text](https://community.arduboy.com/t/make-your-own-arduboy-game-part-2-printing-text/7925)
|
||
- [demo3] [Make Your Own Arduboy Game: Part 3 - Storing Data & Loops](https://community.arduboy.com/t/make-your-own-arduboy-game-part-3-storing-data-loops/7926)
|
||
- [demo4] [Make Your Own Arduboy Game: Part 4 - Questions & Button Input](https://community.arduboy.com/t/make-your-own-arduboy-game-part-4-questions-button-input/7927)
|
||
- [demo5] [Make Your Own Arduboy Game: Part 5 - Your First Game!](https://community.arduboy.com/t/make-your-own-arduboy-game-part-5-your-first-game/7928)
|
||
- [demo6] [Make Your Own Arduboy Game: Part 6 - Graphics!](https://community.arduboy.com/t/make-your-own-arduboy-game-part-6-graphics/7929)
|
||
Link for the [ZennDev1337 Tile Converter](https://zenndev1337.github.io/Rust-for-Arduboy/tile-converter.html)
|
||
- [demo7] [Make Your Own Arduboy Game: Part 7 - Make Pong From Scratch!](https://community.arduboy.com/t/make-your-own-arduboy-game-part-7-make-pong-from-scratch/7930)
|
||
- not done [demo8] [Make Your Own Arduboy Game: Part 8 - Starting DinoSmasher](https://community.arduboy.com/t/make-your-own-arduboy-game-part-8-starting-dinosmasher/7932)
|
||
- [eeprom] [Help, I’m struggling with EEPROM!](https://community.arduboy.com/t/help-im-struggling-with-eeprom/7178)
|
||
- [progmem] Usage of the big 28'000 Bytes flash memory for Bitmaps Sound sequeces and Text.
|
||
- [tone] [ArduboyTonesTest](https://github.com/MLXXXp/ArduboyTones/blob/master/examples/ArduboyTonesTest/ArduboyTonesTest.ino)
|
||
|
||
To upload a demo to the Arduboy use:
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
./run demo2
|
||
./run demo3
|
||
./run demo4
|
||
./run demo5
|
||
./run demo6
|
||
./run demo7
|
||
./run eeprom
|
||
./run eeprom-byte
|
||
./run progmem
|
||
./run tone
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
.\run.bat demo2
|
||
.\run.bat demo3
|
||
.\run.bat demo4
|
||
.\run.bat demo5
|
||
.\run.bat demo6
|
||
.\run.bat demo7
|
||
.\run.bat eeprom
|
||
.\run.bat eeprom-byte
|
||
.\run.bat progmem
|
||
.\run.bat tone
|
||
```
|
||
|
||
# Create a new project
|
||
|
||
In the root of the repo use the command:
|
||
|
||
(Don't use "-" in the name because of a cargo feature that takes the "-" and mixes sometimes with a "\_". You will have some weird behavior with the run tool.)
|
||
|
||
```bash
|
||
cargo new --lib ./Project/newproject
|
||
```
|
||
|
||
Then open the Cargo.toml in your new project and add the following dependencies and settings:
|
||
|
||
```toml
|
||
[lib]
|
||
crate-type = ["staticlib"]
|
||
|
||
[dependencies]
|
||
|
||
arduboy-rust = { path = "../../arduboy-rust" }
|
||
```
|
||
|
||
Next jump in your lib.rs file and add the following:
|
||
|
||
```rust
|
||
#![no_std]
|
||
#![allow(non_upper_case_globals)]
|
||
|
||
//Include the Arduboy Library
|
||
#[allow(unused_imports)]
|
||
use arduboy_rust::prelude::*;
|
||
#[allow(dead_code)]
|
||
const arduboy: Arduboy2 = Arduboy2::new();
|
||
|
||
// Progmem data
|
||
|
||
// dynamic ram variables
|
||
|
||
// The setup() function runs once when you turn your Arduboy on
|
||
#[no_mangle]
|
||
pub unsafe extern "C" fn setup() {
|
||
// put your setup code here, to run once:
|
||
}
|
||
|
||
// The loop() function repeats forever after setup() is done
|
||
#[no_mangle]
|
||
#[export_name = "loop"]
|
||
pub unsafe extern "C" fn loop_() {
|
||
// put your main code here, to run repeatedly:
|
||
}
|
||
```
|
||
|
||
Now the last step. Go in the Cargo.toml in the root directory and add your project:
|
||
|
||
```toml
|
||
[workspace]
|
||
members = [
|
||
{All other Projects...}
|
||
"Project/newproject",
|
||
]
|
||
resolver = "2"
|
||
```
|
||
|
||
To run and upload your game use the run tool
|
||
|
||
```bash
|
||
# Linux
|
||
./run newproject
|
||
```
|
||
|
||
```ps1
|
||
# Windows
|
||
.\run.bat newproject
|
||
```
|
||
|
||
## Creating and building an Arduboy crate [Outdated]
|
||
|
||
You can find instructions on how all build steps work in detail here [ArduboyRust creating and building an arduboy crate](https://github.com/Seeker14491/ArduboyRust#creating-and-building-an-arduboy-crate)
|
||
|
||
## Linking the static library to the Arduino C++ project [Outdated]
|
||
|
||
Instructions on how to link all the static libraries in the Arduino C++ project can be found here [ArduboyRust linking the static library to the arduino c++ project](https://github.com/Seeker14491/ArduboyRust#linking-the-static-library-to-the-arduino-c-project)
|
||
|
||
## Credits
|
||
|
||
Thanks to @Seeker14491 who wrote [ArduboyRust](https://github.com/Seeker14491/ArduboyRust), the starting point for me to create my own project based on this project. (you are a hero <3)
|
||
|
||
Thanks to @simon-i1-h who wrote [arduboy-hello-rs](https://github.com/simon-i1-h/arduboy-hello-rs), the proof of concept that inspired me to try Rust on the Arduboy.
|
||
|
||
## License
|
||
|
||
You can license it under either one of those licenses:
|
||
|
||
- Apache License, Version 2.0
|
||
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
||
- MIT license
|
||
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
||
|
||
Whichever you may prefer.
|
||
|
||
## Contribution
|
||
|
||
Unless you explicitly state otherwise, any contribution intentionally submitted
|
||
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
|