Teleporting

Hytale uses an ECS approach for teleportation — there’s no player.teleport(location) method. Instead, you add a Teleport component to the player entity. TeleportSystems reacts to the component being added, immediately teleports the player, sends the client packet, records teleport history, and removes the component. This is what the built-in /tp command uses internally.

Package: com.hypixel.hytale.server.core.modules.entity.teleport.Teleport

Note

The examples below use Store and Ref to interact with the player entity. Where you get them depends on context:

• Commands — AbstractPlayerCommand passes both to execute()
• Events — event.getPlayerRef() gives the Ref, world.getEntityStore().getStore() gives the Store

See Entity References for details.

Same-World Teleport

Keeping Current Rotation

You can preserve the player’s current look direction so they aren’t disoriented:

TransformComponent transform = store.getComponent(ref, TransformComponent.getComponentType());

Teleport teleport = Teleport.createForPlayer(
    new Vector3d(x, y, z),
    transform.getRotation()
);
store.addComponent(ref, Teleport.getComponentType(), teleport);

Setting a Specific Look Direction

For warps or portals where the player should face a specific direction (e.g. looking at a sign or down a corridor):

// rotation values are in radians
float pitch = 0f;   // vertical angle (positive = down)
float yaw = 1.57f;  // horizontal angle
float roll = 0f;     // typically 0

Teleport teleport = Teleport.createForPlayer(
    targetPos,
    new Vector3f(pitch, yaw, roll)
);
store.addComponent(ref, Teleport.getComponentType(), teleport);

createForPlayer automatically splits the rotation into body and head — the body only rotates horizontally (yaw), while the head gets the full rotation. Use createExact if you need to control body and head independently.

Cross-World Teleport

Pass the target World as the first argument:

Teleport teleport = Teleport.createForPlayer(targetWorld, position, rotation);
store.addComponent(ref, Teleport.getComponentType(), teleport);

Cross-world teleports execute asynchronously.

Factory Methods

Method	Description
createForPlayer(Vector3d, Vector3f)	Same-world teleport, splits head/body rotation
createForPlayer(Transform)	Same-world, rotation from transform
createForPlayer(World, Vector3d, Vector3f)	Cross-world teleport
createForPlayer(World, Transform)	Cross-world, rotation from transform
createExact(Vector3d, Vector3f, Vector3f)	Exact body + head rotation (no split)
createExact(Vector3d, Vector3f)	Exact body rotation, no head rotation

Modifiers

// keep the entity's current velocity (default resets it)
Teleport teleport = Teleport.createForPlayer(position, rotation)
    .withoutVelocityReset();

// set head rotation separately
Teleport teleport = Teleport.createForPlayer(position, rotation)
    .setHeadRotation(new Vector3f(pitch, yaw, roll));

Why Not TransformComponent?

TransformComponent.teleportPosition() is a low-level method that skips client synchronization, teleport history, and velocity reset. Only use it for non-player entities. See TransformComponent for details.