Hello, world

Now before we get into building the Connect-4, let’s get a “Hello, world” program going. This is extremely straightforward as long as you have Rust installed. Here’s the place to start: Rust Installation.

Once you have Rust installed, let’s check the version to verify that the installation worked by running rustc --version in the terminal.

For me the output is rustc 1.90.0 (1159e78c4 2025-09-14), the version might differ for you. But Rust’s backwards compatibility guarantees should ensure the code runs.

Now let’s create an empty folder and a file. As Rust is a compiled language, the folder is useful for co-locating the source code and the compiled artifacts.

mkdir hello_world
cd hello_world
touch hello_world.rs

In the newly created file, let’s write our first function.

// hello_world/hello_world.rs

// 1. entry point
// ↓
fn main() {
//         2. macro
//         ↓
    println!("Hello, world!");
}

1. main function

Every executable Rust program requires an entrypoint, and in ours it’s the main function. Here’s what the Rust book has to say about it:

These lines define a function named main. The main function is special: It is always the first code that runs in every executable Rust program.

As we don’t need the function to return anything, there’s no explicit return type. The implicit return type in Rust is the unit type denoted by (), which is similar to a void in TypeScript.

2. println! macro

Throughout this series, we will use a lot of macros. The syntax can be confusing as it’s similar to a function call, however the key difference is the exclaimation point at the end. The println! macro conveniently hides the machinery that goes into printing a line the the console. It’s similar to the console.log statement in JavaScript.

Rust has other types of macros, I’ll introduce them as we start using them later.

Let’s compile and execute our program:

# hello_world/

rustc ./hello_world.rs
./hello_world

That should print Hello, world! to the terminal! Now that we’ve written our first program, let’s try out the build system that will be used throughout the series.

Cargo

Cargo is the default build system, and package manager for the Rust ecosystem. It sits at the same spot npm (the CLI tool) does in the JavaScript ecosystem.

Let’s create a new project, called hello_universe, but this time using cargo.

cargo new hello_universe
cd ./hello_universe

It should create a structure that looks like:

hello_universe/
├─ src/
│  └─ main.rs                  // entry point
│
└─ Cargo.toml                  // package config and dependencies

The main.rs should already have a main function that prints Hello, world!. I’d like you to update that to print Hello, universe!, and then execute it by running cargo run.

   Compiling hello_universe v0.1.0 (/Users/tauseefk/personal/rust/scratch/hello_universe)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.09s
     Running `target/debug/hello_universe`
Hello, world!

Cargo takes care of compiling the project, and executing it. By default the project gets compiled using a dev profile. The executable lives in target/debug/hello_universe.

We’ll come back to debug/release builds and profiles later. For now this should be enough for us to jump back into writing the Connect-4 game.

In the last post we looked at setting up the Connect-4 game board and transfering data back and forth between the JavaScript and WASM boundary. This allowed us to render a randomized board to the screen, however for it to be a real game we need allow users to make moves.

In this post let’s take a look at adding a bit of interactivity to allow players to play a full game, and at the very end calculate the winner!

Interactivity

The first piece of interactivity we can add to our connect-4 is a way to switch between players. Let’s add a new enum that encodes the player variants, and then add it to our larger game state which is the Board struct.

#[derive(Copy, Clone)]
pub enum Player {
    Red,
    Black,
}

pub struct Board {
    row_count: usize,
    col_count: usize,
    // public so we can read it from the JavaScript side and display it
    pub player_turn: Player,
}

#[wasm_bindgen]
impl Board {

    // 1.
    fn end_player_turn(&mut self) {
        self.player_turn = match self.player_turn {
            Player::Red => Player::Black,
            Player::Black => Player::Red,
        }
    }

    // 2.
    pub fn select_col(&mut self, col_idx: u8) -> bool {
        // board update logic will go here

        self.end_player_turn();
    }
}

1. end_player_turn

The end_player_turn function just flips the player turn state on the overall game state between red and black variants.

2. select_col

The select_col function is where majority of the game logic will go. Once all the required state has been updated, it’ll call end_player_turn and the other player can make their move.

JavaScript to match

Now let’s update our JavaScript to accomodate for these changes, by first adding another div that would display the player turn, updating the rendering logic, and adding an event handler.

import init, { Board, TileType } from "./connectors/connectors.js";
const ROW_COUNT = 6;
const COL_COUNT = 7;

const DISPLAY_TURN_MAP = {
  [Player.Red]: "R",
  [Player.Black]: "B",
};

// this duplication is necessary
// just so it's easy to render as a grid
const DISPLAY_TILE_MAP = {
  [TileType.Empty]: "_",
  [TileType.Red]: "R",
  [TileType.Black]: "B",
};

const playerTurnEl = document.getElementById("player-turn");
const gameBoardEl = document.getElementById("game-board");

init().then(() => {
  const board = Board.new(ROW_COUNT, COL_COUNT);

  // 1. Render
  const render = () => {
    playerTurnEl.innerText = DISPLAY_TURN_MAP[board.player_turn];
    const tiles = Array.from(board.get_board).map(
      (tileEnumValue) => DISPLAY_TILE_MAP[tileEnumValue],
    );
    const fragment = document.createDocumentFragment();

    tiles.forEach((tile, idx) => {
      const span = document.createElement("span");
      span.textContent = tile;
      span.dataset.colIdx = Math.floor(idx % COL_COUNT);
      fragment.appendChild(span);
    });

    gameBoardEl.innerHTML = "";
    gameBoardEl.appendChild(fragment);
  };

  // 2.
  gameBoardEl.addEventListener("click", (event) => {
    const colIdx = parseInt(event.target.dataset.colIdx, 10);
    board.select_col(colIdx);
    render();
  });

  // initial render
  render();
});

That’s a wall of code, however most of it is just a small refactor to ensure that we can render after each user event and not just once when the page loads.

1. Render refactor

We extract the rendering logic into it’s own function so that after each user interaction we can update the entire screen to display the updated state.

2. Adding event listeners

The event handler is applied to the entire grid, it extract the column index from the data attribute and calls the select_col function that we added to the rust code earlier, and finally calls render to update the screen.

If you rebuild and launch the app now you’ll see that clicking anywhere on the grid updates the Player turn back and forth between R and B.

Here’s the full commit.

Making Moves

So far we’ve been using random tiles, now let’s replace those with empty tiles.

#[wasm_bindgen]
pub struct Board {
    row_count: usize,
    col_count: usize,
    pub player_turn: Player,
    // 1. private
    board: Vec<TileType>,
}

#[wasm_bindgen]
impl Board {
    pub fn new(row_count: usize, col_count: usize) -> Self {
        // initialize the entire board to empty values
        //
        //                         2. initialize to Empty
        //                         ↓
        let board: Vec<TileType> = vec![TileType::Empty; row_count * col_count];

        Self {
            row_count,
            col_count,
            board,
            player_turn: Player::Red,
        }
    }

    #[wasm_bindgen(getter)]
    pub fn get_board(&self) -> js_sys::Uint8Array {
        let board: Vec<u8> = self.board.iter().map(|tile| tile.into()).collect();
        js_sys::Uint8Array::from(&board[..])
    }
}

1. private Vec field

Only simple types are directly exposed across the Wasm/JS boundary, so vector fields cannot be public. have to be converted into typed arrays.

2. Initializing Vec to Empty

Here we initialize entire board to TileType::Empty using the vec! macro instead of a randomized board.

Now let’s update the select_col function to update the state based on user’s selected column.

impl Board {
    // 1. bounds check
    fn is_in_bounds(&self, col_idx: u8) -> bool {
        (col_idx as usize) < self.col_count
    }

    pub fn select_col(&mut self, col_idx: u8) -> bool {
        if !self.is_in_bounds(col_idx) {
            return false;
        }

        /////////////////////////////////////
        ///////// Finding Empty Row /////////
        /////////////////////////////////////

        // 2. chunking
        let rows = self.board.chunks(self.col_count);
        // 3. reversing rows
        let rows_reversed = rows.rev();
        let mut empty_row_idx: Option<usize> = None;

        for (idx, row) in rows_reversed.enumerate() {
            let tile_in_row = row.get(col_idx as usize).expect("This cannot happen");

            if tile_in_row.is_empty() {
                // as the rows are reversed we need to subtract from row_count
                empty_row_idx = Some(self.row_count - idx - 1);
                break;
            }
        }

        match empty_row_idx {
            Some(empty_row_idx) => {
                let idx_to_update = self.col_count * empty_row_idx + col_idx;

                // 4. updating the board
                self.board = self
                    .board
                    .iter()
                    .enumerate()
                    .map(|(idx, tile)| {
                        if idx == idx_to_update {
                            return match self.player_turn {
                                Player::Red => TileType::Red,
                                Player::Black => TileType::Black,
                            };
                        } else {
                            return *tile;
                        }
                    })
                    .collect();

                self.end_player_turn();

                true
            }
            // if no empty row found for `col_idx` return false
            None => false,
        }
    }
}

1. Bounds Checking

As we’re storing the entire grid as a single array, checking if the selected index is valid is trivial.

2. Chunking

