Telegraph System

The telegraph system provides visual warnings before titan attacks, giving players time to react and dodge. Ground markers appear showing attack zones before damage applies.

How Telegraphs Work

Three-Step Process

Define OBB - Create hitbox shape
Telegraph OBB - Show warning markers on ground
Damage OBB - Apply damage after warning

{
  "timeline": [
    {"type": "define_obb", "name": "fireball", "shape": "SPHERE", ...},
    {"type": "telegraph_obb", "name": "fireball", "telegraphType": "DANGER"},
    // Telegraph appears for ~2 seconds
    {"type": "damage_obb", "name": "fireball", "damage": "20.0"}
  ]
}

Visual Feedback

Ground Markers:

Appear at base of OBB hitbox
Match OBB shape projection
Fade in, pulse, fade out
Color-coded by danger level

Player Experience:

Sees colored markers on ground
Has time to dodge out of zone
Damage applies when markers disappear

Telegraph Types

WARNING (Yellow)

Color: Bright Yellow (#FFD700) Use Case: Basic attacks, frequent moves Typical Duration: 1.0-1.5 seconds

{"type": "telegraph_obb", "name": "slash", "telegraphType": "WARNING"}

When to Use:

Fast attacks (2-4s cooldown)
Low-medium damage (8-15 damage)
Small-medium OBBs
Phase 1 attacks

Examples:

Basic melee slashes
Quick fire bursts
Standard projectiles

DANGER (Orange-Red)

Color: Orange-Red (#FF4500) Use Case: Powerful attacks, moderate rarity Typical Duration: 1.5-2.5 seconds

{"type": "telegraph_obb", "name": "explosion", "telegraphType": "DANGER"}

When to Use:

Medium attacks (6-10s cooldown)
High damage (15-25 damage)
Medium-large OBBs
Phase 2-3 attacks

Examples:

Charged explosions
Lightning strikes
Beam attacks
AOE fields

CRITICAL (Deep Red)

Color: Deep Red (#8B0000) Use Case: Ultimate attacks, rare occurrences Typical Duration: 2.5-4.0 seconds

{"type": "telegraph_obb", "name": "ultimate", "telegraphType": "CRITICAL"}

When to Use:

Ultimate attacks (20-30s cooldown)
Massive damage (25-50 damage)
Huge OBBs (10+ block radius)
Phase 3 or enrage attacks
Low HP desperation moves

Examples:

Ultimate explosions
Full-arena attacks
Enrage mechanics
One-shot attacks

Duration Calculation

Telegraph duration is automatically calculated based on OBB size:

Formula

duration = 1.0 + (obbSize / 10.0)

Where:

obbSize = Largest dimension of OBB
Result clamped to 1.0-4.0 seconds

Examples

Small OBB (3 block radius):

{"halfExtents": {"x": "3.0", ...}}
// duration = 1.0 + (3 / 10) = 1.3 seconds

Medium OBB (6 block radius):

{"halfExtents": {"x": "6.0", ...}}
// duration = 1.0 + (6 / 10) = 1.6 seconds

Large OBB (10 block radius):

{"halfExtents": {"x": "10.0", ...}}
// duration = 1.0 + (10 / 10) = 2.0 seconds

Massive OBB (15 block radius):

{"halfExtents": {"x": "15.0", ...}}
// duration = 1.0 + (15 / 10) = 2.5 seconds

Why Auto-Duration?

Balance by Size:

Small attacks = fast telegraphs (hard to dodge, less punishing)
Large attacks = long telegraphs (easier to see, more punishing)

Design Intent:

Massive AOE attacks give more warning
Point-blank attacks are quick but dodgeable
Consistent player experience

Visual Appearance

Shape Projection

Telegraph markers project OBB shape onto ground:

SPHERE:

Circular ground marker
Radius matches OBB radius

CONE:

Triangular/fan-shaped marker
Points in attack direction
Base width matches cone base

CYLINDER:

Rectangular marker
Length matches cylinder length
Width matches radius

ARC:

Half-circle marker
180° arc in front of titan
Radius matches arc radius

BOX:

Rectangular marker
Dimensions match box dimensions

CAPSULE:

Rounded rectangle marker
Length matches capsule length
Width matches radius

Animation Sequence

1. Fade In (20% of duration):

Opacity: 0% → 100%
Scale: 90% → 100%

2. Pulse (60% of duration):

Opacity: 100% → 80% → 100% (repeating)
Brightness: 100% → 120% → 100% (repeating)

3. Fade Out (20% of duration):

Opacity: 100% → 0%
Scale: 100% → 110%

Total: Smooth, attention-grabbing sequence

Particle Effects

WARNING (Yellow):

Light particle density
Gentle pulse rhythm
Minimal distraction

DANGER (Orange):

Medium particle density
Faster pulse rhythm
Noticeable presence

CRITICAL (Red):

High particle density
Rapid pulse rhythm
Flashing warning effect
Screen shake (slight)

Customization

Override Duration

Force specific telegraph duration:

{
  "type": "telegraph_obb",
  "name": "custom_attack",
  "telegraphType": "DANGER",
  "duration": "3.0"  // Force 3 second warning
}

When to Override:

Balancing specific attacks
Creating unique timing challenges
Syncing with music/phases
Special mechanics

Custom Colors (Advanced)

Not yet supported, but planned:

{
  "type": "telegraph_obb",
  "name": "ice_attack",
  "telegraphType": "DANGER",
  "color": "#00CED1"  // Cyan for ice attacks
}

Balancing Guidelines

Attack Type Recommendations

Fast Melee (2-4s cooldown):

Telegraph: WARNING
Duration: 1.0-1.3s
OBB Size: Small (2-4 blocks)

Charged Attack (6-10s cooldown):

Telegraph: DANGER
Duration: 1.5-2.0s
OBB Size: Medium (5-8 blocks)

Ultimate (20-30s cooldown):

Telegraph: CRITICAL
Duration: 2.5-3.5s
OBB Size: Large (10-15 blocks)

Player Skill Levels

Casual Players:

Use WARNING for most attacks
1.5-2.0s minimum duration
Clear visual distinction

Experienced Players:

Mix WARNING/DANGER
1.0-1.5s duration acceptable
Require positioning skill

Hardcore Players:

Frequent DANGER/CRITICAL
1.0s duration for some attacks
Punish poor positioning

Difficulty Scaling

Phase 1 (100% HP):

80% WARNING telegraphs
20% DANGER telegraphs
0% CRITICAL telegraphs
Longer durations

Phase 2 (66% HP):

60% WARNING telegraphs
35% DANGER telegraphs
5% CRITICAL telegraphs
Standard durations

Phase 3 (33% HP):

40% WARNING telegraphs
45% DANGER telegraphs
15% CRITICAL telegraphs
Shorter durations

Common Patterns

Pattern: Quick Jab

{
  "type": "telegraph_obb",
  "name": "jab",
  "telegraphType": "WARNING"
  // Auto-duration: ~1.0s for small OBB
}

Design:

Fast attack, easy to dodge
Minimal warning needed
Spam-safe

Pattern: Charged Blast

{
  "timeline": [
    {"type": "pause", "pause": 1.0},  // Charge time
    {"type": "define_obb", "name": "blast", "shape": "SPHERE", "halfExtents": {"x": "7.0", ...}},
    {"type": "telegraph_obb", "name": "blast", "telegraphType": "DANGER"},
    // Auto-duration: ~1.7s
    {"type": "damage_obb", "name": "blast", "damage": "22.0"}
  ]
}

Design:

Charge time + telegraph = total warning
Medium difficulty dodge
Moderate punishment

Pattern: Ultimate Explosion

{
  "timeline": [
    {"type": "pause", "pause": 2.0},  // Dramatic windup
    {"type": "define_obb", "name": "ultimate", "shape": "SPHERE", "halfExtents": {"x": "12.0", ...}},
    {"type": "telegraph_obb", "name": "ultimate", "telegraphType": "CRITICAL"},
    // Auto-duration: ~3.2s
    {"type": "damage_obb", "name": "ultimate", "damage": "45.0"}
  ]
}

Design:

Long buildup + long telegraph = very dodgeable
Massive punishment if hit
Spectacle attack

Pattern: No Telegraph (Advanced)

{
  "timeline": [
    {"type": "define_obb", "name": "instant", ...},
    // Skip telegraph_obb entirely
    {"type": "damage_obb", "name": "instant", "damage": "5.0"}
  ]
}

When to Use:

Very low damage (<8 damage)
Extremely short range
Combo finishers
Use sparingly - telegraphs are core mechanic

Player Strategies

Reading Telegraphs

Visual Cues:

Color - Danger level
Size - Attack range
Shape - Attack direction/type
Pulse Speed - Urgency

Audio Cues:

Titan animations/sounds during windup
Environmental sounds (rumbling, charging)

Dodging Tactics

For Small Telegraphs:

Sidestep perpendicular to attack
Roll through if invulnerable
Short-range repositioning

For Medium Telegraphs:

Run to edge of zone
Use mobility skills
Plan escape route

For Large Telegraphs:

Sprint away early
Use terrain/obstacles
Coordinate with team

Advanced Techniques

Bait and Punish:

Stand in telegraph zone
Dodge at last moment
Counter-attack during recovery

Telegraphs as Timers:

Track when damage will apply
Plan burst damage windows
Coordinate team abilities

Accessibility

Visibility Options

High Contrast:

Increase particle density
Brighter colors
Thicker ground markers

Color Blind Support:

WARNING: Yellow + stripes
DANGER: Orange + dots
CRITICAL: Red + crosses

Reduced Effects:

Lower particle count
Less screen shake
Simpler animations

Note: Some options require client-side mods or resource packs.

Audio Warnings

Recommended Additions:

Play sound on telegraph start
Pitch increase as damage approaches
Distinct sound per telegraph type

Example:

{
  "timeline": [
    {"type": "telegraph_obb", "name": "blast", "telegraphType": "DANGER"},
    {"type": "sound", "sound": "block.note_block.bass", "pitch": "0.5"},
    {"type": "pause", "pause": 0.5},
    {"type": "sound", "sound": "block.note_block.bass", "pitch": "0.7"},
    {"type": "pause", "pause": 0.5},
    {"type": "sound", "sound": "block.note_block.bass", "pitch": "1.0"},
    {"type": "damage_obb", "name": "blast", "damage": "20.0"}
  ]
}

Performance Considerations

Particle Limits

Per Telegraph:

WARNING: ~10-20 particles/second
DANGER: ~20-40 particles/second
CRITICAL: ~40-60 particles/second

Multiple Titans:

Reduce particle count if >3 titans active
Use simpler marker shapes
Disable non-critical effects

Optimization Tips

Efficient Telegraphs:

Use built-in telegraph system (not custom particles)
Avoid overlapping telegraphs
Clean up markers after damage
Use appropriate sizes

Troubleshooting

Telegraph Not Appearing

Symptoms: No ground markers visible

Fixes:

Check OBB defined before telegraph
Verify name matches between keyframes
Ensure particles enabled in client settings
Check ground surface exists below OBB

Telegraph Too Short/Long

Symptoms: Duration doesn’t feel right

Fixes:

Adjust OBB size (affects auto-duration)
Use duration override in telegraph keyframe
Check total timeline timing
Test with different players

Telegraph Wrong Color

Symptoms: Color doesn’t match telegraph type

Fixes:

Verify telegraphType spelling (case-sensitive)
Check client resource pack conflicts
Ensure mod version up to date

Players Can’t Dodge

Symptoms: Attacks feel unavoidable

Fixes:

Increase telegraph duration
Reduce OBB size
Add pause before telegraph
Lower damage to compensate
Test with average player movement speed

Best Practices

Design Philosophy

Always Telegraph Damage:

Every damage_obb should have telegraph_obb
Exception: Very low damage chip attacks (<5 damage)

Match Telegraph to Power:

CRITICAL for attacks that can one-shot
DANGER for attacks requiring healing
WARNING for attacks that chip HP

Consistent Timing:

Keep similar attacks using similar durations
Don’t make players relearn timings
Predictability = skill expression

Testing Checklist

Before Finalizing:

Telegraph visible on all terrain types
Duration feels fair for damage amount
Color matches attack severity
Shape projection clear
Multiple players can see simultaneously
Works with particle settings on low
Tested with lag/low FPS

Common Mistakes

❌ No Telegraph:

{"type": "damage_obb", "name": "attack", "damage": "25.0"}
// Players have no warning!

✅ Always Telegraph:

{"type": "telegraph_obb", "name": "attack", "telegraphType": "DANGER"}
{"type": "damage_obb", "name": "attack", "damage": "25.0"}

❌ Wrong Type for Damage:

{"type": "telegraph_obb", "name": "oneshot", "telegraphType": "WARNING"}
{"type": "damage_obb", "name": "oneshot", "damage": "100.0"}
// 100 damage with yellow warning!

✅ Match Type to Power:

{"type": "telegraph_obb", "name": "oneshot", "telegraphType": "CRITICAL"}
{"type": "damage_obb", "name": "oneshot", "damage": "100.0"}

Next Steps

OBB System → - Complete OBB documentation
Vulnerability System → - Counterplay mechanics
OBB Visualizer → - Preview telegraph shapes in 3D

Master telegraphs to create fair, skill-based boss fights! 🎯