Hytale Playing Sounds Skill

Use this skill when playing sounds to players in Hytale plugins. Sounds are played using SoundUtil with a positional TransformComponent and a sound index resolved from the SoundEvent asset map.

Quick Reference

Concept	Description
SoundEvent	Asset map for resolving sound IDs to numeric indexes
SoundUtil	Utility class for playing sounds to players
SoundCategory	Classifies sound type (`SFX`, `UI`, `Music`, `Ambient`)
TransformComponent	Provides the 3D position where the sound plays
World.execute()	Required thread-safe execution context for sound playback

Sound Playback Flow

•Resolve the sound index from SoundEvent.getAssetMap()
•Get the player reference (Ref<EntityStore>)
•Get the world and entity store
•Execute on the world thread via world.execute()
•Get the TransformComponent for the sound position
•Play the sound via SoundUtil.playSoundEvent3dToPlayer()

Required Imports

java

import com.hypixel.hytale.server.core.modules.entity.component.TransformComponent;
import com.hypixel.hytale.server.core.modules.entity.EntityModule;
import com.hypixel.hytale.server.core.universe.world.World;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import com.hypixel.hytale.server.sound.SoundCategory;
import com.hypixel.hytale.server.sound.SoundEvent;
import com.hypixel.hytale.server.util.SoundUtil;
import com.hypixel.hytale.store.Ref;

Sound Indexes

Sounds are referenced by numeric index, resolved from the SoundEvent asset map using the sound's string key:

java

int index = SoundEvent.getAssetMap().getIndex("SFX_Cactus_Large_Hit");

See the full list of available sounds for valid sound keys.

Sound Categories

SoundCategory classifies the type of sound being played:

Category	Use Case
`SoundCategory.SFX`	Sound effects (combat, interactions, impacts)
`SoundCategory.UI`	User interface sounds (clicks, notifications)
`SoundCategory.Music`	Background music
`SoundCategory.Ambient`	Environmental/ambient audio

Getting the TransformComponent

The TransformComponent determines the 3D position of the sound. Two approaches:

From the Player (Recommended)

Plays the sound at the player's current position:

java

TransformComponent transform = store.getStore().getComponent(
    playerRef,
    EntityModule.get().getTransformComponentType()
);

From a Custom Position

Plays the sound at an arbitrary world position (player must be close enough to hear):

java

Vector3d position = new Vector3d(100, 64, 200);
Vector3f rotation = new Vector3f(0, 0, 0);
TransformComponent transform = new TransformComponent(position, rotation);

Basic Example

Play a sound to a player at their current position:

java

public void playSound(Player player) {
    int index = SoundEvent.getAssetMap().getIndex("SFX_Cactus_Large_Hit");
    World world = player.getWorld();
    EntityStore store = world.getEntityStore();
    Ref<EntityStore> playerRef = player.getReference();

    world.execute(() -> {
        TransformComponent transform = store.getStore().getComponent(
            playerRef,
            EntityModule.get().getTransformComponentType()
        );

        SoundUtil.playSoundEvent3dToPlayer(
            playerRef,
            index,
            SoundCategory.UI,
            transform.getPosition(),
            store.getStore()
        );
    });
}

Common Use Cases

Play a UI Sound on Event

java

public void onPlayerAction(Player player) {
    int soundIndex = SoundEvent.getAssetMap().getIndex("SFX_UI_Click");
    World world = player.getWorld();
    EntityStore store = world.getEntityStore();
    Ref<EntityStore> playerRef = player.getReference();

    world.execute(() -> {
        TransformComponent transform = store.getStore().getComponent(
            playerRef,
            EntityModule.get().getTransformComponentType()
        );

        SoundUtil.playSoundEvent3dToPlayer(
            playerRef,
            soundIndex,
            SoundCategory.UI,
            transform.getPosition(),
            store.getStore()
        );
    });
}

Play a Sound at a Specific Location

java

