HitBox2D Module

Tiny supports a lightweight intersection and overlap checking module that does not require physics. This module is referred to as HitBox2D. This document provides common use cases, examples, and a reference of HitBox2D components.

Use Cases and Examples

This section demonstrates how to use the HitBox2D module through common use cases and usage examples. If a use case or an example is similar to a topic in the Unity User Manual, a link is provided to the appropriate topic.

Simple HitBox2D

  1. Create a Sprite2D entity.
  2. Add a Sprite2DRendererHitBox2D component.

The Sprite2DRendererHitBox2D component will adjust its hitbox to fit the Sprite2D's shape.

Alternatively, you can add a RectHitBox2D component instead of a Sprite2DRendererHitBox2D if you want to specify the hitbox's position and scale.

Please refer to the raider or spaceship entity in the GalaxyRaiders project for examples.

Detect Collisions

  1. Create two Sprite2D entities.
  2. Add a hitbox on both entities using a Sprite2DRendererHitBox2D or a RectHitBox2D component.
  3. Create a system.
  4. Add the HitBoxOverlapResults component to the Component Types list.

You can use the overlaps member of the HitBoxOverlapResults component to check if both entities are overlapping each other.

Both entities have to be under the same camera.

Please refer to the DamageSystem in the GalaxyRaiders project for an example.

Example: Galaxy Raiders

The GalaxyRaiders project found in Assets/UTinySamples covers the use of the HitBox2D Module components. In the project, you will find examples about adding a hitbox on an entity and implementing game logic when hitboxes overlap.

This table can be used to associate a HitBox2D Component to a sample entity and/or system.

HitBox2D Components Entity Name System Name
HitBoxOverlapResults DamageSystem
RectHitBox2D raider, border, defensePoint, groundBorder
Sprite2DRendererHitBox2D raiderLaser, spaceship, spaceshipLaser

Components

Tiny is built around small, lightweight components. This way you only pay for what you need. This design usually creates more component types to represent data held in a single Unity component, which can be confusing at first for some developers.

Use this table to associate familiar Unity concepts with Tiny.

Unity Component HitBox2D Components
Collider2D.OverlapCollider HitBoxOverlapResults
Box Collider 2D RectHitBox2D
Polygon Collider 2D Sprite2DRendererHitBox2D

HitBoxOverlapResults

Provides a list of HitBoxOverlaps. This list contains the other entities that are overlapping with the current entity's hitbox.

Entities must be under the same camera.

RectHitBox2D

A component describing a 2D hitbox for simple collision detection.

Hitboxes can be separate from sprites rendering, but should have a Transform component. A Sprite2DRenderer component (with an alpha color of more than 0) is needed with a RectHitBox2D.

Property Description
box Rectangle of hit area. Used in picking and non physics collision check. Pivot is at (0,0). The position is set with the x and y values. The scaling is set with the width and height. Defaults with the shape of the Sprite2DRenderer.

Sprite2DRendererHitBox2D

A component describing a 2D hitbox for simple collision detection. This component acts the same as a RectHitBox2D, but takes its size from a Sprite2DRenderer.

For custom rectangle shape, use RectHitBox2D. A Sprite2DRenderer component (with an alpha color of more than 0) is needed with a Sprite2DRendererHitBox2D.

Property Description
pixelAccurate Use pixel accurate hit testing from the Sprite. Defaults to false. In order to work, the Image2D component that is used for testing also needs to have the Image2DAlphaMask component placed next to it before image loading. Pixel accurate picking will ignore overlaps or hits where the sprite alpha is zero, but can be very expensive to compute. Please use this feature sparingly.

Systems

HitBox2DSystem

  • Updates Before: Shared.InputFence, Shared.RenderingFence

The main entry system for 2D intersection and overlap check. It will perform Overlap tests between all components under all cameras in the world. It will add or remove HitBoxOverlapResults components to any objects that have overlaps.

It does not take into account motion of objects (use real physics in that case). Only objects that are overlapping under the same camera will have overlaps.

Structs

HitBoxOverlap

A struct describing a 2D hitbox overlap.

Property Description
camera An entity that represents the camera that sees the overlap.
otherEntity The other entity, will have a Sprite2DRendererHitBox2D or RectHitBox2D component.

HitTestResult

Property Description
entityHit An entity that was hit or NONE if there was no hit.
uv Normalized [0..1] coordinates inside the sprite of the hit point. Lower left origin, the same coordinate system as pivot points for Sprite2D components.

RayCastResult

Property Description
entityHit An entity that was hit or NONE if there was no hit.
t Normalized [0..1] distance on ray. The hit point is hit = rayStart + (rayEnd - rayStart) * t. If the ray cast started from inside a hitbox, the t value will be the exit value.

DetailedHitBoxOverlap

Property Description
vertices A 2D convex polygon outline of the intersection of two hitboxes. Can be rendered as a Shape2D.