|Name||Unique Objects vs Generic Objects|
|Description||There are a lot of object types in the Denizen object system, and not all of them behave the same way.
It can be useful to separate object types into categories to better understand how objects work, and how Denizen as a whole works.
While there are some hardlined separations, there are also some generalizations that don't necessarily hold exactly, but are still helpful.
One such generalization is the separation between Unique and Generic object types.
A UNIQUE object is the way you might assume all objects are.
Unique objects most notably include EntityTag objects and the derivative NPCTag / PlayerTag objects.
An entity object identifies in a form like 'e@<uuid>', where '<uuid>' is some unique ID that looks something like 'abc123-4d5e6f'.
This ID is randomly generated by the Minecraft server and is used to identify that one entity in the world separately from any other.
'e@abc123' is not "a creeper" to the engine, it is "that specific creeper over there".
An object that is unique must have some way to specify the exact single instance of it in the world, like the UUID used by entities.
A GENERIC object can be said to be a 'description' of a unique object.
A generic form of an EntityTag might look like 'e@creeper'.
Instead of "that specific creeper over there", it is instead "the concept of a creeper mob".
There is no way for the engine to read only the word 'creeper' and find out which specific creeper in the world it came from...
it could be any of them, there's often hundreds of creepers spawned somewhere in the world at any time.
Objects like items and materials are always generic. There is no unique identifier for any item, there is only the description.
An item usually looks something like 'i@stick'.
ItemTag objects can include more detail, like 'i@stick[lore=hi;display_name=My Stick;enchantments=sharpness,5]'...
but this is still just a description, and there could still be many items out there that match this description.
The consequences of this mostly relate to:
- How you adjust an object (eg change the lore of an item, or teleport an entity).
For example: you can't teleport the generic concept of a creeper, but you can certainly teleport a specific single creeper in the world.
- How reliable tags on the object are.
For example: the result of 'ItemTag.lore' on the item 'i@stick[lore=hi]' will always be 'hi' (because ItemTag are generic),
but the result of 'EntityTag.location' on the entity 'e@abc123' will change every tick as the entity moves,
or even become invalid if the entity dies (because that EntityTag is unique).
Here's where the separation gets muddy:
First, as mentioned, an EntityTag can either be unique ('e@abc123', 'n@42', etc.) OR generic ('e@creeper', 'e@zombie[custom_name=Bob]', etc).
Second, some object types exhibit a bit of both.
For example, a LocationTag refers to a unique block in the world (like, 'l@1,2,3,world' is always that specific block at that position),
but also is a generic object in terms of the location object itself - if for example you want to change the angle of a location,
you have to essentially 'create' a new location, that is an exact copy of the previous one but with a new yaw or pitch value.