oz.Box2D is a plug-in bundle for the graphic development environment Quartz Composer.

It is based on the 2D physics library Box2D and configure some of its functions to be usable through node-based programming.

It makes complex shapes easy to include in physics simulation and contains helper patches to provide the user with some custom functions not basically included in Box2D.


Box2D associate once shapes with a body. When changing width, height, radius, input line or triangle structure at runtime, the plug-in destroys and creates again a body in the same time-step, reassign position, rotation and velocities to the newly created body, and creates the illusion that this is the same body. But it can be terrible for performance with a lot of bodies ! If the user really have to change a lot of shapes at runtime he might want to use simple bodies and texture them.


Version 1.02: minor update

  • Corrected a bug with Emitter that wasn’t reset while resetting the World.
  • Slider example is enhanced.

Version 1.01: minor update

  • Corrected a bug with Emitter emitting objects with lifetime: it now works well.
  • Added an example with a slider (that use oz.Geometry, 1024_Structure_Tools, and Private QC Patches, please install it before opening the composition)

Version 1.0

  • Based on Box2D 2.3.1: the user might want to check his knowledge of the Box2D principles before posting issues.
  • 32 / 64 bits, 10.7+
  • To be installed in Quartz Composer Plug-Ins folder.
  • Use poly2tri for triangulation through custom library OZGeom (also used in oz.Strings and oz.Geometry plug-ins, please make sure these plug-ins are updated too if you use them)
  • Is made to output values to be rendered with Kineme GL Tools (or other GL based rendering plug-ins).
  • Contains 11 patches:
    • World (processor): it’s the central patch of the bundle. The setting pane let the user choose the number of « Object » inputs. Outputs bodies data and bodies count.
    • Simple Body: let the user choose if he wants to create a Box or a Circle, with according parameters. Outputs a body Object.
    • Body With Line Structure: takes a 2D or 3D line structure in input(only the 2D points will be considered) and triangulate it (if filled body) to get displayable triangles (with U, V coordinates). Outputs a body Object.
    • Body With Triangles Structure: takes a 2D or 3D triangles structure in input (only the 2D points will be considered). Triangles may be organized like in the Kineme GL Triangle Structure patch: a 3D (X, Y, Z) vertices structure defining triangles. Outputs a body Object.
    • Model Emitter: takes a body Object in input and allow the user to emit (on trigger or continuously) multiple instances of this body. If the body model changes only the newly emitted bodies are concerned by the change. Manages lifetime of individual bodies. Outputs a body group Object.
    • Hit Test: takes 2 Objects in input (body or body group). Outputs a boolean, contact coordinates (2D structure that can be plugged in Kineme GL Point Structure) and contact normals (3D structure of lines).
    • Break Body: takes a body (not body group, only filled bodies) Object in input and breaks it on trigger. To be inserted between the body Object and the World patch.
    • Destroy Body: takes a body or body group Object in input and destroy it on trigger. To be inserted between the body Object and the World patch.
    • Body Info: takes a body (not a body group) Object in input. Outputs body ID, (X, Y) positions, Z rotation, body’s size (if relevant), body’s vertices and triangles (if relevant) and contact points.
    • Group Info: takes a body group (not a body) Object in input. Outputs body ID, (X, Y) positions, Z rotation, body’s size (if relevant), body’s vertices and triangles (if relevant) and contact points as a structure for each body of the group.
    • Mouse Joint: takes (X, Y) coordinates and boolean in input and allows the user to catch and drag bodies . Outputs a mouse joint Object to be plugged directly in the World patch.
  • Support self-intersecting polygons (see oz.Geometry plug-in for triangulation with holes, and oz.Strings plug-in to get triangles from strings)
  • Includes examples via the patches descriptions
  • Is released as DonationWare
  • Is licensed under Creative Commons Share Alike Attribution 4.0 (Commercial).
  • Concepts:
    • Object: Quartz Composer does not allow to create custom input or output ports, so the plug-in uses structures to get and set the bodies, joints, etc., to be shared between patches. An object can be a body, a body group (like in emitter) or a joint for the moment and is pluggable to the World patch directly or via another patch. The user is responsible to check what kind of object goes where.
    • Line Structure and Triangle Structure: ozBox2D outputs positions data in a Kineme GL-like way so the bodies’ data can be rendered with these patches.
  • Known issues:
    • Box2D ‘degenerate polygons': generated triangles may sometimes be too thin. The plug-ins tries hard to get them Box2D-able but in some particular (and rare) cases Box2D may crash with this issue.
    • Emitter / broken bodies performance: due to the way the plug-in has to cache bodies for re-use and generate values for rendering, body groups Objects may be slow (in particular with circles: only one circle is 96 triangles vertices for filling and 33 vertices for stroke). User might want to adjust FPS and PTM in the World patch to keep a fluid animation over a certain number of bodies emitted, or to use plug-ins specifically made to emit bodies (like the 1024 one).
    • Changing too fast (at each frame for example) the Emitter model body’s parameters may result in some (rare) cases in some issues with the bodies creation in the World (ie. bodies not considered by the plug-in then not rendered, but living in the Box2D world). Corrected in 1.01
    • Does not support creating bodies in iterators due to the current bodies IDs management based on each body’s memory address (that remain the same in an iterator).
    • Some triangles output by oz.Strings Triangulate Character Structure patch or oz.Geometry Constrained Delaunay With Holes may not keep the exact position and U,V coordinates after breaking.
    • World doesn’t destroy bodies in the Box2D world if we unplug an Emitter object.
    • CRASH when mouse joint is released after the caught body is destroyed.
  • Todo list:
    • Huge ! But…
    • Debug what has to be debugged
    • Provide better examples (these are so ugly)
    • Joints creation and management
    • Forces creation and management
    • Raycasting
    • Iterators support
    • More callbacks to get instantaneous and user-selected world data
    • Helper patches for bodies creation: drawing, structure of bodies, jointed bodies, etc.
    • Helper patches to allow more conditions
    • Helper patches to get more data from bodies
    • Bridging with my OpenCV plug-in (new version currently in dev)




I would be very grateful for any feedback.

Licence Creative Commons

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Vous pouvez utiliser ces balises et attributs HTML : <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>