Not only was a piece of computer gaming history fading into obscurity, like the countless silent movies lost forever when their film disintegrated, but a cherished part of my childhood was becoming no more than a memory and a cultural anecdote. I decided to try to do something.

When I was about 7, one of my favorite things to do was watch my dad play Realmz. Compared to the computer games I was playing at the time, such as SimCity and Lemmings, Realmz stood apart as a portal into an expansive world of adventure. Like many games of the era, it was released as shareware, with a restricted, free-to-play base game that could be unlocked and additional content purchased by mailing in registration fees. But unlike others, Fantasoft offered companion scenario and character editors, which allowed users to create their own content. Watching my dad roam around fantastical worlds with a band of powerful adventurers wielding magical weapons, and imagining the awesome items and stories I could create myself, was a key inspiration to me to become a programmer.

Recently, a wave of nostalgia hit me, and I went digging into what it might take to fire up Realmz again. Visiting the disappearing or aging websites that were keeping the game alive confirmed my fears: Realmz was getting more and more difficult to play. The game had long since become abandonware, no one seemed to have heard from the creator Tim Phillips nor the apparent custodian Skip Meier in years, and aside from a buggy 1999 Windows port and a now-obsolete Carbon-ization project from the 2010s, very little had been done to keep the game playable. It seemed that the only options were to try to get the Windows executable working and play through the bugs, set up one of the notoriously tricky Macintosh emulators like Sheepsaver or Basilisk, or simply dust off any old Macintosh that one might happen to have lying around in storage.

I found this incredibly sad. Not only was a piece of computer gaming history fading into obscurity, like the countless silent movies lost forever when their film disintegrated, but a cherished part of my childhood was becoming no more than a memory and a cultural anecdote. I decided to try to do something.

The ultimate way to ensure a piece of software can survive is to open source its code. Although I had no idea how to begin, I made my primary goal to open source Realmz so that, even if I were to fail to keep it updated for modern systems, other enthusiasts might be able to continue the work and eventually succeed. The major obstacle to this goal was that no one seemed to know who currently holds the rights to Realmz, and the two most likely people, Tim and Skip, seemed to have vanished from the internet.

After weeks of research, cold reachouts, consultations with an open source lawyer, and wild geese, I managed to contact Tim. He graciously agreed to release the Realmz source code under a CC NonCommercial license, and I obtained a copy of the codebase from the programmer who worked on the Carbon port years ago. The hardest, most uncertain part of the project was complete!

Now that I had access to the codebase and permission from the original author, I got to work. My plan was to first simply get the code to compile, even if it crashed immediately upon startup. From an interview with one of the original members of Fantasoft, I knew to expect C code written under the c89 standard, so I hoped that it would be mostly compilable, as long as I could stub out the missing Macintosh System 7 system calls. From there, I figured I could re-implement the system calls that were still necessary for the game to run. Others, such as those that took care to lock and unlock moveable and purgeable memory handles, could be left unimplemented and would be elided by the compiler.

This process turned out to be relatively straightforward, if labor-intensive. I would attempt to compile, then look for the missing function symbol in the resulting error. I would then reference an archived copy of Inside Macintosh to find out the signature of the missing function¹. Finally, I would write a declaration and an empty definition of the missing function, recompile, and repeat. Aside from a few minor snags², the process went well, and I soon had a compiled executable which crashed as soon as it launched!

One of the earliest sources of crashes was, predictably, the NULL pointers returned by my stubbed versions of functions like GetNewWindow. GetNewWindow, like many of the missing system calls, loads a game asset, in this case a WIND resource representing an application window definition, then draws it to the screen. “Resources” are what early Macintosh called application data such as images, text that could be localized, sound files, or any other data that the application might use. Historically they were stored in resource forks, an archival format that was hidden within each file, but in the repository that I gained access to, the resource forks had already been extracted into separate files, making them a little easier to deal with.

My plan for rendering windows and graphics, playing sounds, and receiving inputs was to simply write an adapter layer to SDL3 calls, essentially implementing replacement Window Manager, QuickDraw, etc. functionality while leaving the existing API and the callsites in Realmz intact. The harder part would be to write the code to parse and extract the individual resources from the resource fork files. Each resource type has its own storage format, and while there didn’t seem to be anything too difficult involved in unpacking each field, I wasn’t looking forward to the slog of implementing each extractor (and decoder of compressed formats, in the case of certain resources). I started looking around for any existing tools or libraries that I could use.

