Skip to main content

A narrative-focused agent-based settlement simulation framework.

Project description


Neighborly

Neighborly is an extensible agent-based settlement simulation. It was built to be a tool for emergent narrative storytelling research. Neighborly generates a virtual settlement and simulates the individual lives of its residents over multiple generations. It models the characters' traits, statuses, relationships, occupations, life events, and more. Neighborly tracks all the life events (starting a new job, falling in love, turning into a demon, etc.), and these become the building blocks for creating emergent stories about characters and their legacies. The entire history of the settlement and its generations of characters is then made available for data analysis or as content for other applications such as games.

Neighborly's was inspired Talk of the Town, another settlement simulation for emergent narrative storytelling research. It also draws inspiration from commercial world-simulation games like Caves of Qud, Dwarf Fortress, Crusader Kings, RimWorld, and WorldBox. It aims to be an easily customizable simulation that can adapt to various narrative settings and support research or entertainment projects.

If you use Neighborly in a project, please cite this repository. You can read a copy of Neighborly's associated paper that was published in the proceedings of the 2022 IEEE Conference On Games. ⚠️ Warning: Please note that Neighborly's current structure differs greatly from the version the paper describes.

Core Features

  • 🏙️ Procedurally generates a settlement and the history of its residents.
  • 🚀 Utilize a low-fidelity social simulation to simulate hundreds of years of world history within minutes.
  • ⚙️ Built using an entity-component system (ECS) architecture
  • 📦 Plugin system to load and share new content.
  • 👔 Characters can start businesses and hold jobs.
  • ️🧬 Characters have traits that modify their stats and relationships.
  • ❤️ Characters form and cultivate relationships based on romance and reputation.
  • 💥 Simulate random life events that spice up characters' lives.
  • ⚖️ Define Social Rules for how characters should feel about each other.
  • 🏬 Define location preference rules for what locations characters frequent.
  • 📈 Uses Polars for fast data analysis.
  • 📜 Export simulation data to JSON.

System caveats

  • Only simulates a single settlement
  • Characters can only hold one occupation at a time.
  • Does not model the exact position of entities.

Try Neighborly without installing

Neighborly is available to use within this sample Google Colab notebook. It contains a basic walkthrough of how to define content for the simulation and inspect the generated data.

Installation

The latest official release of Neighborly is available to install from PyPI.

pip install neighborly

Installing for local development

If you wish to download a Neighborly for local development or want to play around with any of the samples, you need to clone or download this repository and install using the editable flag (-e). Please see the instructions below. This command will install a Neighborly into the virtual environment along with all its dependencies and a few additional development and testing dependencies such as black, isort, and pytest.

# Step 1: Clone Repository and change into project directory
git clone https://github.com/ShiJbey/neighborly.git
cd neighborly

# Step 2 (MacOS/Linux): Create and activate a Python virtual environment
python3 -m venv venv
source ./venv/bin/activate

# Step 2 (Windows): Create and activate a Python virtual environment
python -m venv venv
.\venv\Scripts\Activate

# Step 3: Install local build and dependencies
python -m pip install -e ".[development]"

Usage

The best way to learn how to use Neighborly is to explore the various samples in the samples directory that demonstrate how to create custom simulations and collect and visualize data. Interactive samples with the .ipynb extension are meant to be run using Jupyter Lab. Please run the following command to ensure all dependencies are installed for the samples. Make sure that you've activated your Python virtual environment beforehand.

python -m pip install -e ".[samples]"

Then, run the following commands to run the sample scripts or notebooks.

# To run sample scripts, use:
python ./samples/<name_of_sample>.py

# Explore IPython notebooks using Jupyter Lab:
jupyter-lab

Plugins

Plugins are importable Python modules or packages that add new content to a simulation. They allow users to change a simulation's behavior without editing the core library code. All plugins should have a top-level load_plugin(sim) function that gets called to load in the plugin content.

As with any piece of software, always express caution when downloading third-party plugins. Ensure they come from a source that you trust.

To read more about plugins, visit the Plugins section of the wiki.

Tests

Neighborly uses PyTest for unit testing. All tests are located in the tests/ directory. I do my best to keep tests updated. However, some tests may need to be added or updated due to constant breaking changes between releases. If you want to contribute unit tests, please refer to CONTRIBUTING.md.

# Step 1: Install additional dependencies for tests
python -m pip install -e ".[development]"

# Step 2: Run Pytest
pytest

# Step3 : (Optional) Generate a test coverage report
pytest --cov=neighborly tests/

Documentation

The best place to find examples of how to use Neighborly is actually in the ./tests directory. There you will find examples of loading content from files, running a simulation, and saving the output to JSON. There is also the Read the Docs. However, the docs has a tendency to be out of date when new, potentially breaking changes are made to the framework. However, unit tests are updated almost every time a new feature is added.

Getting help and submitting bug reports

If you have any questions, feedback, or problems, please create a new Issue. I will do my best to answer as soon as I can. Please be respectful, and I appreciate your patience.

Contributing

Contributions are welcome. Please refer to CONTRIBUTING.md for more information about how to get involved.

License

This project is licensed under the MIT License.

DMCA Statement

Upon receipt of a notice alleging copyright infringement, I will take whatever action it deems appropriate within its sole discretion, including removal of the allegedly infringing materials.

The repo image is something fun that I made. I love The Simpsons, and I couldn't think of anyone more neighborly than Ned Flanders. If the copyright owner for The Simpsons would like me to take it down, please contact me. The same takedown policy applies to code samples inspired by TV shows, movies, and games.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neighborly-2.5.0.tar.gz (155.3 kB view details)

Uploaded Source

Built Distribution

neighborly-2.5.0-py3-none-any.whl (157.3 kB view details)

Uploaded Python 3

File details

Details for the file neighborly-2.5.0.tar.gz.

File metadata

  • Download URL: neighborly-2.5.0.tar.gz
  • Upload date:
  • Size: 155.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.11.8

File hashes

Hashes for neighborly-2.5.0.tar.gz
Algorithm Hash digest
SHA256 e251555ca10561b6074a40c92257565952c008e26bf0cf5c369b756d92cb7aae
MD5 b66dfb33c238c4b460965e9c5c4e4385
BLAKE2b-256 6f8aa92337030423bad0fc40f6799ebe773399b6acb3de66da8d697ab6eb9b14

See more details on using hashes here.

File details

Details for the file neighborly-2.5.0-py3-none-any.whl.

File metadata

  • Download URL: neighborly-2.5.0-py3-none-any.whl
  • Upload date:
  • Size: 157.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.11.8

File hashes

Hashes for neighborly-2.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 95018cd406a2234f3f33abc01a42ff725f0e0bc3b2043d5e30a8bdf504fe953d
MD5 e36ce94a0455711396c26e62dba090bf
BLAKE2b-256 b8090c1a791cc72594273089824f2de92968ab8a4a179b0fac25f7e77c9e2615

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page