Hacking the housing market

**NS**.
There are two possible reactions to reading that.
Someone who hasn't spent a lot of time in the Netherlands might say *bless you*, but a fellow Dutchie will get shivers down their spine.

For those who don't know, 'Nederlandse Spoorwegen' (also known as NS—kudos if you already figured that out) is the main railway operator in the Netherlands. While they operate train services and manage timetables, they share responsibilities with other entities: ProRail manages the actual rail infrastructure and stations, while regional operators handle some local lines.

What's far more interesting (to me) is that they also own and operate extensive IT infrastructure. While they do have some official public APIs, these require permission requests and expose only a limited subset of their data. Meanwhile, their internal tooling often ends up accessible on the public internet—sometimes without authentication requirements.

You can see where this is going. We're going to have some fun with data exfiltration!


# Solving my personal pain points
Every project needs a goal. And the mission I set out for myself is to make my frequent and long commutes more efficient, or at least less cumbersome.

My main gripe with long journeys during peak hours is the inability to find a seat, or being forced to miss my transfer by some vacationers who (respectfully) don't have a fucking clue what they're doing.

Previously, I already made a private service for Efteling waiting times, which has collected two years of ride queue time history and weather conditions, and can predict waiting times decently well (thanks to a hotchpotch of Python, Pandas, Influx 2, and Grafana). Something like that, but for NS, would be amazing.

