Cryptoadz on afloat.boats

Cirque Du Spritesheet

Sun, 28 Apr 2024 23:04:15 -0700

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);
      }
    }
  }
}

I added a second implementation with the PartialEq trait bound for Rasengan and everything was back to normal in the pond.

The reason for adding a separate implementation with an added PartialEq bound instead of adding write_unique to the existing implementation was so that I can still use Rasengan normally without requiring types to implement PartialEq when write_unique is not necessary.

Dead Simple Spritesheet Animation

Sun, 04 Dec 2022 22:57:16 -0800

Live | Repository

Motivation

I’ve been using Bevy for a video game project and it’s been a delightful experience. As the project has grown, I’ve turned into a level designer, animator, illustrator, along with being a programmer.

Sometimes I hit walls, and rabbit holes around those walls are too compelling to pass up. One such rabbit hole was building an animation state machine that could create different looping animations from a single sprite sheet. The only reason for using a single sprite-sheet is that being the dev and the illustrator is very time consuming and I wanted my workflow to remain as simple as possible. But as I’ve built a few different prototypes the single spritesheet model has proven to be quite useful.

I created an animation-transition crate that abstracts most of the details away and I’ve used it on multiple prototypes so I think that it is fairly straight forward to use in 2D games. The following is a sort of how-to guide to create an animation state machine from scratch.

Animation Pages

I first create an enum with variants with self explanatory names. For the above example three variants suffice: Idle, Rising, and Falling. The enum variants are then mapped to animation pages. Pages are a way to encode the information needed to build looping animations. They are made up of two parts: an offset, and a page size. The offset stores the index of the first sprite in a single animation loop, and page size stores the number of sprites in the same animation.

                                                                       
                    DECLARING THE ENUM                                 
                                                                       
                                                                       
       ╔═══════╦═══════╦═══════╦═══════╦═══════╦═══════╗               
       ║       ║       ║       ║       ║       ║       ║▐▌             
       ║   0   ║   1   ║   2   ║   3   ║   4   ║   5   ║▐▌             
       ╚═══════╩═══════╩═══════╩═══════╩═══════╩═══════╝▐▌             
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘             
                           [usize; 6]                                  
                                                                       
                                                                       
     pub enum Variant {                pub trait AnimationLoop {       
         Idle,           implements                                    
         Rising, ━━━━━━━━━━━━━━━━━━━━━▶    fn page() -> (usize, usize);
         Falling,                                                      
     }                                 }                               
                                                                       
                                                                       
                    MAPPING TO idx/offset                              
                                                                       
       ╔═══════╦═══════╦═══════╦═══════╦═══════╦═══════╗               
       ║       ║       ║       ║       ║       ║       ║▐▌             
       ║   0   ║   1   ║   2   ║   3   ║   4   ║   5   ║▐▌             
       ╚═══════╩═══════╩═══════╩═══════╩═══════╩═══════╝▐▌             
        ▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘             
                   └───────┬───────┘                                   
                           ╵                                           
              Idle::pages(); // (offset: 1, size: 3)                   
                                                                       
                                                                       
                                                                       
       ╔═══════╦═══════╦═══════╦═══════╦═══════╦═══════╗               
       ║       ║       ║       ║       ║       ║       ║▐▌             
       ║   0   ║   1   ║   2   ║   3   ║   4   ║   5   ║▐▌             
       ╚═══════╩═══════╩═══════╩═══════╩═══════╩═══════╝▐▌             
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀│▀▀▀▀▀▀▀│▀▀▀▀▀▀▀▀▀▀▀▀▀▘             
                                   └───┬───┘                           
                                       ╵                               
              Rising::pages(); // (offset: 3, size: 2)

Implementation

Let’s take a look at some code.

Animation variants enum

The enum needs to implement PartialEq so that the variants can be compared to each other when making decisions during animation state transitions.

#[derive(Clone, PartialEq)]
pub enum PlayerAnimationVariant {
  Idle,
  Rising,
  Falling,
}

Creating an `AnimationLoop` trait

The trait is straightforward, defines a function that would return the offset and size of the animation page.

pub trait AnimationLoop {
  fn page(&self) -> (usize, usize);
}

Implementing the `AnimationLoop` trait for the enum

