Skip to content

Collider

Jump to bottom
Berke edited this page Oct 2, 2026 · 1 revision

Collider

Inspector name: Collider · Lua: entity.collider · Public field type: Collider

A Collider gives an entity a physical shape. With one, the entity can stand on floors, bump into walls, climb steps and push against other entities. A collider can also be a trigger: a volume that things pass through, which tells your scripts when something enters or leaves it.

A collider only moves if its entity also has a non-static Rigidbody. Without one it is an immovable obstacle that other bodies bump into.

Shapes

Type Lua Size Status
Sphere ColliderType.Sphere Radius (scale.x) Fully working.
AABB (box) ColliderType.Box Scale (scale.x, .y, .z), the box size Not simulated yet. Box colliders don't collide with anything and don't fire trigger or collision callbacks.

Use spheres for now.

Where the sphere sits

The sphere rests on the entity's feet. Its centre is one radius above the Transform position, so an entity with position.y == 0 and a radius of 8 has a sphere touching the floor at 0 with its centre at 8.

How it works

Each frame, after scripts and the Player Controller have set velocities and the Rigidbodies have moved, physics resolves every active, non-trigger sphere on an entity with a non-static Rigidbody:

  1. Other entities. It is pushed out of every other active, non-trigger sphere nearby. If the other entity is static (no Rigidbody, or a static one), only this entity moves. If both are moving bodies, each is pushed half the overlap.
  2. Walls. It is pushed out of the solid parts of nearby walls, and its velocity into the wall is removed so it slides along instead of sticking.
  3. Floor and ceiling. It is kept between the floor and ceiling of the sector it stands in. The body's height for this is the larger of the Transform's scale.y and the sphere's diameter. If its feet end up on the floor, the Rigidbody is marked grounded.

"Nearby" means in the entity's own sector or a neighbouring one. A very large sphere can reach past its neighbours, and things beyond them aren't tested.

Step Size

Step Size lets a body walk up small ledges instead of being stopped by them. When the body walks into the solid lower part of a wall (the face of a step) whose top is no more than Step Size above its feet, it is lifted onto the step. The same limit applies going down: walking off a ledge no taller than Step Size snaps the body down onto the lower floor instead of making it fall.

0 turns stepping off. For a player, 8 to 12 feels right with the default scale. The Camera's Smooth Stepping hides the sudden height change.

Triggers

A collider with Is Trigger ticked isn't solid. Nothing is pushed out of it and it isn't pushed by anything. Instead, the engine reports overlaps each frame:

  • A trigger overlaps any other active sphere collider nearby, trigger or not, that its sphere intersects.
  • A trigger doesn't need a Rigidbody. A static trigger volume is the normal setup.
  • Its entity must stand inside a sector.

Overlaps fire OnTriggerEnter, OnTrigger and OnTriggerExit on scripts of both entities (see Callback Functions).

Collision callbacks

Whenever step 1 pushes two entities apart, both get OnCollisionEnter, OnCollision and OnCollisionExit (see Callback Functions). Walls and floors don't fire these callbacks: only entity-to-entity contacts do.

Is Active

An inactive collider is ignored completely. The entity passes through walls and other entities, floors and ceilings no longer hold it in, and triggers don't notice it. The Player Controller uses this for No Clip, and it sets the player's isActive every frame.

In the editor

Field Lua Default Notes
Is Active isActive on
Collider Type type Sphere Sphere or AABB.
Is Trigger isTrigger off See Triggers.
Radius (sphere) / Scale (AABB) scale 1, 1, 1 Sphere radius is scale.x.
Step Size stepSize 0 See Step Size.

The default radius of 1 is tiny next to the default Transform scale of 32. Give characters a radius of about 6 to 10.

Scripting

Property Type Description
isValid boolean read-only false if the entity or its Collider is gone.
type ColliderType read/write ColliderType.Sphere or ColliderType.Box.
isActive boolean read/write
isTrigger boolean read/write
scale Vector3 read/write Sphere radius is scale.x.
stepSize number read/write

Examples

Damage zone

-- Scripts/DamageZone.lua (entity with a trigger Collider)
-- Hurts anything with a Health script while it stands inside.
---@field damagePerSecond number @ Damage Per Second
damagePerSecond = 20

function OnTrigger(other)
    local health = other:GetScript("Health")
    if health.isValid then health:TakeDamage(damagePerSecond * GameTime.deltaTime) end
end

Health is the script from Getting Started.

Door trigger

-- Scripts/DoorTrigger.lua (entity with a trigger Collider in front of a door)
---@field door Sector @ Door
door = nil

local inside = 0

function OnTriggerEnter(other)
    if door == nil or not other.hasPlayerController then return end
    inside = inside + 1
    door:MoveCeilingTo(1, door.floorHeight + 40, 80)
end

function OnTriggerExit(other)
    if door == nil or not other.isValid or not other.hasPlayerController then return end
    inside = inside - 1
    if inside == 0 then door:MoveCeilingToFloor(1, 80) end
end

Grow a collider with the sprite

-- Scripts/Grow.lua (entity with a Sprite and a sphere Collider)
---@field growPerSecond number
growPerSecond = 4

function Update()
    local s = entity.transform.scale
    local grown = s + Vector3(1, 1, 1) * (growPerSecond * GameTime.deltaTime)
    entity.transform.scale = grown

    -- Keep the collider radius at a quarter of the sprite's width.
    entity.collider.scale = Vector3(grown.x * 0.25, 1, 1)
end

Toggle a force field

-- Scripts/ForceField.lua (entity with a sphere Collider)
-- Solid while "on", passable while "off". Press F to switch.
function Update()
    if Input.GetKeyDown(Key.F) then
        entity.collider.isActive = not entity.collider.isActive
    end
end

Clone this wiki locally