sandspiel Documentation

To run the sandspiel project locally, you must first build the WebAssembly (WASM) component using wasm-pack, install the JavaScript dependencies, and then start the development server. For active development, use cargo watch to automatically rebuild the WASM component whenever changes are detected in the Rust crate.

# build the wasm once:
cd crate && wasm-pack build && cd ..;
npm install;
npm run start;

# then in a separate terminal:
cargo watch -s 'wasm-pack build'

Use Universe::paint(x, y, size, species) to draw a circular area of a specific Species at the given coordinates.

• x, y: The center coordinates of the brush.
• size: The diameter of the brush.
• species: The Species enum value to apply.

Cells are only painted if the target location is currently Species::Empty or if the species being painted is Species::Empty.

Call Universe::tick() to advance the simulation by one generation. This method performs two main phases:

1. Wind Phase: Applies wind forces to cells based on the current winds vector.
2. Update Phase: Iterates through cells (using a scanline approach that alternates direction to prevent directional bias) and updates their state based on their species logic.

Note: tick() increments the internal generation counter.

The Species::update method is the primary entry point for applying the physics and logic associated with a specific species. It takes the current Cell and a SandApi instance to perform state changes in the simulation.

impl Species {
    pub fn update(&self, cell: Cell, api: SandApi) {
        // ... implementation ...
    }
}

To render the simulation, you can access raw pointers to the underlying data buffers:

• cells(): Returns a pointer to the start of the Cell array.
• winds(): Returns a pointer to the start of the Wind array (used for fluid dynamics).
• burns(): Returns a pointer to the start of the burns array.

Use Universe::width() and Universe::height() to determine the dimensions for iterating over these buffers.

The Universe maintains an undo stack of up to 50 previous cell states. Use the following methods to manage history:

• push_undo(): Saves the current state of all cells to the stack.
• pop_undo(): Reverts the universe to the most recent saved state.
• flush_undos(): Clears the entire undo history.

The Cell struct represents a single unit in the cellular automata grid.

#[repr(C)]
pub struct Cell {
    species: Species,
    ra: u8,
    rb: u8,
    clock: u8,
}

The Wind struct represents fluid velocity and pressure at a specific coordinate. It is used for both general wind and 'burn' effects.

#[repr(C)]
pub struct Wind {
    dx: u8,
    dy: u8,
    pressure: u8,
    density: u8,
}

The Species enum defines the different types of elements available in the simulation. It is represented as a u8 in memory. Use these variants to identify or set the type of a Cell.

#[wasm_bindgen]
#[repr(u8)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Species {
    Empty = 0,
    Wall = 1,
    Sand = 2,
    Water = 3,
    Stone = 13,
    Ice = 9,
    Gas = 4,
    Cloner = 5,
    Mite = 15,
    Wood = 7,
    Plant = 11,
    Fungus = 18,
    Seed = 19,
    Fire = 6,
    Lava = 8,
    Acid = 12,
    Dust = 14,
    Oil = 16,
    Rocket = 17,
}