My search led me to the excellent resource_dasm tool and library, authored by fuzziqersoftware. Not only had Martin implemented a tool that unpacks and converts each resource type to a modern equivalent, but the library is written in C++ and I had high hopes that I could integrate it directly into my project to handle all resource file manipulations. I quickly got bare-bones implementations of Window Manager and Resource Manager working, calling into resource_dasm to load the image data, and calling into SDL3 for window creation and rendering, and was greeted by a friendly image from my past:

Encouraged by reaching this huge milestone so quickly, I decided to reach out to Martin to see if he was interested in joining the project. His depth of expertise would mean that together we’d be able to get the game running smoothly much sooner than I could by continuing on my own, stumbling forward without much experience on this ancient system. Thankfully, he quickly agreed, and we set ourselves to the task of implementing the rest of the missing Classic Mac functionality. It took us a while to work through all of the crashes and unimplemented behavior, since we could only spare an hour of our free time here or there, but we were able to overcome some interesting problems³ and achieved a smooth, crash-free experience that allows one to play through entire scenarios successfully.

And so, today, I’m thrilled to announce the first public (beta) release of the Realmz Classic project! I’ll be forever grateful to Tim Phillips for entrusting me with this work and his desire to see the Realmz community continue to thrive; to Sean Sayrs for responding to me and helping me contact Tim; to Aaron Williamson for his advice on options for open sourcing Realmz; to Dave Riley for preserving the Realmz codebase for all these years and for sharing it with me; and to my project partner Martin Michelsen, for laying the excellent groundwork and for agreeing to lend his exceptional talent to the project.

You can visit the releases page and download an installer for either MacOS or Windows, or a zip archive for custom Windows installations. Give it a try, and prepare to be whisked away on a strange and fantastical classic RPG adventure!

I’ve recently been learning Rust. Originally, I was drawn to it because of my embedded projects: Although I’ve appreciated the “behind the curtains” look that writing plan-old C gives into the embedded runtime environment, I was feeling the strain of my limited familiarity with the language and its quirks. Rust seemed like an exciting, modern language to learn, with plenty of developer-friendly features, and the fact that it apparently supports embedded targets was a nice bonus. I read through the online Rust book, the excellent Programming Rust, and had worked through several of this year’s Advent of Code problems using it. I was really enjoying Rust so far, but I wanted to try using it for a larger project that would help me get a better understanding of building fully functional software with it.

I decided to see if I could build a performant physics simulator from the ground up. For me, this meant implementing even basic concepts like vector operations from scratch, to get a feel for the type and trait systems and see what was possible. Starting with astronomical simulations and working in 2D, but then quickly adding support for 3D, I devised a simple configuration format in YAML to specify the starting system state. I used the Earth and Moon system as a test case, drawing starting simulation values from their Wikipedia pages.

Just to get started, I wanted to set up a basic vector multiplication module, which would be essential for representing and manipulating force vectors. Although it would have been easy to use one of several linear algebra crates to handle all of this for me, one of my goals with the project was to get a feel for Rust’s expressiveness. I was quickly able to set up a two-dimensional Vector type for 2D simulations, and in the process of expanding this to three dimensions, I was pleasantly surprised to discover Rust’s const generics feature, akin to constant template parameters from C++, which allowed me to write generic definitions for n-dimensional vectors:

use std::ops::{Index, IndexMut};

pub struct Vector<const N: usize>([f32; N]);

impl<const N: usize> From<[f32; N]> for Vector<N> {
    fn from(components: [f32; N]) -> Self {
        Self(components)
    }
}

impl<const N: usize> Default for Vector<N> {
    fn default() -> Self {
        Self([0.0; N])
    }
}

impl<const N: usize> Index<usize> for Vector<N> {
    type Output = f32;
    fn index(&self, i: usize) -> &Self::Output {
        &self.0[i]
    }
}

impl<const N: usize> IndexMut<usize> for Vector<N> {
    fn index_mut(&mut self, i: usize) -> &mut Self::Output {
        &mut self.0[i]
    }
}