public void playSoundAtPosition(Player player, double x, double y, double z, String soundKey) {
    int soundIndex = SoundEvent.getAssetMap().getIndex(soundKey);
    World world = player.getWorld();
    EntityStore store = world.getEntityStore();
    Ref<EntityStore> playerRef = player.getReference();

    world.execute(() -> {
        Vector3d position = new Vector3d(x, y, z);
        Vector3f rotation = new Vector3f(0, 0, 0);
        TransformComponent transform = new TransformComponent(position, rotation);

        SoundUtil.playSoundEvent3dToPlayer(
            playerRef,
            soundIndex,
            SoundCategory.SFX,
            transform.getPosition(),
            store.getStore()
        );
    });
}

Play a Combat SFX

java

public void playCombatSound(Player player, String soundKey) {
    int soundIndex = SoundEvent.getAssetMap().getIndex(soundKey);
    World world = player.getWorld();
    EntityStore store = world.getEntityStore();
    Ref<EntityStore> playerRef = player.getReference();

    world.execute(() -> {
        TransformComponent transform = store.getStore().getComponent(
            playerRef,
            EntityModule.get().getTransformComponentType()
        );

        SoundUtil.playSoundEvent3dToPlayer(
            playerRef,
            soundIndex,
            SoundCategory.SFX,
            transform.getPosition(),
            store.getStore()
        );
    });
}

Utility Wrapper Class

Consider creating a utility wrapper for consistent sound playback:

java

public class Sounds {

    public static void playToPlayer(Player player, String soundKey, SoundCategory category) {
        int index = SoundEvent.getAssetMap().getIndex(soundKey);
        World world = player.getWorld();
        EntityStore store = world.getEntityStore();
        Ref<EntityStore> playerRef = player.getReference();

        world.execute(() -> {
            TransformComponent transform = store.getStore().getComponent(
                playerRef,
                EntityModule.get().getTransformComponentType()
            );

            SoundUtil.playSoundEvent3dToPlayer(
                playerRef,
                index,
                category,
                transform.getPosition(),
                store.getStore()
            );
        });
    }

    public static void playAtPosition(Player player, String soundKey, SoundCategory category,
                                      double x, double y, double z) {
        int index = SoundEvent.getAssetMap().getIndex(soundKey);
        World world = player.getWorld();
        EntityStore store = world.getEntityStore();
        Ref<EntityStore> playerRef = player.getReference();

        world.execute(() -> {
            Vector3d position = new Vector3d(x, y, z);
            Vector3f rotation = new Vector3f(0, 0, 0);
            TransformComponent transform = new TransformComponent(position, rotation);

            SoundUtil.playSoundEvent3dToPlayer(
                playerRef,
                index,
                category,
                transform.getPosition(),
                store.getStore()
            );
        });
    }

    public static void playSfx(Player player, String soundKey) {
        playToPlayer(player, soundKey, SoundCategory.SFX);
    }

    public static void playUi(Player player, String soundKey) {
        playToPlayer(player, soundKey, SoundCategory.UI);
    }
}

Best Practices

•Always use world.execute(): Sound playback must run on the world thread for thread safety
•Prefer player transform: Getting the transform from the player ensures they hear the sound; custom positions risk being out of audible range
•Choose the correct SoundCategory: This affects volume mixing and player audio settings
•Cache sound indexes: If playing the same sound frequently, resolve the index once and reuse it
•Validate sound keys: Ensure the sound key exists in the SoundEvent asset map before playing
•Don't spam sounds: Avoid playing many sounds in rapid succession as it can overwhelm the client audio

playSoundEvent3dToPlayer Parameters

Parameter	Type	Description
`playerRef`	`Ref<EntityStore>`	The target player reference
`soundIndex`	`int`	Numeric index from `SoundEvent.getAssetMap()`
`category`	`SoundCategory`	Sound classification (`SFX`, `UI`, `Music`, `Ambient`)
`position`	`Vector3d`	3D world position of the sound source
`store`	`Store<EntityStore>`	The entity store instance

Related APIs

•Notifications - For visual notifications with sounds
•Text Holograms - For visual world elements
•ECS - Entity Component System patterns

References

•Official Documentation
•Available Sounds List

code