Interfaces

• ISensor for general event-driven collision awareness.
• IRadar for fast, lightweight proximity checks.
• ICollisionRadar for precise, mask-based collision needs.

How to use:

sensor = {
    radius: 300,
    target_types: [StatefulObject],
    on_enter: function(_collision) { ... }
};
implement(ISensor); // it's important to implement the interface after the configuration

radar = {
    radius: 300,
    target_types: [StatefulObject],
    on_enter: function(_collision) { ... }
};
implement(IRadar);

cradar = {
    radius: 300,
    target_types: [StatefulObject],
    on_enter: function(_collision) { ... }
};
implement(ICollisionRadar);

They can be used for:

• Enemy AI: Detect when a player or NPC enters a guard’s detection zone (on_enter) and trigger pursuit.
• Stealth Mechanics: Use detail_mode to know exactly how close the player is and raise alerts gradually.
• Power-ups or Collectibles: Detect when the player comes within range to highlight or attract items.
• Multiplayer/Allies: Show nearby team mates on a minimap or radar UI.
• Environmental Hazards: Trigger traps, turrets, or alarms when an object enters a danger zone.

Configuration

Each sensor is enriched with default properties:

• is_enabled (bool): Whether the sensor is active. Default: true.
• detail_mode (bool): Whether to store rich collision data or just IDs. Default: true.
• interval (number): Update interval (steps between checks). Default: 5.
• radius (number): Detection radius. Default: 30.
• offset (array [x,y]): Position offset relative to the instance. Default: [0, 0].
• target_instances (array): Specific instances to detect.
• target_types (array): Object types to detect.

And there are a few more for ICollisionRadar:

• exclude_myself (bool): Whether the radar should ignore its own instance during detection. Default: true.

• precise_collision_masks (bool):
  If enabled, collisions use precise sprite masks (pixel-perfect).
  If disabled, bounding boxes are used.
  Default: false.

• order_instances (bool): Whether detected instances should be ordered by distance in the result list. Default: false.

Event Hooks

Sensors can define these optional callbacks for custom behavior:

• on_enter(_collision) → Runs when a new collision is detected.
• on_step(_collision) → Runs each update while a collision persists.
• on_leave(_collision) → Runs when a collision ends.

Collision Structs

When a sensor or radar detects a collision, it can return detailed information in a structured format if detail_mode is enabled. These structs typically include the following fields:

• other_inst (id)
  The ID of the other instance that was detected by the sensor or radar.

• distance_to_other (number)
  The distance between the sensor’s center and the detected instance.

• distance_to_border (number)
  The distance from the detected instance to the edge of the sensor or radar radius (calculated as radius - distance_to_other).

Sensory lifecycle

flowchart LR
    A[Start Sensor Check] --> C{Sensor Enabled?}
    C -- No --> R[Skip]

    C -- Yes --> D[Perform Collision Check]
    D --> E{Collision Detected?}

    E -- No --> L[on_leave]
    E -- Yes --> F{New Collision?}

    F -- Yes --> G[on_enter]
    F -- No --> H[on_step]

    G --> U[Repeat check]
    H --> U
    L --> U

    U --> A