Implementing the Index and IndexMut traits on N-Vectors provides a generic way to access the vector’s members with v[0], v[1], etc., but for convenience I added more ergonomic accessors for my primary 2D and 3D physical simulation use cases, allowing one to use the more familiar (x, y, z) coordinate system:

impl Vector<2> {
    pub fn new(x: f32, y: f32) -> Self {
        Self([x, y])
    }

    pub fn x(&self) -> f32 {
        self.0[0]
    }

    pub fn y(&self) -> f32 {
        self.0[1]
    }
}

impl Vector<3> {
    pub fn new(x: f32, y: f32, z: f32) -> Self {
        Self([x, y, z])
    }

    pub fn x(&self) -> f32 {
        self.0[0]
    }

    pub fn y(&self) -> f32 {
        self.0[1]
    }

    pub fn z(&self) -> f32 {
        self.0[2]
    }
}

pub type Vector2 = Vector<2>;
pub type Vector3 = Vector<3>;

With these definitions established, I could now generically implement field operations on my N-dimensional vectors. This would allow me to perform basic mathematical operations on them, such as addition, subtraction, and even the dot product, by simply writing expressions like (v1 + v2).dot(v3):

use std::ops::{Add, Div, Mul, Sub};

impl<const N: usize> Sub<&Vector<N>> for &Vector<N> {
    type Output = Vector<N>;
    fn sub(self, other: &Vector<N>) -> Self::Output {
        let mut components = [0.0; N];
        for i in 0..N {
            components[i] = self.0[i] - other.0[i];
        }
        Vector::<N>(components)
    }
}

impl<const N: usize> Div<&Vector<N>> for &Vector<N> {
    type Output = Vector<N>;
    fn div(self, other: &Vector<N>) -> Self::Output {
        let mut components = [0.0; N];
        for i in 0..N {
            components[i] = self.0[i] / other.0[i];
        }
        Vector::<N>(components)
    }
}

impl<const N: usize> Div<f32> for &Vector<N> {
    type Output = Vector<N>;
    fn div(self, other: f32) -> Self::Output {
        let mut components = [0.0; N];
        for i in 0..N {
            components[i] = self.0[i] / other;
        }
        Vector::<N>(components)
    }
}

impl<const N: usize> Add<&Vector<N>> for &Vector<N> {
    type Output = Vector<N>;
    fn add(self, other: &Vector<N>) -> Self::Output {
        let mut components = [0.0; N];
        for i in 0..N {
            components[i] = self.0[i] + other.0[i];
        }
        Vector::<N>(components)
    }
}

impl<const N: usize> Mul<&Vector<N>> for f32 {
    type Output = Vector<N>;
    fn mul(self, other: &Vector<N>) -> Self::Output {
        let mut components = [0.0; N];
        for i in 0..N {
            components[i] = self * other.0[i];
        }
        Vector::<N>(components)
    }
}

impl<const N: usize> Vector<N> {
    pub fn dot(&self, rhs: &Self) -> f32 {
        let mut sum = 0.0;
        for i in 0..N {
            sum += self.0[i] * rhs.0[i];
        }
        sum
    }
}

Note the implementation of both vector and scalar versions of Div. The former is for completeness alongside Mul, to allow for inverse operations, while the scalar version would become useful shortly, when implementing a normalize function for my Vector<N> struct:

impl<const N: usize> Div<&Vector<N>> for &Vector<N> { ... }
impl<const N: usize> Div<f32> for &Vector<N> { ... }

With these primitives out of the way, I could now move on to the meat of my simulation project and begin expressing physical force interactions through code. To start, I augmented the definition of my N-vectors to include behavior that is specific to simulations of physical objects in space. The primary force interaction between large celestial bodies like the Earth and Moon is gravity, which correlates the mass of two objects (m₁ and m₂) and the square of the distance between them (expressed as r) with the force of attraction between them, F, scaled by the universal gravitational constant, G:

The masses of the physical objects aren’t related in any way to the objects’ locations or distances between each other, so I decided that mass would be stored elsewhere, as attributes of the objects themselves, alongside their position and velocity vectors. Adding a few quick helper functions to my Vector<N> implementation, and then adding a new trait Distance and implementing it for Vector<N>:

impl<const N: usize> Vector<N> {
    pub fn normalize(&self) -> Self {
        // Scalar division of vector
        self / self.magnitude()
    }

