Entity References

Entity Definitions

Before entities can be used as first-class objects, an entity definition needs to be supplied.

note

Amethyst currently does not provide definitions for Minecraft entities. Eventually they will be provided in libminecraft. See this issue for updates.

Entity definitions work similarly to structs. They can have properties and methods, but currently no virtual methods. Properties in entity definitions correspond to NBT tags that the entity has. To define one, use the entitydef keyword:

entitydef minecraft:entity {
    bool Invulnerable;
    short Air;
}

Entity definitions can also have base classes:

entitydef minecraft:living_entity implements entity {
    float Health;
}

Check the Minecraft Wiki for entity data information.

warning

Beware that not all NBT properties listed are always defined on a given instance of the entity. Accessing an undefined property will result in undefined behavior.

For example, OnGround is undefined if false.

Using Definitions

Amethyst interacts with entities through entity references which take the form of a unique ID score (amethyst_id). UUIDs are not used due to the performance impact of the nbt target selector argument. To create a reference to an existing entity, cast a minecraft:target to an entity definition:

living_entity cow = @e[type="cow", limit=1];

note

While limit=1 is not technically required, it prevents Amethyst giving an ID to every entity that fits the target selector. If multiple entities are selected, the last entity processed will be the one chosen.

Entity NBT can be accessed just like structs:

print(cow.Air);
cow.Health = 1;

amethyst:dummy

Since minecraft:entity may not always be defined, a special all-encompasing entity type exists. amethyst:dummy can be implicitly casted to any entity definition and is the default base type when using entitydef.

Summoning

The other way to reference entities is to directly summon them.

living_entity cow = summon("cow");

minecraft:summon currently returns an amethyst:dummy, so var should not be used in this context.

Existence Checks

There is currently no mechanism for automatically checking if the reference was created successfully. Instead, entity references can be checked manually:

if (!entity) {
    print("Uh oh!");
}

Additionally, entity references can be used in as, at, minecraft:kill, and anything else that uses minecraft:target.

Manual Referencing

In some cases, it may be necessary to manually reference an entity. Calling amethyst:core/entity/ref with no arguments will return a reference to @s.