​

Home Teleport System

​

Overview

• 10-second cast time (interruptible by movement/combat)
• 30-second cooldown (reduced from 15 minutes)
• Visual cast effects with portal animation
• Server-authoritative cooldown tracking
• Minimap orb integration for quick access
• Dual UI: dedicated button + minimap orb

​

Constants

// packages/shared/src/constants/GameConstants.ts
export const HOME_TELEPORT_CONSTANTS = {
  COOLDOWN_MS: 30 * 1000,        // 30 seconds
  CAST_TIME_MS: 10 * 1000,       // 10 seconds (interruptible)
  CAST_TIME_TICKS: 17,           // ~17 ticks at 600ms/tick
} as const;

​

Client Components

​

HomeTeleportButton

• ready - Available to cast
• casting - Cast in progress (shows progress bar)
• cooldown - On cooldown (shows remaining time + refill visual)

import { HomeTeleportButton } from '@/game/hud/HomeTeleportButton';

<HomeTeleportButton world={world} />

• Click to start cast
• Progress bar during 10-second cast
• Cooldown refill visual (bottom-to-top gradient)
• Displays remaining cooldown time (”25s”, “1m 5s”)

​

MinimapHomeTeleportOrb

• Circular progress indicator (SVG-based)
• Color-coded states (purple=ready, blue=casting, gray=cooldown)
• Cooldown refill animation
• Compact design for minimap integration

import { MinimapHomeTeleportOrb } from '@/game/hud/MinimapHomeTeleportOrb';

<MinimapHomeTeleportOrb world={world} />

​

Shared Utilities

​

readHomeTeleportRemainingMs()

export function readHomeTeleportRemainingMs(event?: unknown): number

• event - Event payload from HOME_TELEPORT_FAILED

const onFailed = (event?: unknown) => {
  const remainingMs = readHomeTeleportRemainingMs(event);
  if (remainingMs > 0) {
    // Enter cooldown state
    setState("cooldown");
    setCooldownEndTime(performance.now() + remainingMs);
  }
};

​

getHomeTeleportCooldownProgress()

export function getHomeTeleportCooldownProgress(
  cooldownRemaining: number,
): number

• cooldownRemaining - Remaining cooldown in milliseconds

const cooldownProgress = getHomeTeleportCooldownProgress(15000);
// 50 (halfway through 30-second cooldown)

​

Server Implementation

​

HomeTeleportManager

​

formatCooldownRemaining()

export function formatCooldownRemaining(remainingMs: number): string

• remainingMs - Remaining cooldown in milliseconds

formatCooldownRemaining(0);      // "1s" (rounds up to minimum 1s)
formatCooldownRemaining(999);    // "1s"
formatCooldownRemaining(5000);   // "5s"
formatCooldownRemaining(60000);  // "1m"
formatCooldownRemaining(90500);  // "1m 31s"

​

Server Validation

// Cooldown rejection includes remaining time
if (this.isOnCooldown(playerId)) {
  const remainingMs = this.getCooldownRemaining(playerId);
  return `Home teleport on cooldown (${formatCooldownRemaining(remainingMs)} remaining)`;
}

// Send to client with remainingMs field
socket.send("homeTeleportFailed", {
  reason: error,
  remainingMs: remainingMs > 0 ? remainingMs : undefined,
});

• Already casting
• On cooldown (includes remainingMs)
• In combat
• Dead
• In duel arena

​

Visual Effects

​

Cast Effect (Channel Mode)

• Portal veil (cylinder with gradient)
• Lower orbital ring (bronze, rotating)
• Upper orbital ring (gold, counter-rotating)
• Crown ring (parchment, top of portal)

1. HOME_TELEPORT_CAST_START → spawn channel effect
2. Update every frame with progress-based animations
3. HOME_TELEPORT_FAILED or HOME_TELEPORT_CAST_CANCEL → stop effect
4. PLAYER_TELEPORTED → transition to arrival burst

• Portal anchored to player’s lowest bone position (feet/hips)
• Falls back to terrain height if bones unavailable
• Small ground clearance (0.015m) for visual grounding

​

Arrival Effect (Burst Mode)

• Rune circle
• Beam eruption
• Particle helix
• Shockwave rings

​

Events

​

HOME_TELEPORT_CAST_START

{
  castTimeMs: number;  // Cast duration (typically 10000)
}

• ClientTeleportEffectsSystem - Spawns channel-mode portal effect
• HomeTeleportButton - Enters casting state
• MinimapHomeTeleportOrb - Enters casting state

​

HOME_TELEPORT_FAILED

