Introducing boxbox

Bocoup loves HTML5 games, so Darius Kazemi and I have been running a training called Intro to HTML5 Game Development. We cover lots of fun stuff, including canvas animation and audio. When designing the training, we wanted trainees to make a simple game using a JavaScript physics engine. Box2dWeb came up as a good one to use, but I had a few concerns about it.

Box2dWeb is a port of Box2DFlash to JavaScript. Box2dFlash is a port of Box2D, a C++ rigid body physics simulation. You have probably played at least one game that uses Box2D, such as Angry Birds. The C++ code style persists in these ports, and what you get is distinctly non-JavaScripty code like this: (comments by me)

In a training where we have non-programmers and programmers who are new to JavaScript, this isn’t what I want people to learn from.

Don’t get me wrong: I love Box2D, Box2DFlash, and Box2dWeb. I wouldn’t use them if I didn’t. These are issues that naturally arise in semi-automated cross-language ports. Since I wanted to use Box2dWeb but with sugar, I made boxbox.

boxbox is a library that you use along with Box2dWeb. It wraps Box2dWeb and provides a simpler API and some handy new features. It is great for learning, prototyping, and simple games.

In this article, I am going to step through the process of creating a simple boxbox game. If you want to follow along, start out with the boilerplate here:

download boilerplate

This project already includes boxbox and Box2dWeb as well as a simple stylesheet. If you load up index.html in a browser you’ll see a blank slate.

Getting Started

Edit game.js. The first thing we’re going to do is create a “world”, which is a stand-alone physics simulation. It takes a canvas element as a parameter, since boxbox provides canvas rendering.

Create the Player

The world is pretty boring without anything in it, so lets create our first entity. All entity options have defaults in boxbox, so if you create an entity without any options, you’ll get the most basic entity possible: a gray square in the middle of the screen.

The world has gravity by default, so when you run the game, the square will just fall off the screen.

Try it!

Create the Ground

Let’s create an entity for the ground. This time we’ll provide some options to get the sort of entity we want.

This is still quite basic. We’re telling boxbox’s rendering layer to show this entity in green. We’re giving it a starting position and a width and height. Setting the type to static makes this entity immobile, so it will not be affected by gravity or collisions.

Now when you run the game, the box falls and lands on the ground.

Try it!

Keyboard Input

Let’s add keyboard input. To keep it simple, we’ll make it so that any key moves the player.

If you’re used to making websites, this should look familiar. this is set to the boxbox entity that the event was attached to. applyImpulse is a method that applies an instantaneous force on an entity. boxbox also supports continuous force with applyForce, but for now we’ll apply a swift kick to the entity each time a key is pressed. The first parameter to applyImpulse is the magnitude of the force (higher is stronger) and the second parameter is the direction of the force (in degrees). 45 degrees is to the upper right.

Create Targets

That works, but what fun is a physics engine without collisions? Let’s make a stack of targets to knock over. Here I demonstrate a boxbox feature that lets you share configuration among similar entities.

Now you can see the beginnings of what this physics engine can do. You can also imagine what sort of game you can make from it ;)

Try it!

What’s Next

Want to take it to the next level? Try adding images instead of solid colors (boxbox takes care of rotating / scaling images), more keyboard control over the player, or tweak the density and friction of each entity to get different dynamics. If you want to report any bugs or make any changes, boxbox is MIT licensed and on Github. Happy coding!

This entry was posted by Greg Smith (@_gsmith) on May 11, 2012 in Canvas, HTML5, JavaScript and Games.

Tweet