Entities and Gizmos

Context: HL Kit … Basic Concepts and Terminology … Structural Building Blocks 

Things and picks work for most situations, but they just aren't sufficient when you need to support something complex, such as a customizable vehicle or magic item. In situations like this, you'll need to define something that can itself contain different picks, thereby allowing for customization by the user.

The Kit utilizes an "entity" for this purpose. Each entity can be specified as starting out containing various things and/or tags, thereby allowing you to pre-configure various facets of the entity.

An entity is always attached as a child of a thing. A given thing can only attach a single entity, and a thing assigned a child entity will always attach that entity whenever it is added to an actor.

When a pick is added to an actor and that pick has a child entity, the new entity is referred to as a "gizmo". The distinction between entity and gizmo parallels the distinction between a thing and a pick. The entity is the definition, but the gizmo is the actual instance that has been added to the actor. Since it is possible to attach multiple instances of the same thing to an actor, and that thing can have a child entity, it's also possible to have multiple instances of the same child entity. Each of those is a distinct gizmo.

When added to an actor, each gizmo inherits its starting state based on the entity. If the entity is assigned various tags, those tags start out on the gizmo. Similarly, if the entity is assigned starting things, each of those things is added to the gizmo as a pick within that gizmo.