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;constspider=newEntity({ controller:newSimpleEntityController(), 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 instanceofPlayerEntity) { aggroPlayer = other; } }, }, ] }});// Some chasing logic from our sensor collider that detects an aggro radius// Now, when our player goes within thspider.onTick= () => {if (aggroPlayer) {// Chase the player (spider.controller asSimpleEntityController).move(aggroPlayer.position,5); (spider.controller asSimpleEntityController).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;constspider=newEntity({ controller:newSimpleEntityController(), 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 colliderspider.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 instanceofPlayerEntity) { aggroPlayer = other; } },});// Some chasing logic from our sensor collider that detects an aggro radius// Now, when our player goes within thspider.onTick= () => {if (aggroPlayer) {// Chase the player (spider.controller asSimpleEntityController).move(aggroPlayer.position,5); (spider.controller asSimpleEntityController).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!
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.