2D Tuesdays: Box2D Developer Updates

Kickoff

Greetings everyone. It's 2D Tuesday! Each week someone on the 2D team will post a blog or resource related to Torque 2D and/or iTorque 2D. The majority of the posts will come from myself, but don't be shocked if someone else takes over for me from time to time.

Last week, I continued the discussion of Box2D integration in an R&D branch of our repository. Theory turned into reality when actual code and a video were posted. This week, I'm going to wrap up Box2D and move onto other topics. First, here's the "let's cover our bacon section":

FULL DISLOSURE

Do not take the content from these blogs as law. I'm never going to say "this will be in x.x version" or "this is ready to be used right now". There's going to be a lot of R&D discussion. I might even post a discussion I had with Melv that ended up being scrapped. It might be useful for you to understand how we communicate internally, or amusing to see the mad scientists we really are. I will not post timelines. I will not post release dates. I will not commit the team to something we cannot deliver on.

Will ____ work?

There is one guaranteed question type multiple people will ask when you talk about changing major systems. It almost always relates to an existing project or a project planned in the near future. That question is "Will ____ still work?" The blank part is usually a feature, function call, or something a user has written. With the discussion of Box2D, the most common targets are moveTo, rotateTo, and coordinate conversions. As I said in my past blogs, I come prepared with a backlog of e-mails, chats, and SVN commit messages. Why spend time thinking of scenarios when I can just copy/paste something like this:

Quote:Everyone,

I have added both a new "MoveTo" and "RotateTo" to the t2dSceneObject. These new methods have different arguments than the previous ones and are far less invasive. The previous ones caused interpenetration issues and essentially went against the physics/collision system. The new ones work with it so let me explain how they work.

moveTo

%sceneObject.MoveTo( worldPoint, [time = 1000], [autoStop = true] )

Quote:
All "moveTo" really does is calculate the required linear velocity from the current position to the specified "worldPoint". It does this by calculating the relative distance and dividing it by the specified time (which is specified in milliseconds and defaults to 1000 i.e. 1 second). It then immediately sets the linear velocity. The third and final (optional by defaults to true) parameter is "autoStop" which will, if set to true, reset the linear velocity to zero after the specified period of time. It will not reset any angular velocity, only linear.

As is described in the method documentation, there are a number of things that can stop the object reaching its target. The first is if the object as linear damping active. The second is if the object collides. I didn't want the "moveTo" touching anything other than the linear velocity so it is entirely up to you to ensure the object is able to reach the destination.

When the time has elapsed, the method will perform a callback to the scripts as so:

function t2dSceneObject::onMoveToComplete( %obj, %targetPosition )
{
   echo( "Object" SPC %obj SPC "moved to" SPC %targetPosition );
}

Quote:As you can see, the function returns the object that has completed the move-to as well as the target position you originally specified. You are therefore free to ensure the object really did reach the specified target by using something like:

%obj.setPosition( %targetPosition );

... within the callback.

rotateTo

%sceneObject.rotateTo( angle, [time = 1000], [autoStop = true]) )

Quote:
All "rotateTo" really does is calculate the required angular velocity from the current angle to the specified "angle". It does thi by calculating the relative, smallest arc to reach the target angle, dividing it by the specified time (again in milliseconds and defaults to 1000). It then immediately sets the angular velocity. The third and final parameter is identical to the one used in the "moveTo" call expect this time, if set to true, it resets the angular velocity to zero after the specified period of time. It will not reset any linear velocity, only angular.

As is described in the method documentation, there are a number of things that can stop the object reaching its target angle. The first is if the object as angular damping active. The second is if the object collides. I didn't want the "rotateTo" touching anything other than the angular velocity so it is entirely up to you to ensure the object is able to reach the destination.

When the time has elapsed, the method will perform a callback to the scripts as so:

function t2dSceneObject::onRotateToComplete( %obj, %targetAngle )
{
   echo( "Object" SPC %obj SPC "rotated to" SPC %targetAngle );
}

Quote:
As you can see, the function returns the object that has completed the rotate-to as well as the target angle you original specified. You are therefore free to ensure the object really did reach the specified target by using something like:

%obj.setAngle( %targetAngle );

... within the callback.

Quote:As a quick note: if you issue another move-to or rotate-to while a previous one is running, the previous one will immediately stop and will not result in a callback or stop the velocity however your new call will set the velocity and result in a callback. If you need to know whether a previous "moveTo" or "rotateTo" has completed on a scene object then you can use:

echo( %obj.isMoveToComplete() );
echo( %obj.isRotateToComplete() );

Quote:The above set-up requires the minimum of processing as it only requires modifying an initial velocity and performing a single schedule over the specified time at which point it takes the final action (auto-stop) and then performs a callback. For situations where these methods are used, it is unlikely that the objects being moved/rotated have either damping or collision activated however if they do then you need to understand the implications.

Hopefully, this will provide everything everyone needs.

Coordinate System Changes
As I mentioned in last week's blog, integrating Box2D resulted in sweeping changes throughout the engine. One of the bigger changes is severing the connection between the scene and screen resolution. Previously, if your object was 64x64, that was a measurement of both world units and pixels. They were tied together, which is an old way of doing 2D. It works, but there are better alternatives.