    pub fn magnitude(&self) -> f32 {
        // Use f64 to avoid precision loss
        let mut sum_of_squares = 0_f64;
        for i in 0..N {
            sum_of_squares += (self.0[i] as f64).powi(2);
        }
        sum_of_squares.sqrt() as f32
    }
}

pub trait Distance {
    type Output: Distance;

    fn distance(&self, other: &Self) -> f32;
    fn direction(&self, to: &Self) -> Self::Output;
}

impl<const N: usize> Distance for Vector<N> {
    type Output = Vector<N>;

    fn distance(&self, other: &Self) -> f32 {
        (self - other).magnitude()
    }

    fn direction(&self, to: &Self) -> Self::Output {
        (to - self).normalize()
    }
}

…gave me everything I needed to describe a Force trait and define Gravity itself:

const G: f32 = 6.67430e-11;

type PositionVector<const N: usize> = Vector<N>;
type VelocityVector<const N: usize> = Vector<N>;

pub struct ForceVector<const N: usize> {
    pub label: String,
    pub v: PositionVector<N>,
}

impl<const N: usize> ForceVector<N> {
    pub fn magnitude(&self) -> f32 {
        self.v.magnitude()
    }
}

struct Body<const N: usize> {
    pub label: String,
    pub mass: f32,
    pub diameter: f32,
    pub position: PositionVector<N>,
    pub velocity: VelocityVector<N>,

    pub forces: Vec<ForceVector<N>>,
}

// A ForceMap associates each Body label as the hash key with the list 
// of forces that are acting upon it.
pub type ForceMap<const N: usize> = HashMap<String, Vec<ForceVector<N>>>;

pub struct Gravity {
    g: f32,
}

impl Gravity {
    pub fn new(g: Option<f32>) -> Self {
        Gravity { g: g.unwrap_or(G) }
    }

    // Given a list of Bodies, calculates the force of gravity imposed on
    // each by every other Body.
    pub fn forces_from_bodies<const N: usize>(&self, bodies: &Vec<&Body<N>>) -> ForceMap<N> {
        let mut force_map = ForceMap::new();
        for body_pair in bodies.iter().combinations(2) {
            let (b1, b2) = (body_pair[0], body_pair[1]);

            force_map
                .entry(b1.label.clone())
                .or_insert(vec![])
                .push(self.calculate(b1, b2));

            force_map
                .entry(b2.label.clone())
                .or_insert(vec![])
                .push(self.calculate(b2, b1));
        }
        force_map
    }
}

impl Force for Gravity {
    fn calculate<'a, const N: usize>(&self, on: &'a Body<N>, from: &'a Body<N>) -> ForceVector<N> {
        let distance = on.position.distance(&from.position);
        let magnitude = self.g * on.mass * from.mass / distance.powi(2);

        let on_force_name = format!("gravity_{}", from.label);
        ForceVector {
            label: on_force_name,
            v: magnitude * &on.position.direction(&from.position),
        }
    }
}

To display the output, I started with plain textual output of the incremental positions and velocities of each object in the simulation, but soon enough found myself wondering what it would take to render the simulation visually. Working through the phenomenal free tutorials on learnopengl.com, I was able to get a basic sphere modeled, and to draw an Earth texture on it. I soon did the same for the moon. Although the tutorials are written for C++, the concepts were fairly easy to translate into Rust, with the help of a Rust crate called miniquad which provides type-safe bindings for the OpenGL calls.

There’s a lot more to this project that I wasn’t able to cover in this post: My OpenGL learning journey; the structure of the actual Simulation struct which uses these code snippets; my brief encounter with quaternions in order to simply get my simulated objects to spin correctly. But I’m proud of how the foundations of this project turned out, and I wanted to highlight how expressive Rust can be. For future work, I’d like to continue to improve the visuals of the simulator, adding a trackball and zoom interface, as well as labels and other textual information. From there, I want to try to stress test the simulation: How many bodies can it handle at once? If I encounter performance problems, what optimizations can I implement to speed it up? Can I leverage CUDA or similar high-performance computing techniques to parallelize the force calculations? Can I develop a testing mechanism to see how accurate my simulation is over long timeframes, and what can I do to improve that accuracy? Hopefully, this is only the beginning of my journey through graphics programming and Rust!