The roles system
The SpaceObject class has methods for assigning and removing 'roles' to objects.
Roles are like sides but can be more dynamic and are not seen by the simulation. You can have multiple roles on an object. Roles can be used in targeting etc.
** This need more documentation** placing examples for now
Adding a role
add_role(some_id, 'spy')
Remove a role
remove_role(some_id, 'spy')
Check for a role
if has_role(some_id, 'spy')
pass
Using with targeting
close = closest(some_id, role("spy"))
# class names are included in roles
close = closest(some_id, role("station"))
# side is included in roles
close = closest(some_id, role("tsn"))
API: Roles
add_role(set_holder, role)
Add a role to an agent or a set of agents.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
set_holder
|
Agent | int | set[Agent | int]
|
An agent or ID or a set of agents or IDs. |
required |
role
|
str
|
The role to add. |
required |
all_roles(roles)
Returns a set of all the agents which have all of the given roles.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
roles
|
str
|
A comma-separated list of roles. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: a set of agent IDs. |
any_role(roles)
Returns a set of all the agents which have any of the given roles.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
str
|
The role, or a comma-separated list of roles. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: a set of agent IDs. |
get_role_list(id_or_obj)
Returns a list of role names an Agent has.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The object or ID. |
required |
Returns:
| Type | Description |
|---|---|
|
list[str]: The list of roles. |
get_role_string(id_or_obj)
Returns a comma-separated list of role names an Agent has.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The Agent or id. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
A comma-separated string. |
has_any_role(so, roles)
Check if an agent has any of the roles specified.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
An agent or id. |
required |
role
|
str
|
A comma-separated list of roles. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if the agent has one or more of the roles. |
has_role(so, role)
Check if an agent has the specified role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
An agent or id. |
required |
role
|
str
|
The role to test for |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if the agent has that role |
has_roles(so, roles)
Check if an agent has all the roles specified.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
An agent or id. |
required |
role
|
str
|
A comma-separated list of roles. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if the agent has all the listed roles. |
remove_role(agents, role)
Remove a role from an agent or a set of agents.a
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
agents
|
Agent | int | set[Agent | int]
|
An agent or ID or a set of agents or IDs. |
required |
role
|
str
|
The role to add. |
required |
role(role)
Returns a set of all the agents with a given role as a set of IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
str
|
The role. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: a set of agent IDs. |
role_allies(id_or_obj)
Returns a set of the IDs of all objects allied with the specified object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The object for which to get the allies. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: a set of agent IDs |
role_ally_add(id_or_obj, side)
Adds a side as an ally and add all the objects with that side to the specified object's ally list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The object for which to add allies. |
required |
side
|
str
|
The side string. |
required |
role_ally_remove(id_or_obj, side)
Remove a side as an ally and remove all objects of that side from the specified object's ally list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The object from which to remove allies. |
required |
side
|
str
|
The side string. |
required |
role_are_allies(id_or_obj, other_id_or_obj)
Check if the two objects are allied.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id_or_obj
|
Agent | int
|
The first object. |
required |
other_id_or_obj
|
Agent | int
|
The second object. |
required |
Returns: bool: True if they are allied.