neighborly package

Subpackages

Submodules

neighborly.config module

neighborly.data_analysis module

neighborly.data_collection module

Data collection.

This module contains functionality for collecting and exporting data from a simulation.

Its structure is informed by the data collection layer of Mesa, an agent-based modeling library written in Python. Here we adapt their functionality to fit the ECS architecture of the simulation.

class neighborly.data_collection.DataCollectionSystems[source]

Bases: neighborly.ecs.SystemGroup

System group for collecting data.

Any system that collects data during the course of the simulation should belong to this group.

class neighborly.data_collection.DataTables(tables: Optional[dict[str, tuple[str, ...]]] = None)[source]

Bases: object

A shared resource that collects data from the simulation into tables.

add_data_row(table_name: str, row_data: dict[str, Any]) → None[source]

Add a new row of data to a table.

Parameters

table_name – The table to add the row to.
row_data – A row of data to add to the table where each dict key is the name of the column.

create_table(table_name: str, column_names: tuple[str, ...]) → None[source]

Create a new table for data collection.

Parameters

table_name – The name of the new table.
column_names – The names of columns within the table.

get_data_frame(table_name: str) → polars.dataframe.frame.DataFrame[source]

Create a Polars data frame from a table.

Parameters: table_name – The name of the table to retrieve.
Returns: A polars DataFrame.
Return type: pl.DataFrame

to_dict() → dict[str, Any][source]: Serialize the object to a JSON-serializable dict.

class neighborly.data_collection.DataTablesIterator(table_names: Sequence[str], tables: neighborly.data_collection.DataTables)[source]

Bases: object

Iterator for DataTables resource.

idx: int: The current index in the table names tuple.

table_names: tuple[str, ...]: table names to iterate over.

tables: neighborly.data_collection.DataTables: Tables to iterate over.

neighborly.datetime module

Simulation date representation.

Implements a 12 month calendar

neighborly.datetime.MONTHS_PER_YEAR = 12: The number of months per calendar year.

class neighborly.datetime.SimDate(year: int = 1, month: int = 1)[source]

Bases: object

Records the current date of the simulation counting in 1-month increments.

copy() → neighborly.datetime.SimDate[source]: Create a copy of this date.

increment(months: int = 0, years: int = 0) → None[source]: Increment the date by the given time.

increment_month() → None[source]: Increments the month by one.

property month: int: The current month of the year [1 - 12].

to_iso_str() → str[source]

Create an ISO date string of format YYYY-MM.

Returns: The date string.
Return type: str

property total_months: int: Get the total number of elapsed months since month 1, year 1.

property year: int: The current year.

neighborly.ecs module

Entity Component System

This ECS implementation blends Unity-style GameObjects with the ECS logic from the Python esper library and the Bevy Game Engine.

This ECS implementation is not thread-safe. It assumes that everything happens sequentially on the same thread.

Sources:

class neighborly.ecs.Active[source]

Bases: neighborly.ecs.TagComponent

Tags a GameObject as active within the simulation.

class neighborly.ecs.Component[source]

Bases: abc.ABC

A collection of data attributes associated with a GameObject.

property gameobject: neighborly.ecs.GameObject: Get the GameObject instance for this component.

on_add() → None[source]: Lifecycle method called when the component is added to a GameObject.

on_remove() → None[source]: Lifecycle method called when the component is removed from a GameObject.

abstract to_dict() → dict[str, Any][source]: Serialize the component to a JSON-serializable dictionary.

exception neighborly.ecs.ComponentNotFoundError(component_type: Type[neighborly.ecs.Component])[source]

Bases: Exception

Exception raised when attempting to access a component that does not exist.

component_type: Type[neighborly.ecs.Component]: The type of component not found.

message: str: An error message.

class neighborly.ecs.Event(world: neighborly.ecs.World)[source]

Bases: abc.ABC

Events signal when things happen in the simulation.

dispatch() → None[source]: Dispatch the event to registered event listeners.

property event_id: int: A unique ordinal ID for this event.

to_dict() → dict[str, Any][source]: Serialize the event to a JSON-compliant dict.

