Hitbox Shapes
Hitbox shapes define the geometric volume used for collision detection in skills. Two separate hitbox parameters control different aspects: hitbox-params defines the main overlap volume (entities and areas), while hitbox-blocks-params defines a separate block-collision check (typically much smaller).
Shape Registry
Five shapes are registered and available for configuration. Both hitbox-params and hitbox-blocks-params select a shape via the hitbox-type field:
Shape | Use Case |
|---|---|
| Symmetric, omnidirectional overlap (e.g., area heals, projectile hitboxes). |
| Axis-aligned box, useful for directionally-neutral detection. |
| Directional cone-shaped volume, oriented along the skill direction (e.g., melee sweeps). |
| Ring-shaped volume around a center, oriented by yaw (e.g., circular AoE spins). |
| Oriented cuboid aligned to travel direction (+Z forward), supports local offset and pitch/yaw rotation (e.g., melee cones). |
Note: A TetrahedronShape class exists in source but is not registered in ThreeDimensionalShapeResolver, so it cannot be selected in configuration.
How Hitbox Shapes Are Used
Impact Skills
Impact skills use hitbox-params as their AoE volume centered at the impact point. The shape's boundary determines which entities are hit. For example, a sphere of radius 0.6 will hit all entities whose bounding box overlaps that sphere.
Projectile & Laser Skills
Projectile and laser skills sweep hitbox-params continuously along the projectile's travel path. At each frame, the shape moves to the projectile's current position and checks for overlapping entities. Additionally, hitbox-blocks-params is sampled along the path to gate the stop-on-block behavior — if the block-overlap shape would collide with solid blocks, the projectile stops.
Direction-Aware vs. Orientation-Independent
Some shapes are direction-aware and rotate to face the skill's current direction vector:
Direction-aware:
square_pyramid,torus,rotated_cuboid— their orientation follows the skill's direction (computed as the projectile's velocity direction or, for impacts, the caster's facing direction).Orientation-independent:
sphere,cube— they are symmetric and do not rotate.
Shape Parameters
sphere
A sphere centered at the position with a given radius. Overlaps are checked against bounding boxes using strict sphere-geometry intersection.
Parameter | Type | Required | Description |
|---|---|---|---|
| double | Yes | Radius of the sphere in blocks. |
Example: projectile with small hitbox
Example: block collision sphere (tiny)
cube
An axis-aligned cuboid (AABB) centered at the position. The X and Z dimensions use the same size; Y is independent. Useful for area-of-effect skills that should not rotate with direction.
Parameter | Type | Required | Description |
|---|---|---|---|
| double | Yes | Width and depth of the box (same value used for X and Z half-extents). |
| double | Yes | Height of the box (Y half-extent). |
Example: symmetric area heal
square_pyramid
A pyramid whose apex points along the skill direction, with a rectangular base perpendicular to that direction. The base can be rectangular (different width and length). The shape tapers from the apex toward the base, so the effective AoE expands with distance from the apex.
Parameter | Type | Required | Description |
|---|---|---|---|
| double | Yes | Despite the name, this value is halved again internally before being used as the true half-width, so the resulting full base width equals the configured value (not double it). |
| double | Yes | Same behavior as |
| double | Yes | Distance from apex to base along the direction vector. |
Example: melee sweep cone
This creates a pyramid with apex at the impact point, extending 5 blocks forward (along direction), with a base 5 blocks wide and 3 blocks long.
torus
A torus (doughnut-shaped ring) centered at the position, oriented horizontally (ring in the XZ plane). The ring rotates around the Y-axis based on the skill's yaw angle. Useful for circular area effects that sweep around a point.
Parameter | Type | Required | Description |
|---|---|---|---|
| double | Yes | Radius to the center of the torus tube (distance from center to ring). |
| double | Yes | Thickness of the tube (radial thickness). |
| double | Yes | Height of the torus ring (extruded vertically). |
| double | Yes | Angular spread in degrees (360 = full circle, 180 = half circle). |
| double | Yes | Offset angle in degrees applied to the base direction's yaw. |
Example: spinning ring attack
This creates a half-ring (180°) with radius 4 blocks, tube thickness 1 block, and height 2 blocks, oriented along the skill's yaw direction.
rotated_cuboid
An oriented bounding box (OBB) aligned to the skill's travel direction, with independent X, Y, and Z dimensions. The cuboid's local +Z axis points along the travel direction (+Z forward). Supports local offset to move the shape away from the skill position, and pitch/yaw rotation offsets for fine-tuning orientation.
Parameter | Type | Required | Description |
|---|---|---|---|
| double | Yes | Width of the cuboid (X size in blocks). |
| double | Yes | Height of the cuboid (Y size in blocks). |
| double | Yes | Depth of the cuboid, along the travel direction (Z size in blocks). |
| double | No | Pitch rotation offset in degrees (rotation around X-axis, relative to direction). Default: |
| double | No | Yaw rotation offset in degrees (rotation around Y-axis, relative to direction). Default: |
| double | No | Local offset along the cuboid's X-axis. Default: |
| double | No | Local offset along the cuboid's Y-axis. Default: |
| double | No | Local offset along the cuboid's Z-axis (forward direction). Default: |
Example: forward-reaching melee cone
This creates a 1.5 × 2.5 × 6 block cuboid, offset 3 blocks forward (+Z) and 0.5 blocks down (-Y) from the caster's position. Useful for frontal melee attacks that reach ahead of the caster.
Complete Configuration Example
This impact skill uses a rotated cuboid for entity detection and a tiny sphere for block collision. When cast, the rotated cuboid checks for enemies in its 6-block forward-reaching cone; the sphere ensures the hitbox respects block geometry.
Hitbox Block Parameters
The hitbox-blocks-params field gates whether the skill or projectile should stop on collision with solid blocks. It is typically configured as a small sphere (radius 0.01 to 0.1) centered at the skill's position, and only affects skills with stop-on-block: true.
If you want a projectile to ignore certain block types, use a small hitbox-blocks-params. If you want precise block detection, ensure hitbox-blocks-params is at least the size of the block grid (1.0).