Think Buienradar-like prediction, but only slightly less terrible.
> Now that's a joke that won't land at all for international readers. You're welcome.

 
# The Hunt for Data
Before we can generate anything, we need input data. And what better way to get that than their own tooling?
Unlikely to break (they haven't been updated in 5+ years), runs on their production service, and provides instant data.

> **Disclaimer**: I know I'm not being a model web citizen here by poking around internal tools, but I'm keeping things ethical—no aggressive scraping, no overloading their servers, and I won't be sharing specific endpoints or methods to keep things clean.

My favorite entry point for NS data and APIs is their internal sign builder tool, which generates the digital displays you see in stations. While I won't share specifics about how to access it, I can tell you that it provides a fascinating window into their real-time data systems. The interface lets you configure new (local only) station displays, choose content layouts, and much more. The interesting part begins when you examine how it works under the hood—everything runs client-side, including their API integrations, all in readable, unminified JavaScript that essentially serves as live documentation!

![A very real sign for Delft, running on my iPad](/blog/articles/ns/signbuilder.jpg)

The data it's processing looks a lot like this:
```json
{
  "departures": [
    {
      "direction": "Schiphol Airport ✈",
      "name": "NS  3589",
      "plannedDateTime": "2025-07-17T23:07:00+0200",
      "plannedTimeZoneOffset": 120,
      "actualDateTime": "2025-07-17T23:07:00+0200",
      "actualTimeZoneOffset": 120,
      "plannedTrack": "1",
      "actualTrack": "1",
      "product": {
        "number": "3589",
        "categoryCode": "IC",
        "shortCategoryName": "NS Intercity",
        "longCategoryName": "Intercity",
        "operatorName": "NS",
        "operatorCode": "NS",
        "type": "TRAIN"
      },
      "trainCategory": "IC",
      "cancelled": false,
      "routeStations": [
        {
          "uicCode": "8400280",
          "mediumName": "Den Haag HS"
        },
        {
          "uicCode": "8400380",
          "mediumName": "Laan v NOI"
        },
        {
          "uicCode": "8400390",
          "mediumName": "Leiden C."
        }
      ],
      "messages": [],
      "departureStatus": "ON_STATION"
    }
  ]
}
```


This gives us a treasure trove of information, which will be useful for future projects. But what we're most interested in right now is the product number, which is a unique ID for every currently in-use train.

If we do these requests for a handful of hub stations, process and remove duplicates, we end up with a reliable list of currently deployed hardware.

We can then take these IDs and use another API to ask for more specific details, like an estimated occupancy metric.

> Sidenote: The way they do their occupancy estimation is actually really interesting. Though it's true that this data is crowdsourced to some extent, [they primarily get the data from the train's weight](https://tweakers.net/nieuws/137243/ns-app-toont-hoe-druk-het-per-wagon-is-in-trein-op-traject-arnhem-den-bosch.html#:~:text=De%20NS%20brengt%20de%20drukte,het%20is%20in%20bepaalde%20rijtuigen.), which is measured at various points.

 
# Processing Data
Now, we've got a reliable method of reading real-time information. What's next?

Well, dear reader, it's once again time to spin the **🎰🎲✨WHEEL OF SUFFERING✨🎲🎰**, where we'll be choosing our tech stack.

For this project, we'll need:
- a server-side environment to run the lovely crawling scripts
- a persistent database of some sort
- web hosting

And to run it RELIABLY, FAST, and for CHEAP (yeahhhh).

This naturally leads me to the Cloudflare stack, specifically:
- [Workers](https://workers.cloudflare.com/) for a cron-based compute environment, and to host the public REST API to serve data back to the web UI
- [D1](https://developers.cloudflare.com/d1/), an affordable SQL offering with generous free tiers
- [Pages](https://pages.cloudflare.com/), their static site hosting that's competitive with Vercel

The worker is written in TypeScript and is responsible for calling all the external APIs and ingesting the data into D1. Workers are actually the perfect fit for this, because unlike competitors (like AWS Lambda), they only bill you for CPU duration, not request wall-clock time. This is great in our case, because our script will spend most of its time waiting on external API requests (time for which I will not be billed).

After our requests, we end up with four key metrics:
- the number of trains currently in service
- and how many of them are empty, well-filled, or busy

I want to have a single score/percentage which indicates the busyness across the network, which needs to adapt well to the number of trains in service.
Such a formula is pretty easy to come up with, and I ended up with this:
```typescript
function calculateBusynessPercentage(low: number, medium: number, high: number): number {
  const totalTrains = low + medium + high;
  if (totalTrains === 0) {
    return 0; // No trains, no business
  }

  // Calculate weighted score directly
  const weightedScore = (low * 1 + medium * 2 + high * 3);
  const maxPossibleScore = totalTrains * 3; // All trains at highest utilization

  // Normalize to 0-100 scale
  return (weightedScore / maxPossibleScore) * 100;
}
```

where `low`, `medium`, and `high` are all carriages sorted by their occupancy, totaling to the total service. Each value is weighted, and then normalized by the total amount.

This isn't perfect and leads to some weird temporary spikes when a lot of trains are taken into or out of service, but it's good enough for now.

I then store this data in D1 through a cron job and call it a day.
> Yes, a time series database would be more appropriate for this use case, but D1's generous free tier and SQL familiarity make it a practical choice for this project's scale.


# Those Who Hoard Data... Have a Lot to Sort Through
Those 288 data points per day are enough to do some fun stuff with.
The web page I built for this project (in NextJS, though this part is rendered client-side) makes a request to my worker for the last 7 days' worth of data, and then visualizes it.

Then, for the real kicker, it tries to look at historical metrics from the same time frame in prior days and comes up with an educated guess of what the next hour will bring.

And thus I can finally make an educated guess if it's worth running for my train to ride before the wave of peak hours, or to ride it out and wait for things to cool down.


# BONUS: Fun with Napkin Math
Since we have all this real-time data about train occupancy and network utilization, I thought it would be interesting to do some back-of-the-envelope calculations about revenue streams. This is purely for entertainment and educational purposes—think of it as a data science exercise rather than any serious financial analysis.

As a student who's acutely aware of travel costs (especially during summer months when the free travel doesn't apply), I was curious: what does all this passenger movement actually translate to in terms of revenue? The numbers are fascinating, even if they're built on assumptions and estimates.

We have real-time metrics, we know how big trains are, and we can make an educated guess about how many students and gate-hoppers there are at a given moment.
And with that, we can also guess their real-time worth!

```javascript

const avgSeatsPerTrain = 450; // Average seats per train (source: 600 Sprinter, and we'll deduct an arbitrary 25% for people who take up 2 seats)
const avgStandingCapacity = 300; // Standing room (source: my own estimate)
const totalCapacityPerTrain = avgSeatsPerTrain + avgStandingCapacity;

// Calculate current snapshot metrics
const totalCapacity = totalTrains * totalCapacityPerTrain;
const currentPassengers = Math.round((occupancyPercent / 100) * totalCapacity);

// Revenue calculations with more nuanced pricing
const avgTicketPrice = 7.80; // Based on my personal average
const studentDiscountRate = 0.4; // 40% discount for students
const nonPayingRate = 0.12; // (source: once again, freshly pulled from my own head)
const studentRate = 0.25; // 25% students (source: you'd never guess, my own estimate)

const payingFullPrice = Math.round(currentPassengers * (1 - nonPayingRate - studentRate));
const payingStudents = Math.round(currentPassengers * studentRate);
const nonPayingPassengers = Math.round(currentPassengers * nonPayingRate);

const fullPriceRevenue = payingFullPrice * avgTicketPrice;
const studentRevenue = payingStudents * avgTicketPrice * (1 - studentDiscountRate);
const totalRevenue = fullPriceRevenue + studentRevenue;
```

Not enough to make the costs hurt less, but a funny reminder that things are indeed messed up, and well on track to get even worse next year (hope you enjoy this excellent railway pun).

# [You can explore this data yourself on this page](/projects/train-rush)
![The final result](/blog/articles/ns/screenshot.png)


Dutch Rail Data Heist: Real-Time Metrics, APIs, and Commuter Chaos

Saying goodbye to Java rebuilds, hello to JavaScript (but still in the JVM)


- Note: This project was completed in October 2024, and newer, more advanced smart rings have since been released. This article isn't a product recommendation, but rather a walkthrough of how I learned to reverse engineer Bluetooth protocols and build a custom app.

# The gadget I couldn't resist: A €12 Smart Ring

Let me tell you about the qring from AliExpress—a €12 piece of hardware that claims to measure your heart rate, blood oxygen, and steps. For the price of a fancy sandwich, you get surprisingly decent hardware wrapped in the digital equivalent of a sketchy back-alley deal.

The ring itself? Actually pretty impressive. The vendor app that comes with it? Let's just say it makes Facebook's privacy policy look like a love letter to user rights.

But, the offer was too good to pass up, especially considering that western alternatives (like the samsung smart ring) are priced at €300+, and locks you into their ecosystem (he complains, as avid Apple user).

But here's the thing—I want to own my data. And I'd never really written a mobile app before, so this felt like the perfect excuse to dive headfirst into the beautiful chaos of reverse engineering.

## The Vendor App: A Masterclass in "Please Don't"

First stop: grabbing the APK and diving into the decompiled Java code. What I found was a maze of obfuscated classes, UI components built in web views with Angular (because apparently native mobile development is too mainstream), and enough questionable architectural decisions to make any developer weep.

But buried in all that chaos was gold: the Bluetooth protocol implementation. With enough patience (and beer), I started piecing together how this little ring actually talks to the outside world.

## The Protocol: 16 Bytes of Pure Chaos

The ring uses Bluetooth Low Energy (BLE) with custom GATT services—basically, it's speaking its own private language that only the vendor app understood. Until now.

Every conversation with the ring happens through 16-byte packets. Think of it like sending telegrams, but with more math and less poetry:

```
| Byte 0 | Bytes 1-14 | Byte 15 |
|--------|------------|---------|
| Command|    Data    |Checksum |
```

The first byte tells the ring what you want (read heart rate, set time, etc.). The last byte is a checksum to make sure nothing got corrupted in transit. Everything in between is where the real party happens.

Here's what a typical packet looks like in JavaScript:

```js
// Build a packet to read heart rate log
const packet = new Uint8Array(16);
packet[0] = 0x15; // Command: "give me heart rate data"
packet[1] = 0x01; // Sub-command: "from today"
// ... fill in the middle with timestamp data ...
packet[15] = calculateChecksum(packet); // "did this arrive intact?"
```

Each feature gets its own packet builder and parser. Want to set the time? Here's how:

```js
export function setTimePacket(target = new Date()) {
  const data = new Uint8Array(14);
  
  // Convert date to BCD format because apparently
  // normal timestamps are too mainstream
  data[0] = toBCD(target.getFullYear() % 100);
  data[1] = toBCD(target.getMonth() + 1);
  data[2] = toBCD(target.getDate());
  data[3] = toBCD(target.getHours());
  data[4] = toBCD(target.getMinutes());
  data[5] = toBCD(target.getSeconds());
  
  return makePacket(CMD_SET_TIME, data);
}
```

And parsing the response:

```js
export function parseSetTimePacket(packet) {
  // Extract capability flags from the response
  const capabilities = {
    hasHeartRate: !!(packet[1] & 0x01),
    hasSteps: !!(packet[1] & 0x02),
    hasBloodOxygen: !!(packet[1] & 0x04),
    // ... more flags because hardware is complicated
  };
  
  return { success: packet[0] === 0x01, capabilities };
}
```

## The Heart Rate Nightmare: When 16 Bytes Aren't Enough

Here's where things get spicy. The ring stores up to 7 days of heart rate data—288 points per day, one measurement every 5 minutes. That's 2,016 data points that somehow need to squeeze through our 16-byte packet pipeline.

Obviously, that's not happening in a single packet. So the ring does something clever (and mildly infuriating): it chunks the data across multiple packets, each containing a piece of the puzzle.

The conversation looks like this:

```
App:  "Hey, give me heart rate data for today"
Ring: "Sure! I have 22 chunks of data coming your way"
Ring: "Chunk 1: Here's a timestamp + 9 heart rate values"
Ring: "Chunk 2: Here's 13 more values"
Ring: "Chunk 3: Here's 13 more values"
... (repeat 19 more times) ...
App:  "Cool, let me stitch these 288 values together"
```

This chunked approach means you have to carefully track state between packets, handle out-of-order data, and only process results once everything arrives. It's like assembling IKEA furniture, but the instructions are in binary and some of the pieces might be missing.

### The Packet Dance: A Technical Ballet

Each heart rate chunk has its own structure:

```ascii
Request: [0x15][day_offset][...padding...][checksum]
Response (header): [0x15][0x00][chunk_count][day_range][...]
Response (first): [0x15][0x01][timestamp][9 values][...]
Response (others): [0x15][chunk_id][13 values][...]
```

The first chunk is special—it includes a timestamp so you know when the measurements started. Every subsequent chunk is just pure data, 13 heart rate values packed into the remaining bytes.

But here's the kicker: sometimes chunks arrive out of order. Sometimes they don't arrive at all. Welcome to the wonderful world of Bluetooth Low Energy, where "reliable" is more of a suggestion than a guarantee.

## BLE: The Unreliable Narrator

If you've ever worked with Bluetooth Low Energy, you know it's like that friend who's great at parties but terrible at keeping promises. Packets get lost. Responses arrive late. Connections drop at the worst possible moments.

That's why the RequestQueue became the unsung hero of this entire project. It's a simple but crucial piece of infrastructure that ensures:

- Only one request is in flight at a time
- Responses are matched to the correct request
- Timeouts and retries happen automatically
- The app doesn't get stuck waiting for responses that never come

Without this queue, BLE communication would quickly devolve into chaos. With it, you get something that almost resembles reliability.

```js
class RequestQueue {
  constructor() {
    this.queue = [];
    this.currentRequest = null;
    this.timeout = null;
  }
  
  enqueue(request) {
    this.queue.push(request);
    this.processNext();
  }
  
  processNext() {
    if (this.currentRequest || this.queue.length === 0) return;
    
    this.currentRequest = this.queue.shift();
    this.timeout = setTimeout(() => {
      this.handleTimeout();
    }, 5000); // 5 second timeout
    
    this.sendRequest(this.currentRequest);
  }
  
  handleResponse(response) {
    if (!this.currentRequest) return;
    
    clearTimeout(this.timeout);
    this.currentRequest.resolve(response);
    this.currentRequest = null;
    this.processNext();
  }
}
```

## Building the App: React Native to the Rescue

For the mobile app, I went with React Native because life's too short to write everything twice. The architecture is beautifully modular:

- **UI Components** live in `src/components/`
- **Bluetooth Logic** is isolated in `src/services/bluetooth/`
- **State Management** handled by Redux (because I hate myself)
- **Native Bridges** handle the low-level BLE work on iOS and Android

The home screen shows your ring's current status and latest measurements:

![App Home Screen](/blog/articles/ring/home.jpg)

Tap through to see the week overview, where you can browse the last 7 days of data stored on the ring:

![Week Overview](/blog/articles/ring/week-overview.jpg)

There's also a settings modal for the important stuff—renaming your ring and tweaking preferences:

![Ring Settings](/blog/articles/ring/ring settings.jpg)

And of course, a main page to manage all your rings (because apparently I'm optimistic about my future ring collection):

![Rings Management](/blog/articles/ring/rings.jpg)

## The Detective Work: Decoding Binary Blobs

The hardest part wasn't the Bluetooth protocol or the mobile app—it was figuring out what the hell the ring was actually telling me. Binary data doesn't come with documentation, and the vendor certainly wasn't about to explain their proprietary format.

It was pure detective work. I'd send a command, get back a blob of bytes, then try to figure out what they meant:

```js
// What does this response mean?
// [0x15, 0x01, 0x42, 0x68, 0x72, 0x75, 0x82, ...]
//   ^     ^     ^     ^     ^     ^     ^
//   |     |     |     |     |     |     |
//   cmd   ok   ???   ???   ???   ???   ???
```

Sometimes it was timestamps in BCD format. Sometimes it was sensor readings packed into 12-bit values. Sometimes it was status flags where each bit meant something different. The only way to figure it out was trial and error, lots of logging, and the occasional educated guess.

## The Modular Approach: Packets All the Way Down

Every feature in the ring gets its own packet builder and parser. Want to read battery status? There's a packet for that. Want to set the time? Different packet. Want to configure sleep tracking? You guessed it—another packet.

```js
// Battery status
export function getBatteryPacket() {
  return makePacket(CMD_GET_BATTERY, new Uint8Array(14));
}

export function parseBatteryPacket(packet) {
  return {
    level: packet[1],
    charging: !!(packet[2] & 0x01),
    voltage: (packet[3] << 8) | packet[4]
  };
}

// Sleep settings
export function setSleepTrackingPacket(enabled, startHour, endHour) {
  const data = new Uint8Array(14);
  data[0] = enabled ? 0x01 : 0x00;
  data[1] = startHour;
  data[2] = endHour;
  return makePacket(CMD_SET_SLEEP, data);
}
```

This modular approach makes the codebase maintainable and makes it easy to add new features as I discover them. It's like having a Swiss Army knife, but for ring communication.

## Redux: Because State Management is Hard

All the parsed data flows into Redux slices, making it easy for the UI to stay in sync with the ring's state:

```js
const ringSlice = createSlice({
  name: 'ring',
  initialState: {
    connected: false,
    battery: null,
    heartRate: [],
    steps: 0,
    bloodOxygen: null
  },
  reducers: {
    updateBattery: (state, action) => {
      state.battery = action.payload;
    },
    updateHeartRate: (state, action) => {
      state.heartRate = action.payload;
    },
    // ... more reducers for other data types
  }
});
```

The Redux store becomes the single source of truth for all ring data, and the UI components can just subscribe to the pieces they care about.

## The Privacy Win: My Data, My Rules

With my custom app, I finally have what I wanted from the beginning: complete control over my data. No sketchy servers. No mysterious data collection. No ads. Just my health information, synced straight to Apple HealthKit where it belongs.

The ring still does its job—measuring heart rate, tracking steps, monitoring blood oxygen. But now all that data stays on my device, under my control, integrated into the ecosystem I actually use.

It's like having your cake and eating it too, except the cake is a €12 smart ring and eating it means not having your data harvested by unknown third parties.

## What's Next

This project opened up a whole world of possibilities:

- **More Health Metrics**: The ring probably supports sleep tracking, temperature monitoring, and other features I haven't discovered yet
- **UI Polish**: The app works, but it could be prettier (and more importantly, more functional)
- **Protocol Documentation**: I should probably write down everything I learned for the next poor soul who wants to reverse engineer this thing
- **Open Source Considerations**: Parts of this could be useful to other developers, though the commercial implications are... complex

But, lets be real—this was never just about the ring. It was about taking back control of my technology, understanding how it works, and building something that respects my privacy.
The chances of me following through on all that are... well, 0.

## The Real Victory: Understanding vs. Consuming

Reverse engineering isn't just about breaking things apart—it's about understanding how they work, improving them, and taking control of your own technology. It's the difference between being a consumer and being a creator.

Sure, I could have just used the vendor app and accepted the privacy trade-offs. But where's the fun in that? By diving into the protocol, building my own app, and understanding exactly how this little ring communicates, I turned a €12 piece of hardware into something way cooler than the manufacturer ever intended.

And sometimes, that's exactly what technology needs—someone who refuses to accept that "good enough" is actually good enough.

---

*The €12 qring is still chugging along, faithfully reporting my heart rate to an app that actually respects my privacy. Sometimes the best solutions come from the most unexpected places—like a sketchy AliExpress purchase and a weekend of reverse engineering.*

---

## Freebie: Protocol Deep Dive

For the curious (or masochistic), here's a peek at the actual packet structure for heart rate data:

```js
// Heart rate log request structure
const CMD_HEART_RATE_LOG = 0x15;

function buildHeartRateLogPacket(dayOffset = 0) {
  const packet = new Uint8Array(16);
  packet[0] = CMD_HEART_RATE_LOG;
  packet[1] = dayOffset; // 0 = today, 1 = yesterday, etc.
  // ... fill remaining bytes with padding ...
  packet[15] = calculateChecksum(packet.slice(0, 15));
  return packet;
}

// Response parsing - this is where it gets interesting
function parseHeartRateResponse(packet) {
  const subCommand = packet[1];
  
  if (subCommand === 0x00) {
    // Header packet - tells us how many chunks to expect
    return {
      type: 'header',
      chunkCount: packet[2],
      dayRange: packet[3],
      totalPoints: packet[2] * 13 - 4 // magic math
    };
  } else if (subCommand === 0x01) {
    // First data chunk - includes timestamp
    const timestamp = parseTimestamp(packet.slice(2, 8));
    const values = parseHeartRateValues(packet.slice(8, 17));
    return {
      type: 'data',
      chunk: 1,
      timestamp,
      values
    };
  } else {
    // Subsequent data chunks - just values
    const values = parseHeartRateValues(packet.slice(2, 15));
    return {
      type: 'data',
      chunk: subCommand,
      values
    };
  }
}

function parseHeartRateValues(data) {
  const values = [];
  for (let i = 0; i < data.length; i++) {
    if (data[i] !== 0) { // 0 = no measurement
      values.push(data[i]);
    }
  }
  return values;
}
```

The checksum calculation is a simple XOR of all bytes:

```js
function calculateChecksum(data) {
  return data.reduce((sum, byte) => sum ^ byte, 0);
}
```

And the timestamp parsing involves converting BCD format back to a proper date:

```js
function parseTimestamp(data) {
  const year = fromBCD(data[0]) + 2000;
  const month = fromBCD(data[1]) - 1; // JS months are 0-indexed
  const day = fromBCD(data[2]);
  const hour = fromBCD(data[3]);
  const minute = fromBCD(data[4]);
  const second = fromBCD(data[5]);
  
  return new Date(year, month, day, hour, minute, second);
}

function fromBCD(bcd) {
  return ((bcd >> 4) * 10) + (bcd & 0x0F);
}
```

*There you have it—the secret sauce that turns binary gibberish into meaningful health data. Use it wisely.*


The €12 Privacy Rebellion: How I Reverse Engineered a Smart Ring and Built My Own App


# The Challenge of Inter-Service Communication

In distributed systems, particularly stateful applications like large-scale game networks, robust inter-service communication is a fundamental requirement. Services, often running in separate JVMs or on different machines, must exchange data and trigger behavior on one another. For example, a lobby server may need to query a game server for player statistics, or a minigame instance might need to update a player's inventory on a central data service.

The conventional solutions to this problem involve creating and maintaining explicit communication protocols, such as REST APIs or custom message-based systems over a queue. These approaches, while effective, introduce significant overhead in both development and maintenance. Developers must write and manage API specifications, handle network logic, and often write client libraries. This boilerplate can obscure the core business logic and create a disconnect between local development environments and deployed production systems.

The primary motivation for Meteor was to abstract this complexity away. The goal was to enable developers to write code against standard Java interfaces, with the underlying communication mechanism becoming a transparent detail of the runtime environment. This allows for identical application code to run in a monolithic local environment for testing or in a distributed production environment, simply by changing a configuration setting.

## Design: Abstracting Communication Behind Interfaces

Meteor is a Java RPC (Remote Procedure Call) framework designed to make remote method invocations appear as local method calls. It achieves this by allowing developers to work with their own Java interfaces, decoupling the application logic from the networking layer.

Consider a simple `Scoreboard` interface:

```java
public interface Scoreboard {
    int getScoreForPlayer(String player);
    void setScoreForPlayer(String player, int score);
    Map<String, Integer> getAllScores();
}
```

On a service that owns the data (the "server"), a concrete implementation is registered with a Meteor instance:

```java
// The service with the authoritative state registers its implementation.
Scoreboard implementation = new ScoreboardImplementation();
meteor.registerImplementation(implementation, "parkour-leaderboard");
```

Any other service (a "client") can then obtain a proxy instance that conforms to the `Scoreboard` interface, without needing access to the implementation class:

```java
// A client service obtains a remote-controlled proxy.
Scoreboard parkourScoreboard = meteor.registerProcedure(Scoreboard.class, "parkour-leaderboard");

// This method call is transparently sent to the remote implementation.
int score = parkourScoreboard.getScoreForPlayer("Notch");
```

The `parkourScoreboard` object is a dynamically generated proxy. When its methods are invoked, Meteor intercepts the call, serializes it, sends it over a configured transport, and awaits a response from the remote service where the actual implementation is running.

## Core Architecture

The flexibility of Meteor stems from its pluggable architecture. The core library is unopinionated about the underlying mechanisms for transport and serialization, allowing them to be swapped out to fit different use cases.

-   **`RpcTransport`**: This interface defines the contract for sending and receiving invocation and result packets. The `meteor-jedis` module provides an implementation that uses Redis pub/sub for broadcasting packets, a suitable strategy for fan-out communication patterns. For local development and testing, a `LoopbackTransport` is provided, which performs all communication in-memory within a single JVM, eliminating network overhead and dependencies.
-   **`RpcSerializer`**: This interface handles the serialization of method arguments and return values. The default implementation uses Gson for JSON serialization, but custom implementations can be provided for other formats (e.g., Protocol Buffers, Kryo) to meet specific performance or compatibility requirements.
-   **Dynamic Proxies**: At its core, Meteor leverages Java's `java.lang.reflect.Proxy` to generate proxy classes at runtime. When `registerProcedure` is called, Meteor creates a new class that implements the target interface. The invocation handler for this proxy is responsible for coordinating with the `RpcSerializer` and `RpcTransport` to execute the remote call.

This design allows for a clean separation of concerns, where application code is concerned only with business logic defined in interfaces, while the framework handles the underlying communication mechanics.

## Runtime Instrumentation and Dynamic Tooling

The design philosophy of Meteor is that the framework should adapt to the application's code, not the other way around. Instead of requiring developers to extend framework-specific classes or use annotations, Meteor uses runtime instrumentation to generate the necessary components. This approach can be thought of as creating adapters from "playdough"—the framework molds itself around the existing code structure.

Here is a breakdown of the process:

1.  **Interface as Contract**: The developer provides a standard Java interface. This interface is the sole contract and remains free of any framework-specific code.
2.  **Runtime Proxy Generation**: When `meteor.registerProcedure(YourInterface.class, ...)` is invoked, Meteor's runtime dynamically creates a proxy class that implements `YourInterface`. The methods of this generated class contain the necessary instrumentation to delegate calls to the Meteor Core.
3.  **Invocation Interception**: When a method is called on the proxy object, the invocation is intercepted. The method name, arguments, and other metadata are packaged into an invocation object, which is then handed off to the serialization and transport layers.

This runtime-centric approach means the developer is not burdened with writing boilerplate networking or serialization code. The framework handles it transparently.

### Call Flow Visualization

The sequence of events for a remote procedure call can be visualized as follows:

![Meteor sequence diagram](/blog/articles/meteor/dia1.png)

### System Architecture Overview

Internally, the components of Meteor work together to provide this transparent RPC mechanism.

![Meteor architecture](/blog/articles/meteor/dia2.png)

This pluggable and dynamic nature allows Meteor to handle the complex, error-prone networking tasks, freeing developers to focus on application logic.

## Conclusion

Meteor was developed by Duco and Mats in 2023 over a period of two months. It provides a practical solution to the challenges of inter-service communication in Java applications. By leveraging runtime proxy generation and a pluggable component model, it successfully abstracts network communication behind standard Java interfaces. This approach simplifies development, improves testability by allowing local execution without code changes, and decouples business logic from the underlying transport mechanism. The result is a more maintainable and scalable system where developers can focus on their core domain without being burdened by the intricacies of distributed systems programming.

The project was also a significant milestone for us as it was our first to be accepted into the public OSS Sonatype repository. The source code is available on [GitHub](https://github.com/pixelib/meteor).


Meteor: Interfaces as networking contract

Lights are cool. That's just a fact.
You have pretty colored static ones, you have wobbly moving ones, you have ones that can do both.
You know what else has wobbly moving lights and effects? Minecraft. [ImagineFun, the Minecraft disney experience](https://imaginefun.net/) I work for, has a lot of them.

And in the past few years, we've made a ton of improvements to our workflows and pipelines to make it easier for our creative folks to make cool stuff.
But, shows are still made by people, and people are still people. And people are lazy. And people are forgetful. And people are bad at math. And people are bad at random numbers.
This doesn't mean we're bad at making shows, but it does mean that we can make even bigger ones by tapping into the decades of experience from the real Theatre and Live Event industry.
And after months of work, we've crafted a full pipeline to bring real show technology into Minecraft.

## Managing expectations
Before we dive into the technical details, let's set some expectations.
I won't be able to share any of our specific implementations, code, or secret sauce. I will, however, share the general concepts and ideas behind our work.

## What is DMX and Art-Net?
![A DMX splitter from my local student pub, taking one 3pin input, and splitting it into 6 lines for different facades](/blog/articles/ma_minecraft/img_6.png)
DMX is a protocol used in the lighting industry to control fixtures. It's a simple serial protocol that sends a stream of bytes [(RS-485)](https://en.wikipedia.org/wiki/RS-485). It's been around for a long time, and it's still widely used today. You can imagine each "command" as an array, a huge list of numbers (DMX512, has 512 usable addresses, with remaining bytes being used for the sync and frame protocols) that represent the intensity of a light, the color of a light, or any other parameter you can think of.

Each fixture has an address, which is the Nth slot in this list, from where it will read a few numbers (depending on it's parameters) and parse them as it's state.
For example, let's say that we have a simple RGB light, that has 3 channels (1: red, 2: green, 3: blue) If we send the command `[255, 0, 0]` to the light, it will turn on at full brightness and be red. If we add a second light, then it would start listening at the 4th slot, at which point our *universe* would look like this: `[255, 0, 0, 255, 0, 0]`.

You can imagine that this becomes a huge list pretty fast, mostly because most lights need far more than 3 parameters (moving lights can have 20+ channels, for all its gobos, movements, colors, etc). This is why DMX is usually split into *universes*, which are separate lists of 512 slots. This way, you can have a lot of lights, but you can also have a lot of parameters for each light. If one universe gets full, you can just overflow into the next one. It's not uncommon for this to get out of hand. [Eurovision (2024), used a whopping 663 DMX universes.](https://www.malighting.com/news/article/grandma3-for-eurovision-2024-1375/#:~:text=All%20the%20non%2Dkey%20light%20fixtures%20with%20RGB%20or%20a%20fast%20dimmer%20were%20pixel%2Dmapped%20in%20the%20media%20servers%20to%20keep%20the%20creative%20options%20as%20open%20as%20possible%2C%20so%20most%20of%20the%20outputting%20DMX%20universes%20were%20merged%20with%20the%20663%20DMX%20universes%20of%20Art%2DNet%20input.%C2%A0)

DMX is normally transferred over a 3 (or 5) pin XLR cable, but it can also be sent over Ethernet, which is where Art-Net comes in.
Art-Net is a protocol that sends DMX over IP, which is a lot more flexible than physical cables. It's also a lot easier to work with, as you can just use a normal network cable to send DMX around. And that's also where we start to differ from the real world.

Because it's a network signal, we can setup a socket to listen for Art-Net commands, and do with them whatever we want. The lighting desk/software doesn't know if it's talking to a real light or a Minecraft block, it just sends the commands and hopes that something will listen.

[It's an open standard](https://art-net.org.uk/downloads/art-net.pdf) provided by [Artistic License](https://artisticlicence.com/), so you can just implement it in your own software. And that's what we did.

## The pipeline
We have two separate pipelines for working with Art-Net, the primary one is for the creative folks, and the secondary one is for playback.

- Primary pipeline (live)

![A cobalt debug view that shows when someone is connected to the Art-Net node](/blog/articles/ma_minecraft/img_2.png)
When building a show, you want to see what you are programming in your lighting software, preferably in real-time. This is where the primary pipeline comes in. This runs an embedded Art-Net node in-game, which we can target through unicast and then gets injected into our rendering engine. This way, we can see the lights in-game, and we can see the lights in our lighting software. This is a huge improvement over the old way of doing things, where we had to manually convert the show into Minecraft commands or scriptable actions.

- Secondary pipeline (playback)

![The self made Art-Net recorder with timecode support](/blog/articles/ma_minecraft/img_1.png)
And while this works for building shows, it doesn't work for running them. We don't want to have someone operating every show, because they run on a set schedule and we want to be able to run them without us having to get up at 3 AM. This is where the secondary pipeline comes in. We have a custom standalone application (written in Go), that also listens for Art-Net commands, but instead of rendering them in-game, it processes them, minifies every frame (only using keyframes every few seconds), and then pumps them into a file (shared protocolbuffer) that we can upload to our server.

Then, when it's time for our night spectacles, the show can be loaded into our server, and the server will play the show back, parsing the protocolbuffer and sending the raw timecoded DMX changes to our rendering engine, the same way our primary pipeline does. 

## Mapping to in-game actions
![Snippet from Cobalt's abstract fixture class](/blog/articles/ma_minecraft/img_3.png)
We have a predefined set of virtual fixtures (like lasers, moving spots, command triggers, and even pixel-mapped LED blocks), which are all 'patched' to listen to a specific universe and address. That way, our rendering engine can take the raw DMX universe states, and pass them on to our fixtures. And this is where the magic happens. We can now control our in-game lights with a real lighting desk, and we can control our real lights with in-game actions.

| Universe | Type | Start Channel | End Channel | Amount | Description                       |
|----------|------|---------------|-------------|---------|-----------------------------------|
| 5 | End Beam | 0 | 127 | 32 | Castle End Beams                  |
| 5 | Moving Head | 128 | 131 | 1 | Castle Moving Head                |
| 5 | Pixel Block | 132 | 320 | 63 | Castle Matrix                     |
| 5 | Moving Head | 321 | 328 | 2 | Ballroom Lasers                   |
| 6 | Pixel Block | 0 | 62 | 20 | Decorative Pixel (Christmas Tree) |

![Main castle end beams](/blog/articles/ma_minecraft/endbeams.png)
![Main castle pixel mapping screen](/blog/articles/ma_minecraft/pixels.png)

## Conclusion
This has been a huge project for us, and it's been a lot of fun to work on. A few of us work in the real life event industry as well, and are incredibly passionate about bringing the work we love so much into the game we love even more. We've been able to make some really cool shows with this technology, and are still working on improving it every day and seeing how far we can push it to build shows on scales we've never seen before.

![End product - show by SlinxMC](/blog/articles/ma_minecraft/img_7.png)


Block art with Art-Net

We’ve all been there before.
You’re working on a project with some large inherited codebase, from code elder gods who cannot be reasoned with. Or, you’re interacting with a library, that just does this one annoying thing coming from some terrible decision, and now you need to work around it.

Forking it might be an option, but do you really want to take on that responsibility for this one off thing? And do you really want to challenge the senior elder gods? Your situation is feeling more dire with every class you decompile, no way you’re picking all of this up.

The go-to method within modding communities is to setup mixins, or even dabble with the occasional javaassist, which does the job, but is fragile and breaks between versions. Or maybe the code you write now may run in weird configurations or security policies, in which case, you certainly don’t want to work with either.

If only there was some vanilla way in Java, that when mastered, will allow you to bodge through pretty much **anything**.
>  **Foreshadowing: a literary device in which a writer gives an advance hint of what is to come later in the story**

## Bodging
[Tom Scott explained it best in his video](https://youtu.be/lIFE7h3m40U?si=zdAtMWJ-E7tmLZrO). It’s the art of patching something ugly together, that works, just for now, or as a permanent solution if you’re willing to ignore the war crimes you committed in the form of code.
Java is no stranger to either, and though that can lead some pitfalls and boilerplate abstraction hell, this is one of the cases where you can play god, and literally bend classes at your will during runtime.

## Introduction to proxies
Proxies, best known from their JavaScript implementation, are special elements that let you intercept calls and interactions with an object. 
```js
const target = { name: 'John', age: 30 };

const handler = {
  get: (target, prop) => prop in target ? target[prop] : `No such property: ${prop}`,
  set: (target, prop, value) => prop === 'age' && value <= 0 ? false : (target[prop] = value),
  deleteProperty: (target, prop) => prop === 'name' ? false : delete target[prop]
};

const proxy = new Proxy(target, handler);

console.log(proxy.name);     // John
proxy.age = 25;              // Sets age to 25
console.log(proxy.age);      // 25
proxy.age = -5;              // Invalid age, doesn't change
console.log(proxy.age);      // 25
```
This is something that works really well in JS land, types are only a suggestion after all. There’s no governing body running around, telling you that they wouldn’t be compatible.

But, what if I tell you that Java is more forgiving than you might think? And it would let you do similar gymnastics as well. You might not care as much, but this stuff absolutely rocked my world.

## Java Types - why is this so powerful
Types in java are strict. You may simply not cast `7` to a `2001 Toyota corolla` no matter how hard you try. If a field is marked as a specific object type, then there’s no way to change it’s type to a different family (maybe if you were to play with [Unsafe](https://github.com/openjdk/jdk/blob/master/src/jdk.unsupported/share/classes/sun/misc/Unsafe.java), but we’re talking about bodging here, not inventing new means of self destruction).

The only way to overwrite existing behavior is to extend the type you’re targeting and only implement the methods you’re trying to manipulate, passing the rest back to super. This works, but is technical debt when the target type is outside of your control and may be updated (with new methods, signatures, or even worse).

## Java Proxies
Yes, they exist, and they work.
It’s one of the exceptions where java will actually generate new class definitions during runtime, and it is awesome.

They work by creating a new real class during runtime, and registering it directly in [JavaLanguageAccess](https://code.yawk.at/java/15/java.base/jdk/internal/access/JavaLangAccess.java#jdk.internal.access.JavaLangAccess%23defineClass(java.lang.ClassLoader%2Cjava.lang.String%2Cbyte%5B%5D%2Cjava.security.ProtectionDomain%2Cjava.lang.String)) (which is really interesting on it own, and i highly recommend looking into), and it is even smart enough to cache the generated class for future use (when you want to generate a new proxy of the same type).

To get started, we need to create a new `InvocationHandler` that will intercept the calls to the object we’re trying to proxy. This is a functional interface, so we can use a lambda to implement it.
```java
InvocationHandler handler = (proxy, method, args) -> {
    if (method.getName().equals("toString")) {
        return "Hello from the proxy!";
    }
    return null;
};
```

Next, we need to create the proxy itself. This is done by using the `Proxy.newProxyInstance` method, which takes a classloader, an array of interfaces we want to proxy, and the handler we just created. For the examples moving forward, we'll be manipulating a bukkit Player object, and we'll be using the `Player` interface as the target.
```java
Player player = (Player) Proxy.newProxyInstance(
    Player.class.getClassLoader(),
    new Class[] { Player.class },
    handler
);
```

And voila, we have a proxy object that will intercept calls to the `Player` object, and return `Hello from the proxy!` when `toString` is called.
But, this isn't useful in the real world, because this will explode when you try to call any other method on the object, but this is also where the beauty of proxies comes in. You can now implement the methods you want to intercept, and pass the rest back to the original object dynamically, without having to implement the entire interface or even worrying about future changes because it'll be evaluated during runtime, and your used api version doesn't matter.

Where is this useful?

# Example 1: Faking permissions
This may sound far fetched, but is a diabolical thing I had to do in the past. I was calling out to a library which was not worth the effort to fork, and it **insisted** that the passed player had to be OP. Though it's possible to just wrap that call with a setOP invocation, I'd rather not give the player any OP permissions *ever*

Well, we can use a proxy to work around this! I wrote this little middleware, that only intercepts the isOp method, and returns our custom value, but still passes the rest of the calls to the original object.
```java
public class PlayerOpProxy implements InvocationHandler {

    private boolean opStatus;
    private final Player originalPlayer;
    private Player proxiedPlayer;

    public PlayerOpProxy(Player originalPlayer, boolean isOp) {
        this.originalPlayer = originalPlayer;

        this.proxiedPlayer = (Player) Proxy.newProxyInstance(
                originalPlayer.getClass().getClassLoader(),
                originalPlayer.getClass().getInterfaces(),
                this
        );
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        if (method.getName().equals("isOp")) {
            return this.opStatus;
        } else if (method.getName().equals("setOp")) {
            this.opStatus = (boolean) args[0];
            return null;
        } else {
            return method.invoke(this.originalPlayer, args);
        }
    }

    public Player getProxiedPlayer() {
        return this.proxiedPlayer;
    }
}
```

# Example 2: Function middleware (caching)
This is a more practical example, where we want to cache the result of a function call, and return the cached value if the function is called. Normally we would have to implement a caching strategy ourself, but with a proxy we can abstract all of this as if it were a code generator (which it is, in a way).

If we use a proxy based method, then all we need to do is
```java
public interface UserService {
    @CacheUtil.Cache(retention = 5)
    String getUserName(int id);
}

// Creating a proxy
UserService service = new UserServiceImpl();
UserService proxiedService = CacheUtil.createProxy(service, UserService.class);

// Using the proxied service
String result = proxiedService.getUserName(1); // calls the original method
String cachedResult = proxiedService.getUserName(1); // returns the cached value, never actually reaching the original method
```

And this entirely works without any external dependencies, and without requiring ahead of time binary manipulation or mixins. It's a simple, clean, and effective way to manipulate objects at runtime, and it's a tool that I'm surprised isn't used more often.

Here's my CacheUtil implementation, as a freebie for reading this far.
```java
public final class CacheUtil {
    
    /**
     * Annotation to specify caching behavior for methods.
     * Methods annotated with {@code @Cache} will have their return values cached
     * for the specified retention time in seconds.
     */
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    public @interface Cache {
        /**
         * Specifies how long the cached value should be retained in seconds.
         * @return retention time in seconds
         */
        int retention() default 5;
    }

    /**
     * Creates a proxy instance that implements caching behavior for annotated methods.
     *
     * @param <T> the type of the interface to be proxied
     * @param target the object to be proxied
     * @param interfaceClass the interface class that the proxy will implement
     * @return a proxied instance with caching behavior
     * @throws IllegalArgumentException if target or interfaceClass is null
     */
    @SuppressWarnings("unchecked")
    public static <T> T createProxy(T target, Class<T> interfaceClass) {
        if (target == null || interfaceClass == null) {
            throw new IllegalArgumentException("Target and interface class cannot be null");
        }
        return (T) Proxy.newProxyInstance(
            interfaceClass.getClassLoader(),
            new Class<?>[] { interfaceClass },
            new CacheHandler(target)
        );
    }

    private static class CacheEntry {
        private final Object value;
        private final long expirationTime;

        CacheEntry(Object value, long expirationTime) {
            this.value = value;
            this.expirationTime = expirationTime;
        }

        boolean isExpired() {
            return System.currentTimeMillis() > expirationTime;
        }

        Object getValue() {
            return value;
        }
    }

    private static class CacheHandler implements InvocationHandler {
        private final Object target;
        private final Map<String, CacheEntry> cache = new ConcurrentHashMap<>();

        CacheHandler(Object target) {
            this.target = target;
        }

        @Override
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
            Cache cacheAnnotation = method.getAnnotation(Cache.class);
            if (cacheAnnotation == null) {
                return method.invoke(target, args);
            }

            String cacheKey = generateCacheKey(method, args);
            CacheEntry entry = cache.get(cacheKey);
            
            if (entry != null && !entry.isExpired()) {
                return entry.getValue();
            }

            Object result = method.invoke(target, args);
            long expirationTime = System.currentTimeMillis() + (cacheAnnotation.retention() * 1000L);
            cache.put(cacheKey, new CacheEntry(result, expirationTime));

            return result;
        }

        private String generateCacheKey(Method method, Object[] args) {
            return method.getName() + ":" + (args != null ? Arrays.deepHashCode(args) : "");
        }
    }
}
```


Bodging in Java - crimes against the runtime

# Two things have always been true about me:
- I love sharing things I work on
- I am incredibly lazy and drop anything that has the slightest bit of friction

And sadly, these two things are not compatible.
So I decided to build a blog. But not just any blog, a blog that is so overengineered that there's a really fair chance that I spent more time building it than I will ever spend writing on it.

In a perfect world, I would just have a folder where I could quack out some markdown files and have them automagically appear on the internet. And there are many tools that do just that, leagues better than what I could ever build. But that's not the point. The point is to build something myself, and to learn from it.
The last site I built with this idea (the OpenAudioMc docs) required me to manually register markdown files in a JSON file, provide metadata, and then painfully wait for Next.js to rebuild the site. It was a pain, but it worked. And it was fun to build.

Naturally, I asked myself: "How can I make this even more painful?".
The answer was simple: "Let's build a vite plugin that does this".
Why should vite have anything to do with this? Because fuck it, that's why.

# Drafting
I started building the site normally, quick router, sprinkle in some [ReactMarkdown](https://github.com/remarkjs/react-markdown), hardcode a text blob, and, then, well shit, what now?

Well, markdown "supports" comments, not every parser respects them, but you can abuse this mechanism to embed metadata in a markdown file itself!
A quick
```yaml
---
title: Overbuilding a blog
date: '2024-01-27'
excerpt: Probably the worst way to build a blog
tags:
  - Personal
coverImage: /blog/articles/welcome/scheveningen.png
author:
  name: Mats
  avatar: https://github.com/Mindgamesnl.png
  role: The king
---
```
then, pull it through [Gray Matter](https://www.npmjs.com/package/gray-matter) (or any other yaml  parser), and congratulations! You are now the proud owner of some goofy ahh metadata system!

# Indexing
Like I said, I didn't want to write yucky manual indexes for my files, but I also didn't want to setup a full CMS or crud (I want this to be a dumb static site, no fancy serverless nonsense).

Vite already bundles my garbage JS code, so why not also abuse it to bundle my markdown?
And with that, I don't mean bundling it as huge fuckass strings/blobs, but building a custom plugin that reads markdown files, parses it's embedded metadata, listens for changes, and then makes a virtual module to export all this data.
So I did just that.

## What are Virtual Modules?
Virtual Modules are a concept by the Module government, to sell you more modules without needing to write out a file. You can dynamically generate them in a plugin, and then access them through a special namespace/prefix in your code.

We can implement the resolve method in our vite plugin, to tell it that an import statement should actually be using our virtual module instead!
```js
resolveId(id) {
    if (id === 'virtual:blog-data') {
        return '\0virtual:blog-data';
    }
}
```
Vite will then later call the load method, where we can return the actual content of our virtual module.
```js
load(id) {
    if (id === '\0virtual:blog-data') {
        return `export const exampleData = ${JSON.stringify({ someObject: 'thingy' })};`;
    }
}
```

## Implementing a virtual blog module
Now that we know that we can dynamically generate bundles, we can make one that:
- Lists all my markdown files
- Parses its content and metadata yaml blob
- is pretty slow but I don't care yet

```js
const processArticle = (filePath) => {
  const source = fs.readFileSync(filePath, 'utf-8');
  const { data: frontmatter, content } = matter(source);
  const slug = path.basename(filePath, '.md');

  return {
    slug,
    content,
    ...frontmatter,
    title: frontmatter.title || 'Untitled',
    date: frontmatter.date || new Date().toISOString(),
    excerpt: frontmatter.excerpt || '',
    readTime: calculateReadTime(content),
    author: {
      name: frontmatter.author?.name || 'Mats',
      avatar: frontmatter.author?.avatar || 'https://github.com/Mindgamesnl.png',
      role: frontmatter.author?.role || '',
      bio: frontmatter.author?.bio || ''
    },
    tags: frontmatter.tags || [],
    coverImage: frontmatter.coverImage || '/blog/articles/cover.png'
  };
};

const loadAllArticles = () => {
  const blogDir = path.resolve('src/content/blog/articles');
  const files = fs.readdirSync(blogDir)
    .filter(file => file.endsWith('.md'));

  const articles = files.map(file => {
    const filePath = path.join(blogDir, file);
    return processArticle(filePath);
  });

  articles.sort((a, b) => new Date(b.date) - new Date(a.date));
  return articles;
};
```

which we can then use in our module, where we'll embed it as a json object (passed as string, because vite doesn't like objects). You could also provide function implementations here, and import them like you would any other function from any other module, but this already feels incredibly dirty (it is), and even I have some standards.

So, with that, our load method will look like this:
```js
load(id) {
  if (id === '\0virtual:blog-data') {
    const articles = loadAllArticles();

    return `
      const articles = ${JSON.stringify(articles, null, 2)};
      export { articles };
    `;
  }
}
```

# Consuming the data
Now that we have our data, we can import it in our React components, and use it to render our blog posts.
I wrote a quick little hook that fetches the data from our virtual module, and returns it as a normal object.
```jsx
import { useMemo } from 'react';
import { articles } from 'virtual:blog-data';

export const useBlogArticles = () => {
  return articles;
};

export const useBlogArticle = (slug) => {
  return useMemo(() => {
    if (!slug) return undefined;
    const article = articles.find(article => article.slug === slug);
    return article || null;
  }, [slug]);
};
```

And that's it! this will work just like any other hook. But I don't like it.
This is forgetting my main goal: to let myself be as lazy as possible.

I want hot reloading, I want to be able to write a markdown file, and see it appear on my site without needing to refresh the page. And I want to do this without needing to write a single line of code or god forbid, tab out of my editor.

# Self-reloading
Making the plugin listen for changes is the easy part, we add markdown files, sprinkle in a listener, and we're gaming
```js
const blogDir = path.resolve('src/');

server.watcher.add(path.resolve(blogDir, '**/*.md'));

server.watcher.on('change', (file) => {
  if (file.endsWith('.md')) {
    console.log(`[blog] File changed: ${file}`);
    const article = processArticle(file);
  }
});
```
but how do we then get this to the client?
We don't have to! Our magnificent vite overlords got us covered here too!
Vite already runs a websocket server under the hood which is attached and available to us in our plugin and hook, 
all we need to do is send a custom event, catch it in the hook, and we're absolutely golden!

```js
server.watcher.on('change', (file) => {
  if (file.endsWith('.md')) {
    console.log(`[blog] File changed: ${file}`);
    const article = processArticle(file);
    server.ws.send({
      type: 'custom',
      event: 'blog-article-update',
      data: {
        slug: article.slug,
        event: 'blog-article-update',
        article
      }
    });
  }
});
```

# End result
And that's it! I can now build my blog by writing markdown files, and have them automagically appear on my site, even while running a development instance with hot reloading.
All it took was this (final) vite blog plugin:
```js
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';

const calculateReadTime = (content) => {
  const wordsPerMinute = 200;
  const words = content.trim().split(/\s+/).length;
  const minutes = Math.ceil(words / wordsPerMinute);
  return minutes === 1 ? '1 minute read' : minutes < 1 ? 'Quick read' : `${minutes} minutes read`;
};

export default function blogPlugin() {
  const virtualModuleId = 'virtual:blog-data';
  const resolvedVirtualModuleId = '\0' + virtualModuleId;

  const processArticle = (filePath) => {
    const source = fs.readFileSync(filePath, 'utf-8');
    const { data: frontmatter, content } = matter(source);
    const slug = path.basename(filePath, '.md');

    return {
      slug,
      content,
      ...frontmatter,
      title: frontmatter.title || 'Untitled',
      date: frontmatter.date || new Date().toISOString(),
      excerpt: frontmatter.excerpt || '',
      readTime: calculateReadTime(content),
      author: {
        name: frontmatter.author?.name || 'Mats',
        avatar: frontmatter.author?.avatar || 'https://github.com/Mindgamesnl.png',
        role: frontmatter.author?.role || '',
        bio: frontmatter.author?.bio || ''
      },
      tags: frontmatter.tags || [],
      coverImage: frontmatter.coverImage || '/blog/articles/cover.png'
    };
  };

  const loadAllArticles = () => {
    const blogDir = path.resolve('src/content/blog/articles');
    const files = fs.readdirSync(blogDir)
      .filter(file => file.endsWith('.md'));

    const articles = files.map(file => {
      const filePath = path.join(blogDir, file);
      return processArticle(filePath);
    });

    articles.sort((a, b) => new Date(b.date) - new Date(a.date));
    return articles;
  };

  return {
    name: 'vite-plugin-blog-data',
    enforce: 'pre',

    configureServer(server) {
      const blogDir = path.resolve('src/');
      server.watcher.add(path.resolve(blogDir, '**/*.md'));

      server.watcher.on('change', (file) => {
        if (file.endsWith('.md')) {
          console.log(`[blog] File changed: ${file}`);
          const article = processArticle(file);
          server.ws.send({
            type: 'custom',
            event: 'blog-article-update',
            data: {
              slug: article.slug,
              event: 'blog-article-update',
              article
            }
          });
        }
      });
    },

    resolveId(id) {
      if (id === virtualModuleId) {
        return resolvedVirtualModuleId;
      }
    },

    load(id) {
      if (id === resolvedVirtualModuleId) {
        const articles = loadAllArticles();

        return `
          const articles = ${JSON.stringify(articles, null, 2)};
          export { articles };
        `;
      }
    }
  };
}
```

and this hook:
```js
import { useState, useEffect, useMemo } from 'react';
import { articles as initialArticles } from 'virtual:blog-data';

// Shared state between hooks
let currentArticles = [...initialArticles];

export function useBlogArticles() {
  const [articles, setArticles] = useState(currentArticles);

  useEffect(() => {
    // Only set up hot reloading in development
    if (!import.meta.hot) return;

    const handleUpdate = (data) => {
      if (data.event === 'blog-article-update') {
        const updatedArticle = data.article;
        const index = currentArticles.findIndex(
          article => article.slug === updatedArticle.slug
        );
        
        if (index !== -1) {
          currentArticles[index] = updatedArticle;
        } else {
          currentArticles.push(updatedArticle);
        }

        // Update component state
        setArticles([...currentArticles]);
      }
    };

    import.meta.hot.on('blog-article-update', handleUpdate);
    return () => import.meta.hot.off('blog-article-update', handleUpdate);
  }, []);

  return articles;
}

export function useBlogArticle(slug) {
  const articles = useBlogArticles();

  return useMemo(() => {
    if (!slug) return undefined;
    return articles.find(article => article.slug === slug) || null;
  }, [slug, articles]);
}

if (import.meta.env.DEV) {
  window.__blogArticles = currentArticles;
}
```


Abusing virtual modules for a blog


# The 80% Problem

Running a large-scale Minecraft theme park comes with some interesting performance challenges. The most sobering metric we discovered? **80% of our server's processing power** was being consumed by a single system: our ride mechanics.

This overhead was happening **every single tick**, 20 times per second, regardless of whether anyone was actually riding the attractions. We had a serious performance bottleneck that was limiting everything else we could build.

## The Ticking Time Bomb

Here's how Minecraft works: everything that needs to happen in the game world gets 50 milliseconds to complete, 20 times per second. Miss that deadline by even 1 millisecond, and the entire server starts falling behind. Players see rides freeze mid-air, shows desync, and the magic disappears faster than you can say "server lag."

Our profilers painted a grim picture. While player movement, commands, animatronics, and literally everything else on the server combined took up about 20% of resources, our ride system was hogging the remaining 80% doing things like:

- Calculating entity positions every tick for hundreds of vehicles
- Computing track orientations and banking in real-time  
- Managing entity tracking and interactions
- Triggering effects and redstone systems
- Handling collision detection

It was death by a thousand calculations, and we were running out of computational headroom fast.

## The Relationship That Couldn't Last

[TrainCarts](https://www.spigotmc.org/resources/traincarts.39592/) was absolutely essential to ImagineFun's existence. When we opened in June 2018, TrainCarts and its companion plugin TCCoasters were revolutionary—they literally enabled the second wave of Minecraft theme park servers.

But as our ambitions grew and our player base expanded, we started hitting fundamental limitations. The system that got us started wasn't going to scale to where we wanted to go.

We needed to completely rethink how we handle entities in Minecraft. Not just optimize the existing system—replace it entirely.

## The Nuclear Option: Going Straight to the Protocol

Most sane developers would have tried optimizing the existing TrainCarts system first. We decided to be insane instead.

Instead of working within Minecraft's entity system, we decided to bypass it completely. What if we could intercept all network traffic between the server and clients, and handle our own entities without Minecraft even knowing they exist?

Here's the key insight: Minecraft clients don't actually care where entity data comes from. They just want to receive the right packets at the right time. So we built COBALT to work entirely at the network layer, intercepting traffic and managing our own parallel universe of entities.

When a player interacts with a COBALT entity, the Minecraft server doesn't know something happened. When we spawn 1,000 entities for a massive ride, the server continues operating normally. We essentially created a way to have extensive entity interactions that are completely invisible to the main server process.

### Under the Hood: The Protocol Hijack

The technical implementation of this network interception is actually quite elegant. We hook directly into Minecraft's networking layer using [Netty](https://netty.io/)—the same framework that powers Minecraft's own networking.

Every packet that flows between server and client gets a chance to be intercepted, modified, or completely replaced by COBALT. When we need to spawn an entity, we generate the exact same packets that Minecraft would send, but we do it from our own thread pool without any of Minecraft's overhead.

This gives us some incredible superpowers:

- **Chunk tracking**: We know exactly which chunks each player has loaded
- **Zero server overhead**: COBALT entities don't exist in Minecraft's entity tracker
- **Perfect compatibility**: Clients can't tell the difference between real and virtual entities
- **Horizontal scaling**: COBALT runs in its own thread pool, completely separate from Minecraft's tick loop

The result? We can spawn 100,000 entities and the Minecraft server thinks it's managing zero. We essentially created an invisible parallel entity system that operates alongside the main server.

### The API: Making the Complex Look Simple

Here's the beautiful part—despite all the complexity under the hood, the API for developers is dead simple. Let's compare spawning an entity the traditional way versus the COBALT way:

**Traditional Bukkit API:**
```java
ArmorStand armorStand = (ArmorStand) loc.getWorld().spawn(loc, ArmorStand.class);
```

**COBALT API:**
```java
ArmorStand armorStand = new VirtualArmorStand(location, entityHandle);
```

Both have the exact same client-side behavior, but one runs in Minecraft's entity system while the other runs in our parallel universe. The beauty is that other developers on our team don't need to learn a completely new API—it follows the same patterns they already know.

## The Animation Revolution: From Real-Time to Pre-Baked

The old system calculated every single frame of animation in real-time. This meant constantly computing positions, rotations, and interactions for every vehicle on every ride, 20 times per second.

COBALT takes a fundamentally different approach. Instead of calculating positions on the fly, we pre-bake everything. Every animation becomes a data file that specifies exactly where each entity should be at every moment in time, what effects should trigger when, and how smooth transitions should happen.

This approach eliminates virtually all runtime calculation. When a ride starts, COBALT reads from the animation file and sends the appropriate packets. No physics calculations, no pathfinding, no real-time decision making—just efficient data playback.

## The Architecture: Building Virtual Reality Inside Minecraft

COBALT's architecture is built around layers of abstraction that provide flexibility while maintaining performance.

At the core, every entity is a `VirtualEntity` that carries its own `EntityNetworkManager`. This network manager acts as a translator between our high-level APIs and the low-level Minecraft protocol, handling all the messy details of packet generation and client communication.

But here's where it gets interesting: we built different types of virtual entities for different use cases:

**Vehicle Entities**: The stars of the show, these handle all the ride logic. They can have custom behavior like the spinning teacups in *Roger Rabbit's Car Toon Spin* or the banking on *Big Thunder Mountain*.

**Animatronic Entities**: Static display entities that don't need player interaction but can have complex animations and effects.

**Show Elements**: Special entities with custom rendering rules, optimized render distances, and performance tweaks.

Each vehicle can contain multiple virtual entities—seats, model parts, particle effects, you name it. The front car of Big Thunder Mountain, for example, has separate entities for the locomotive model, the smoke particles, and each individual seat.

![Roger Rabbit's vehicle with custom onSteer handler for spinning](/blog/articles/cobalt/roger-rabbit-vehicle.png)

*Roger Rabbit's vehicle with custom onSteer handler for spinning*

![Class hierarchy of a Chicken](/blog/articles/cobalt/chicken-hierarchy.png)

*Class hierarchy of a Chicken - showing the layered abstraction approach*

![Big Thunder Mountain vehicle](/blog/articles/cobalt/big-thunder-vehicle.png)

*Big Thunder Mountain vehicle structure*

![Vehicle handler for the front train from Big Thunder Mountain with smoke particles](/blog/articles/cobalt/big-thunder-smoke.png)

*Vehicle handler for the front train from Big Thunder Mountain with smoke particles*

![Screenshot of COBALT entity tracker visualization showing chunks and entity counts](/blog/articles/cobalt/radar.png)

*COBALT's in-game entity tracker, showing chunks around a player and the number of tracked entities in each chunk.*

## The Blender Connection: When Art Meets Code

Creating animations for COBALT isn't just about writing code—it's about giving our creative team the tools they deserve. We integrated directly with [Blender](https://www.blender.org/), the industry-standard 3D animation software that Disney and Pixar use for their movies.

Our Imagineers can now design rides with the same tools used to create *Toy Story* and *The Incredibles*. They get proper 3D viewport, professional animation tools, and all the creative freedom they could want.

But here's the problem we ran into: we already had dozens of existing rides that were built with the old TrainCarts system. Converting each one manually would have taken months and probably driven our creative team to quit.

So naturally, we built *another* pipeline that could automatically convert TrainCarts rides into COBALT animations. This conversion process:

- Loads existing TrainCarts path nodes
- Discovers event triggers from sign placement  
- Converts TrainCarts animations into our format
- Applies post-processing and optimization

Converting a ride from TrainCarts to COBALT now takes about 10 minutes instead of 10 weeks. This automated conversion process was crucial for migrating our existing content.

Here's a converted render of the Big Thunder Mountain dataset (note that it isn't running in real-time for debugging purposes):

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/t0EuaVgH-Ck?si=IdIcPni5i8EPTTjk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Performance: The Numbers Don't Lie

After months of development and testing, we finally had our answer to the 80% problem. The results were so dramatic that we initially thought our profilers were broken.

COBALT manages 500+ entities per server while consuming processing time measured in **microseconds**. The old system was consuming 80% of server resources; COBALT uses less than 1%.

That's not a typo. We achieved roughly **200x performance improvement** over the original TrainCarts system.

![Screenshot of production performance metrics showing microsecond-level processing times](/blog/articles/cobalt/grafana.png)

*Production metrics from July 8th, 2022, showing COBALT handling 500 entities with tick times in microseconds.*

But the performance gains go beyond just raw numbers. Because COBALT entities don't exist in Minecraft's entity tracker, they don't interfere with other plugins, don't cause chunk loading issues, and don't contribute to entity cramming or other Minecraft limitations.

We went from a system that was severely limiting our server capacity to one that barely registers on performance monitors. The improvement opened up possibilities we hadn't even considered before.

## Future-Proofing: Building Tomorrow's Foundation

COBALT wasn't just built to solve today's problems—it was designed to enable features we couldn't even dream of with the old system. The modular architecture means we can easily add new entity types, behaviors, and optimizations without rebuilding from scratch.

We're already experimenting with:

- **Dynamic render distances** based on player movement and attention
- **Predictive entity loading** for smoother experiences  
- **Cross-server entity synchronization** for massive events
- **Real-time animation editing** for rapid iteration

The best part? None of these features require changes to the core engine. COBALT's plugin-style architecture means new capabilities can be added as modules without touching the foundation.

## The Human Impact: When Tech Meets Magic

All this technical wizardry might sound abstract, but it has very real impacts on player experience. Before COBALT, we had to carefully manage how many rides could run simultaneously. Large events required disabling attractions to keep the server stable.

Now? We can run every single ride at full capacity while handling hundreds of players across multiple experiences simultaneously. The difference is night and day.

Players notice the difference immediately. Rides run smoothly, shows stay synchronized, and the overall experience feels much more polished. Good technology should be invisible to the end user, and COBALT achieves that goal.

## Battle-Testing: When Theory Meets Reality

COBALT has been running in production at ImagineFun since mid-2022, handling millions of ride cycles and thousands of player hours. We've stress-tested it with events that would have caused problems with the old system, and it continues to perform reliably.

One of the most satisfying moments was running a server-wide event with every attraction operating simultaneously while maintaining excellent performance. It demonstrated how far we'd come from the original 80% overhead problem.

## The Ripple Effect: Beyond Just Rides

COBALT started as a ride system, but it's evolved into something much bigger. The entity management capabilities are now used throughout ImagineFun for:

- **Animatronics** in restaurants and shops
- **Dynamic show elements** for parades and events  
- **Interactive displays** that respond to player actions
- **Custom vehicles** for transportation around the park

What began as a solution to one specific problem became the foundation for an entirely new level of creative possibilities.

## Behind the Scenes: Development Screenshots

![Development screenshot 1](/blog/articles/cobalt/render-1.png)

![Development screenshot 2](/blog/articles/cobalt/render-2.png)

![Development screenshot 3](/blog/articles/cobalt/render-3.png)

## FAQ: The Technical Deep Dive

**Q: How does COBALT handle edge cases like player disconnections or chunk unloading?**

A: COBALT maintains its own chunk tracking system and gracefully handles all the edge cases that Minecraft's entity system struggles with. When a player disconnects, COBALT immediately stops sending packets to that client. When chunks unload, COBALT pauses entity updates for that region until players return.

**Q: Can other servers use COBALT?**

A: COBALT was built specifically for ImagineFun's needs and is tightly integrated with our infrastructure. While the concepts could be applied elsewhere, the implementation is custom-tailored to our specific use case and requirements.

**Q: How do you debug entities that don't exist in Minecraft?**

A: We built extensive debugging tools including real-time entity visualizers, performance profilers, and logging systems that track every aspect of COBALT's operation. It's actually easier to debug than traditional Minecraft entities because we have complete control over the data flow.

**Q: What's next for COBALT?**

A: We're continuously evolving the system based on our growing ambitions. Future plans include enhanced cross-server synchronization and even more sophisticated animation capabilities. The modular architecture means we can keep pushing boundaries without rebuilding the foundation.


Mats' Digital Journal

Featured Story

Hacking the housing market

Recent Posts

Dutch Rail Data Heist: Real-Time Metrics, APIs, and Commuter Chaos

Saying goodbye to Java rebuilds, hello to JavaScript (but still in the JVM)

The €12 Privacy Rebellion: How I Reverse Engineered a Smart Ring and Built My Own App

Meteor: Interfaces as networking contract

Block art with Art-Net

Bodging in Java - crimes against the runtime

Abusing virtual modules for a blog

COBALT: Building a 200x Faster Entity Engine from Minecraft Protocol

About

Featured Work

Pixelib

OpenAudioMc

ImagineFun

Connect