Hytale Teleporting Players

Hytale Teleporting Players

Use this skill when teleporting players to a position or world in Hytale plugins. Teleportation works by attaching a Teleport component to the player entity with the desired target world and transform. You can only trigger teleports from the world where the player is currently present.

Source: https://hytalemodding.dev/en/docs/guides/plugin/teleporting-players

Quick Reference

Key Concepts

Teleport Component

Teleport is an ECS component. Adding it to a player entity triggers the teleport. It provides factory methods (createForPlayer) to configure the destination world and transform.

Transform

A Transform encapsulates a position and rotation:

• Position: Vector3d(x, y, z) — world coordinates
• Rotation: Rotation(yaw, pitch, 0) — the last value (roll) should always be 0

Constraints

• You can only trigger teleports from the world where the player is currently present.
• Requires a Ref<EntityStore> and Store<EntityStore> for the player entity.

Required Imports

import com.hypixel.hytale.server.world.World;
import com.hypixel.hytale.server.world.Transform;
import com.hypixel.hytale.server.world.Rotation;
import com.hypixel.hytale.server.world.Teleport;

import com.hypixel.ecs.Ref;
import com.hypixel.ecs.Store;
import com.hypixel.ecs.EntityStore;

import org.joml.Vector3d;

Basic Teleport (Position Only)

Teleport a player to x/y/z coordinates in a target world:

public static void teleportPlayer(Ref<EntityStore> ref, Store<EntityStore> store,
                                   World targetWorld, double x, double y, double z) {
    Transform transform = new Transform(x, y, z);
    Teleport teleport = Teleport.createForPlayer(targetWorld, transform);
    store.addComponent(ref, Teleport.getComponentType(), teleport);
}

Parameters

Teleport with Rotation

Teleport a player to a position and set their facing direction:

public static void teleportPlayer(Ref<EntityStore> ref, Store<EntityStore> store,
                                   World targetWorld, double x, double y, double z,
                                   float yaw, float pitch) {
    Transform transform = new Transform(
        new Vector3d(x, y, z),
        new Rotation(yaw, pitch, 0)  // Roll is always 0
    );
    Teleport teleport = Teleport.createForPlayer(targetWorld, transform);
    store.addComponent(ref, Teleport.getComponentType(), teleport);
}

Rotation Values

Transform Construction

Position-Only Transform

Transform transform = new Transform(x, y, z);

Position + Rotation Transform

Transform transform = new Transform(
    new Vector3d(x, y, z),       // Position
    new Rotation(yaw, pitch, 0)  // Rotation (roll always 0)
);

Usage Notes

• Thread safety: Execute teleport operations within the world's execution context (world.execute(() -> { ... })) if called from outside the world tick.
• Same-world teleport: Pass the player's current world as targetWorld to teleport within the same world.
• Cross-world teleport: Pass a different World object to move the player between worlds.
• Instance teleportation: For teleporting into instanced worlds, see the hytale-instances skill which provides higher-level APIs via InstancesPlugin.

Complete Example: Teleport Command Utility

import com.hypixel.ecs.EntityStore;
import com.hypixel.ecs.Ref;
import com.hypixel.ecs.Store;
import com.hypixel.hytale.server.world.Transform;
import com.hypixel.hytale.server.world.Rotation;
import com.hypixel.hytale.server.world.Teleport;
import com.hypixel.hytale.server.world.World;
import org.joml.Vector3d;

public class TeleportUtil {

    /**
     * Teleport a player to coordinates in a target world.
     */
    public static void teleport(Ref<EntityStore> ref, Store<EntityStore> store,
                                World targetWorld, double x, double y, double z) {
        Transform transform = new Transform(x, y, z);
        Teleport teleport = Teleport.createForPlayer(targetWorld, transform);
        store.addComponent(ref, Teleport.getComponentType(), teleport);
    }

    /**
     * Teleport a player to coordinates with a specific facing direction.
     */
    public static void teleport(Ref<EntityStore> ref, Store<EntityStore> store,
                                World targetWorld, double x, double y, double z,
                                float yaw, float pitch) {
        Transform transform = new Transform(
            new Vector3d(x, y, z),
            new Rotation(yaw, pitch, 0)
        );
        Teleport teleport = Teleport.createForPlayer(targetWorld, transform);
        store.addComponent(ref, Teleport.getComponentType(), teleport);
    }

    /**
     * Teleport a player to a pre-built Transform in a target world.
     */
    public static void teleport(Ref<EntityStore> ref, Store<EntityStore> store,
                                World targetWorld, Transform transform) {
        Teleport teleport = Teleport.createForPlayer(targetWorld, transform);
        store.addComponent(ref, Teleport.getComponentType(), teleport);
    }
}