OBB System

OBB (Oriented Bounding Box) System

The OBB system provides precise 3D collision detection for titan attacks, replacing old radius-based damage with shaped hitboxes that rotate with the entity.

What is an OBB?

An Oriented Bounding Box is a 3D shape that:

✅ Rotates with the entity’s look direction
✅ Has precise collision detection
✅ Supports 6 different shapes
✅ Can be positioned relative to the entity
✅ Integrates with telegraph system

Why Use OBBs?

vs Radius Damage

❌ Radius: Sphere only, no rotation ✅ OBB: 6 shapes, rotates naturally

vs MoLang Math

❌ MoLang: Complex manual calculations ✅ OBB: Built-in collision detection

Performance

OBBs use native collision code, faster than MoLang loops

Visual Clarity

OBB telegraphs show EXACT attack zones

The Three-Step OBB Workflow

Every OBB attack follows this pattern:

{
  "timeline": [
    // 1. DEFINE - Create the OBB
    {
      "type": "define_obb",
      "name": "my_attack",
      "shape": "CONE",
      "positioning": "IN_FRONT",
      "distance": "2.5",
      "halfExtents": {"x": "1.5", "y": "5.0", "z": "1.5"}
    },

    // 2. TELEGRAPH - Show warning (optional)
    {
      "type": "telegraph_obb",
      "obbName": "my_attack",
      "color": "WARNING",
      "duration": "800",
      "markerDensity": "25"
    },

    // 3. DAMAGE - Apply damage
    {
      "type": "damage_obb",
      "obbName": "my_attack",
      "damage": "q.move_damage",
      "expressions": ["q.damage_all(q.move_damage)"]
    }
  ]
}

1. Define OBB Keyframe

Creates an OBB that can be referenced by later keyframes.

Basic Syntax

{
  "type": "define_obb",
  "name": "attack_zone",
  "shape": "SPHERE",
  "positioning": "AT_TARGET",
  "distance": "3.0",
  "halfExtents": {"x": "5.0", "y": "5.0", "z": "5.0"},
  "includePitch": true
}

Parameters

`name` (Required)

Unique identifier for this OBB:

"name": "flamethrower_cone"
// Reference later: "obbName": "flamethrower_cone"

`shape` (Required)

One of 6 collision shapes:

Shape	Description	Best For
`SPHERE`	Ball centered at origin	Explosions, radial attacks
`CONE`	Cone pointing forward	Breath attacks, beams
`CYLINDER`	Cylinder along forward axis	Lightning bolts, charge attacks
`ARC`	180° arc in front	Claw swipes, tail attacks
`BOX`	Rectangular box	Ground pounds, walls
`CAPSULE`	Cylinder with rounded ends	Dash attacks

`positioning` (Required)

How to position the OBB:

Mode	Description	Use Case
`AT_TARGET`	Center on attack target	Targeted explosions
`AT_USER`	Center on titan	Self-centered AOE
`IN_FRONT`	In front of titan	Directional attacks

// Most common for directional attacks
"positioning": "IN_FRONT"

`distance` (Required for IN_FRONT)

Blocks in front of entity:

"distance": "2.5"  // 2.5 blocks forward

// Adjust based on attack range:
"distance": "1.0"  // Close-range (bite, slash)
"distance": "3.0"  // Medium-range (sweep)
"distance": "5.0"  // Long-range (beam)

`offset` (For advanced positioning)

Custom offset in local space (forward, up, right):

"offset": {"x": "0", "y": "2.0", "z": "5.0"}
// x = right (+) / left (-)
// y = up (+) / down (-)
// z = forward (+) / backward (-)

`halfExtents` (Required)

Half-widths along each axis (actual size is 2x these values):

"halfExtents": {"x": "3.0", "y": "2.0", "z": "5.0"}
// Creates a 6×4×10 block box

Shape-Specific Usage:

"shape": "SPHERE",
"halfExtents": {"x": "5.0", "y": "5.0", "z": "5.0"}
// Only X matters (radius)
// Creates 5-block radius sphere

"shape": "CONE",
"halfExtents": {"x": "2.0", "y": "8.0", "z": "2.0"}
// x = base radius (2 blocks)
// y = length (8 blocks forward)
// z = ignored

"shape": "CYLINDER",
"halfExtents": {"x": "1.5", "y": "10.0", "z": "1.5"}
// x = radius (1.5 blocks)
// y = half-length (10 blocks forward)
// z = ignored

"shape": "ARC",
"halfExtents": {"x": "4.0", "y": "3.0", "z": "4.0"}
// x = radius (4 blocks)
// y = half-height (3 blocks up/down)
// z = ignored
// Always 180° arc in front

"shape": "BOX",
"halfExtents": {"x": "3.0", "y": "2.0", "z": "5.0"}
// x = half-width (3 blocks left/right)
// y = half-height (2 blocks up/down)
// z = half-depth (5 blocks forward)
// Total size: 6×4×10

"shape": "CAPSULE",
"halfExtents": {"x": "1.0", "y": "8.0", "z": "1.0"}
// x = radius (1 block)
// y = half-length PLUS hemisphere (8 blocks total)
// z = ignored

