This page is part tutorial, part troubleshooting resource. It is designed to address questions and problems such as:
What are bounding boxes?
Why am I getting a bounding box error, and how do I fix it?
Help! My agent floats above the ground!

What are bounding boxes?

A bounding box is an invisible box that the game maps out when an agent is first created, so that it knows what the basic dimensions of that agent are. The CAOS documentation often refers to the bounding box as a "bounding rectangle", but it's actually a diamond shape.

Basically, the game determines where the sides, top and bottom of the agent's first sprite are, and then draws an invisible diamond to fill that space. For example, here is what the Archie's bounding box looks like:

The Archie fits snugly within its bounding box.

This is why the corners of rectangular objects may appear to "sink" into the ground if you place them on a slope: they might match the shape of the sprite, but they don't match the shape of the bounding box.

You can actually set the dimensions of the bounding box yourself using the CORE command, but this is one command you only want to use when the agent is first created. Changing the bounding box in an existing agent can cause weird errors, like the agent falling through the floor of the metaroom and disappearing into oblivion! This can be considered a kind of bounding box error, but it isn't the same kind that most coders encounter.

Why am I getting a bounding box error? How do I fix it?

Your typical bounding box error is very easy to recognize: an error window will appear that says "Bounding box error:" followed by various additional details. This happens when an agent's sprites aren't the same size as each other. Maybe most of its sprites are 50x50 pixels, but one of them just happens to be 50x51 pixels. The agent will appear to act normally (giving the appearance that all is well), but as soon as it tries to use that sprite it will display the bounding box error.

See arrows. These numbers are the dimensions for each frame. As you can see, the frame outlined in red is two pixels wider than the others.
Although too subtle to be apparent when "eyeballing" the sprites, this difference would cause a bounding box error in-game.

This can be really confusing the first time you get it, because "bounding box" doesn't really sound like something sprite-related. But once you know what a bounding box is and how it is generated, it makes sense. The game relies on the dimensions of an agent's sprites to know how to draw the bounding box. So if the dimensions ever change, that affects the bounding box.

It's hard to say what would happen if the game didn't throw the error. Would it crash altogether, or would the agent just "slip away", like what happens when you use the CORE command on an agent already in the world? Just imagine how many agents you might end up with over time, lurking in the void outside the metaroom boundaries. Maybe not doing anything sinister outright, but certainly bogging down your game after a while.

So, the moral of the story is to always make sure your agent's sprites are of a consistent size. Typically, that's all it takes to avoid bounding box errors.

Help! My agent floats above the ground!

The default bounding box created for an object is based on the dimensions of the whole sprite, not just the opaque pixels. If an agent is supposed to fall to the ground, but appears to "hang" in the air several pixels above it, chances are the bounding box doesn't match where the object is in the sprite.

To better show you what I mean, below is the sprite sheet for the kittiwake feather from the Devil's Reef metaroom. I've changed the background to red so it's easier to see, since the feather has dark barring on it.

The feather was designed to have a nice spinning animation, and in order to accomplish that, it must stay in the center of each frame. However, the seventh frame—in which the feather is completely horizontal—is also used when the feather is resting on the ground.

Here is another version of that seventh frame, with the bounding box traced around it in green. As you can see, the bottom of the bounding box is a good thirty pixels below the bottom edge of the actual feather.

Here is what the result in-game: the feather floats in mid-air. The game has positioned it "right" in the sense that the bounding box is interacting with the floor the way it is supposed to, but since the bounding box doesn't match the shape of the agent, the end result doesn't look right at all. (I've included the version with the superimposed boundary box for comparison's sake.)

What the feather looks like when resting on the ground.

Is there any way to make the bottom of the object line up with the bottom of the bounding box, without using CORE? In general, it's best just to cut off extra space and avoid using the CORE command whenever possible. But sometimes (like now) that won't work. There isn't any "extra" space in this agent's sprites for me to crop off, because the sprites are only as tall as the upright feather requires.

For example, this is how I considered making the sprites look, to get around the problem without using CORE.

The feather sinks a little more in each frame, so that by the time we get to that horizontal pose, the feather is "lying" on the bottom of the sprite. This does mean that it won't float above the ground anymore. But does the animation still look okay in-game? Not really! See what the original animation looked like (left) compared to the "fixed" one (right):

Both feathers are hovering a short distance above the ground.

Sometimes this technique works very nicely, but for this agent it just doesn't look right. So I am going to use the CORE command to change the shape of the bounding box.

Because the bounding box doesn't change from one frame to the next, changing the CORE will make the bottom half of the upright feather sink through the floor. For an agent that is animated while on the ground, that would not be ideal. But the feather's animation only plays when it is in mid-air, so in this instance nobody's going to notice.

The structure of the command is CORE [top] [bottom] [left] [right]. Remember that like all calculations that refer to position and size, CORE uses cartesian coordinates, which means it starts counting from the top and left sides (of the sprite) and counts how many pixels it takes to get to the bottin and the right side. The game uses the size of the sprite to calculate the default bounding box. So for the kittiwake feather, which has sprites 63 pixels wide by 60 pixels high, the default "ordinary" setting would be CORE 0 60 0 63.

I'm going to leave all of the "extra" space on the sides and top within the bounding box, because the engine does have some annoying quirks that can pop up if an agent is extremely short or narrow. So I'm just going to "cut off" 19 pixels from the bottom of the bounding box, so that the bottom will match where the bottom of the feather is.

In the script where the feather is first created, in the block that includes the feather's ATTR, BHVR, et cetera, I add the following line:

CORE 0 31 0 63

Now the kittiwake feather's bounding box will look like this:

Now let's take a look at how this appears in game. As you can see, the bottom of the agent is now level with the ground in the metaroom. It's just like if the extra space at the bottom of the sprite didn't even exist.

Problem solved—and we didn't have to compromise our nice spinning animation.