Teleport Component

The Teleport component provides flexible teleportation functionality that moves players to specific destinations in your Hyperfy world through events. Think of it as a precision teleportation system that can instantly transport players to any location in your scene with configurable triggers and synchronization.

Important: This component handles instant player teleportation to predefined destinations. It reads the world position of a destination node and teleports players there when triggered by events. It works across all connected players with proper server-client coordination.

Download Component

What Does It Do?

The Teleport component is like having a precision teleportation system for your 3D world. You can:

• Teleport players instantly to any location in your scene
• Create spawn points for player respawning
• Build interactive portals with proximity triggers
• Set up fast travel systems between different areas
• Sync teleportation across all players in multiplayer environments
• Chain actions by triggering other components when teleportation completes
• Handle multiple destinations with different trigger events

Important: This component uses a destination node's world position to determine where players will be teleported. The destination node should be positioned exactly where you want players to appear, and collision should be enabled to prevent players from falling through geometry.

Video Demo

Watch the Teleport component in action: instant player teleportation, spawn points, interactive portals, and synchronized effects across all players.

Properties

Basic Settings

Property	Type	Default	Description
App ID	text	Auto	Unique name for this component (auto-generated)
Node Name	text	""	Required: Name of the destination node in your scene
Debug Logs	toggle	false	Show detailed information for troubleshooting
Add Collision	toggle	true	Make the destination node solid (prevents falling through)

Teleport Settings

Property	Type	Default	Description
Accept Any Event	toggle	false	Listen to any signal sent to this component?
Event Listeners	textarea	[]	List of events that trigger teleportation

How Events Work

The Teleport component listens for "signals" (events) from other components. When it receives a signal with a playerId, it teleports that player to the destination node's position. The component uses its unique App ID (generated by Hyperfy) to identify itself in the event system.

Event Format

In the Event Listeners field, you can specify events like this:

[
  {
    "id": "a1b2c3d4e",
    "actions": [
      {
        "type": "teleport",
        "params": {}
      }
    ]
  }
]

Note: When referencing this component in events from other components, use the App ID that Hyperfy generated for this component. Also, when duplicating components, be sure you make the app unique, so it has a new AppID.

Action Types

Action	Description	Parameters
teleport	Teleport player to destination	None (playerId comes from event)

Event Parameters

When an event triggers teleportation, the event must include:

Parameter	Type	Description
playerId	string	Required: ID of the player to teleport

Emitted Events

The component automatically emits these events when teleportation completes:

Event	Description	Payload
teleport-complete-<appID>	Emitted when teleportation is successful	{ playerId, destination, timestamp }

Common Use Cases

1. Spawn Points

• Object: A spawn location node
• Event: Player respawns or enters world
• Action: Player is teleported to spawn point

2. Interactive Portals

• Object: A portal destination node
• Event: Player touches portal trigger
• Action: Player is teleported to portal destination

3. Fast Travel Systems

• Object: Multiple destination nodes
• Event: Player selects travel destination
• Action: Player is teleported to selected location

4. Boss Room Entry

• Object: Boss room entrance node
• Event: Player defeats prerequisite boss
• Action: Player is teleported to boss room

5. Puzzle Completion

• Object: Reward area destination
• Event: Player solves puzzle
• Action: Player is teleported to reward area

Step-by-Step Setup

1. Create Destination Node

• Add a 3D model or node to your scene where you want players to appear
• Name it something descriptive like "teleport-destination"
• Position it exactly where you want players to land

2. Add the Component

• Drag the Teleport component into your scene
• Select the destination node you created

3. Configure Basic Settings

• Set the Node Name to match your destination node's name
• Enable Add Collision to prevent players from falling through
• Choose if the destination should be visible

4. Configure Events

• In Event Listeners, add the events that should trigger teleportation
• Use the JSON format shown above
• Replace event names with actual events from other components

5. Set Up Triggers

• Enable Accept Any Event for simpler setups
• Or configure specific event listeners for more control
• Test with debug logs enabled

6. Test Your Setup

• Enable Debug Logs to see what's happening
• Trigger your events and watch players teleport
• Check that all players see the same teleportation effects

Tips for Designers

Positioning Destination Nodes

• Place destination nodes exactly where you want players to appear
• Ensure there's solid ground beneath the destination
• Test with different player sizes and positions

Planning Teleportation Systems

• Think about when players should be teleported
• Consider timing and delays for dramatic effects
• Plan for both single-player and multiplayer scenarios

Testing Your Setup

• Always test with multiple players
• Use debug logs to troubleshoot issues
• Test edge cases (what happens if players disconnect?)

Performance Considerations

• Teleportation is instant - no performance impact
• Consider the impact on player experience
• Test with different network conditions

Troubleshooting

Player Not Teleporting

• Check that the Node Name matches your destination node exactly
• Verify that the event includes a playerId parameter
• Enable Debug Logs to see what's happening

Player Falls Through Ground

• Enable Add Collision on the destination node
• Check that the destination node has solid geometry
• Verify the destination position is above solid ground

Teleportation Not Syncing

• Make sure Accept Any Event is enabled for server-client communication
• Check that the event is being sent correctly
• Verify all players are connected

Multiple Destinations Not Working

• Create separate teleport components for each destination
• Use different event IDs for each destination
• Ensure each component has a unique App ID

Events Not Triggering

• Check that the event id matches exactly
• Verify the Event Listeners JSON format is correct
• Test with Accept Any Event enabled

Best Practices

• Start Simple: Test with basic teleportation before adding complexity
• Use Descriptive Names: Make your destination node names clear
• Plan for Multiplayer: Consider how teleportation affects all players
• Test Thoroughly: Always test with multiple players and scenarios
• Use Debug Logs: Enable debug mode during development
• Document Your Setup: Keep notes on your teleportation configurations
• Position Carefully: Place destination nodes precisely where players should appear
• Enable Collision: Always enable collision on destination nodes
• Chain Actions: Use teleport-complete events to trigger additional effects
• Test Edge Cases: Verify behavior with different player states and network conditions