property world: neighborly.ecs.World: The world instance to fire this event on.

class neighborly.ecs.EventManager(world: neighborly.ecs.World)[source]

Bases: object

Manages event listeners for a single World instance.

dispatch_event(event: neighborly.ecs.Event) → None[source]

Fire an event and trigger associated event listeners.

Parameters: event – The event to fire

get_next_event_id() → int[source]: Get an ID number for a new event instance.

on_any_event(listener: Callable[[neighborly.ecs.Event], None]) → None[source]

Register a listener function to all event types.

Parameters: listener – A function to be called any time an event fires.

on_event(event_type: Type[neighborly.ecs._ET_contra], listener: Callable[[neighborly.ecs._ET_contra], None]) → None[source]

Register a listener function to a specific event type.

Parameters

event_type – The type of event to listen for.
listener – A function to be called when the given event type fires.

class neighborly.ecs.GameObject(unique_id: int, world: neighborly.ecs.World, component_manager: esper.World, name: str = '')[source]

Bases: object

A reference to an entity within the world.

GameObjects wrap a unique integer identifier and provide an interface to access associated components and child/parent gameobjects.

activate() → None[source]: Tag the GameObject as active.

add_child(gameobject: neighborly.ecs.GameObject) → None[source]

Add a child GameObject.

Parameters: gameobject – A GameObject instance.

add_component(component: neighborly.ecs._CT) → neighborly.ecs._CT[source]

Add a component to this GameObject.

Parameters: component – The component.
Returns: The added component
Return type: _CT

children: list[neighborly.ecs.GameObject]: Child GameObjects below this one in the hierarchy.

deactivate() → None[source]: Remove the Active tag from a GameObject.

destroy() → None[source]: Remove a GameObject from the world.

property exists: bool

Check if the GameObject still exists in the ECS.

Returns: True if the GameObject exists, False otherwise.
Return type: bool

get_component(component_type: Type[neighborly.ecs._CT]) → neighborly.ecs._CT[source]

Get a component associated with a GameObject.

Parameters: component_type – The class type of the component to retrieve.
Returns: The instance of the component with the given type.
Return type: _CT

get_component_in_child(component_type: Type[neighborly.ecs._CT]) → tuple[int, _CT][source]

Get a single instance of a component type attached to a child.

Parameters: component_type – The class type of the component.
Returns: A tuple containing the ID of the child and an instance of the component.
Return type: tuple[int, _CT]

Notes

Performs a depth-first search of the children and their children and returns the first instance of the component type.

get_component_in_children(component_type: Type[neighborly.ecs._CT]) → list[tuple[int, _CT]][source]

Get all the instances of a component attached to children of a GameObject.

Parameters: component_type – The class type of the component
Returns: A list containing tuples with the ID of the children and the instance of the component.
Return type: list[tuple[int, _CT]]

get_component_types() → tuple[Type[neighborly.ecs.Component], ...][source]

Get the class types of all components attached to the GameObject.

Returns: Collection of component types.
Return type: tuple[Type[Component], …]

get_components() → tuple[neighborly.ecs.Component, ...][source]

Get all components associated with the GameObject.

Returns: Component instances
Return type: tuple[Component, …]

has_component(component_type: Type[neighborly.ecs.Component]) → bool[source]

Check if this entity has a component.

Parameters: component_type – The class type of the component to check for.
Returns: True if the component exists, False otherwise.
Return type: bool

has_components(*component_types: Type[neighborly.ecs.Component]) → bool[source]

Check if a GameObject has one or more components.

Parameters: *component_types – Class types of components to check for.
Returns: True if all component types are present on a GameObject.
Return type: bool

property is_active: bool: Check if a GameObject is active.

property metadata: dict[str, Any]: Get the metadata associated with this GameObject.

property name: str: Get the GameObject’s name

parent: Optional[neighborly.ecs.GameObject]: The parent GameObject that this GameObject is a child of.

remove_child(gameobject: neighborly.ecs.GameObject) → None[source]

Remove a child GameObject.

Parameters: gameobject – The GameObject to remove.

remove_component(component_type: Type[neighborly.ecs.Component]) → bool[source]