Rust Vecs support non overlapping chunks out of the box.

3. Reversing the rows

As Connect-4 fills bottom up, we have to find the last row that’s empty to replace the tile.

There’s another way to combine the chunking and reversing via self.boards.rchunks which gives us an iterator over already reversed chunks but I wanted to break this down for clarity.

4. Updating the board

Once an empty row is found we can map over the board and replace it after updating the appropriate tile. If we go through all the rows without finding an empty row, we can just return false to signify that no update was made.

That should be it for interactivity!

Winning Move

As this requires changes in a lot of places I’ll only go over the crucial bits that use Rust features we haven’t explored before. The full diff can be found here. Currently the game never ends even if one of the player connects 4 of their tiles. The win condition requires a player to connect four of their tiles either horizontally, vertically, or diagonally. Let’s look at the first one.

As the state only changes when a player makes a move we can narrow things down to a player, a row, and a column.

//                    1. PartialEq
//                    ↓
#[derive(Copy, Clone, PartialEq)]
pub enum Player {
    Red,
    Black,
}

#[wasm_bindgen]
pub struct Board {
    // 2.
    pub winner: Option<Player>,
}

impl Board {
    fn is_game_over(&self, row_idx: usize, col_idx: usize) -> bool {
        self.has_4_consecutive_tiles_in_row(self.player_turn, row_idx)
            || self.has_4_consecutive_tiles_in_col(self.player_turn, col_idx)
    }

    fn has_4_consecutive_tiles_in_row(&self, player: Player, row_idx: usize) -> bool {
        // cell idx for the start of row
        let row_start_idx = self.idx_from_row_col(row_idx, 0);
        // cell idx for the end of row
        let row_end_idx = row_start_idx + self.col_count;
        // get a slice of tiles that belong to the row with `row_idx`
        let row_tiles = &self.board[row_start_idx..row_end_idx];

        let mut consecutive_count = 0;
        for tile in row_tiles {
            // 3.
            if tile.does_belong_to(player) {
                consecutive_count += 1;
                if consecutive_count >= 4 {
                    return true;
                }
            } else {
                consecutive_count = 0;
            }
        }

        false
    }
}

Similarly we can check if four tiles in a column belong to the expected player, I won’t write the code here but it’s part of the commit.

There are several ways of encoding the winning player but as we don’t advance the player turn after the winning move, it’s just simpler to combine the player_turn and is_game_over.

1. PartialEq trait

The partial eq trait is necessary to perform equality checks on enum variants. The derive macro conveniently implements the trait for us here as the Player enum variants are trivial.

2. Option type

Rust has no null values, the idiomatic way to encode the absence of a value is to use an Option of the appropriate type. In this case Option<Player> can either store Some(Player::Red) or Some(Player::Black) or None. We initialize the winner to None when the game starts and replace it with the appropriate player that makes the winning move.

On the JavaScript side None shows up as undefined.

3. does_belong_to

As we have more TileType variants than Player variants, we need a way to map whether a tile belongs to a player.

impl TileType {
    pub fn does_belong_to(&self, player: Player) -> bool {
        match self {
            TileType::Empty => false,
            TileType::Red => player == Player::Red,
            TileType::Black => player == Player::Black,
        }
    }
}

The JavaScript changes are trivial (updating text and disabling click events after game ends) and I’ll skip those here.

This concludes all of the gameplay for Connect-4, we’ve exposed the smallest amount of API required to play a full game. There’s no clean-up required as refreshing the page frees the memory allocated in WASM and reallocates the memory when the game restarts.

In the last post we looked at setting up the codebase to build Rust crates, and then importing them into a JavaScript project.

By the end of the post we’d gone over a simple enum based design for each position of the Connect 4 board. In this post, I’m going to expand on how we can take that simple data structure, build out the entire grid, and then render it using HTML elements.

But first, a bit of house-keeping. We’d looked at calling Rust functions from JavaScript, but not the other way around. So let’s dive into that.

Calling Home

Let’s expose a JavaScript function (Math.random), on the global object as that’s how it is made available to WASM. Everything else remains the same.

// only new line
window.mathRandom = Math.random;

// existing code

Right now if we try to call: mathRandom directly in Rust, the compiler won’t let us build.

Let’s repurpose our say_hello function with this:

#[wasm_bindgen]
pub fn say_hello() {
    let random_float = mathRandom();
    web_sys::console::log_1(&format!("Random number: {}", random_float).into());
 }

On re-building connecto.rs, it throws the following error.

error[E0425]: cannot find function `mathRandom` in this scope
  --> connectors/src/lib.rs:22:24
   |
22 |     let random_float = mathRandom();
   |                        ^^^^^^^^^^ not found in this scope

The problem here is that even though the function is attached to the window object, Rust has no way of knowing it exists. Now let’s write the equivalent of a “trust me bro” to placate the Rust compiler.

// wasm bindgen ensures that the glue code for this function exists
#[wasm_bindgen]
// 1.
extern "C" {
    // 2.
    #[wasm_bindgen(js_name = mathRandom)]
    // 3.
    fn math_random() -> f32;
}

1.

The extern block is used as an FFI (Foreign Function Interface) to allow Rust code to call foreign code. This generally means that the safety guarantees of the Rust compiler can’t save you anymore, and you better be really sure about what this function does.

2.

The second thing worth highlighting is the js_name = mathRandom. This is a way to translate names between JavaScript and Rust, so we can maintain appropriate style-guides on either end of the FFI.

3.

In our Rust code the function will be available as math_random and as the javascript function Math.random returns a floating point value between 0-1 the return type of f32 will suffice. Let’s put it to use.

#[wasm_bindgen]
pub fn say_hello() {
    web_sys::console::log_1(&format!("Random number: {}", math_random()).into());
}

Once re-compiled the app should log:

Random number: 0.7674366

The actual random number would vary.

As calling JavaScript’s standard library function is a common thing people do, the js_sys crate conveniently provides us handles to all of them. Let’s swap our hand-rolled version of Math.random and just use the one provided by the crate.

#[wasm_bindgen]
pub fn say_hello() {
    web_sys::console::log_1(&format!("Random number: {}", js_sys::Math::random()).into());
}

That works as expected: Random number: 0.583796439883168

Printing the grid

For rendering the grid it would be ideal to only print 1 character per enum variant so all the positions align. Let’s update the Display trait implementation.

If you rememeber from the last time, the Display trait is implemented so when we try to print each of the TileType variants the actual string will be displayed.

impl fmt::Display for TileType {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let tile_repr = match self {
            TileType::Red => "R", // formerly: Red
            TileType::Black => "B", // formerly: Black
            TileType::Empty => "_", // formerly: Empty
        };
        write!(f, "{tile_repr}")
    }
}

Let’s try printing the enum variant.

let tile_1 = TileType::Red;
web_sys::console::log_1(&format!("Tile 1 belongs to: {}", tile_1).into());

This now prints: Tile 1 belongs to: R

And with that we’re ready to print the entire connect 4 board. As printing an empty board is not fun, let’s generate a randomized board using the js_sys::Math::random() function.

Game Board

//  all usages of `const`s are replaced by the value at compilation
//  ↓
const ROWS_COUNT: usize = 6;
const COLS_COUNT: usize = 7;

/// This returns a Vec<TileType> of the given length
///
fn get_random_variants(n: usize) -> Vec<TileType> {
    let mut values = Vec::with_capacity(n);
    for _ in 0..n {
        //                                                 for 3 enum variants
        //                                                 ↓
        let random_variant_idx = (js_sys::Math::random() * 3.0).floor() as u8;
        let variant = match random_variant_idx {
            0 => TileType::Empty,
            1 => TileType::Red,
            2 => TileType::Black,
            _ => panic!("Unexpected value encountered")
        };

        values.push(variant);
    }
    // anything not followed by a semi-colon is returned
    values
}

This should be fairly similar to a JavaScript function that tries to populate an array with enum values. The as keyword is used to cast one type of number into another, and we want to go from a floating point number to a whole number. In this case as we’re never going to have more than 3 variants, there’s no need to store anything larger than an unsigned 8-bit int (max value: 255).

Let’s print this sucker.

#[wasm_bindgen]
pub fn say_hello() {
    let board = get_random_variants(ROWS_COUNT * COLS_COUNT);

    // first create a string
    let mut output = String::new();
    //           without enumerate we won't have access to the index
    //           │
    //           │                      index
    //           ↓                      ↓
    board.iter().enumerate().for_each(|(i, tile)| {
        if i > 0 && i % COLS_COUNT == 0 {
            output.push('\n');
        }
        output.push_str(&format!("{} ", tile));
    });
    output.push('\n');
    web_sys::console::log_1(&output.into());
}

This should print a nice randomly populated grid of R | B | _.

Connect-4 boards cannot assume arbitrary random states due to the constraint of each tile dropping to the lowest available position. However we’ll come back to that after we look at sending this data over to the JavaScript side.

Returning the grid

Let’s expose our TileType enum to the JavaScript side by adding a #[wasm_bindgen] macro at it’s top.

So far we’ve only exposed a function and an enum to the JavaScript side, however another data type struct is more suitable for returning custom data structures. Let’s start by creating a new struct that can be later reused to implement the gameplay.