Now, the term better is subjective. I talked about this with Conor O'Kane pretty early this morning in IRC. He expressed dismay over the change to the coordinate system. Make no mistake, we wouldn't apply these changes without going through the pains ourselves. Eat your own dog food, right? In the very same e-mail that contained the information on moveTo and rotateTo, the team started to report major issues with an existing game we were working on. We were porting an older T2D project, which still contained values related to pixels. Here is that discussion log (please forgive any typos, we weren't writing an English paper):

BEGIN TRANSCRIPT

Richard Ranft: Indeed, thanks! The script versions were ... inadequate.


Doug Poston: So it looks like we're still having issues. Is there some sort of limiter on velocity? Can you think of any reason why we can't travel 1km in 1.2 seconds
(other than Nevada speed limits)?


Melv May: I'd be surprised if there's a limit using linear velocity even if you're pushing the limits on the forces involved. I'll check out the speeds you're referring to.


Doug Poston: I'd be surprised too, but it looks an awful lot like that's the case. Since we're using 1 pixel = 1 meter (which is crazy), we're moving 105m tall cards almost 1km in distance in 1.2 seconds (breaking all natural laws of physics).


Kyle Miller: Below are the relevant areas in the documentation:

Box2D FAQ - "How do I convert pixels to meters?" in the API section
Box2D Manual - Section 1.7 "Units"


Doug Poston: The problem does appear to go away when you reduce the playing field by two orders of magnitude (e.g. divide everything by 100).


Michael Perry: So we have isolated the problem. The next step is to try and decouple the resolution and pixels from the world units. We have this hierarchy:

GuiCanvas - Set to window resolution 1024x768
-> t2dSceneWindow - Set to window resolution 1024x768, also contains the camera which uses the window resolution values
-> t2dSceneGraph - Set to window resolution 1024x768, contains all the scene objects which are too large right now

To me, it makes sense that we keep GuiCanvas at 1024x768. This is a sub-view that needs to fit the window. t2dSceneWindow is also a GuiControl, so I think it makes sense for that to be

1024x768. However, the internal camera should start working with Box2D world units. t2dSceneGraph is a SimSet that contains a property called cameraSize, which is pulled by t2dSceneWindow.

It does not actually get used for anything in t2dSceneGraph.

So my opinion is we break the pixel/world unit coupling in t2dSceneWindow's camera. We obviously need the camera to zoom in dramatically, kind of like what Doug just mentioned in his reply.

I might be muddling things up because of how hectic things are for me right now.

@Melv - Am I making sense? Anything you can add?


Melv May: Maybe I need to read this when I'm more awake but the system is decoupled from pixels which is what I did in my testbed and the truck demo.

You create your scene using world units and set your camera area to scale it. If you are running different resolutions it makes no difference apart from when the aspect ration changes. In the end, the camera renders to the target resolution but all code within it is unaware of that.


Kyle Miller: Unless I'm misinterpreting it, Box2D FAQ - "How do I convert pixels to meters?" in the API section seems to suggest a different approach - that we set a scaling standard and convert at the engine/physics level? This is perhaps something we should consider. What's best for usability? Is it better for a user to have a direct correlation between the art they're creating in Photoshop and that in the tools? We need to carefully consider our approach here as this is a major decision that will greatly affect current and all future templates.


Melv May: This is not a physics issue, it's an issue that affects all game engines so there are no changes required from the physics standpoint. Let's not bring box2d into it. :) You

simply cannot create a single resolution art the works 1:1 on different resolution devices without showing different scene areas i.e. scaling. This is the same situation you had prior to the box2d work.

If you want the art to be 1:1 with pixels on the screen then you've got a hard task. By far the easiest way is to have the artwork created for the highest res and it be scaled down during texturing on lower resolutions which is what happens now. If that doesn't suit then you need the system to choose alternate artwork for different ranges of resolutions. Again, nothing to do with box2d.


Kyle Miller: Sorry for the confusion, Melv - I don't think I was very clear in my email. I did not intend to imply there was an issue with Box2D. I think we're on different pages a bit here, and there are additional factors Mich and I have gone over at this point, so let's just continue this in our discussion tomorrow. Thanks for taking the time to respond!


Melv May: Let me illustrate....Truck demo creates objects at reasonable sizes suited for the physics system. I chose an area of the camera to show around 100 x 75 meters wide (4:3).

This is resolution independence. Now, at 1024 x 768 (4:3) you can see there's a fixed scaling i.e. 1 pixel = (100/1024) meters in X and (75/768) in Y. If you change the resolution then you change the pixel:meter ratio and there's little you can do about it.

You can either live with the fact that the art is scaled or you can select alternate art for that resolution or a range of resolutions. Nothing to do with box2d. In you previous code, you used 1:1 of world units to pixels however that breaks down if the resolution changes. So I ask, what has changed? The need to have multi-resolution artwork?

(To Kyle)Hey, no problem. I'm simply confused on what has changed here. Te same problem existedin the previous codebase.

END TRANSCRIPT

I admit, it's a fairly dry discussion with the exception of Doug's Nevada reference and some smileys. As you can see, miscommunication can happen and sometimes a single thread can't close the loop. We ended up having a lengthy Skype call to hash out the details and debate the merits of retaining the pixel sizing of objects vs more realistic world units.

In the end, using standard world units won. For anyone who might be concerned that their project might be getting gimped, even if they do not create a physics-driven game, do not be alarmed. We have ported two games that do not need a full physics simulator. One is a card game, the other uses A* pathing. That requires full control over placement and motion. The games turned out just fine. Then, there are the games that will make clever use of physics:

Next Time

That's it for this week folks. I'm sure you have plenty of questions related to Box2D and I could probably keep posting for another month on the topic, but I'm going to end it in this post. Feel free to ask more questions here, because next week I'm leaving the realm of physics and talking about other exciting R&D that has been going on. I've seen a lot of naysayers who demote the usefulness of behaviors, so I'm also going to try to convert a few of you. Behaviors rock! Next week I'm going to prove it to you.