Remove a component from the GameObject.

Parameters: component_type – The type of the component to remove.
Returns: Returns True if component is removed, False otherwise.
Return type: bool

to_dict() → dict[str, Any][source]

Serialize the GameObject to a dict.

Returns: A dict containing the relevant fields serialized for JSON.
Return type: dict[str, Any]

try_component(component_type: Type[neighborly.ecs._CT]) → Optional[neighborly.ecs._CT][source]

Try to get a component associated with a GameObject.

Parameters: component_type – The class type of the component.
Returns: The instance of the component.
Return type: _CT or None

property uid: int: A GameObject’s ID.

property world: neighborly.ecs.World: The World instance to which a GameObject belongs.

class neighborly.ecs.GameObjectManager(world: neighborly.ecs.World)[source]

Bases: object

Manages GameObject and Component Data for a single World instance.

clear_dead_gameobjects() → None[source]: Delete gameobjects that were removed from the world.

property component_manager: esper.World: Get the esper world instance with all the component data.

destroy_gameobject(gameobject: neighborly.ecs.GameObject) → None[source]

Remove a gameobject from the world.

Parameters: gameobject – The GameObject to remove.

Note

This component also removes all the components from the gameobject before destruction.

property gameobjects: Iterable[neighborly.ecs.GameObject]

Get all gameobjects.

Returns: All the GameObjects that exist in the world.
Return type: list[GameObject]

get_gameobject(gameobject_id: int) → neighborly.ecs.GameObject[source]

Get a GameObject.

Parameters: gameobject_id – The ID of the GameObject.
Returns: The GameObject with the given ID.
Return type: GameObject

has_gameobject(gameobject_id: int) → bool[source]

Check that a GameObject exists.

Parameters: gameobject_id – The UID of the GameObject to check for.
Returns: True if the GameObject exists. False otherwise.
Return type: bool

spawn_gameobject(components: Optional[list[neighborly.ecs.Component]] = None, name: str = '') → neighborly.ecs.GameObject[source]

Create a new GameObject and add it to the world.

Parameters

components – A collection of component instances to add to the GameObject.
name – A name to give the GameObject.

Returns

The created GameObject.

Return type

GameObject

world: neighborly.ecs.World: The manager’s associated World instance.

exception neighborly.ecs.GameObjectNotFoundError(gameobject_id: int)[source]

Bases: Exception

Exception raised when attempting to access a GameObject that does not exist.

gameobject_id: int: The ID of the desired GameObject.

message: str: An error message.

class neighborly.ecs.ISystem[source]

Bases: abc.ABC

Abstract Interface for ECS systems.

abstract on_add(world: neighborly.ecs.World) → None[source]

Lifecycle method called when the system is added to the world.

Parameters: world – The world instance the system is mounted to.

abstract on_destroy(world: neighborly.ecs.World) → None[source]

Lifecycle method called when a system is removed from the world.

Parameters: world – The world instance the system was removed from.

abstract on_start_running(world: neighborly.ecs.World) → None[source]

Lifecycle method called before checking if a system will update.

Parameters: world – The world instance the system is mounted to.

abstract on_stop_running(world: neighborly.ecs.World) → None[source]

Lifecycle method called after a system updates.

Parameters: world – The world instance the system is mounted to.

abstract on_update(world: neighborly.ecs.World) → None[source]

Lifecycle method called each when stepping the simulation.

Parameters: world – The world instance the system is updating

abstract set_active(value: bool) → None[source]

Toggle if this system is active and will update.

Parameters: value – The new active status.

abstract should_run_system(world: neighborly.ecs.World) → bool[source]: Checks if this system should run this simulation step.

class neighborly.ecs.ResourceManager(world: neighborly.ecs.World)[source]

Bases: object

Manages shared resources for a world instance.

add_resource(resource: Any) → None[source]

Add a shared resource to a world.

Parameters: resource – The resource to add

get_resource(resource_type: Type[neighborly.ecs._RT]) → neighborly.ecs._RT[source]

Access a shared resource.

Parameters: resource_type – The class of the resource.
Returns: The instance of the resource.
Return type: _RT