{
  reason: string;       // Human-readable rejection reason
  remainingMs?: number; // Remaining cooldown (if rejected due to cooldown)
}

• ClientTeleportEffectsSystem - Stops channel effect
• HomeTeleportButton - Enters cooldown or ready state
• MinimapHomeTeleportOrb - Enters cooldown or ready state

​

HOME_TELEPORT_CAST_CANCEL

• ClientTeleportEffectsSystem - Stops channel effect
• HomeTeleportButton - Returns to ready state
• MinimapHomeTeleportOrb - Returns to ready state

​

PLAYER_TELEPORTED

{
  playerId: string;
  position: { x: number; y: number; z: number };
  suppressEffect?: boolean;
}

• ClientTeleportEffectsSystem - Spawns arrival burst effect, stops channel effect
• HomeTeleportButton - Enters cooldown state
• MinimapHomeTeleportOrb - Enters cooldown state

​

Network Protocol

​

Client → Server

​

homeTeleport

• Success: homeTeleportCastStart packet
• Failure: homeTeleportFailed packet with reason

​

homeTeleportCancel

​

Server → Client

​

homeTeleportCastStart

{
  castTimeMs: number;  // Cast duration
}

​

homeTeleportFailed

{
  reason: string;       // Rejection reason
  remainingMs?: number; // Remaining cooldown (if applicable)
}

​

homeTeleportCastCancel

​

playerTeleported

{
  playerId: string;
  position: { x: number; y: number; z: number };
  suppressEffect?: boolean;
}

​

Server-Side Logic

​

Cast State Machine

1. Idle - Not casting
2. Casting - Cast in progress (10 seconds)
3. Cooldown - Recently teleported (30 seconds)

Idle → Casting (on homeTeleport request)
Casting → Cooldown (on cast complete)
Casting → Idle (on cancel/fail)
Cooldown → Idle (after 30 seconds)

​

Interruption Conditions

• Player moves
• Player enters combat
• Player takes damage
• Player dies

​

Cooldown Tracking

private castStates = new Map<string, {
  startTick: number;
  castTimeMs: number;
}>();

private cooldowns = new Map<string, number>(); // playerId → cooldown end tick

isOnCooldown(playerId: string): boolean {
  const endTick = this.cooldowns.get(playerId);
  if (!endTick) return false;
  return this.getCurrentTick() < endTick;
}

getCooldownRemaining(playerId: string): number {
  const endTick = this.cooldowns.get(playerId);
  if (!endTick) return 0;
  const currentTick = this.getCurrentTick();
  if (currentTick >= endTick) return 0;
  return (endTick - currentTick) * TICK_DURATION_MS;
}

​

Testing

​

Unit Tests

• Cast start and completion
• Cooldown enforcement (30 seconds)
• Interruption by movement/combat
• Multiple players casting simultaneously
• Cooldown expiration
• remainingMs field in rejection packets
• formatCooldownRemaining() edge cases

bunx vitest run packages/server/tests/unit/teleport/HomeTeleportManager.test.ts

​

Integration Tests

1. Click teleport button
2. Verify cast progress bar appears
3. Wait 10 seconds
4. Verify player teleports to spawn
5. Verify cooldown state
6. Wait 30 seconds
7. Verify ready state

​

Performance Considerations

​

Channel Effect Pool

​

Bone Iteration

const TELEPORT_GROUND_CONTACT_BONES = [
  "leftFoot", "rightFoot",
  "leftToes", "rightToes",
  "leftLowerLeg", "rightLowerLeg",
  "leftUpperLeg", "rightUpperLeg",
  "hips", "spine", "chest", "upperChest",
] as const;

​

Troubleshooting

​

Cast Effect Not Appearing

1. Check browser console for HOME_TELEPORT_CAST_START event
2. Verify ClientTeleportEffectsSystem is initialized
3. Check object pool availability (may be exhausted)

// Increase pool size if needed
const POOL_SIZE = 12; // Was 8

​

Cooldown Stuck

1. Check server logs for cooldown state
2. Verify remainingMs field in homeTeleportFailed packet
3. Check client is reading remainingMs correctly

​

Portal Not Grounded

1. Verify terrain system is ready (terrain.isReady())
2. Check getHeightAt() returns valid values
3. Verify bone transforms are available

1. Lowest bone position (if avatar has bones)
2. Terrain height (if terrain system ready)
3. Player position + small offset (final fallback)

​

See Also

• ClientTeleportEffectsSystem - Visual effects implementation
• HomeTeleportManager - Server-side logic
• GameConstants - Cooldown and cast time constants