Fixture

These properties are used for collision filtering. That is useful if you want only some of your fixtures to collide with each other. By default, all fixtures collide with each other, so the default categories is Category1. The default collidesWith is All, and the default groupIndex is 0.

For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Therefore Box2D supports such collision filtering using categories and groups.

Box2D supports 16 collision categories. For each fixture you can specify which category it belongs to. You also specify what other categories this fixture can collide with. For example, you could specify in a game that all players don't collide with each other and enemies don't collide with each other, but players and enemies should collide. If you also have powerups in your game, the player should be able to collide with it but not the monsters. This can be done with masking bits. For example:

 Scene {
   EntityBase {
     entityType: "player"

     BoxCollider {
       categories: Box.Category1
       // collide with enemies and powerups
       collidesWith: Box.Category2 | Box.Category3
     }
   }

   EntityBase {
     entityType: "enemy"

     BoxCollider {
       categories: Box.Category2
       // collide with players
       collidesWith: Box.Category1
     }
   }

   EntityBase {
     entityType: "powerup"

     BoxCollider {
       categories: Box.Category3
       // collide with players
       collidesWith: Box.Category1
     }
   }
 }

The groupIndex can also be used to choose fixtures that collide with each other: Fixtures with the same positive group index will always collide, regardless of their categories or collidesWith settings. Fixtures with the same negative groupIndex will never collides regardless of categories or collidesWith.

Note: Only dynamic bodies collide with others. So 2 static bodies or 2 kinematic bodies can never collide with each other. When you use Joints to connect 2 fixtures, you can enable or disable collisions between these connected fixtures.

These properties are used for collision filtering. That is useful if you want only some of your fixtures to collide with each other. By default, all fixtures collide with each other, so the default categories is Category1. The default collidesWith is All, and the default groupIndex is 0.

For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Therefore Box2D supports such collision filtering using categories and groups.

Box2D supports 16 collision categories. For each fixture you can specify which category it belongs to. You also specify what other categories this fixture can collide with. For example, you could specify in a game that all players don't collide with each other and enemies don't collide with each other, but players and enemies should collide. If you also have powerups in your game, the player should be able to collide with it but not the monsters. This can be done with masking bits. For example:

 Scene {
   EntityBase {
     entityType: "player"

     BoxCollider {
       categories: Box.Category1
       // collide with enemies and powerups
       collidesWith: Box.Category2 | Box.Category3
     }
   }

   EntityBase {
     entityType: "enemy"

     BoxCollider {
       categories: Box.Category2
       // collide with players
       collidesWith: Box.Category1
     }
   }

   EntityBase {
     entityType: "powerup"

     BoxCollider {
       categories: Box.Category3
       // collide with players
       collidesWith: Box.Category1
     }
   }
 }

The groupIndex can also be used to choose fixtures that collide with each other: Fixtures with the same positive group index will always collide, regardless of their categories or collidesWith settings. Fixtures with the same negative groupIndex will never collides regardless of categories or collidesWith.

Note: Only dynamic bodies collide with others. So 2 static bodies or 2 kinematic bodies can never collide with each other. When you use Joints to connect 2 fixtures, you can enable or disable collisions between these connected fixtures.

This property holds the density in kg/pixels^2. If, for example, a Box of 100x100 pixels should have 10kg, set the density to 10kg/(100px*100px) = 1/1000 kg/px^2.

The fixture density is used to compute the mass properties of the parent body. The density can be 0 or positive. You should generally use similar densities for all your fixtures. This will improve stacking stability.

The default value is 0. The masses of all fixtures of a Body get added for dynamic bodies. If none of the fixtures of a body has a density set, the default body mass is set to 1kg.

Consider that static and kinematic bodies internally do not have a mass, so setting the density for them is useless.

If you want to make objects fall down faster, increase the PhysicsWorld::gravity property.

Friction is used to make objects slide along each other realistically. It is usually in the range [0,1]. The default value is 0.2. A friction value of 0 turns off friction and a value of 1 makes the friction strong. If any of 2 colliding shapes has 0 friction, the resulting friction is 0 as the friction values get multiplied.

These properties are used for collision filtering. That is useful if you want only some of your fixtures to collide with each other. By default, all fixtures collide with each other, so the default categories is Category1. The default collidesWith is All, and the default groupIndex is 0.

For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Therefore Box2D supports such collision filtering using categories and groups.

Box2D supports 16 collision categories. For each fixture you can specify which category it belongs to. You also specify what other categories this fixture can collide with. For example, you could specify in a game that all players don't collide with each other and enemies don't collide with each other, but players and enemies should collide. If you also have powerups in your game, the player should be able to collide with it but not the monsters. This can be done with masking bits. For example:

 Scene {
   EntityBase {
     entityType: "player"

     BoxCollider {
       categories: Box.Category1
       // collide with enemies and powerups
       collidesWith: Box.Category2 | Box.Category3
     }
   }

   EntityBase {
     entityType: "enemy"

     BoxCollider {
       categories: Box.Category2
       // collide with players
       collidesWith: Box.Category1
     }
   }

   EntityBase {
     entityType: "powerup"

     BoxCollider {
       categories: Box.Category3
       // collide with players
       collidesWith: Box.Category1
     }
   }
 }

The groupIndex can also be used to choose fixtures that collide with each other: Fixtures with the same positive group index will always collide, regardless of their categories or collidesWith settings. Fixtures with the same negative groupIndex will never collides regardless of categories or collidesWith.

Note: Only dynamic bodies collide with others. So 2 static bodies or 2 kinematic bodies can never collide with each other. When you use Joints to connect 2 fixtures, you can enable or disable collisions between these connected fixtures.

Restitution is used to make objects bounce, so to simulate elastic objects like a rubber ball. It is usually in the range [0,1]. The default value is 0. Consider dropping a ball on a table. A value of zero means the ball won't bounce. This is called an inelastic collision. A value of one means the ball's velocity will be exactly reflected. This is called a perfectly elastic collision. The resulting restitution of 2 colliding shapes will be the maximum value.

Set this property if you do not want the shape to react to collisions. This is useful if you only want to know that a collision happened, but not physically respond to it. The default value is based on the collisionTestingOnlyMode property - if it is set to true, the sensor flag also is set to true, otherwise to false.

This handler is called when 2 fixtures start to collide with each other. This is the first call before contactChanged and endContact will be called.

The contactNormal vector contains the information if the 2 objects collided on the horizontal axis (if contactNormal.x is 1 or -1) or on the vertical axis (if contactNormal.y is 1 or -1). The non-affected axis will be 0.

You can also retrieve information of the collided fixture with the other argument. To get access to the collided entity, use one of the following calls:

 BoxCollider {
     fixture.onBeginContact: {
       // for access of the collided entity and the entityType and entityId:
       var body = other.getBody();
       var collidedEntity = body.target;
       var collidedEntityType = collidedEntity.entityType;
       var collidedEntityId = collidedEntity.entityId;
     }
 }

Note: The corresponding handler is onBeginContact.

This handler is called every update cycle when 2 fixtures are colliding with each other. The update rate depends on the PhysicsWorld::updatesPerSecondForPhysics property. By default, that is 30 times per second and can be 60 times per second as well, so only perform game logic in this function if no other solution exists as it is called frequently.

Note: The corresponding handler is onContactChanged.

This handler is called when 2 fixtures stop colliding with each other. Before this handler gets called, at least onBeginContact was called.

Note: The corresponding handler is onEndContact.

Returns the Body which contains this Fixture.