has_resource(resource_type: Type[Any]) → bool[source]

Check if a world has a shared resource.

Parameters: resource_type – The class of the resource.
Returns: True if the resource exists, False otherwise.
Return type: bool

remove_resource(resource_type: Type[Any]) → None[source]

Remove a shared resource to a world.

Parameters: resource_type – The class of the resource.

property resources: Iterable[Any]: Get an iterable of all the current resources.

try_resource(resource_type: Type[neighborly.ecs._RT]) → Optional[neighborly.ecs._RT][source]

Attempt to access a shared resource.

Parameters: resource_type – The class of the resource.
Returns: The instance of the resource.
Return type: _RT or None

exception neighborly.ecs.ResourceNotFoundError(resource_type: Type[Any])[source]

Bases: Exception

Exception raised when attempting to access a resource that does not exist.

message: str: An error message.

resource_type: Type[Any]: The class type of the resource.

class neighborly.ecs.System[source]

Bases: neighborly.ecs.ISystem, abc.ABC

Base class for systems, providing implementation for most lifecycle methods.

on_add(world: neighborly.ecs.World) → None[source]

Lifecycle method called when the system is added to the world.

Parameters: world – The world instance the system is mounted to.

on_destroy(world: neighborly.ecs.World) → None[source]

Lifecycle method called when a system is removed from the world.

Parameters: world – The world instance the system was removed from.

on_start_running(world: neighborly.ecs.World) → None[source]

Lifecycle method called before checking if a system will update.

Parameters: world – The world instance the system is mounted to.

on_stop_running(world: neighborly.ecs.World) → None[source]

Lifecycle method called after a system updates.

Parameters: world – The world instance the system is mounted to.

set_active(value: bool) → None[source]

Toggle if this system is active and will update.

Parameters: value – The new active status.

should_run_system(world: neighborly.ecs.World) → bool[source]: Checks if this system should run this simulation step.

class neighborly.ecs.SystemGroup[source]

Bases: neighborly.ecs.System, abc.ABC

A group of ECS systems that run as a unit.

SystemGroups allow users to better structure the execution order of their systems.

add_child(system: neighborly.ecs.System, priority: int = 0) → None[source]

Add a new system as a sub_system of this group.

Parameters

system – The system to add to this group.
priority – The priority of running this system relative to its siblings.

iter_children() → Iterator[tuple[int, neighborly.ecs.System]][source]

Get an iterator for the group’s children.

Returns: An iterator for the child system collection.
Return type: Iterator[tuple[SystemBase]]

on_update(world: neighborly.ecs.World) → None[source]

Run all sub-systems.

Parameters: world – The world instance the system is updating

remove_child(system_type: Type[neighborly.ecs.System]) → None[source]

Remove a child system.

If for some reason there are more than one instance of the given system type, this method will remove the first instance it finds.

Parameters: system_type – The class type of the system to remove.

set_active(value: bool) → None[source]

Toggle if this system is active and will update.

Parameters: value – The new active status.

class neighborly.ecs.SystemManager(world: neighborly.ecs.World)[source]

Bases: neighborly.ecs.SystemGroup

Manages system instances for a single world instance.

add_system(system: neighborly.ecs.System, priority: int = 0, system_group: Optional[Type[neighborly.ecs.SystemGroup]] = None) → None[source]

Add a System instance.

Parameters

system – The system to add.
priority – The priority of the system relative to the others in its system group.
system_group – The class of the group to add this system to

get_system(system_type: Type[neighborly.ecs._ST]) → neighborly.ecs._ST[source]

Attempt to get a System of the given type.

Parameters: system_type – The type of the system to retrieve.
Returns: The system instance if one is found.
Return type: _ST or None

remove_system(system_type: Type[neighborly.ecs.System]) → None[source]

Remove all instances of a system type.

Parameters: system_type – The type of the system to remove.

Notes

This function performs a Depth-first search through the tree of system groups to find the one with the matching type.

No exception is raised if it does not find a matching system.

update_systems() → None[source]: Update all systems in the manager.

exception neighborly.ecs.SystemNotFoundError(system_type: Type[Any])[source]

