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 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—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:

ArmorStand armorStand = (ArmorStand) loc.getWorld().spawn(loc, ArmorStand.class);

COBALT API:

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

Roger Rabbit's vehicle with custom onSteer handler for spinning

Class hierarchy of a Chicken

Class hierarchy of a Chicken - showing the layered abstraction approach

Big Thunder Mountain vehicle

Big Thunder Mountain vehicle structure

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

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

Screenshot of COBALT entity tracker visualization showing chunks and entity counts

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, 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):

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

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

Development screenshot 2

Development screenshot 3

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.