UUIDComponent

Unique identifier for entities. Used for entity lookup, persistence, and cross-reference.

Access

UUIDComponent uuidComponent = store.getComponent(ref, UUIDComponent.getComponentType());
UUID uuid = uuidComponent.getUuid();

Creating UUIDs

// generate random UUID (standard Java)
UUIDComponent component = UUIDComponent.randomUUID();

// generate version 3 UUID (Hytale's default)
UUIDComponent component = UUIDComponent.generateVersion3UUID();

// from existing UUID
UUIDComponent component = new UUIDComponent(existingUuid);

Adding to Entities

// when spawning via Holder
Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
holder.addComponent(UUIDComponent.getComponentType(), UUIDComponent.randomUUID());

// for players (use their account UUID)
holder.putComponent(UUIDComponent.getComponentType(), new UUIDComponent(playerUuid));

Entity Lookup

The EntityStore maintains a UUID-to-reference map for fast lookup:

// from World (recommended)
Ref<EntityStore> ref = world.getEntityRef(uuid);

// from EntityStore directly
Ref<EntityStore> ref = world.getEntityStore().getRefFromUUID(uuid);

// from ComponentAccessor (in ECS context)
Ref<EntityStore> ref = componentAccessor.getExternalData().getRefFromUUID(uuid);

Automatic Assignment

Entities spawned from prefabs or world generation automatically receive a new UUID via EntitySystems.OnLoadFromExternal. This ensures uniqueness even if the prefab has a UUID defined.

Duplicate Prevention

The EntityStore.UUIDSystem monitors entity additions. If an entity is added with a UUID that already exists:

1. The new entity is immediately removed
2. A warning is logged

When cloning entities, always replace the UUID:

Holder<EntityStore> copy = original.toHolder();
copy.replaceComponent(UUIDComponent.getComponentType(), UUIDComponent.randomUUID());
store.addEntity(copy, AddReason.SPAWN);

Persistent References

For storing entity references that survive serialization, use PersistentRef:

public class MyComponent implements Component<EntityStore> {
    private PersistentRef targetRef = new PersistentRef();

    // set target
    public void setTarget(Ref<EntityStore> ref, ComponentAccessor<EntityStore> accessor) {
        targetRef.setEntity(ref, accessor);  // stores UUID internally
    }

    // get target (resolves UUID to ref, caches result)
    public Ref<EntityStore> getTarget(ComponentAccessor<EntityStore> accessor) {
        return targetRef.getEntity(accessor);
    }
}

PersistentRef stores the UUID for serialization and caches the resolved reference for performance.

Command Arguments

Entity UUIDs can be passed as command arguments:

// in command definition
.arg(ArgTypes.ENTITY.required("target"))

// in execute
UUID uuid = context.get("target");
Ref<EntityStore> ref = world.getEntityStore().getRefFromUUID(uuid);

Immutability

The UUID component is immutable once created. The clone() method returns the same instance since there’s no mutable state.