Colliders & Hitbox

All entities by default will automatically calculate their own best-sized collider for their initial hitbox that represents them in the world.

For block entities, this collider is calculated on the provided blockHalfExtents.

For model entities, this collider is calculated by an internal approximation based on the .gltf or .glb file of the entity and its modelScale .

Overriding Default Colliders & Aggro Sensor Example

You can override the default colliders for any entity by providing your own collider options to the rigidBodyOptions of the entity when creating an instance of it. You'll set the colliders property with an array of ColliderOptions objects.

Let's use custom colliders to do something a little more interesting, how about we add an aggro sensor to our spider?

let aggroPlayer: PlayerEntity | undefined;

const spider = new Entity({
  controller: new SimpleEntityController(),
  modelUri: 'models/spider.gltf',
  modelScale: 10,
  modelLoopedAnimations: [ 'idle' ],
  rigidBodyOptions: {
    colliders: [ // If we provide colliders, the default collider will not be created.
      Collider.optionsFromModelUri('models/spider.gltf', 2),
      { // Create a sensor to detect players 
        shape: ColliderShape.CYLINDER,
        radius: 5,
        halfHeight: 2,
        isSensor: true, // This makes the collider not collide with other entities/objects, just sense their intersection
        tag: 'aggro-sensor',
        onCollision: (other: BlockType | Entity, started: boolean) => {
          if (started && other instanceof PlayerEntity) {
            aggroPlayer = other;
          }
        },
      },
    ]
  }
});

// Some chasing logic from our sensor collider that detects an aggro radius
// Now, when our player goes within th
spider.onTick = () => {
  if (aggroPlayer) {
    // Chase the player
    (spider.controller as SimpleEntityController).move(aggroPlayer.position, 5);
    (spider.controller as SimpleEntityController).face(aggroPlayer.position, 3);
  }
};

spider.spawn(world, { x: 0, y: 5, z: 0 });

There's multiple ways to do this as well, one way may be better depending on your logical patterns, but performance is the same internally.

Sometimes it's simpler to create your custom colliders when creating the instance of your entity. Other times, it might be easier to create some additional custom colliders at some point after creating the instance of your entity but before spawning it.

One example where this would be useful is when a Entity Controller needs to attach custom colliders to the entity that becomes attached to it. You can see this is use in the Player Entity Controller guide.

We can accomplish the with our custom sensor collider in the following way as well.

let aggroPlayer: PlayerEntity | undefined;

const spider = new Entity({
  controller: new SimpleEntityController(),
  modelUri: 'models/spider.gltf',
  modelScale: 10,
  modelLoopedAnimations: [ 'idle' ],
});

// Create a default approximated collider for the hitbox from the model
// This is the same way the default collider is created internally for an entity
// if no other colliders are specified.
spider.createAndAddChildCollider(Collider.optionsFromModelUri('models/spider.gltf', 2));

// Add our sensor collider
spider.createAndAddChildCollider({
  shape: ColliderShape.CYLINDER,
  radius: 5,
  halfHeight: 2,
  isSensor: true, // This makes the collider not collide with other entities/objects, just sense their intersection
  tag: 'aggro-sensor',
  onCollision: (other: BlockType | Entity, started: boolean) => {
    if (started && other instanceof PlayerEntity) {
      aggroPlayer = other;
    }
  },
});

// Some chasing logic from our sensor collider that detects an aggro radius
// Now, when our player goes within th
spider.onTick = () => {
  if (aggroPlayer) {
    // Chase the player
    (spider.controller as SimpleEntityController).move(aggroPlayer.position, 5);
    (spider.controller as SimpleEntityController).face(aggroPlayer.position, 3);
  }
};

spider.spawn(world, { x: 0, y: 5, z: 0 });

Now that's fun! Our spider chases us down as we run around!

Our spider chasing us by making use of our custom colliders for an aggro sensor.

Diving Deeper

Collider control is probably one of the most powerful unlocks in the HYTOPIA SDK, enabling you to create all sorts of interactions and behaviors for your entities relative to the physical world.

If you'd like to learn more about colliders, we recommend you dive deeper into the physics guides for the SDK, specifically Colliders.