Welcome to Neighborly’s documentation!
Neighborly is an agent-based settlement simulation for emergent narrative storytelling and data analysis. It simulates generations of characters living within a village/town/city with a particular focus on their relationships and life events (starting a new job, falling in love, turning into a demon, etc.). It combines social simulation elements, like relationship tracking, with RPG elements, such as character stats and skills, to generate backstories about characters and their families. Neighborly simulates characters’ traits, statuses, relationships, occupations, and life events and makes the entire simulated history available for data analysis and game development.
Neighborly’s was inspired by Talk of the Town and aims to be a more customizable and user-friendly alternative to support research or entertainment projects. It also draws inspiration from commercial simulation-driven emergent narrative games like Caves of Qud, Dwarf Fortress, Crusader Kings, RimWorld, and WorldBox.
How to use these docs
This wiki explains the core building blocks of Neighborly and how to get started simulating your own procedurally generated settlements. If you’re looking for a tutorial or would like to try Neighborly without downloading it, here is a Google Colab notebook that covers the basics of Neighborly.
What if I find errors?
If you notice any errors with sample code or typos within the docs, please file a GitHub issue stating the issue. We appreciate your help in making Neighborly an accessible tool for learning and experimentation.
Installation
Neighborly is available to install from PyPI. Please use the following command to install the latest release.
python3 -m pip install neighborly
We recommend that users specify a specific Neighborly release in their pyproject.toml or requirements.txt files. For example, neighborly==2.*. Neighborly’s function and class interfaces may change drastically between releases, and this will prevent errors from appearing in your code if an updated version of Neighborly breaks something you rely on.
Neighborly’s core content types
Neighborly is a data-driven. So, user’s need to feed it a decent amount of data to get diverse and interesting results. However, Neighborly makes it easy for people to start simulating with a small amount of data and gradually add more. Below are the main content types that users can define.
Settlements and Districts: The overall place where characters live and start businesses.
Businesses: Places where characters work.
Traits: Represent characters’ personalities, relationship statuses, faction affiliations, etc.
Relationships: Track how characters feel about other characters.
Skills: Skills that characters can cultivate during their lives
Residential Buildings: Places where characters live
Characters: The characters that make everything run
Life Events: Events that implement character behaviors