xevion/rust-sdl2-emscripten
1
0
Fork 0
mirror of https://github.com/Xevion/rust-sdl2-emscripten.git synced 2025-12-14 12:13:00 -06:00
Code Issues Packages Projects Releases 1 Wiki Activity

Revamp README

Browse Source
This commit is contained in:
Xevion
2024-04-23 21:57:40 -05:00
parent d0bf154c59
commit 3b4b12ae6a
1 changed files with 41 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
README.md
View File

@@ -1,55 +1,49 @@
# rust-sdl2-emscripten # rust-sdl2-emscripten
This is an experimental repository while testing a Rust + SDL2 project built with Emscripten. A [demo](https://xevion.github.io/rust-sdl2-emscripten/) project to explore Rust + SDL2 + Emscripten.
- [hello-rust-sdl2-wasm](https://github.com/awwsmm/hello-rust-sdl2-wasm) - A bit of a weird repository, I'm not sure that the creator knows Rust that well, but it compiles. Note that the `asmjs-unknown-emscripten` target is deprecated, and you should use `wasm32-unknown-emscripten` instead. You'll need to change all the files, flags etc. to make it match. - Cross-platform build scripts with GitHub Actions for Windows, Linux, and Web Assembly.
- All SDL2 extensions enabled (Image, Mixer, TTF, GFX) and used in the project.
- [build.sh](./scripts/build.sh) - One of the core files in this repository, it builds the project with Emscripten. Note all the flags available for modifying the behavior of the build. - Emscripten: Asyncify for the game loop, Javascript Interop, `extern` functions & hooks.
### Goals ### Goals
- [X] Automatic Builds - [ ] Emscrimpten Looping Method
- [X] Asyncify
- [ ] `emscripten_set_main_loop`
- [ ] Automatic Builds
- [X] Web Assembly (Emscripten) - [X] Web Assembly (Emscripten)
- [ ] Windows - [ ] Windows
- [ ] MacOS
- [ ] Linux - [ ] Linux
- This ensures that the project can iterate safely and be inspected in a safe environment, free from errors. Helps ensure errors are isolated to the machine or build script. - [ ] MacOS
- [X] SDL2 Extensions - [X] SDL2 Extensions
- [X] Image - [X] Image
- [X] Mixer - [X] Mixer
- [X] TTF - [X] TTF
- [X] GFX - [X] GFX
- [X] Example of External Javascript Interop - [X] Javascript Interop
- The basic ability to provide some kind of Javascript binding would be important for a decent web-based project or game. - [X] LocalStorage
- The ability to use localStorage, fetch, or some browser-only API would be important. - [ ] Fetch
- [ ] Resizable Window
### Concept ### Considerations
- A decent codebase without extras or warnings. Straightforward build process for Windows, Linux, and WASM. This project took a lot of work to get 'right', and it's still quite hacky.
- Note: Cross-compiling for Windows is a bit of a pain, but it's possible. That said, GitHub Actions can handle Windows builds natively.
- While SDL2 has annoying as fuck lifetimes, Emscripten callback loop imbibes even worse static lifetimes that are damn near impossible to satisfy. - It's not possible to quickly get accurate non-monotonic timings with Emscripten, as `Instant::now()` is not broken (seconds only), and `emscripten_get_now()` is only accurate to milliseconds. The FPS counter shows inconsistent (but stable) readings on different browsers for this reason.
- A simple example of a game loop, input handling, and rendering. - `emscripten_set_main_loop` was quite difficult for me to use due to static lifetime issues, perhaps this is just a skill issue on my part, but I found it easier to use `Asyncify` initially.
- Pausing functionality, native-only quit.
- FPS counter toggle (TTF example). If you're new to Rust + SDL2 and are interested in Emscripten, I would recommend reconsidering your need for Web builds, focusing entirely on Web-only, or using a different language/framework. Native C++ with SDL2 is likely more stable and easier to work with.
- Sprites with Atlas
- Resizable Canvas While this combination and project is possible, it's not easy, documentation/examples are sparse, and the tooling is not as mature as other languages.
- Javascript Interop
- LocalStorage My worry with a bigger project is that the complexity of the system will grow exponentially, and the time spent on debugging and fixing issues will be much higher than the time spent on actual development.
- Fetch
### Resources ### Resources
- [KyleMiles/Rust-SDL-Emscripten-Template/](https://github.com/KyleMiles/Rust-SDL-Emscripten-Template/) A list of various resources I relied on and studied while building this project. Organized in descending 'usefulness'.
- Has some special javascript interop code
- [gregbuchholz/RuSDLem](https://github.com/gregbuchholz/RuSDLem) - [build.sh](./scripts/build.sh) - One of the core files in this repository, it builds the project with Emscripten. Note all the flags available for modifying the behavior of the build.
- One of the few with a [demo](https://gregbuchholz.github.io/) available.
- [tung/ruggrogue](https://github.com/tung/ruggrogue/)
- A very large game example, great codebase, documentation, online player.
- [arskiy/chess](https://github.com/arskiy/chess/)
- Image usage, decent code example
- Has more advanced javascript config and examples to look at.
- [deckarep/flappy-rust](https://github.com/deckarep/flappy-rust/)
- Image + Mixer Usage, possibly GFX & TTF
- [aelred/tetris](https://github.com/aelred/tetris) - [aelred/tetris](https://github.com/aelred/tetris)
- Contains multiple sub-projects, including a web server. Uses SDL2 TTF & Mixer. - Contains multiple sub-projects, including a web server. Uses SDL2 TTF & Mixer.
- Most recent development (3 months ago). - Most recent development (3 months ago).
@@ -57,6 +51,20 @@ This is an experimental repository while testing a Rust + SDL2 project built wit
- Advanced Emscripten bindings for Javascript (fetch, GET/POST) - Advanced Emscripten bindings for Javascript (fetch, GET/POST)
- No Asyncify, uses `emscripten_set_main_loop` callback instead. - No Asyncify, uses `emscripten_set_main_loop` callback instead.
- See the [REST functions](https://github.com/aelred/tetris/blob/master/tetris/src/rest.rs#L99) for Emscripten. - See the [REST functions](https://github.com/aelred/tetris/blob/master/tetris/src/rest.rs#L99) for Emscripten.
- [gregbuchholz/RuSDLem](https://github.com/gregbuchholz/RuSDLem)
- One of the few with a [demo](https://gregbuchholz.github.io/) available.
- [tung/ruggrogue](https://github.com/tung/ruggrogue/)
- A very large game example, great codebase, documentation, online player.
- [KyleMiles/Rust-SDL-Emscripten-Template/](https://github.com/KyleMiles/Rust-SDL-Emscripten-Template/)
- Has some special javascript interop code
- [hello-rust-sdl2-wasm](https://github.com/awwsmm/hello-rust-sdl2-wasm)
- A bit of a weird repository, I'm not sure that the creator knows Rust that well, but it compiles.
- Note that the `asmjs-unknown-emscripten` target is deprecated, and you should use `wasm32-unknown-emscripten` instead. You'll need to change all the files, flags etc. to make it match.
- [arskiy/chess](https://github.com/arskiy/chess/)
- Image usage, decent code example
- Has more advanced javascript config and examples to look at.
- [deckarep/flappy-rust](https://github.com/deckarep/flappy-rust/)
- Image + Mixer Usage, possibly GFX & TTF
- [coderedart/rust-sdl2-wasm](https://github.com/coderedart/rust-sdl2-wasm/tree/master) - [coderedart/rust-sdl2-wasm](https://github.com/coderedart/rust-sdl2-wasm/tree/master)
- This is mostly interesting because it has an egui implementation; egui is very cool for demos, developer tooling, debug menus, and so on. - This is mostly interesting because it has an egui implementation; egui is very cool for demos, developer tooling, debug menus, and so on.
- The only thing I don't understand is where SDL2 is; there is almost no real code referencing SDL2 except a `SDL2Backend` provided by the `egui` crate. Weird. - The only thing I don't understand is where SDL2 is; there is almost no real code referencing SDL2 except a `SDL2Backend` provided by the `egui` crate. Weird.