A type representing entity names, currently a synonym for Text. In the future it is conceivable that it might become more complex.

Various properties that an entity can have, which affect how robots can interact with it.

How long an entity takes to regrow. This represents the minimum and maximum amount of time taken by one growth stage (there are two stages). The actual time for each stage will be chosen uniformly at random between these two values.

The default growth time (100, 200) for a growable entity with no growth time specification.

Properties of combustion.

The default combustion specification for a combustible entity with no combustion specification:

• ignition rate 0.5
• duration (100, 200)
• product ash

A record to hold information about an entity.

The constructor for Entity is intentionally not exported. To construct one manually, use the mkEntity function.

There are two main constraints on the way entities are stored:

1. We want to be able to easily modify an entity in one particular cell of the world (for example, painting one tree red).
2. In an inventory, we want to store identical entities only once, along with a count.

We could get (2) nicely by storing only names of entities, and having a global lookup table from names to entity records. However, storing names instead of actual entity records in the world makes (1) more complex: every time we modify an entity we would have to generate a fresh name for the modified entity and add it to the global entity table. This approach is also annoying because it means we can't just uses lenses to drill down into the properties of an entity in the world or in an inventory, but have to do an intermediate lookup in the global (mutable!) entity table.

On the other hand, if we just store entity records everywhere, checking them for equality becomes expensive. Having an inventory be a map with entities themselves as keys sounds awful.

The solution we adopt here is that every Entity record carries along a hash value of all the other fields. We just assume that these hashes are unique (a collision is of course possible but extremely unlikely). Entities can be efficiently compared just by looking at their hashes; they can be stored in a map using hash values as keys; and we provide lenses which automatically recompute the hash value when modifying a field of an entity record. Note also that world storage is still efficient, too: thanks to referential transparency, in practice most of the entities stored in the world that are the same will literally just be stored as pointers to the same shared record.

Create an entity with no orientation, an empty inventory, providing no capabilities (automatically filling in the hash value).

The Display explaining how to draw this entity in the world display.

The name of the entity.

The irregular plural version of the entity's name, if there is one.

Get a version of the entity's name appropriate to the number---the singular name for 1, and a plural name for any other number. The plural name is obtained either by looking it up if irregular, or by applying standard heuristics otherwise.

A longer, free-form description of the entity. Each Text value represents a paragraph.

The direction this entity is facing (if it has one).

How long this entity takes to grow, if it regrows.

Susceptibility to and duration of combustion

The name of a different entity yielded when this entity is grabbed, if any.

The properties enjoyed by this entity.

Test whether an entity has a certain property.

The capabilities this entity provides when equipped.

The inventory of other entities carried by this entity.

Get the hash of an entity. Note that this is a getter, not a lens; the Swarm.Game.Entity module carefully maintains some internal invariants ensuring that hashes work properly, and by golly, no one else is going to mess that up.

An EntityMap is a data structure containing all the loaded entities, allowing them to be looked up either by name or by what capabilities they provide (if any).

Build an EntityMap from a list of entities. The idea is that this will be called once at startup, when loading the entities from a file; see loadEntities.

Load entities from a data file called entities.yaml, producing either an EntityMap or a parse error.

Find an entity with the given name.

Find all entities which are devices that provide the given capability.

An inventory is really just a bag/multiset of entities. That is, it contains some entities, along with the number of times each occurs. Entities can be looked up directly, or by name.

A convenient synonym to remind us when an Int is supposed to represent how many of something we have.

The empty inventory.

Create an inventory containing one entity.

Create an inventory from a list of entities.

Create an inventory from a list of entities and their counts.

Look up an entity in an inventory, returning the number of copies contained.

Look up an entity by name in an inventory, returning a list of matching entities. Note, if this returns some entities, it does not mean we necessarily have any in our inventory! It just means we know about them. If you want to know whether you have any, use lookup and see whether the resulting Count is positive, or just use countByName in the first place.

Look up an entity by name and see how many there are in the inventory. If there are multiple entities with the same name, it just picks the first one returned from lookupByName.

Check whether an inventory contains at least one of a given entity.

Check whether an inventory has an entry for the given entity, even if there are 0 copies. In particular this is used to indicate whether a robot "knows about" an entity.

Get the entities in an inventory and their associated counts.

Check if the first inventory is a subset of the second. Note that entities with a count of 0 are ignored.

Check whether an inventory is empty, meaning that it contains 0 total entities (although it may still know about some entities, that is, have them as keys with a count of 0).

Compute the set of capabilities provided by the devices in an inventory.

List elements that possess a given Capability and exist with nonzero count in the inventory.

Groups entities by the capabilities they offer.

Insert an entity into an inventory. If the inventory already contains this entity, then only its count will be incremented.

Insert a certain number of copies of an entity into an inventory. If the inventory already contains this entity, then only its count will be incremented.

Delete a single copy of a certain entity from an inventory.

Delete a specified number of copies of an entity from an inventory.

Delete all copies of a certain entity from an inventory.

Union two inventories.

Subtract the second inventory from the first.