#[wasm_bindgen]
pub struct Board {
    row_count: usize,
    col_count: usize,
}

Nothing new here, the wasm_bindgen macro will create the JavaScript glue code for this struct. usize just means unsigned int corresponding to the size of memory addresses for your particular machine. For most modern machines this translates to u64.

Now let’s expose a constructor:

#[wasm_bindgen]
impl Board {
    pub fn new(row_count: usize, col_count: usize) -> Self {
        Self {
            row_count,
            col_count,
        }
    }
}

The glue code for struct results in a JavaScript class. All JavaScript classes (other than pure static ones) need to be instantiated. new constructor ends up becoming a static method on the corresponding Board class in the JavaScript package. We can instantiate it like this: const board = Board.new(6, 7).

Let’s add another method that can return the randomized board we generated earlier:

    //                     1. Uint8Array
    //                     ↓
pub fn get_board(&self) -> js_sys::Uint8Array {
    let board = get_random_variants(self.row_count * self.col_count);
    // js_sys crate includes utility functions to convert `slices` to typed arrays
    //
    //                       2. slice
    //                       ↓
    js_sys::Uint8Array::from(&board[..])
}

1.

The best way to return array like data from Rust to JavaScript is TypedArrays, and in this case it ends up being a Uint8Array. As each board position can only take one of three enum variants, 8-bits are more than sufficient.

2.

Slices are one of three array like data types available in Rust. The details are outside the scope of this tutorial and the Rust book provides a much better explanation than I’d be able to here.

Now let’s get rid of our say_hello function as we won’t been needing that anymore, and print the data received on the JavaScript side.

This is the entirely of the script now:

import init, { Board, TileType } from "./connectors/connectors.js";
const ROW_COUNT = 6;
const COL_COUNT = 7;
// this duplication is necessary
// just so it's easy to render as a grid
const DISPLAY_TILE_MAP = {
  [TileType.Empty]: "_",
  [TileType.Red]: "R",
  [TileType.Black]: "B",
};

init().then(() => {
  const board = Board.new(ROW_COUNT, COL_COUNT);
  const tiles = Array.from(board.get_board()).map(
    (tileEnumValue) => DISPLAY_TILE_MAP[tileEnumValue],
  );
  let boardGrid = "";
  tiles.forEach((tile, idx) => {
    // if next tile starts a new row, add a newline
    boardGrid = (idx + 1) % COL_COUNT === 0
      ? `${boardGrid} ${tile} \n`
      : `${boardGrid} ${tile}`;
  });
  console.log(boardGrid);
});

This should print an entire 7x6 grid of randomized Tiles.

Rendering Board as HTML

This part should be familiar. As we have all the data on the JavaScript side, we can use it to render the Board as HTML instead of logging it to the console.

// ...
const fragment = document.createDocumentFragment();
// create a span per tile and display the TileType
tiles.forEach((tile, idx) => {
  const span = document.createElement("span");
  span.textContent = tile;
  fragment.appendChild(span);
});

const gameBoard = document.getElementById("game-board");
gameBoard.innerHTML = "";
gameBoard.appendChild(fragment);

// ...

We won’t go into the CSS changes, but feel free to get creative here. The full project at this stage is here.

We’re getting close to gameplay now. In the next post we’ll look into adding player turns to the Board struct, and some methods that allow players to make moves.

Frankenpenguin | Repository

[2:30 PM] I discovered a blog post about vibe coded performance benchmarks for drawing a large number of rectangles on the HTML canvas. It was an interesting read and I was nodding along until I saw that all the Typescript benchmarks were better than the Rust ones. That can’t be right?

[3:00 PM] My hunch was that most of the time was spent crossing the boundary between Rust and Javascript. This is something I’ve been burned by in the past.

[3:30 PM] I decoupled the work scheduling from the sync compute and rendering [1]. Deleted a few lines of code that were creating the render loop and recursively calling it from the request_animation_frame. And then moved the scheduling to Javascript.

BEFORE

// Rust updates the rectangle positions
//      renders to canvas
//      updates the fps counter
//      recursively schedules next render loop

┌─────────────────┐                       ┌───────────────────────────────────┐
│  Javascript     │                       │  Rust                             │
│                 │                       │                                   │
│                 │                       │  ┌─────────────────────────────┐  │
│                 │                       │  │ start                       │  │
│                 │                       │  │                             │  │
│                 │                       │  │ ┌──────────────────────┐    │  │
│                 │                       │  │ │ start_animation_loop │    │  │
│                 │                       │  │ │                      │◀┐  │  │
│                 │  wasm_bindgen(start)  │  │ └──────┬───────────────┘ │  │  │
│                 │  ──────────────────▶  │  │        │                 │  │  │
│                 │                       │  │        ▼                 │  │  │
│                 │                       │  │ ┌──────────────────────┐ │  │  │
│                 │                       │  │ │ render               │ │  │  │
│                 │                       │  │ │                      │ │  │  │
│                 │                       │  │ └──────┬───────────────┘ │  │  │
│                 │                       │  │        │                 │  │  │
│                 │                       │  │        └─────────────────┘  │  │
│                 │                       │  └─────────────────────────────┘  │
└─────────────────┘                       └───────────────────────────────────┘

AFTER

// JavaScript calls the `frankenpenguin.tick()`

// Rust       updates the rectangle positions
//            renders to canvas

// JavaScript updates the fps counter
//            recursively schedules the ticks

┌────────────────────────────────────┐                   ┌────────────────────┐
│  JavaScript                        │                   │ Rust               │
│                                    │                   │                    │
│  ┌────────────────────────────┐    │                   │                    │
│  │ render                     │◀─┐ │                   │                    │
│  │                            │  │ │                   │                    │
│  │ ┌───────────────────────┐  │  │ │                   │ ┌──────────────┐   │
│  │ │                       │  │  │ │                   │ │ tick         │   │
│  │ │                       │  │  │ │                   │ │              │   │
│  │ │                       │  │  │ │                   │ └──┬───────────┘   │
│  │ │                       │  │  │ │                   │    ▼               │
│  │ │ frankenPenguin.tick() │────────────────────────▶  │ ┌──────────────┐   │
│  │ │                       │  │  │ │                   │ │ render       │   │
│  │ │ requestAnimationFrame │─────┘ │                   │ │              │   │
│  │ │                       │  │    │                   │ └──────────────┘   │
│  │ └───────────────────────┘  │    │                   │                    │
│  └────────────────────────────┘    │                   │                    │
└────────────────────────────────────┘                   └────────────────────┘

[3:45 PM] I run the benchmarks. Hmmmm, it’s 2x faster, not bad. I was mistakenly comparing the updated Rust + WebGL implementation to the TS + WebGL version.

[4:00 PM] The train is unusually late.

[4:38 PM] I get to the gym, but the person turns me away as I’m too late [2].

[5:21 PM] I push the repository to GitHub.

[This morning] I realize that I was comparing the wrong benchmarks and the diff resulted in a 10x bump in perf.

Aside 1: To schedule async work in the browser you can pass a callback to the requestAnimationFrame API. As Rust doesn’t ship with a runtime, scheduling work requires using the closest one avaiable. In the browser it ends up being… the browser. So you have to use a crate that would provide the bindings to the requestAnimationFrame API.

Aside 2: I ended with playing Table Tennis afterwards so it’s all good.

[Edit] After receiving some generous feedback from my friend Tim, I’ve made some changes to clarify confusing topics, and added another post that should make it easier for first time Rust users to get started here. If You’re already familiar with Rust project structures, and have written some amount of Rust, please continue reading.

When I first wanted to learn Rust in 2017, I had no idea where to start. I had written some C starting back in 7th grade, however I wasn’t particularly good at it. The only language I was competent at was JavaScript, and there weren’t a lot of resources that bridged the gap between JavaScript and Rust.

My hope with this series is that it’ll allow people familiar with JavaScript to incrementally adopt Rust.

There are a lot of similarities between the ecosystems surrounding these languages. As all the Rust code is compiled to WASM, it can open up a path for adoption into existing JavaScript project workflows, hopefully lowering the barrier of entry.

There are also a lot of differences between these languages, some of which might be out of the scope of this series. I’ll add links to more information when encountering jargon that might not make the most sense to somebody unfamiliar with the Rust ecosystem just yet.

In this series I go over building a small browser based Connect-4 game, which uses Rust compiled to WebAssembly for the core gameplay mechanics and state management. This is very much a follow along, as that’s what I find most effective for information retention. Here is the accompanying repository, that I’ll use for reference. It can also serve as checkpoints in case the readers find their own implementations diverge.

Directory Structure

connectors/
├─ connecto.rs/                // 1. workspace
│  ├─ build.sh                 // 2. WASM build script
│  └─ connectors/
│     └─ src/lib.rs            // 3. Rust crate's (connectors) entry point
└─ www/                        // 4. client-side code
   ├─ connectors/              //    WASM package
   └─ src/                     //    JS entrypoint

This is the general directory structure I use for building applications with Rust and JavaScript. I’ve found that this works best for building the rust crates [1] into packages that can be directly consumed by the JavaScript projects.

