|0.1.0||Jan 8, 2022|
#1765 in Game dev
Rust libraries for WASM-4 fantasy console
Home page: https://wasm4fun.neocities.org/
The WASM-4 fantasy console has the following hardware:
Display: 160×160 screen using a customizable 4-colours palette.
This means that at any time there can only be 4 different colours on the screen, but at any time the game can switch to a different set of colours.
Memory: 64 KiB.
Cartridge size: 64 KiB.
An entire game cannot exceed the cartridge size. This limits the number and complexity of game resources, such a graphical sprites, and the complexity of game logic (convoluted implementation results in larger binary size).
Disk storage: 1 KiB.
The game can write and read up to 1 KiB of data, for instance for saving progress or high scores.
WASM-4 engine exposes a small set of primitives and memory mapping, and expects games to expose two callback functions. This approach allows to easily support several programming languages, but has the drawback that the programming interface is rather low level and simplistic. The purpose of these libraries is to wrap WASM-4 primitives and expose a much richer, more idiomatic and safer API.
This library is divided in several independent crates, each implementing specific functionalities.
wasm4fun-input implements functions and data types for reading the console input, whether it is mouse or gamepad, and
wasm4fun-storage implements functions to save or load data from the storage system.
Some crates depend on other crates.
wasm4fun-core, which exports the bare WASM-4 interface, is used in most crates, and so is
wasm4fun-log, which exports a
debug!() macro to write formatted text to the output console.
wasm4fun crate re-exports all sub-crates, but it is possible to ignore it and explicitly depend on some of the sub-crates, in order to trim the dependency tree.
These libraries do not use any dynamic allocation, and therefore do not use any part of Rust standard library.
In technical terms, they do not use anything from
std:: module, but only from
Dynamic allocation makes development much easier, but it has one major drawback on WASM-4: it results in a significant larger cartridge size, since the cartridge must contain the allocator itself. Due to the 64 KiB cartridge size constraint, this might force to use smaller game resource, such as sprites, or to avoid some of the complex libraries.
On the other hand, while dynamic allocation brings many advantages in other environments, it is not so necessary on Rust on WASM-4. Many crates exist to implement data structures and algorithms on the stack. For instance, the tinyvec crate offers "dynamic" vectors backed by arrays in the stack.
Finally, avoiding dynamic allocation fits well with the general minimalistic philosophy of WASM-4:
The idea is that by removing excess and focusing on the essential, it becomes easier to start and finish developing a game.
Documentation and Examples
Documentation is available on https://docs.rs/wasm4fun/.
Several examples are available inside directory
They can be run with the command
cargo make run-example EXAMPLE_NAME (executable
w4 from WASM-4 must be in path).
Copyright Claudio Mattera 2022
You are free to copy, modify, and distribute this application with attribution under the terms of either
- Apache License, Version 2.0
- MIT license
at your option.