`includePitch` (Optional, default: true)

Whether to rotate OBB with entity’s up/down look:

// Rotate with look direction (for beams, breath)
"includePitch": true

// Stay horizontal (for ground attacks)
"includePitch": false

2. Telegraph OBB Keyframe

Shows visual warning markers on the ground.

Basic Syntax

{
  "type": "telegraph_obb",
  "obbName": "attack_zone",
  "playSound": true,
  "soundPitch": 0.6,
  "telegraphText": "FLAMETHROWER!!!",
  "color": "WARNING",
  "duration": "800",
  "markerDensity": "25"
}

Parameters

`obbName` (Required)

Name of OBB to visualize:

"obbName": "flamethrower_cone"

`color` (Required)

Threat level determines color and sound:

Color	Hex	Sound Pitch	Use For
`WARNING`	Yellow	1.0	Light attacks (8-12 dmg)
`DANGER`	Orange	0.7	Medium attacks (13-16 dmg)
`CRITICAL`	Red	0.4	Ultimate attacks (21+ dmg)

"color": "DANGER"

`duration` (Required)

How long telegraph shows (milliseconds):

"duration": "800"   // 0.8 seconds

// Balance warning time:
"duration": "600-800"   // Light attacks
"duration": "800-1200"  // Medium attacks
"duration": "1200-1800" // Ultimate attacks

`markerDensity` (Optional, default: 20)

Markers per unit length:

"markerDensity": "15"  // Sparse (performance)
"markerDensity": "25"  // Standard
"markerDensity": "40"  // Dense (clear warning)
"markerDensity": "50"  // Very dense (ultimate attacks)

Higher = more visible but more lag.

`telegraphText` (Optional)

Text shown above markers:

"telegraphText": "FLAMETHROWER!!!"

`playSound` (Optional, default: true)

Play warning sound:

"playSound": true

`soundPitch` (Optional, default: 0.5)

Sound pitch (lower = more ominous):

"soundPitch": 0.4   // Deep, ultimate attack
"soundPitch": 0.6   // Medium threat
"soundPitch": 1.0   // Light attack

3. Damage OBB Keyframe

Applies damage to entities within the OBB.

Basic Syntax

{
  "type": "damage_obb",
  "obbName": "attack_zone",
  "damage": "q.move_damage",
  "expressions": [
    "q.damage_all(q.move_damage)",
    "q.knockback_all(0.0, 1.0, 0.0)"
  ],
  "delay": "0"
}

Parameters

`obbName` (Required)

Name of OBB to use:

"obbName": "flamethrower_cone"

`damage` (Required)

Base damage value (MoLang expression):

// Use move's configured damage
"damage": "q.move_damage"

// Fixed damage
"damage": "15.0"

// Scaled damage
"damage": "q.move_damage * 1.5"

`expressions` (Required)

MoLang scripts to run on entities:

"expressions": [
  "q.damage_all(q.move_damage)",
  "q.knockback_all(0.0, 1.5, 0.0)",
  "q.apply_burn(2.0)"
]

See Damage Functions for all options.

`delay` (Optional, default: 0)

Delay before damage (seconds):

"delay": "0.5"  // Wait 0.5s after telegraph

Complete Examples

Cone Flamethrower

{
  "timeline": [
    {"type": "add_holds", "holds": ["effects"]},
    {"type": "stop_movement", "duration": "2500"},

    // Define 8-block cone
    {
      "type": "define_obb",
      "name": "flamethrower",
      "shape": "CONE",
      "positioning": "IN_FRONT",
      "distance": "2.0",
      "halfExtents": {"x": "2.0", "y": "8.0", "z": "2.0"},
      "includePitch": true
    },

    // Telegraph warning
    {
      "type": "telegraph_obb",
      "obbName": "flamethrower",
      "color": "WARNING",
      "duration": "800",
      "markerDensity": "25",
      "telegraphText": "FLAMETHROWER!"
    },

    {"type": "pause", "pause": 0.5},
    {"type": "animation", "animation": ["special", "fire"]},

    // Damage
    {
      "type": "damage_obb",
      "obbName": "flamethrower",
      "damage": "q.move_damage",
      "expressions": [
        "q.damage_all(q.move_damage)",
        "q.apply_burn(3.0)"
      ]
    },

    {"type": "set_vulnerable", "vulnerabilityType": "RECOVERING", "duration": "1.0"},
    {"type": "remove_holds", "holds": ["effects"]},
    {"type": "pause", "pause": 1.0}
  ]
}

Sphere Explosion