This is also straightforward, I match the enum variant to the appropriate animation page tuple i.e. frame offset and page size.

impl AnimationLoop for PlayerAnimationVariant {
  fn page(&self) -> (usize, usize) {
    match self {
      // (idx_offset, loop_size) describe the animation loop
      PlayerAnimationVariant::Idle => (0, 3),
      PlayerAnimationVariant::Rising => (2, 2),
      PlayerAnimationVariant::Falling => (4, 4),
    }
  }
}

State Transitions

Playing a single looping animation can be accomplished by flipping through a contiguous array of indices, that are then used to fetch the appropriate sprite from a sprite atlas. Moving between different animations can be accomplished by simply updating the animation variant.

                                                                       
                                                                       
                   FLIPPING THROUGH SPRITES                            
                                                                       
                                                                       
                                   ┌───────┐                           
                                   │       │                           
       ╔═══════╦═══════╦═══════╦═══════╦═══▼═══╦═══════╗               
       ║       ║       ║       ║       ║       ║       ║▐▌             
       ║   0   ║   1   ║   2   ║   3   ║   4   ║   5   ║▐▌             
       ╚═══════╩═══════╩═══════╩═══════╩═══════╩═══════╝▐▌             
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘             
                                                                       
              animation_state.variant; // Variant::Rising              
              animation_state.idx; // 3                                
              animation_state.wrapping_next_idx(); //  4               
                                                                       
                                                                       
                       VARIANT TRANSITION                              
                                                                       
                                                                       
                                       ┏━━━━━━━━━━━┓                   
                                       ┃           ┃                   
                                   ┌───────┐       ┃                   
       ╔═══════╦═══════╦═══════╦═══════╦═══════╦═══▼═══╗               
       ║       ║       ║       ║       ║       ║       ║▐▌             
       ║   0   ║   1   ║   2   ║   3   ║   4   ║   5   ║▐▌             
       ╚═══════╩═══════╩═══════╩═══════╩═══════╩═══════╝▐▌             
        ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▘             
                                                                       
              animation_state.variant;              // Variant::Rising 
              animation_state.transition_variant(); // ()              
              animation_state.variant;              // Variant::Falling
              animation_state.idx;                  // 5

Implementation

I encapsulate the information needed for the two actions (looping animation, and variant transition) in a struct called PlayerAnimationState.

Animation state manager

The struct stores the animation variant to play, and the current index of the frame.

pub struct PlayerAnimationState {
  pub variant: PlayerAnimationVariant,
  pub idx: usize,
}

Implementing transition functions

wrapping_next_idx increments the current index and wraps around at the page boundary. It makes looping animations trivial to implement.

impl PlayerAnimationState {
  fn wrapping_next_idx(&mut self) -> usize {
    let current_idx = self.idx;
    let (offset, size) = self.variant.page();

    self.idx = offset + (current_idx + 1) % size;

    self.idx
  }
}

transition_variant updates the animation state manager so that I can play a different animation based on in-game events. This one accepts an argument of type PlayerAnimationVariant, so different in-game events can trigger appropriate animations in response. For example when I press spacebar on Toad, the animation state is first updated to Rising, once the toad reaches it’s maximum jump height the animation is updated to Falling, and finally on touching the ground it can be transitioned back to Idle.

impl PlayerAnimationState {
  ...

  fn transition_variant(&mut self, to: PlayerAnimationVariant) {
    let (offset, _) = to.page();
    self.variant = to;
    self.idx = offset;
  }
}

All of this can be somewhat tedious, and repetitive if you’re working on multiple games. I created a Rust crate that simplifies the process by providing:

the traits AnimationLoop and AnimationTransition
a handy proc macro AnimationTransitionMacro that implements the necessary index/variant manipulation functions for the animation state manager

Cryptoadz on afloat.boats

Cirque Du Spritesheet

Enter - Rasengan

Trail Rendering System

Extending Rasengan with write_unique

Dead Simple Spritesheet Animation

Motivation

Animation Pages

Implementation

Animation variants enum

Creating an AnimationLoop trait

Implementing the AnimationLoop trait for the enum

State Transitions

Implementation

Animation state manager

Implementing transition functions

Extending `Rasengan` with `write_unique`

Creating an `AnimationLoop` trait

Implementing the `AnimationLoop` trait for the enum