1.

Here is the definition of Cargo workspaces from the Rust Book.

“…you might find that the library crate continues to get bigger and you want to split your package further into multiple library crates. Cargo offers a feature called workspaces that can help manage multiple related packages that are developed in tandem.”

It’s similar in nature to a yarn workspace where different npm packages can share project dependencies.

2.

# connecto.rs/build.sh

#!/bin/bash

set -euo pipefail

TARGET=web
OUTDIR=../../www/connectors

# The only interesting part
wasm-pack build connectors --target $TARGET --release --out-dir $OUTDIR

It basically means that we’re going to compile the connectors crate for web target into the JavaScript project’s directory so it can be imported.

3.

// connecto.rs/connectors/src/lib.rs

// use statements are similar to an `import` statement
// here we're importing the `wasm_bindgen` macro from `wasm_bindgen` crate's `prelude` module
// <crate>::<module>::<macro>
use wasm_bindgen::prelude::wasm_bindgen;

// wasm_bindgen takes care of creating the glue code we need to call the `say_hello` function from JavaScript
#[wasm_bindgen]
pub fn say_hello() {
  // web_sys crate encapsulates a bunch of useful JavaScript functions for ease of use
  //
  //                      reference       into
  //                      ↓               ↓
  web_sys::console::log_1(&"Hello, WASM!".into());
}

In JavaScript all non-primitives types are passed by reference, but in Rust you have to specify whether something is a reference or a value. For more details on this topic, check out this section of the Rust Book. Will come back to the into call at a later point, but here’s what Rust by Example has to say.

4.

The client side code will be the most familiar to JavaScript engineers, it’s a single JavaScript file that starts an http server using node and serves the index.html.

Let’s look at the javascript code:

// www/index.js

import init, { say_hello } from "./connectors/connectors.js";

// WASM modules compiled for the web require initialization
init().then(() => {
  // calling Rust function we declared earlier
  say_hello();
});

Running the code

Now that the project structure is somewhat out of the way, let’s trying running the code.

# building the engine
cd connecto.rs
chmod +x build.sh
./build.sh

# starting the node server
cd www
node server.mjs

If you’ve been following along so far, open up http://localhost:8000 in your favorite browser, “Hello, WASM!” should be logged in the console.

Connect Four

At this point we’ve (hopefully) established a good baseline understanding of different parts of the codebase, we can start working towards the connect four game.

Let’s look at the crate changes first.

engine.rs

This is the module which will hold all the data structures relevant to the gameplay. The most important part of connect-4 are the states of each position. All three configurations “empty”, “red”, and “black” can be stored as variants of an enum. And as we need to import this enum into the entrypoint lib.rs, I’m declaring it using a pub keyword. This is necessary as data in Rust is private by default.

// connecto.rs/connectors/src/engine.rs

// declaring the enum public allows us to access it outside of the `engine.rs` file
// variants for a public enum are also public
   pub enum TileType {
       Empty,
       Red,
       Black,
   }

lib.rs

Using engine.rs in the entrypoint lib.rs.

// connecto.rs/connectors/src/lib.rs

// this is similar to importing a local module in JavaScript
mod engine;

// this is a bit of controversial indirection, that isn't necessary but allows all other local modules to keep their imports organized.
// Instead of each module having to keep track of it's own crate and local imports, they can just say `use crate::prelude::*` and call it a day.
mod prelude {
    ...
    pub use crate::engine::*;
}

// this makes everything imported inside the `prelude` module available to the `lib.rs`
use prelude::*;
---

Now to the significant bit. I’ve updated the say_hello function to declare a few variables with the let keyword and assigned enum variants. The let keyword is different from JavaScript in that it by default doesn’t not allow re-assignment to those variables.

// connecto.rs/connectors/src/lib.rs

#[wasm_bindgen]
pub fn say_hello() {
    let tile_1 = TileType::Red;
    let tile_2 = TileType::Black;
    let tile_3 = TileType::Empty;

    web_sys::console::log_1(&format!("Tile 1 belongs to: {}", tile_1).into());
    web_sys::console::log_1(&format!("Tile 2 belongs to: {}", tile_2).into());
    web_sys::console::log_1(&format!("Tile 3 belongs to: {}", tile_3).into());
}

What happens on compiling the crate via the build.sh?

I get a few errors, including the following:

error[E0277]: `engine::TileType` doesn't implement `std::fmt::Display`
  --> connectors/src/lib.rs:19:63
   |
19 |     web_sys::console::log_1(&format!("Tile 1 belongs to: {}", tile_1).into());
   |                                                               ^^^^^^ `engine::TileType` cannot be formatted with the default formatter
   |
   = help: the trait `std::fmt::Display` is not implemented for `engine::TileType`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead
   = note: this error originates in the macro `$crate::__export::format_args` which comes from the expansion of the macro `format` (in Nightly builds, run with -Z macro-backtrace for more info)

This is the one I really care about:

the trait `std::fmt::Display` is not implemented for `engine::TileType`

Let’s go ahead and implement the trait for TileType.

// connecto.rs/connectors/src/lib.rs

impl fmt::Display for TileType {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        // Rust's match statements are something between a ternary and a switch statement in JavaScript
        // But as every statement in Rust is an expression (i.e. returns a value), we can assign the values to `tile_repr`
        // And then write the value to the format "stream"
        let tile_repr = match self {
            TileType::Empty => "Empty",
            TileType::Red => "Player Red",
            TileType::Black => "Player Black",
        };

        write!(f, "{tile_repr}")
    }
}

Compiles without a hitch! And the browser console now logs:

Tile 1 belongs to: Player Red
Tile 2 belongs to: Player Black
Tile 3 belongs to: Empty

Traits are Rust’s way of defining shared behavior. They are more akin to composition via object extension than classical inheritence.

The trait fmt::Display requires that the function fn fmt be implemented, which gives our enum TileType the ability to define how each of its variants are to be formatted when using the format! macro.

Let’s try one more thing, and implement a method on our enum directly called is_empty.

// connecto.rs/connectors/src/lib.rs

impl TileType {
    //               the borrowed self here is used for a regular method
    //               ↓
    pub fn is_empty(&self) -> bool {
        // if the match expression is only used to return bool values, you can just use the shorthand macro
        matches!(self, TileType::Empty)
    }
}

Enums in Rust can also have methods. This allows us to check if a particular TileType variant is empty, like the following:

// connecto.rs/connectors/src/lib.rs

#[wasm_bindgen]
pub fn say_hello() {
    // existing code

    web_sys::console::log_1(&format!("Is Tile 3 empty: {}", tile_3.is_empty()).into());
}

After re-compiling, the console should now log four statements:

Tile 1 belongs to: Player Red
Tile 2 belongs to: Player Black
Tile 3 belongs to: Empty
is Tile 3 empty: true

Remember that this method is associated to the concrete instance of the enum, so we’d call the method on the variant instead of the enum itself.

Here’s the complete diff.

In the next post we’re going to look into rendering the Connect-4 board as HTML.

Flashlight | Perf comparison

I recently talked to a group of engineers about integrating WASM into Javascript projects. I’ve integrated some Rust compiled to WASM into my projects a few times for various reasons ranging from performance to FOMO. I wanted to write down the architecture of a tiny game I wrote recently (with vanilla JS, HTML, and WASM), to demonstrate how to integrate very small parts of Rust using WASM into Javascript/TS projects. And eventually let it consume your entire life.

I’ve been interested in roguelikes since I first saw Gridbugs’ Rain Forest and started reading the blog posts. The rabbit hole led me down recursive shadowcasting and the work Roguelike Celebration conference speakers have been creating. I wanted to make something for the web without an engine or external libraries, just for shits and giggles.

This post highlights some aspects of the architecture that I think are most crucial to recreating something like Flashlight without excessive handholding.

The architecture has undergone several small refactors but the following constraints have always guided the changes:

• run in the browser
• fast
• LGTM on mobile
• no libraries
• avoid exploits

Current Architecture

                                          ┌────────────┐
                                          │            │
                                   ┌─────▶│Shadowcaster│
                                   │      │            │
                                   │      └────────────┘
┌─────────┐      ┌──────────┐      │      visibility
│         │      │          │      │
│   Rex   ├─────▶│Flashlight│──────┤
│         │      │          │      │
└─────────┘      └──────────┘      │      pathfinding
Javascript        Rust             │      ┌────────────┐
                  entrypoint       │      │            │
                                   └─────▶│ Pathfinder │
                                          │            │
                                          └────────────┘

Rex

Usually when I write a new web app I just use React as it’s straightforward and I can focus on the app logic. This time I didn’t want to bloat the bundle size for something this simple.

Rex is an incredibly thin library for wrangling observable streams. All of the event handling, data manipulation, and visual side effects are handled by it.

It can do a handful of things:

1. create a stream

   1.1. from an event

   1.2. from a timer

2. apply filtering over a stream

3. map over a stream

4. merge two streams

5. cause side effects via stream subscriptions

