Entities — Balladeer 0.39.0

# Entities

## Entity objects

The `Entity` class is the base for all objects in your narrative. Earlier we saw the need for more than one name for the same thing. Entities are like that too. They can have many names, many types, and many states.

class balladeer.lite.entity.Entity

  All parameters are optional. Without any, you’ll get an anonymous Entity which is unique by virtue of its uid:

      >>> Entity()
      Entity(names=[], types=set(), states={}, uid=UUID('76f72aba-056c-4d84-9da0-7e8c8451cf7e'), links=set(), sketch='', aspect='', revert='')

  As a convenience you can pass an Entity a single name argument, but note how this is stored in the names attribute of the created object:

      >>> Entity(name="Anna")
      Entity(names=['Anna'], types=set(), states={}, uid=UUID('0797bd07-9cdc-47c0-9cae-f6cae5d69ded'), links=set(), sketch='', aspect='', revert='')

  Of course, you can do this:

      >>> Entity(names=["Bob", "Robert"])
      Entity(names=['Bob', 'Robert'], types=set(), states={}, uid=UUID('bc8ba6bf-565e-4588-97cc-337dd54bdc31'), links=set(), sketch='', aspect='', revert='')

  Entity type works the same way, except the supporting structure is a set. The declared types of an entity should all be strings:

      >>> Entity(name="Chuck", type="Squirrel")
      Entity(names=['Chuck'], types={'Squirrel'}, states={}, uid=UUID('5aab38be-3147-4647-a635-c999943ff017'), links=set(), sketch='', aspect='', revert='')

      >>> Entity(name="Chuck", types={"Squirrel", "Cartoon"})
      Entity(names=['Chuck'], types={'Squirrel', 'Cartoon'}, states={}, uid=UUID('a468f8e5-1372-45a1-8795-dab5be51902a'), links=set(), sketch='', aspect='', revert='')

  Entity objects have a links attribute, which allows you to associate one Entity with another.

      >>> a, b = (Entity(), Entity())
      >>> a.links.add(b.uid)
      Entity(names=[], types=set(), states={}, uid=UUID('e594b6ad-88df-4199-9694-18acc788b81d'), links={UUID('aa66771b-5ba6-40fe-857d-d7c57099a013')}, sketch='', aspect='', revert='')

  To delete a link:

      >>> a.links.discard(b.uid)

  There are three `Speech` attributes, which you can modify at any time:

  aspect

    Here you can record this entity’s most recent mood or disposition.

  revert

    This is a backup for a previous aspect, so you can revert to it after a temporary change.

  sketch

    This is a piece of speech which should be always true of the entity object. It will be processed as a string with format specifiers. It may contain named arguments to reference names, aspect, etc.

  property name: str

    Return a random choice of the object’s declared names.

  property description: str

    Return a description of the object based on its sketch and other attributes

## Entity state

Entity objects have methods and properties to support state allocation.

Entity.set_state(*args: tuple[balladeer.lite.types.State | int])

  Set a state value on the object.

      >>> entity = Entity()
      >>> entity.set_state(Politics.ind)
      Entity(names=[], types=set(), states={'Politics': <Politics.ind: ['Independent']>}, uid=UUID('4f02535e-b386-400c-9297-350fd73cd6fa'), links=set(), sketch='', aspect='', revert='')

  As a special case, an argument of type int is also considered a state value:

      >>> entity = Entity()
      >>> entity.set_state(12)
      Entity(names=[], types=set(), states={'int': 12}, uid=UUID('4f02535e-b386-400c-9297-350fd73cd6fa'), links=set(), sketch='', aspect='', revert='')

  You may supply multiple state values to this method.

      >>> entity = Entity()
      >>> entity.set_state(Politics.ind, 12)
      Entity(names=[], types=set(), states={'Politics': <Politics.ind: ['Independent']>, 'int': 12}, uid=UUID('4f02535e-b386-400c-9297-350fd73cd6fa'), links=set(), sketch='', aspect='', revert='')

  The return value is the entity object, allowing a declarative style of state assignment as follows:

      >>> entity = Entity().set_state(Politics.ind, 12)

Entity.get_state(typ: ~balladeer.lite.types.State | str = <class 'int'>)

  Get a state by type or type name.

      >>> entity.get_state(Politics)
      <Politics.ind: ['Independent']>

      >>> entity.get_state("Politics")
      <Politics.ind: ['Independent']>

      >>> entity.get_state(int)
      12

      >>> entity.get_state("int")
      12

  This method returns None if the state type is not set on the object.

property Entity.state

  This property provides an alternative idiom when allocating a single state:

      >>> entity.state = Politics.ind

  When used to access state, it will return integer state only:

      >>> entity.state
      12