<h1 align="center">
<img
width="150"
height="150"
src="https://user-images.githubusercontent.com/11076525/165836171-9ffdea6e-1633-440c-be06-b46e1e3e4e04.png"
>
<br>
Neighborly
</h1>
<p align="center">
<img src="https://img.shields.io/pypi/v/neighborly">
<img src="https://img.shields.io/pypi/pyversions/neighborly">
<img src="https://img.shields.io/pypi/l/neighborly">
<img src="https://img.shields.io/pypi/dm/neighborly">
<img src="https://img.shields.io/badge/code%20style-black-black">
<img src="https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336">
</p>
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_](https://github.com/james-owen-ryan/talktown), 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](./CITATION.bib). You can read a copy of
Neighborly's associated [paper](https://shijbey.github.io/publications/Neighborly.pdf) 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](https://www.pola.rs) 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](https://colab.research.google.com/drive/1WxZnCR8afekfBl-vI6WcIcS6OhRGdkam?usp=sharing). 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](https://pypi.org/project/neighborly/).
```bash
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_.
```bash
# 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](https://jupyter.org/). 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.
```bash
python -m pip install -e ".[samples]"
```
Then, run the following commands to run the sample scripts or notebooks.
```bash
# 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](https://github.com/ShiJbey/neighborly/wiki/plugins) section of the
wiki.
# Tests
Neighborly uses [PyTest](https://docs.pytest.org/) 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](./CONTRIBUTING.md).
```bash
# 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](https://neighborly.readthedocs.io/en/latest/index.html). 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](./CONTRIBUTING.md) for more information about how to get
involved.
# License
This project is licensed under the [MIT License](./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.
Raw data
{
"_id": null,
"home_page": null,
"name": "neighborly",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "social simulation, games, simulation, artificial intelligence, agent-based modeling, multiagent systems, emergent narrative, narrative generation, interactive storytelling, settlement simulation",
"author": null,
"author_email": "Shi Johnson-Bey <shijbey@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6f/8a/a92337030423bad0fc40f6799ebe773399b6acb3de66da8d697ab6eb9b14/neighborly-2.5.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <img\n width=\"150\"\n height=\"150\"\n src=\"https://user-images.githubusercontent.com/11076525/165836171-9ffdea6e-1633-440c-be06-b46e1e3e4e04.png\"\n >\n <br>\n Neighborly\n</h1>\n\n<p align=\"center\">\n <img src=\"https://img.shields.io/pypi/v/neighborly\">\n <img src=\"https://img.shields.io/pypi/pyversions/neighborly\">\n <img src=\"https://img.shields.io/pypi/l/neighborly\">\n <img src=\"https://img.shields.io/pypi/dm/neighborly\">\n <img src=\"https://img.shields.io/badge/code%20style-black-black\">\n <img src=\"https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\">\n</p>\n\nNeighborly 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.\n\nNeighborly's was inspired [_Talk of the Town_](https://github.com/james-owen-ryan/talktown), 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.\n\nIf you use Neighborly in a project, please [cite this repository](./CITATION.bib). You can read a copy of\nNeighborly's associated [paper](https://shijbey.github.io/publications/Neighborly.pdf) that was published in the\nproceedings of the 2022 IEEE Conference On Games. \u26a0\ufe0f **Warning**: Please note that Neighborly's current structure\ndiffers greatly from the version the paper describes.\n\n# Core Features\n\n- \ud83c\udfd9\ufe0f Procedurally generates a settlement and the history of its residents.\n- \ud83d\ude80 Utilize a low-fidelity social simulation to simulate hundreds of years of world history within minutes.\n- \u2699\ufe0f Built using an entity-component system (ECS) architecture\n- \ud83d\udce6 Plugin system to load and share new content.\n- \ud83d\udc54 Characters can start businesses and hold jobs.\n- \ufe0f\ud83e\uddec Characters have traits that modify their stats and relationships.\n- \u2764\ufe0f Characters form and cultivate relationships based on romance and reputation.\n- \ud83d\udca5 Simulate random life events that spice up characters' lives.\n- \u2696\ufe0f Define Social Rules for how characters should feel about each other.\n- \ud83c\udfec Define location preference rules for what locations characters frequent.\n- \ud83d\udcc8 Uses [Polars](https://www.pola.rs) for fast data analysis.\n- \ud83d\udcdc Export simulation data to JSON.\n\n# System caveats\n\n- Only simulates a single settlement\n- Characters can only hold one occupation at a time.\n- Does not model the exact position of entities.\n\n# Try Neighborly without installing\n\nNeighborly is available to use within this [sample Google Colab notebook](https://colab.research.google.com/drive/1WxZnCR8afekfBl-vI6WcIcS6OhRGdkam?usp=sharing). It contains a basic walkthrough of how to define content for the simulation and inspect the generated data.\n\n# Installation\n\nThe latest official release of Neighborly is available to install from [PyPI](https://pypi.org/project/neighborly/).\n\n```bash\npip install neighborly\n```\n\n## Installing for local development\n\nIf you wish to download a Neighborly for local development or want to play around with\nany of the samples, you need to clone or download this repository and install\nusing the _editable_ flag (-e). Please see the instructions below. This command will install\na Neighborly into the virtual environment along with all its dependencies and a few\nadditional development and testing dependencies such as _black_, _isort_, and _pytest_.\n\n```bash\n# Step 1: Clone Repository and change into project directory\ngit clone https://github.com/ShiJbey/neighborly.git\ncd neighborly\n\n# Step 2 (MacOS/Linux): Create and activate a Python virtual environment\npython3 -m venv venv\nsource ./venv/bin/activate\n\n# Step 2 (Windows): Create and activate a Python virtual environment\npython -m venv venv\n.\\venv\\Scripts\\Activate\n\n# Step 3: Install local build and dependencies\npython -m pip install -e \".[development]\"\n```\n\n# Usage\n\nThe best way to learn how to use Neighborly is to explore the various samples in the `samples` directory\nthat demonstrate how to create custom simulations and collect and visualize data. Interactive samples with the `.ipynb`\nextension are meant to be run using [Jupyter Lab](https://jupyter.org/). Please run the following command\nto ensure all dependencies are installed for the samples. Make sure that you've activated your Python virtual\nenvironment beforehand.\n\n```bash\npython -m pip install -e \".[samples]\"\n```\n\nThen, run the following commands to run the sample scripts or notebooks.\n\n```bash\n# To run sample scripts, use:\npython ./samples/<name_of_sample>.py\n\n# Explore IPython notebooks using Jupyter Lab:\njupyter-lab\n```\n\n# Plugins\n\nPlugins are importable Python modules or packages that add new content to a simulation. They allow users to change\na simulation's behavior without editing the core library code. All plugins should have a top-level\n`load_plugin(sim)` function that gets called to load in the plugin content.\n\nAs with any piece of software, always express caution when downloading third-party plugins. Ensure they come from a\nsource that you trust.\n\nTo read more about plugins, visit the [Plugins](https://github.com/ShiJbey/neighborly/wiki/plugins) section of the\nwiki.\n\n# Tests\n\nNeighborly uses [PyTest](https://docs.pytest.org/) for unit testing. All tests are located in the `tests/` directory. I\ndo my best to keep tests updated. However, some tests may need to be\nadded or updated due to constant breaking changes between releases. If you want to contribute unit tests, please refer\nto [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n```bash\n# Step 1: Install additional dependencies for tests\npython -m pip install -e \".[development]\"\n\n# Step 2: Run Pytest\npytest\n\n# Step3 : (Optional) Generate a test coverage report\npytest --cov=neighborly tests/\n```\n\n# Documentation\n\nThe 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](https://neighborly.readthedocs.io/en/latest/index.html). 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.\n\n# Getting help and submitting bug reports\n\nIf you have any questions, feedback, or problems, please create a new Issue. I will do my best to answer as soon as I\ncan. Please be respectful, and I appreciate your patience.\n\n# Contributing\n\nContributions are welcome. Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about how to get\ninvolved.\n\n# License\n\nThis project is licensed under the [MIT License](./LICENSE).\n\n# DMCA Statement\n\nUpon receipt of a notice alleging copyright infringement, I will take whatever action it deems appropriate within its\nsole discretion, including removal of the allegedly infringing materials.\n\nThe repo image is something fun that I made. I love _The Simpsons_, and I couldn't think of anyone more neighborly than\nNed Flanders. If the copyright owner for _The Simpsons_ would like me to take it down, please contact me. The same\ntakedown policy applies to code samples inspired by TV shows, movies, and games.\n",
"bugtrack_url": null,
"license": null,
"summary": "A narrative-focused agent-based settlement simulation framework.",
"version": "2.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/ShiJbey/neighborly/issues",
"Changelog": "https://github.com/ShiJbey/neighborly/blob/main/CHANGELOG.md",
"Documentation": "https://neighborly.readthedocs.io/en/latest/",
"Homepage": "https://github.com/ShiJbey/neighborly",
"Repository": "https://github.com/ShiJBey/neighborly.git"
},
"split_keywords": [
"social simulation",
" games",
" simulation",
" artificial intelligence",
" agent-based modeling",
" multiagent systems",
" emergent narrative",
" narrative generation",
" interactive storytelling",
" settlement simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8090c1a791cc72594273089824f2de92968ab8a4a179b0fac25f7e77c9e2615",
"md5": "e36ce94a0455711396c26e62dba090bf",
"sha256": "95018cd406a2234f3f33abc01a42ff725f0e0bc3b2043d5e30a8bdf504fe953d"
},
"downloads": -1,
"filename": "neighborly-2.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e36ce94a0455711396c26e62dba090bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 157284,
"upload_time": "2024-03-25T04:31:44",
"upload_time_iso_8601": "2024-03-25T04:31:44.775231Z",
"url": "https://files.pythonhosted.org/packages/b8/09/0c1a791cc72594273089824f2de92968ab8a4a179b0fac25f7e77c9e2615/neighborly-2.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6f8aa92337030423bad0fc40f6799ebe773399b6acb3de66da8d697ab6eb9b14",
"md5": "b66dfb33c238c4b460965e9c5c4e4385",
"sha256": "e251555ca10561b6074a40c92257565952c008e26bf0cf5c369b756d92cb7aae"
},
"downloads": -1,
"filename": "neighborly-2.5.0.tar.gz",
"has_sig": false,
"md5_digest": "b66dfb33c238c4b460965e9c5c4e4385",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 155275,
"upload_time": "2024-03-25T04:31:46",
"upload_time_iso_8601": "2024-03-25T04:31:46.895523Z",
"url": "https://files.pythonhosted.org/packages/6f/8a/a92337030423bad0fc40f6799ebe773399b6acb3de66da8d697ab6eb9b14/neighborly-2.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 04:31:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ShiJbey",
"github_project": "neighborly",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "neighborly"
}
JSON