// Emit a tuple of values every 500 millisecond.
// Log 5 times and then unsubscribe.
//
// - `Stream.fromInterval(500)` creates a stream that emits a value every 500 milliseconds.
// - `Stream.fromInterval(1000)` creates a stream that emits a value every 1 second.
// - withLatestFrom combines both the Streams.
const halfSecStream$ = Stream.fromInterval(500);
const mixedTimerStream$ = Stream.fromInterval(1000).withLatestFrom(
  halfSecStream$,
);

mixedTimerStream$.subscribe({
  next: ([halfSecTick, oneSecTick]) => {
    console.log(halfSecTick, oneSecTick);
    // unsubscribe after logging 5 times
    if (halfSecTick >= 5) mixedTimerStream$.unsubscribe?.();
  },
  complete: () => {
    console.log("stream concluded");
  },
});

These are sufficient to build a tiny game like Flashlight.

Entrypoint - Flashlight (crate)

This is the entrypoint into the gameplay logic all of which is compiled to WASM and runs in the browser. The game uses recursive shadowcasting to calculate the visible tiles. Initially I wrote shadowcaster to use on a game I wrote with Bevy (a Rust game engine), so instead of re-implementing shadowcasting in Javascript I build the game around it and used WASM to run it on the browser. Later on in the post you’ll see that running the core game logic in WASM provides a gameplay benefit that aligns with the core mechanic.

Flashlight takes care of the following:

• process character movement
• process enemy movement
• get clipped map state from camera
• update map state
• enforce gameplay rules like walkable tiles, consumables, combat etc

Shadowcaster

Flashlight calls into Shadowcaster to calculate the tiles visible to the character at any given time. I won’t go much into the details of the implementation other than that it was implemented without looking at existing implementations and was pretty incorrect for a long time. Here are some references that I’ve used while building it.

• Visible Area Detection with Recursive Shadowcast - Gridbugs
• Roguelike Vision Algorithms - Adam Milazzo

The compute_visible_tiles function does the heavy lifting of finding the visible tiles and returning their positions, and Flashlight then decides how to best use that to update map state.

// Rust
pub enum TileType {
    Transparent,
    Opaque,
}

pub struct TileGrid {
    pub tiles: Vec<TileType>,
    ..
}

fn compute_visible_tiles(&mut self, world: &TileGrid) -> HashMap<IVec2, i32> { ... }

Pathfinder

This is just a naive breadth-first search implementation that allows the enemy to find the character. I wanted to keep pathfinding in a separate create as I’ve been using it on other projects that don’t share the core gameplay of Flashlight. It merely takes a vector of glyphs, grid width, a starting glyph and an ending glyph, and returns the shortest set of moves between those glyphs. The rules engine then determines what to do with all this data.

// Rust

fn find_path(
    starting_map: &Vec<Glyph>,
    width: u8,
    from_glyph: Glyph,
    to_glyph: Glyph,
) -> Vec<Move> { ... }

Flashlight (crate) contd.

Once the crate has all the information it updates the state and converts it to a JS UInt8Array to communicate the updated map state back to the JS for rendering. As the only way to communicate between the JS context and the WASM boundary is via character move commands and a map state in the form of a UInt8Array there’s little room for leaking extra information. This ensures that the player can’t just inspect element on the hidden glyphs to find the locations of the enemy and the health pack. Only returning a single array of glyphs that represent each cell on the map has it’s drawbacks. The state can only represent full moves, and no sub move data can be represented using the map state. Eg. animation direction of the character when it bumps into an obstacle is kept firmly in the JS land. Visual properties of how each cell is rendered have to be mapped from a single UInt8 (glyph). On one hand it’s very limiting but it also means that the frontend can be completely independent. I can write it using canvas, a native gui library, as a terminal UI etc.

This brings me back to Rex and how the glyphs are rendered to the screen (it’s just HTML divs).

UI and Ephemeral State Management

Rendering the UI elements and the game is handled via JS functions all of which are orchestrated using Rex.

Any state that doesn’t impact the core gameplay stays firmly in the JS land. The state of the UI is stored in a class which keeps track of things like character animation states, in-game dialog, dialog boxes, button states, etc. All of this isn’t part of the core gameplay logic (inside flashlight crate) as it can either be derived from the map state or it’s too tightly coupled to the visual representation. Particle effect states like position and intensity of rain, damage numbers over the player character and the monster, etc are part of the closure state of their update functions. This data doesn’t have gameplay consequences and that’s why colocating it inside the core engine has no benefits.

I want to focus on a small section of the game that triggers a state update and renders the map to demonstrate the end to end flow. At the start of the game the user is expected to turn the flashlight on by tapping the button three consecutive times.

Local state update

This is an ever so slightly simplified version of the code that connects events to state updates. The code comments point to the capabilities of Rex mentioned earlier.

// Typescript

// 1.1. create a stream from an event
const keyDownInput$ = Stream.fromEvent("keydown", document.body);

// 2. apply filtering to a stream
// filtered stream only contains instances of `f` keydown events
const fKeyInput$ = keyUpInput$.filter((e) => keyIsF(e));

const flashlightButtonClick$ = Stream.fromEvent(
  "click",
  document.getElementById("flashlight"),
);

flashlightButtonClick$
  // 4. merge two streams
  .withLatestFrom(fKeyInput$)
  // only continue if the flashlight is turned off
  .filter(() => !playerState.isFlashlightOn)
  // 3. map over a stream
  .map(([e1, e2]) => {
    e1?.preventDefault();
    e2?.preventDefault();

    // update state
    return { value: playerState.isFlashlightOn };
  })
  .subscribe({
    next: ({ value }) => {
      // 5. cause side effects
      toggleFlashlight({ value });
    },
    complete: () => {},
  });

Rendering

This is a version of the render function, simplified for illustration.

// Typescript

export const render = () => {
  // this computes the visibility of each time from the player's POV
  if (playerState.isFlashlightOn) engine.compute_visibility();

  // UInt8Array converted to an array of glyph indices
  const mapState = Array.from(engine.get_map_state());

  // render target
  const mapGridContainer = document.getElementById("grid-container");

  // render each tile as a div
  arr.forEach((glyphIdx, cellIdx) => {
    const cell = document.createElement("div");
    const cellVisibility = visibility[cellIdx];

    // set luminance value based on calculated visibility for the tile
    cell.style.backgroundColor = `hsla(44, 96, ${cellVisibility}, 100)`;

    // ['+', ' ', '♣', ' ', '.', '@', 'G', 'g']
    cell.textContent = GLYPHS[glyphIdx];

    mapGridContainer.appendChild(cell);
  });
};

Once the filter is satisfied the state for flashlight (in-game item) is toggled which results in the compute_visibility function getting invoked in the next render loop. Flashlight uses the shadowcaster crate to get a hashmap of tiles that are visible.

// Rust

impl Flashlight {
    ...
    pub fn compute_visibility(&mut self) {
        // shadowcaster only cares if a tile is opaque or transparent
        // so I map each Glyph to the appropriate tile type
        let tiles = self
            .map_state
            .iter()
            .map(|glyph| match glyph {
                | Glyph::Monster
                | Glyph::Player
                | Glyph::Floor => TileType::Transparent,
                Glyph::Target | Glyph::Tree => TileType::Opaque,
            })
            .collect();
        let mut visibility = Visibility { ... };
        visibility.observer = IVec2 {
            // set the player position as the observer
        };
        let visible_tiles_hashmap = visibility.compute_visible_tiles(&TileGrid {
            tiles,
            ...
        });
        // store the visibility on the main struct
        self.visibility_state = visible_tiles_hashmap;
    }
}

I’ve written UI apps in React since before the first major version was released. Things like a rich text editor, a photo-editor, some games etc. Back in my day, things had lifecycle methods.. And we injected an instance of V8 inside Laravel to SSR before it was mainstream.

I like React, it’s been straightforward to use. There are faster/lighter/easier things out there, some more interesting like this. I don’t really want to talk about them.

I despise NextJS, not for it’s own faults although I can talk about those too, but for the bullshit surrounding it. From Guillermo’s annoying tweets to the npm package name grab, to two bilboards on the same street corner to Youtube videos titled “Cool FramerJS animations with NextJS”. Bro it’s an SSR framework why do you need to… ugh.

Anyway, I recently discovered that NextJS 15 forces some sync APIs like useParams to be async. It reminded me of a discourse from a few years ago about function coloring.

TLDR; NextJS needs to know which components to skip when pre-rendering, async is how they do it. GGPO.

What the hell is component coloring?

If you’re familiar with async/await you’d remember that to use the output of an awaited function you have two choices:

• make the caller async
• or slap a .then(callback)

The second option isn’t really “using the awaited value” as things are out of the caller’s hands now and the awaited value can only be used in the callback.

The first option is what the cool kids are doing. And this “making caller async” can potentially go all the way to your root component. Good luck.

But what does this have to do with server components? I’m glad you asked.

NextJS pre-renders components. Which means it’ll render some components before a user even asks for them. Eg: some static stuff that doesn’t depend on user behavior. However evaluating the contents of an entire component to determine whether it can be statically rendered is costly.

Remember the stupid annotations “use client”? The thing that everyone slaps at the top of every component so they can keep writing React code the way they already liked. That’s how React sorts your client/isomorphic components into neat little buckets.

