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[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