Bases: Exception

Exception raised when attempting to access a system that does not exist.

message: str: An error message.

system_type: Type[Any]: The class type of the system.

class neighborly.ecs.TagComponent[source]

Bases: neighborly.ecs.Component

An Empty component used to mark a GameObject as having a state or type.

to_dict() → dict[str, Any][source]: Serialize the component to a JSON-serializable dictionary.

class neighborly.ecs.World[source]

Bases: object

Manages Gameobjects, Systems, events, and resources.

property event_manager: neighborly.ecs.EventManager: Get the world’s event manager.

property gameobject_manager: neighborly.ecs.GameObjectManager: Get the world’s gameobject manager

get_component(component_type: Type[neighborly.ecs._CT]) → list[tuple[int, _CT]][source]

Get all the GameObjects that have a given component type.

Parameters: component_type – The component type to check for.
Returns: A list of tuples containing the ID of a GameObject and its respective component instance.
Return type: list[tuple[int, _CT]]

get_components(component_types: tuple[Type[_T1]]) → list[tuple[int, tuple[_T1]]][source]

get_components(component_types: tuple[Type[_T1], Type[_T2]]) → list[tuple[int, tuple[_T1, _T2]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3]]) → list[tuple[int, tuple[_T1, _T2, _T3]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3], Type[_T4]]) → list[tuple[int, tuple[_T1, _T2, _T3, _T4]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3], Type[_T4], Type[_T5]]) → list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3], Type[_T4], Type[_T5], Type[_T6]]) → list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3], Type[_T4], Type[_T5], Type[_T6], Type[_T7]]) → list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6, _T7]]]

get_components(component_types: tuple[Type[_T1], Type[_T2], Type[_T3], Type[_T4], Type[_T5], Type[_T6], Type[_T7], Type[_T8]]) → list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6, _T7, _T8]]]

Get all game objects with the given components.

Parameters

component_types – The components to check for

Returns

Union[ – list[tuple[int, tuple[_T1]]], list[tuple[int, tuple[_T1, _T2]]], list[tuple[int, tuple[_T1, _T2, _T3]]], list[tuple[int, tuple[_T1, _T2, _T3, _T4]]], list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5]]], list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6]]], list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6, _T7]]], list[tuple[int, tuple[_T1, _T2, _T3, _T4, _T5, _T6, _T7, _T8]]],
] – list of tuples containing a GameObject ID and an additional tuple with the instances of the given component types, in-order.

property resource_manager: neighborly.ecs.ResourceManager: Get the world’s resource manager

step() → None[source]: Advance the simulation as single tick and call all the systems.

property system_manager: neighborly.ecs.SystemManager: Get the world’s system manager.

neighborly.inspection module

neighborly.libraries module

neighborly.life_event module

neighborly.loaders module

neighborly.simulation module

neighborly.systems module

neighborly.tracery module

Tracery

Neighborly uses Kate Compton’s Tracery to generate names for characters, items, businesses and other named objects. Users can add data to the simulations Tracery instance using JSON files loaded using the neighborly.loaders.load_tracery(…) function.

class neighborly.tracery.Tracery(rng_seed: Optional[Union[str, int]] = None)[source]

Bases: object

A class that wraps a tracery grammar instance.

add_rules(rules: dict[str, list[str]]) → None[source]

Add grammar rules.

Parameters: rules – Rule names mapped to strings or lists of string to expend to.

generate(start_string: str) → str[source]

Return a string generated using the grammar rules.

Parameters: start_string – The string to expand using grammar rules.
Returns: The final string.
Return type: str

set_rng_seed(seed: Union[int, str]) → None[source]

Set the seed for RNG used during rule evaluation.

Parameters: seed – An arbitrary seed value.

Module contents

Neighborly Character-Driven Social Simulation Framework.

Neighborly is an extensible, data-driven, agent-based modeling framework designed to simulate towns of characters for games. It is intended to be a tool for exploring simulationist approaches to character-driven emergent narratives. Neighborly’s simulation architecture is inspired by roguelikes such as Caves of Qud and Dwarf Fortress.