However that’s not good enough, you need even more fine grained buckets to make sure you’re not wasting compute evaluating the contents of a component that’s dependent on indeterminate data.

In a recent update NextJS decided to make a few APIs asynchronous that actually are not. Think of it as an async IIFE, basically Promise.resolve(value).

What in the world?

The reason for doing this is to force the developers to somehow color their components, which makes it easier for NextJS to determine where to draw the pre-rendering boundary.

An example of this is the useParams API.

// app/greeting/page.jsx
const BlueComponent = () => {
  return <div>Hello!</div>
}

// NextJS 14
// app/greeting/[:username]/page.jsx
const AnotherBlueComponent = () => {
  const { username } = useParams();

  if (!username) {
    <BlueComponent />
  }

  return <div>Hello! {username}</div>
}

As the parameters come from a request, NextJS would have to see into the future to pre-render this. But as brilliant as Vercel is at marketing, they can’t really pre-render something that’s dynamic. Why? Coz it could literally be anything, like social security numbers, or the phone number of your high school crush.

So to be able to efficiently draw a boundary around the work that NextJS needs to do around SSR they want you to declare which components are dependent on these indeterminate parameters.

But how can a framework be sure that developers will do the right categorization? You could either do something like introduce a new keyword that developers would have to use to define which components our dynamically rendered like “server pre-render pls” and “server skip” or you could use something that already exists in the language. JavaScript already has a keyword that could be helpful, but a framework can’t still reliably ensure that a user will declare their components asynchronous. So by making a handful crucial APIs asynchronous NextJS can effectively force the developers to color their components. If a component is blue, i.e. synchronous NextJS can pre-render it but if a component is green, i.e. asynchronous NextJS can reliably skip without leaving perf gains on the table.

// app/greeting/page.jsx
const BlueComponent = () => {
  return <div>Hello!</div>
}

// NextJS 15
// app/greeting/[:username]/page.jsx
const GreenComponent = async () => {
  const { username } = await useParams();
  return <div>Hello! {username}</div>
}

Theo will tell you that these greens (components) are good for you. I will tell you that using existing language feature to improve a framework is good but selling your soul to SSR for the “perceived” speed improvement is not worth it. You’re only writing a client-side Framer animation for a marketing website anyway!

If you love NextJS and really disagree with everything I mention, LMK in the comments below.

In the last post I built the UX component, but so far it doesn’t do anything other than being highly entertaining for cats.

In this one I’m gonna write a render pipeline and by the end it still won’t makes sense how to connect the *cough* Dots.

How old is this browser?

In a past life I worked on an extremely cool photo editor that had a ton of features and 100k MAUs. It was built using WebGL, and it works on most browsers and most phones. So naturally I wanted to build this one on WebGPU which is available on less than 50% of the browsers that matter.

I use Firefox, so to build this thing I downloaded Firefox Nightly. Safari works too, but I had to enable the WebGPU feature flag.

Render..er

As I’m quite an overachiever I decideed that the API had to be right from the beginning, and I couldn’t just throw everything inside a useEffect.

So I wrote a class that takes care of initialization, tear down, and rendering. WebGPU initialization is async, and Javascript doesn’t have async constructors so I did the right thing and routed the initialization through a static function. Do the right thing.

export class RenderDude {
  gpuConfiguration: GPUConfiguration;

  // making the constructor private ensures that RenderDude can't be called with `new`
  private constructor(gpuConfiguration: GPUConfiguration) {
    this.gpuConfiguration = gpuConfiguration;
  }

  // this is the only API that gets called from external code to initialize the GPU and return an instance of RenderDude
  static async init() {
    const gpuConfig = await RenderDude.initializeGPU();
    return new RenderDude(gpuConfig);
  }

  // this does the heavy lifting of getting the WebGPU context and initializing the pipeline
  private static async initializeGPU() {
    if (!navigator.gpu) {
      throw new Error("Your browser doesn't support GPUs");
    }

    const canvas = document.getElementById("canvas-root") as HTMLCanvasElement;
    const adapter = await navigator.gpu.requestAdapter();
    const device = await adapter?.requestDevice();
    const context = canvas.getContext("webgpu");

    // ... pipeline init omitted for later
    return { device, context, pipeline };
  }
}

Loading an image

Vertex Shader

It’s easier to render a triangle, but that’s unrelated to photo editors so I just skipped that part. The simplest vertex shader I could write for the editor is one that loads an image.

const vertexShaderOutputStructName = "VertexShaderOutput";
const vertexShaderOutputStruct = {
  name: vertexShaderOutputStructName,
  struct: `
struct ${vertexShaderOutputStructName} {
  @builtin(position) position: vec4<f32>,
  @location(0) texcoord: vec2<f32>,
};`,
};

const vertex = `
${vertexShaderOutputStruct.struct}

@vertex
fn main(@builtin(vertex_index) vertexIndex: u32) -> ${vertexShaderOutputStruct.name} {

  // I'm using triangle lists, so have to pass 2 sets of 3 vertices to render a rectangle
  // texture coordinates go 0.0 -> 1.0, across and down
  var pos = array<vec2<f32>, 6>(
    vec2f( 0.0,  0.0),  // center
    vec2f( 1.0,  0.0),  // right, center
    vec2f( 0.0,  1.0),  // center, top
    vec2f( 0.0,  1.0),  // center, top
    vec2f( 1.0,  0.0),  // right, center
    vec2f( 1.0,  1.0),  // right, top
    );

  var vsOutput: VertexShaderOutput;
  let xy = pos[vertexIndex];

  // scale the quarter screen, so it renders on the entire canvas
  vsOutput.position = vec4<f32>(xy * 2.0 - 1.0, 0.0, 1.0);
  vsOutput.texcoord = xy;
  return vsOutput;
}
`;

Fragment Shader

This is even simpler as all I did here was to return the color sampled from the texture, using the texture coordinates.

const fragment = `
${vertexShaderOutputStruct.struct}

@group(0) @binding(1) var imageSampler: sampler;
@group(0) @binding(2) var imageTexture: texture_2d<f32>;

@fragment
fn main(fsInput: ${vertexShaderOutputStruct.name}) -> @location(0) vec4<f32> {
  let sampledColor = textureSample(imageTexture, imageSampler, fsInput.texcoord);

  return sampledColor;
}
`;

There hasn’t been a lot of advancement in the ease of use of photo editing tools, and the barrier remains fairly high. Generative AI doesn’t do as much for photo editing as it does for full blown photo generation. So while the new iPhone and iOS launches have all been about Apple Intelligence, the feature that I’ve loved is the new style edit tool in the Photos app. Style edit is the much needed improvement in editing UX. It’s akin to Prometheus making fire accessible to mere mortals.. well mortals who own an iPhone 16. It’s a 2-dimensional slider that combines something they call a palette, and a general 3-channel curves tool. After testing a few styles I’ve concluded that what they call palette is just a look-up-table (LUT). Something colorists have used for decades to create a consistent visual language through color scheme. It’s an incredibly fast way to alter the look and feel of an image, but I digress.

Why do I care so much?

When Douglas Engelbart first introduced the mouse in ‘68 it opened UX possibilities that are still the primary mode of interacting with a computer. Multi-touch screens ushered in a new era of user experiences that were not possible before, eg. doomscrolling. Now I can’t claim that the 2D slider is going to change our world, but for lazy photographers like myself it might be the best compromise between unedited photos and a cohesive visual language.

What’s annoying though is that Style editor is paywalled behind the latest version of the iPhone, and it only works on the photos taken with the iPhone 16. Bummer, I wonder if I can just write a web version.

This is what it looks like:

Let’s bring it to the web, shall we?

As I like to have fun and not burning out on side-projects, I decided to build the toy first, that is the 2D slider component.

Rendering the dots

I start off by creating a dot grid. CSS grid made this trivial once I decided on the number of rows and columns. Once the cells are in place, I render a circle in the middle of each cell.

I wanted to make the size of each dot react to the distance from the pointer. And also ensure that the effect dissipates quickly leaving any dots outside of a certain distance un-affected. As I want the strength of the effect to decrease sharply I can make it proportional to the inverse of some power of the distance. Square should work, right?

Calculating distance of dots

To calculate the distance I need the position of the cell’s center where the dot is rendered. Once the cell is rendered and its layout calculated, I use getBoundingClientRect to get its position and size. Position of the center is just: x = (rect.left + rect.width / 2) y = (rect.top + rect.height / 2)

To validate I can render the actual value of the square distance inside each cell.

squareDist = (dot.x - touchPosition.x)^2 + (dot.y - touchPosition.y)^2

Currently this gives me actual pixel distance, but what I really want is a relative distance grounded in the bounds of the container, in a range [0, 1]. For instance if I move the pointer to a corner of the container, the diagonally opposite corner should be at a distance of 1.

The normalized square distance then becomes: squareDist / (diagonal length)^2 This ensures that the values we get are always under 1.

Frame of reference

