247 lines
8.2 KiB
Markdown
247 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
|
||
|
||
**The run script** only work if you use the given folder structure!
|
||
|
||
requirements:
|
||
|
||
- Python3.11 or higher
|
||
- [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
|
||
python ./run.py <Project_Name>
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
python .\run.py <Project_Name>
|
||
```
|
||
|
||
All commands:
|
||
|
||
```
|
||
Usage build and upload Project:
|
||
run.py list Get a list of all Projects
|
||
run.py new <Project-Name> Create a new game in the Project folder
|
||
run.py <Project-Name> For uploading a game
|
||
|
||
Usage FX-Data build and upload:
|
||
run.py fxbuild <Project-Name> Build your fxdata
|
||
run.py fxupload <Project-Name> Upload your fxdata
|
||
run.py fxall <Project-Name> Build and Upload your fxdata
|
||
and the game in one step
|
||
```
|
||
|
||
## List of all the Example Games:
|
||
|
||
### ZennDev1337 Games
|
||
|
||
- drboy
|
||
|
||
### Rust Games
|
||
|
||
- snake
|
||
- rustacean
|
||
|
||
### 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)
|
||
- Prepare for
|
||
demo9 [Make Your Own Arduboy Game: Part 8 - Starting DinoSmasher](https://community.arduboy.com/t/make-your-own-arduboy-game-part-8-starting-dinosmasher/7932)
|
||
- [demo9] [Make Your Own Arduboy Game: Part 9 - Mapping DinoSmasher](https://community.arduboy.com/t/make-your-own-arduboy-game-part-9-mapping-dinosmasher/7931)
|
||
- [eeprom] [Help, I’m struggling with EEPROM!](https://community.arduboy.com/t/help-im-struggling-with-eeprom/7178)
|
||
- [eeprom-byte] [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)
|
||
|
||
## Usage of the FX Chip
|
||
|
||
requirements:
|
||
|
||
```
|
||
python3 -m pip install pyserial pillow
|
||
```
|
||
|
||
You need to create a fxdata folder in your project directory.
|
||
|
||
Don't forget to uncomment the `ArduboyFX_Library` line in the `import_config.h` file.
|
||
|
||
run Commands:
|
||
|
||
```
|
||
|Project_Dir
|
||
->fxdata
|
||
->fxdata.txt
|
||
->src
|
||
->lib.rs
|
||
>cargo.toml
|
||
```
|
||
|
||
You also need a fxdata.txt file in this new folder.
|
||
|
||
See the examples in `Examples/ArduboyFX`.
|
||
|
||
More information:
|
||
|
||
- [Arduboy-Python-Utilities by MrBlinky](https://github.com/MrBlinky/Arduboy-Python-Utilities)
|
||
|
||
run Commands:
|
||
|
||
- `fxbuild` is used to build the fxdata.dat file.
|
||
- `fxupload` is used to upload the fxdata.dat file.
|
||
- `fxall` is used to build and upload the fxdata.dat file and build and upload the game all in one step.
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
python ./run.py fxbuild <Project_Name>
|
||
python ./run.py fxupload <Project_Name>
|
||
python ./run.py fxall <Project_Name>
|
||
```
|
||
|
||
Windows:
|
||
|
||
```ps1
|
||
python .\run.py fxbuild <Project_Name>
|
||
python .\run.py fxupload <Project_Name>
|
||
python .\run.py fxall <Project_Name>
|
||
```
|
||
|
||
### Convert the fxdata.h file to Rust
|
||
|
||
[FXdata Converter by ZennDev1337](https://zenndev1337.github.io/Rust-for-Arduboy/fxdata-converter.html)
|
||
|
||
# Create a new project
|
||
|
||
In the root of the repo use the command:
|
||
|
||
```bash
|
||
python ./run.py new <Project-Name>
|
||
```
|
||
|
||
To run and upload your game use the run tool
|
||
|
||
```bash
|
||
# Linux
|
||
python ./run.py <Project-Name>
|
||
```
|
||
|
||
```ps1
|
||
# Windows
|
||
python .\run.py <Project-Name>
|
||
```
|
||
|
||
## 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.
|