{
  "timeline": [
    {"type": "add_holds", "holds": ["effects"]},
    {"type": "stop_movement", "duration": "4000"},

    // Define 12-block sphere at titan
    {
      "type": "define_obb",
      "name": "explosion",
      "shape": "SPHERE",
      "positioning": "AT_USER",
      "halfExtents": {"x": "12.0", "y": "12.0", "z": "12.0"}
    },

    // Critical warning
    {
      "type": "telegraph_obb",
      "obbName": "explosion",
      "color": "CRITICAL",
      "duration": "1500",
      "markerDensity": "40",
      "telegraphText": "EXPLOSION!!!"
    },

    {"type": "pause", "pause": 1.0},

    // Damage with knockback
    {
      "type": "damage_obb",
      "obbName": "explosion",
      "damage": "q.move_damage",
      "expressions": [
        "q.damage_all(q.move_damage)",
        "q.knockback_all(0.0, 2.0, 0.0)"
      ]
    },

    {"type": "set_vulnerable", "vulnerabilityType": "EXHAUSTED", "duration": "2.5"},
    {"type": "remove_holds", "holds": ["effects"]},
    {"type": "pause", "pause": 2.0}
  ]
}

Arc Claw Swipe

{
  "timeline": [
    {"type": "add_holds", "holds": ["effects"]},
    {"type": "stop_movement", "duration": "1800"},

    // Define 180° arc
    {
      "type": "define_obb",
      "name": "claw_swipe",
      "shape": "ARC",
      "positioning": "IN_FRONT",
      "distance": "1.0",
      "halfExtents": {"x": "5.0", "y": "3.0", "z": "5.0"}
    },

    {
      "type": "telegraph_obb",
      "obbName": "claw_swipe",
      "color": "WARNING",
      "duration": "600",
      "markerDensity": "20"
    },

    {"type": "animation", "animation": ["special", "attack"]},

    {
      "type": "damage_obb",
      "obbName": "claw_swipe",
      "damage": "q.move_damage",
      "expressions": ["q.damage_all(q.move_damage)"]
    },

    {"type": "set_vulnerable", "vulnerabilityType": "RECOVERING", "duration": "0.8"},
    {"type": "remove_holds", "holds": ["effects"]},
    {"type": "pause", "pause": 0.8}
  ]
}

OBB Best Practices

1. Shape Selection

Attack Type	Recommended Shape
Breath/Beam	CONE or CYLINDER
Explosion	SPHERE
Claw/Tail	ARC
Charge	CAPSULE
Ground Pound	BOX
Lightning	CYLINDER

2. Telegraph Timing

Balance between fair warning and game feel:

Attack Damage	Telegraph Duration
Light (8-12)	0.6-0.8s
Medium (13-16)	0.8-1.2s
Heavy (17-20)	1.0-1.5s
Ultimate (21+)	1.4-1.8s

3. OBB Sizing

Consider titan scale and player mobility:

Range	halfExtents Example	Use Case
Close	x:3, y:2, z:3	Melee attacks
Medium	x:5, y:3, z:7	Standard attacks
Long	x:7, y:5, z:12	Ranged attacks
Ultimate	x:12, y:8, z:12	AOE explosions

Troubleshooting

Telegraph Not Showing

✅ Check duration > 0
✅ Check markerDensity reasonable (15-50)
✅ Ensure GameTest enabled (1.21.1+)
✅ Check render distance

Damage Not Applying

✅ Verify obbName matches define_obb name
✅ Check expressions syntax
✅ Ensure entities are within OBB bounds
✅ Check player gamemode (creative ignores damage)

OBB Positioning Wrong

✅ Check positioning mode
✅ Verify distance value
✅ Try toggling includePitch
✅ Use telegraph to visualize actual hitbox

Next Steps

Telegraph System → - Advanced telegraph customization
Damage Functions → - All MoLang damage options
Creating Custom Moves → - Build complete ActionEffects

Master OBBs to create precise, readable boss attacks!

OBB System

OBB (Oriented Bounding Box) System

What is an OBB?

Why Use OBBs?

The Three-Step OBB Workflow

1. Define OBB Keyframe

Basic Syntax

Parameters

name (Required)

shape (Required)

positioning (Required)

distance (Required for IN_FRONT)

offset (For advanced positioning)

halfExtents (Required)

includePitch (Optional, default: true)

2. Telegraph OBB Keyframe

Basic Syntax

Parameters

obbName (Required)

color (Required)

duration (Required)

markerDensity (Optional, default: 20)

telegraphText (Optional)

playSound (Optional, default: true)

soundPitch (Optional, default: 0.5)

3. Damage OBB Keyframe

Basic Syntax

Parameters

obbName (Required)

damage (Required)

expressions (Required)

delay (Optional, default: 0)

Complete Examples

Cone Flamethrower

Sphere Explosion

Arc Claw Swipe

OBB Best Practices

1. Shape Selection

2. Telegraph Timing

3. OBB Sizing

Troubleshooting

Telegraph Not Showing

Damage Not Applying

OBB Positioning Wrong

Next Steps

`name` (Required)

`shape` (Required)

`positioning` (Required)

`distance` (Required for IN_FRONT)

`offset` (For advanced positioning)

`halfExtents` (Required)

`includePitch` (Optional, default: true)

`obbName` (Required)

`color` (Required)

`duration` (Required)

`markerDensity` (Optional, default: 20)

`telegraphText` (Optional)

`playSound` (Optional, default: true)

`soundPitch` (Optional, default: 0.5)

`obbName` (Required)

`damage` (Required)

`expressions` (Required)

`delay` (Optional, default: 0)