The diagonal length comes from the container. To get the bounds of the container I use getBoundingClientRect. It provides the left, top, height, and width of the component. From the touch events I already have the position of the cursor, so I can determine the cursor position relative to the container. x = touchPosition.x - rect.left y = touchPosition.y - rect.top normalized(x) = (touchPosition.x - rect.left) / rect.width normalized(y) = (touchPosition.y - rect.top) / rect.height Then clamping the value to (0, 1) would give me the position inside the container.

Dot sizes

Now that I have the normalized distance, I can use that to bump the size of each dot based on an arbitrary constant multiple: SCALE_MULTIPLE * (1 - normalizedSquareDist) But before that I want to debug the normalized distance values. A fairly intuitive way to do this is to use hsl color values. And I replaced the dots with actual clampedScale values with two precision points.

CSS makes the first part trivial: hsl(${(1 - normalizedSquareDist) * 360}, 100%, 60%). As hue values range between [0, 360], and normalizedSquareDist ranges between [0, 1], hence (1 - normalizedSquareDist) * 360 becomes [360, 0] and gives me the whole rainbow.

Check out the interactive version here.

const normalizedSquareDist = clamp(
  squareDistFromTouchPoint / squareDiagonalLen,
  0,
  1,
);

const clampedScale = 1 - normalizedSquareDist;

// ...

<span
  style={{
    color: `hsl(${(1 - normalizedSquareDist) * 360}, 100%, 60%)`,
  }}
>
  {clampedScale.toFixed(2)}
</span>;

Interesting results

Now if I add scale multiple on top of the square distance and scale the text content, I get an interesting result. The numbers are almost unreadable closer to the cursor, and it affects almost the entire grid.

Interactive

// normalized
const normalizedSquareDist = clamp(
  squareDistFromTouchPoint / squareDiagonalLen,
  0,
  1,
);

const clampedScale = clamp(
  (1 - normalizedSquareDist) * SCALE_MULTIPLE,
  SCALE_MIN,
  Number.POSITIVE_INFINITY,
);

// ...

<span
  style={{
    // ...
    transform: `scale(${clampedScale})`,
  }}
>
  {clampedScale.toFixed(2)}
</span>;

Scale multiple with faster attenuation

To reduce the radius of the scaling, I can make the initial fraction smaller i.e. 1 - normalizedSquareDist * <some-multiple>. This causes the scaling to drop sharply creating a blob quite similar to what I initially set out to make.

Interactive

// normalized
const normalizedSquareDist = clamp(
  squareDistFromTouchPoint / squareDiagonalLen,
  0,
  1,
);

const clampedScale = clamp(
  (1 - normalizedSquareDist * 5) * SCALE_MULTIPLE,
  SCALE_MIN,
  Number.POSITIVE_INFINITY,
);

// ...

<span
  style={{
    // ...
    transform: `scale(${clampedScale})`,
    // ...
  }}
>
  {clampedScale.toFixed(2)}
</span>;

Skittles

Once I had the attenuation effect working, I wanted to turn the “debugger” off and go back to rendering the dots. This is my favorite version, I wonder what the cat thinks.

Interactive

const clampedScale = clamp(
  (1 - normalizedSquareDist * ATTENUATION) * SCALE_MULTIPLE,
  SCALE_MIN,
  Number.POSITIVE_INFINITY,
);

<span
  style={{
    // ..
    transform: `scale(${clampedScale})`,
  }}
  className={"pointer-events-none dark:bg-white bg-black rounded-full w-4 h-4"}
/>;

Monochrome, just like Steve wanted

I simplified the effect a little bit so I don’t get distracted by my own UI. This is supposed to be a photo editor remember! To add just a little bit of visual interest I applied similar but simpler math to the opacity.

Interactive

const opacity = isMouseDown
  ? clamp(1 - normalizedSquareDist, OPACITY_MIN, OPACITY_MAX)
  : OPACITY_MIN;

const clampedScale = clamp(
  (1 - normalizedSquareDist * ATTENUATION) * SCALE_MULTIPLE,
  SCALE_MIN,
  Number.POSITIVE_INFINITY,
);

<span
  style={{
    opacity,
    transform: `scale(${clampedScale})`,
  }}
  className={"rounded-full w-4 h-4"}
/>;

What’s next?

This is only the beginning, I haven’t built a renderer yet. I’ll write about that next time as it’s too late and I wanna go back to reading my book.

I recently wrote an algorithm to make rounded rectangles for a grid with “holes”. The goal was to ensure that all the convex corners of the grid sections were rounded. I looked at existing implementations in softwares that I use daily, the most used are code editors. One of my favorite text editors Zed, renders text selections with beautifully rounded convex and concave corners.

I couldn’t find a way to add external rounded corners without adding extra blocks at the beginning and end of each row, so decided to focus on internal corners, which led me to a somewhat elegant solution. The algorithm requires that I evaluate for each cell it’s neighboring cells, starting with the one to its left, and going clockwise at 45 degree increments. Here are the directions: [⇐, ⇖, ⇑, ⇗, ⇒, ⇘, ⇓, ⇙] For each corner I had to evaluate the three adjacent cells that it touches. Evaluating each corner cell clockwise staring from left-top makes it awkward as the last corner (left-bottom) requires that I look at the first direction (left) again. This would require array index shenanigans and I wanted to avoid that for the sake of obsession. However, if I duplicate the first direction at the end, it simplifies the code. The final directions array: [⇐, ⇖, ⇑, ⇗, ⇒, ⇘, ⇓, ⇙, ⇐] Now I can implement a sliding window of width three on top of this array which can account for all the corners.

Who drew the short stick?

A corner that touches three empty cells is rounded. Vice-versa an empty cell that touches three filled cells, is rounded. As I’m only concerned with the external rounding, I ended up ignoring the empty cell case.

Let’s look at an example:

       ┌───┬───┬───┬───┐
       │   │   │   │   │▐▌
       ├───┼───┼───┼───┤▐▌
       │   │ x │ x │   │▐▌
       ├───┼───┼───┼───┤▐▌
       │   │ x │ x │   │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

       ┌───┬───┬───┬───┐
       │   │   │   │   │▐▌
       ├── ╭───┬───╮ ──┤▐▌
       │   │ x │ x │   │▐▌
       ├── ├───┼───┤ ──┤▐▌
       │   │ x │ x │   │▐▌
       └── ╰───┴───╯ ──┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

Evaluating the cell marked with *, xs are filled, and _s are empty.

By looking at the rectangle I can deduce that * should have the left top corner rounded and nothing else.

       ┌───┬───┬───┬───┐
       │ _ │ _ │ _ │ _ │▐▌
       ├── ╭───┬───┼───┤▐▌
       │ _ │ * │ x │ _ │▐▌
       ├── ├───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

Dry running the algorithm for the top left corner, I start by checking the cell to the left, then the one to the left and above, and then finally the one above.

       ┌───┬───┬───┬───┐
       │ 2 │ 3 │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ 1 │ * │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

As I was evaluating a filled cell, and all the neighboring cells for the left top corner are empty, I can mark the corner as rounded.

Let’s look at a more complicated example:

       ┌───┬───┬───┬───┐
       │ x │ _ │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

For ths particular case, all the corners except the corner that’s common between the large and the small rectangle should be rounded. The clockwise sweeping algorithm is a generalized solution and works fine for this case.

Expected Outcome:

       ╭───╮ ──┬───┬───┐
       │ x │   │   │   │▐▌
       ╰───┼───┬───╮ ──┤▐▌
       │   │ x │ x │   │▐▌
       ├── ├───┼───┤ ──┤▐▌
       │   │ x │ x │   │▐▌
       └── ╰───┴───╯ ──┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

Let’s look at the cell marked with *, starting with the top left corner:

     2   3
      →┌───┬───┬───┬───┐
     1 │ * │ _ │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

As the three relevant adjacent cells are out of bounds, I can mark the corner rounded.

Let’s look at the top right corner:

           ↓
       ╭───┬───┬───┬───┐
       │ * │ _ │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

The first two adjacent cells are out-of-bounds and hence considered empty. The last one is actually empty, I can mark that corner rounded.

         1 ↓ 2
       ╭───┬───┬───┬───┐
       │ * │ _ │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
        // 1 and 2 are out-of-bounds

           ↓
       ╭───┬───┬───┬───┐
       │ * │ 3 │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
        // 3 is empty

           ↓
       ╭───╮ ──┬───┬───┐
       │ * │ 3 │ _ │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
        // rounded corner

Let’s look at the bottom right corner.

       ╭───╮ ──┬───┬───┐
       │ * │ 1 │ _ │ _ │▐▌
       ├ → ┼───┼───┼───┤▐▌
       │ 3 │ 2 │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

As the cells marked 1 and 3 are empty but cell 2 is not, this corner can’t be rounded.

Last corner:

       ╭───╮ ──┬───┬───┐
     3 │ * │ _ │ _ │ _ │▐▌
      →├───┼───┼───┼───┤▐▌
     2 │ 1 │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

As all the relevant cells are either empty or out of bounds, this corner can be marked as rounded similar to the right top corner.

