Box2D: 15,000 lines of code, 7 platforms, 2 weeks? No problem.

Read below to find out how a Particle engineer ported over 15,000 lines of code into the platform to get the Box2D engine working on every phone in just a few weeks.

With the popularity of physics-based games such as Angry Birds and Bubble Ball, we wanted to offer our developers a way to quickly and easily create this type of content across all platforms. We searched for the right engine and settled on an open-source solution, the Box2D engine.

When Particle engineer Leon Willis got drafted to port a physics engine to the Particle Platform, he had just two problems: First, he’d never worked on a physics engine. Second, Leon, who normally works on the internals of Particle’s translator, had never written a Particle application. He also had less than a month to complete the project. Make that three problems.

“My first step was to learn the concepts behind Box2D, and learn how to create worlds, create objects, and set properties.”

Luckily, our chosen physics engine already has a solid Java port, JBox2D. But in order to translate to four different languages on eight different platforms, Particle imposes certain restrictions on the input language. The code made use of J2SE classes that aren’t available to Particle applications. Leon’s challenge: ensure that more than 15,000 lines of Java code met Particle’s requirements.

First, Leon developed a couple of simple test applications that could be used to verify each step of the porting process. Then he imported the test application and JBox2D code into the Particle IDE.

“I needed to learn the paradigm of organizing code and resources in the Particle Platform. Once you get used to it, it’s really just good programming practices. You use the MVC pattern, store resources in separate resource folders, and design UIs in a WYSIWYG GUI Editor.”

“The Particle IDE really helped track down all of the issues in the code. It provides direct and helpful information on fixing errors. The translator figures out errors and suggests fixes, and the IDE displays them in the Eclipse problems view. The same way Java developers are familiar with seeing Java errors in Eclipse.”

“Most of the changes were simple fixes, like replacing calls to System.out.println with calls to the Particle Logger class. I discovered, though, that meeting the method overloading restrictions would be more work.”

Currently, the Particle translator can’t translate arbitrary method overloads. For example, the JBox2D AABB (axis-aligned bounding box) class has three constructors:

public AABB(Vec2 minVertex, Vec2 maxVertex) {
    // clone to be safe
    this.lowerBound = minVertex.clone();
    this.upperBound = maxVertex.clone();
}

public AABB(AABB copy) {
    // relies on cloning in AABB(Vec2, Vec2) constructor
    this(copy.lowerBound, copy.upperBound);
}

public AABB() {
    lowerBound = new Vec2();
    upperBound = new Vec2();
}

Since the second constructor is basically a shortcut to the first constructor, it was removed and code that called it:
AABB newInstance = new AABB(oldInstance);

Was replaced with:
AABB newInstance = new AABB(oldInstance.lowerBound, oldInstance.upperBound);

The first and third constructors were collapsed to:

public AABB(Vec2 minVertex, Vec2 maxVertex) {
    // clone to be safe
    lowerBound = (minVertex == null ? new Vec2() : minVertex.clone());
    upperBound = (maxVertex == null ? new Vec2() : maxVertex.clone());
}

After two weeks, Leon had his physics test application as a native Particle Java application. Then he started building and testing it on all of the target platforms.

“At the time, my estimation was that I needed 2 more weeks from that point to finish deploying the engine to all platforms. However, amazingly, it was pretty smooth after I adapted the code to our supported Java language features. Then porting it to specific platforms became easier and easier. In the end it took less than a week to deploy the entire engine to all target platforms, which was quite incredible.”

The Particle translator adds garbage collection code when translating to C++, so Leon was able to build for C-based platforms like iOS without worrying about allocating and freeing memory. This is especially useful when building more complex applications like games and rich media that tend to suffer from performance lags when not ported efficiently.

Porting such a large amount of code into Particle helped us improve the platform tremendously, such as by streamlining the way we report translation errors and other issues. And the snazzy Box2D engine is now available to Particle developers to make compelling, physics-driven content on every smartphone and tablet from one codebase. Pretty neat. Check out the samples page to see the engine in action.

Avatars by Sterling Adventures