Outcome:

       ╭───╮ ──┬───┬───┐
       │ * │ _ │ _ │ _ │▐▌
       ╰───┼───┼───┼───┤▐▌
       │ 1 │ x │ x │ _ │▐▌
       ├───┼───┼───┼───┤▐▌
       │ _ │ x │ x │ _ │▐▌
       └───┴───┴───┴───┘▐▌
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘

        // Expected outcome

In practice

const DIRECTION_DELTAS = [
  [-1, 0], //  ⇐
  [-1, -1], // ⇖
  [0, -1], //  ⇑
  [1, -1], //  ⇗
  [1, 0], //   ⇒
  [1, 1], //   ⇘
  [0, 1], //   ⇓
  [-1, 1], //  ⇙
  [-1, 0], //  ⇐
] as const;

/**
 * Grid can be represented as a string: "x____xx__xx_"
 * and width.
 * or formatted as
 * `
 * x___
 * _xx_
 * _xx_
 * '
 */

const isEmpty = (char: string) => char === "_";

const getCornerRounding = (
  str: string,
  width: number,
  currIdx: Vec2,
): readonly [boolean, boolean, boolean, boolean] => {
  const isCurrentEmpty = isEmpty(str[currIdx]);

  // get indices of the cells to evaluate
  const surroundingIndices = DIRECTION_DELTAS.map(([dX, dY]) => {
    // ...
  });

  const isNeighborEmpty = (directionIdx: number) => {
    const neighboringIdx = surroundingIndices[directionIdx];
    return isEmpty(str[neighboringIdx]);
  };

  const directionsForTopLeft = [0, 1, 2];
  const directionsForTopRight = [2, 3, 4];
  const directionsForBottomRight = [4, 5, 6];
  const directionsForBottomLeft = [6, 7, 8];

  return [
    directionsForTopLeft
      .map(isNeighborEmpty)
      // check if the neighbors are different from the current cell
      .every(isEmpty !== isCurrentCellEmpty),
    // ...
  ] as const;
};

Q: Can this use a compute shader to find the solution much faster?

I think so.

There isn’t much of a connection between Cirque Du Soleil and circular buffers. However, when I look at an animated gif of circular buffers the motion of the read and write heads reminds me of the wall of death. The write head’s ever advancing march over values that were yet to be read, but might never see I/O.

An ongoing video game project of mine is where I experiment with Rust’s features to expand my understanding of the language. When I initially wrote Rasengan, a minimal circular buffer implementation, I had no plans on integrating it into the project. However, recently I wanted to implement a sort of blurred motion streak behind the video game character and Rasengan popped into my brain.

There are several ways to implement a motion streak, and some of them don’t need instantiating new entities. I’m going to look for ways to do this as a camera effect in Bevy eventually, but it was quite tempting to use Rasengan.

You see, a simple array can be used to store all the information I needed to achieve this. When the character starts moving, at regular intervals its positions can be pushed into an array. At some other regular interval, the values from the array can be read back to render the streak (I use the same sprite, but with lower opacity and color adjustment). As the game runs at 60 fps under normal circumstances, this array can get incredibly large quickly. For instance, if you hold down the right arrow key, you would end up with 5MBs of positions data in the array in an hour.

That doesn’t sound so bad considering the memory that ships with modern computers. For instance the computer I’m using to write this blog post has 18 gigs of RAM. With that said, the video game binary is only 15 Mbs itself, and one hour of gameplay generating a third of that seems awfully wasteful.

As the motion streak is quite short, I only needed to store a handful of previous positions. An array of length 10 can store all the data I was going to need, but continuously writing to the array would end up with an ever increasing size which would require a lot of re-allocations. Once a position has been read, it would never be used again. If only I could re-use the array of length 10.

One solution is to use a queue, I would push a new position into the queue on player move and pop one when rendering the streak. In Rust, a queue would require a RefCell to create the self referential data structure needed to implement a queue, details of which are out of the scope of this post.

I wanted to allocate all the data on the stack without pointers which could be achieved by using an array. However the frequent (60 frames a second) re-sizing of the array seemed like an unnecessary overhead.

If I could just wrap around a fixed size array and overwrite older values when writing the data, I could achieve similar outcome.

Enter - Rasengan

Yeah I’m aware that it’s a corny reference, fortunately that’s the last you’d have to think about references.

I first wrote Rasengan as a side project to explore const generics and circular buffers in general. My understanding of arrays in Rust was also fuzzy. There are quite a few different data structures that represent contiguous memory: array, slice, and vector. Vectors are allowed to grow and shrink as needed, but I wanted a constant sized chunk. Slices are a view into an existing array. Which leaves us the array: [T; usize].

Usually circular buffers prevent new writes until previous data has been read. Rasengan implements circular buffer with overwrite, which means that once the buffer is completely full (unread data is at capacity), it starts to overwrite the least recently updated values. Which works perfectly for rendering the motion streak as lost frames aren’t a big deal.

Here’s a box diagram detailing how the wraparound overwrite works.

    W       R
    │       │
┌───▼───┬───▼───┬───────┬───────┬─ ─ ─ ─ ─ ─ ─ ─
│       │       │       │       │       │        ▐▌
│       │       │       │       │       │        ▐▌
└───▲───┴───────┴───────┴───────┴─ ─ ─ ─ ─ ─ ─ ─ ▐▌
 ▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
    └─── Capacity = 4 ──────┘

// buffer has no unread values
read() -> panic("Nothing to read here")

    W       R
    │       │
┌───▼───┬───▼───┬───────┬───────┬─ ─ ─ ─ ─ ─ ─ ─
│       │       │       │       │       │        ▐▌
│       │   5   │       │       │       │        ▐▌
└───▲───┴───────┴───────┴───────┴─ ─ ─ ─ ─ ─ ─ ─ ▐▌
 ▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
    └───────────────────────┘

inc(W); write(5); // increment W before writing

    w       R                       W
    │       │                       │
┌───▼───┬───▼───┬───────┬───────┬─ ─▼─ ─ ─ ─ ─ ─
│       │       │       │       │       │        ▐▌
│   8   │   5   │   2   │   4   │       │        ▐▌
└───▲───┴───────┴───────┴───────┴─ ─ ─ ─ ─ ─ ─ ─ ▐▌
 ▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘
    └───────────────────────┘

inc(W); write(2); inc(W); write(4); inc(W); write(8);
w = W % capacity // write with wrap-around

Trail Rendering System

I use the Bevy game engine and its ECS model. Explaining how ECS works is out of the scope of this post, but I’m happy to talk you out of OOP if you’re considering it.

Bevy allows instantiating resources that need to be accessed by systems which is exactly what I needed for storing the positions data. I initialize a Rasengan instance at game launch, and then read and write to it in the trail systems. Here is the entirely of the trail system.

pub fn trail_position_write_system(
  // ECS models usually depend on queries to access different entities
  player_transform_query: Query<&Transform, With<Player>>,
  // this is the data that I'm writing to and reading from
  mut trail_position: ResMut<Rasengan<Vec3, TRAIL_LENGTH>>,
) {
  if player_transform_query.get_single().is_err() {
    return;
  }
  let player_transform = player_transform_query.single();
  trail_position.write(player_transform.translation);
}

pub fn trail_position_read_system(
  mut player_trail_transform_query: Query<&mut Transform, With<PlayerTrail>>,
  mut trail_position: ResMut<Rasengan<Vec3, TRAIL_LENGTH>>,
) {
  if player_trail_transform_query.get_single().is_err() {
    return;
  }
  let mut player_transform = player_trail_transform_query.single_mut();
  if let Some(trail_position) = trail_position.read() {
    player_transform.translation = trail_position;
  }
}

There’s a minor problem with it though, the system is writing values to the positions data each frame, even when the position doesn’t change. Although Rasengan is not allocating more memory, this still feels unnecessary.

Extending Rasengan with write_unique

I decided to update the api to write only when the system attempted to write a new value. This would prevent unnecessary writes when the game character wasn’t moving.

The Rasengan::write_unique is quite simple, it leverages Rasengan::write but first compares the value at the write head.

impl<T: Copy, const N: usize> Rasengan<T, N> {
  ...
  pub fn write_unique(&mut self, data: T) {
    if self.write_ptr == 0 {
      self.write(data);
      return;
    }

    let idx = self.write_ptr % self.buf.len();
    let last_written = self.buf[idx];

    if let Some(last_written) = last_written {
      if data != last_written {
        self.write(data);
      }
    }
  }
}

There’s another hiccup though. This doesn’t compile.

error[E0369]: binary operation `!=` cannot be applied to type `T`
   --> src/rasengan.rs:131:21
    |
131 |             if data != last_written {
    |                ---- ^^ ------------ T
    |                |
    |                T

The problem here is that Rasengan’s implementation doesn’t have sufficient trait bounds that ensure the concrete type passed to write_unique implements core::cmp::PartialEq.

impl<T: Copy + PartialEq, const N: usize> Rasengan<T, N> {
  pub fn write_unique(&mut self, data: T) {
    if self.write_ptr == 0 {
      self.write(data);
      return;
    }

    let idx = self.write_ptr % self.buf.len();
    let last_written = self.buf[idx];

    if let Some(last_written) = last_written {
      if data != last_written {
        self.write(data);
      }
    }
  }
}