Перейти к содержимому
Mineforgian

MindOfTheColony

Mind of the Colony is a mod that transforms your settlement inhabitants from silent workers into living, thinking individuals

Загрузки
634
Подписчики
5
Обновлён
10 февраля 2026 г.
Лицензия
MIT

Опубликован 2 февраля 2026 г.

Mind of the Colony: Giving a Voice to Your Villagers

Player2 AI Game Jam For MineColonies

Mind of the Colony is a mod that transforms your settlement's inhabitants from silent workers into living, thinking individuals. Created by Goodbird for the Player2 AI Game Jam, this project moves beyond typical gameplay mechanics to answer a simple question: what are your colonists really thinking?

Instead of adding another "gimmick," this mod deeply integrates with the social fabric of the renowned MineColonies mod, allowing you to peer into the soul of each citizen and discover what makes them happy, what troubles them, and what they truly desire.

The Concept: The Colony as a Living Organism

In MineColonies, you build a town, manage resources, and assign jobs. But have you ever wondered what your farmer feels when the warehouse is full and there's nowhere to store the harvest? Or why your guard looks so grim after a nighttime raid?

Mind of the Colony gives you the chance to find out. By leveraging the power of the Player2 API, every citizen in your colony is given their own "inner monologue." They become fully-fledged characters with unique personalities shaped by their job, skills, background, and -- most importantly -- their current happiness level.

  • Talk to Your Citizens: Walk up to any colonist and start a conversation through the integrated chat window.
  • Learn Their Thoughts: Their responses are dynamically generated based on their current state -- job, health, mood, skills, inventory, and colony situation.
  • Solve Their Problems: Is a citizen unhappy? They might tell you what's bothering them -- perhaps they're short on food, their home is too far from their workplace, or they're mourning a fallen comrade.
  • Discover Their Past: Every citizen carries a unique background -- an origin story, a personality trait, and sometimes a dark secret or personal flaw that subtly shapes how they speak and think.
  • Experience Colony Events: The colony itself generates events -- raids, births, festivals, rumors -- that affect citizen happiness and give them something to talk about.

How It Works: The Technology Behind the Soul

The magic of this mod lies in its elegant integration with MineColonies, not in creating new entities from scratch.

1. The Central Mind: CitizenNpcManager

This singleton class acts as the central nervous system for the entire colony's AI.

  • Manages AI Instances: It creates and tracks a CitizenNpcBridge for every citizen currently loaded in the world, ensuring each NPC has its own "mind."
  • Conversation Tracking: The manager tracks active conversations between players and citizens, routing messages through a client-server network protocol (AIChatMessage and AIChatResponseMessage).
  • Lifecycle Management: Citizens are automatically given their AI bridge when they load into the world and cleaned up when they unload, via Mixin hooks into MineColonies' citizen manager.

2. The Individual Personality: CitizenNpcBridge

Each citizen possesses their own CitizenNpcBridge, which shapes their unique personality and responses.

  • Personalized Prompts: A unique system prompt is generated for every single citizen, based on their name, profession, gender, age, happiness level, and background. Your lumberjack will not speak like your baker.
  • Deep Contextual Awareness: Before generating a response, the AI is fed a comprehensive snapshot of the citizen's reality:
    • Personal Status: Health, saturation, sickness, sleep state, job details, skills, inventory, equipment, home location, happiness modifiers, and current requests.
    • Colony Status: Colony name, population, buildings, overall happiness, whether the colony is under attack, day count, and recent colony events.
  • Background Integration: Each citizen's origin story, personality trait, and penalties are woven into the system prompt, creating consistent and distinctive character voices.

3. Colony Events: ColonyEventManager

The colony generates dynamic events that shape the world and give citizens context for conversation.

  • Detected Events: The event manager subscribes to MineColonies' event bus and captures real gameplay moments -- citizen deaths, births, hirings, building completions, job changes, and raids.
  • Flavor Events: Periodic randomly-generated events add atmosphere -- traveling merchants spotted nearby, bumper harvests, colony festivals, strange noises from the mines, or disputes between workers.
  • Happiness Impact: Events apply temporary happiness modifiers to all citizens. A raid lowers morale; a festival raises it.
  • AI Context: Active events are injected into citizen system prompts, so they naturally reference recent happenings in conversation.
  • Configurable: Event types, durations, happiness modifiers, generation intervals, and chances are all configurable.

4. Citizen Backgrounds: CitizenBackground

Each citizen is assigned a permanent background identity when they first spawn.

  • Origins: 12 possible backstories -- refugee farmer, disgraced noble, wandering trader, shipwreck survivor, former soldier, orphan street kid, and more.
  • Personality Traits: 10 distinct traits -- cheerful, grumpy, cautious, boastful, quiet, superstitious, kind-hearted, sarcastic, ambitious, or nostalgic.
  • Penalties: 18 possible burdens across four categories:
    • Criminal: Past theft, desertion, fraud, or smuggling.
    • Conversation Secrets: Hidden identity, deep regret, fears, haunted past, or forbidden knowledge.
    • Social: Outcast status, unpaid debts, exile, or broken oaths.
    • Personal Flaws: Laziness, frailty, clumsiness, short temper, or cowardice.
  • Persistence: Backgrounds are serialized to NBT and saved permanently with the citizen data.
  • Configurable: Origins, traits, and penalties can be customized via JSON config files.

5. Clean Integration with MineColonies

The mod uses Mixins to non-invasively inject its functionality into MineColonies without altering its core code. This ensures maximum compatibility and stability.

  • MixinCitizenManager: Hooks into citizen registration and unregistration to automatically create and destroy AI bridges as citizens load and unload.
  • MixinCitizenData: Extends citizen data serialization to persist background information and conversation history via NBT.
  • MixinMainWindowCitizen: Injects a chat tab button into the existing MineColonies citizen window, opening a dedicated chat interface.
  • MixinDebugWindowCitizen: Adds background information display to the citizen debug window for development and inspection.

Why This is "Beyond an AI Gimmick"

  • Deep Systemic Integration: The AI doesn't just exist in the game; it reacts to its core systems -- economy, social bonds, and events. A citizen's happiness is no longer just a number; it's the reason for their mood, which they can now articulate to you.
  • Emergent Narrative: Colony events, citizen backgrounds, and real-time game state combine to create stories unique to your world. A former soldier turned guard who just survived a raid will speak very differently from a cheerful baker celebrating a harvest festival.
  • A New Layer of Gameplay: Managing a colony is no longer just about resource management. It becomes a social challenge. For your colony to thrive, you must not only build structures but also care for the well-being and happiness of its people by listening to their problems.

Mind of the Colony is not about adding chatbots. It's about giving a soul to an already living world.

Acknowledgements

This project stands on the work and support of many.

Player2

This framework was created for the Player2 AI Game Jam and is designed to integrate seamlessly with the Player2 API, realizing their vision for intelligent, interactive agents.

We are a team of researchers and engineers that are passionate about advancing the state of the art in AI. Our team members have worked at some of the world's leading tech companies and research institutions, and we are united by our shared vision of building intelligent agents that can interact with the world in a meaningful way.

Foundation & Inspiration

  • MineColonies: The mod is built over the vast and comprehensive API of MineColonies mod, an interactive building mod that allows you to create your own thriving town within Minecraft.

Special Thanks

  • Itsuka: For his invaluable guidance with the Player2 API, brainstorming sessions, and rigorous testing.

Ченджлог

v1.0.3Релиз1.21.1 · 10 февраля 2026 г.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Make NPCs stop moving and look at players when player is in UI
  • Add background story and personality traits to citizens and visitor
  • Rework Traits to be more flexible and support both positive and negative modifiers configurable via traits.json
  • Update debug ui to show traits and their modifiers
  • Add commands to regenerate backgrounds for testing and debugging

[1.0.1] - 2026-02-02

Added

  • Unified trait system with gameplay modifiers
    • Traits can have both positive and negative effects on disease rate, happiness, work speed, and food consumption
    • Supported modifiers: diseaseRate, contactDiseaseRate, happinessBase, happinessDecayRate, workSpeed, foodConsumption
    • Weighted random trait selection (2-4 traits per citizen)
    • Configurable via traits.json and origins.json
  • Visitor background support
    • Visitors now receive AI-generated backgrounds when spawned via MixinVisitorManager
    • Background data persists through recruitment (NBT transfer)
    • Missing backgrounds checked and generated on server startup
    • Debug window displays visitor backgrounds
  • Admin commands (/motc) - requires operator level 2
    • /motc language [lang] - Get or set NPC conversation language
    • /motc regenbackground <colonyId> <citizenId> - Regenerate a single citizen's background
    • /motc regenall <colonyId> - Regenerate all citizens' backgrounds in a colony
    • /motc regenvisitors <colonyId> - Regenerate all visitors' backgrounds in a colony
  • Disease modifier system
    • Job-based disease modifiers via disease_config.json
    • Trait-based disease modifiers that stack multiplicatively with job modifiers
    • Contact disease rate modifiers for disease spread
  • Citizen background and personality system (#1)
    • AI-generated backstories for citizens
    • Background data persistence via NBT serialization
    • Configurable backgrounds via JSON config files
    • Background display in citizen debug window
  • Colony events system (#2)
    • Real-time event detection from MineColonies (citizen deaths, births, hires, building completions, job changes, raids)
    • Randomly generated flavor events (traveling merchants, bumper harvests, festivals, strange noises, worker disputes)
    • Happiness modifiers based on events
    • Event context injection into citizen AI prompts
    • Configurable event types, durations, happiness modifiers, and generation intervals
  • NPC conversation history tracking (#4)
    • Persistent NPC memory across server restarts via UUID-based resume
    • NPC IDs stored in NBT compound tags for state persistence
    • Fixed game session ID for identity consistency
    • Conversation history continuity across reloads
  • Chat window UI improvements (#3)
    • Enter-to-send functionality in chat interface
    • Auto-scroll feature in chat history
    • Chat tab button in MineColonies citizen window
    • Dedicated chat interface for citizen conversations
  • Comprehensive Mixin integrations
    • MixinCitizenManager for automatic AI bridge lifecycle management
    • MixinCitizenData for background and conversation history persistence
    • MixinMainWindowCitizen for chat UI integration
    • MixinDebugWindowCitizen for background information display
  • Network messaging system
    • AIChatMessage and AIChatResponseMessage for chat communication
    • BackgroundRequestMessage and BackgroundResponseMessage for background data sync
    • ModNetworking for network protocol management
  • Configuration system
    • ModSettings for mod-wide configuration
    • BackgroundConfigLoader for loading custom background definitions
    • BackgroundConfigData for background data structures
  • Client-side functionality
    • ClientChatHandler for handling chat on client
    • ClientBackgroundCache for caching citizen backgrounds
    • ChatWindowCitizen for chat UI rendering
  • NeoForge 1.21.1 support
    • Migration from Forge to NeoForge
    • Updated mod metadata to neoforge.mods.toml
    • Gradle wrapper integration
  • Build automation
    • GitHub Actions workflow for automated builds
  • Automated release workflow (#10)
    • GitHub Actions for automated publishing to Modrinth and CurseForge
    • Builds and uploads on GitHub release publication
    • Uses CHANGELOG.md for release notes
  • Configurable disease system (#5)
    • Job-specific disease susceptibility modifiers (miners/quarriers 2.0x, healers 0.05x, etc.)
    • Configurable contact spread rates per job type
    • DiseaseConfig.java with TOML configuration
    • MixinCitizenDiseaseHandler.java for custom disease spread logic
  • Development tools
    • VSCode settings for project
    • Git attributes configuration

Changed

  • Refactored AI bridge architecture
    • Renamed CitizenAIManager to CitizenNpcManager for clarity
    • Replaced CitizenAIBridge with CitizenNpcBridge
    • Improved conversation management with client-server network protocol
    • Enhanced system prompt generation with contextual awareness
  • BackgroundRequestMessage now checks both citizen and visitor managers
  • MixinCitizenData updated for NeoForge's HolderLookup.Provider in NBT serialization
  • Improved citizen status reporting (#3)
    • Added Level 0 → 1 build phrasing in citizen AI prompts
    • Enhanced job/request status strings with work order and requester details
    • Added null safety guards for citizen status
  • Updated dependency management
    • Moved MineColonies and related libraries from local lib/ to Maven dependencies
    • Cleaned up build.gradle configuration
  • Enhanced .gitignore to exclude build artifacts and IDE files
  • Replaced hardcoded healer disease immunity with configurable low-susceptibility modifier (#5)

Removed

  • Local library JARs from repository
    • blockui-1.20.1-1.0.193.jar
    • domum_ornamentum-1.20.1-1.0.290-snapshot-universal.jar
    • minecolonies-1.20.1-1.1.989-snapshot.jar
    • multipiston-1.20-1.2.43-RELEASE.jar
    • structurize-1.20.1-1.0.777-snapshot.jar
  • Obsolete Player2 API service classes
    • HTTPUtils.java
    • Player2APIService.java
  • Old Forge metadata (META-INF/mods.toml)
  • pack.mcmeta file
  • ConversationHistory.java (functionality integrated into new bridge)
  • ChatEventHandler.java (replaced by NpcEventHandler.java)
v1.0.2Релиз1.21.1 · 5 февраля 2026 г.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Make NPCs stop moving and look at players when player is in UI
  • Add background story and personality traits to citizens and visitor
  • Rework Traits to be more flexible and support both positive and negative modifiers configurable via traits.json
  • Update debug ui to show traits and their modifiers
  • Add commands to regenerate backgrounds for testing and debugging

[1.0.1] - 2026-02-02

Added

  • Unified trait system with gameplay modifiers
    • Traits can have both positive and negative effects on disease rate, happiness, work speed, and food consumption
    • Supported modifiers: diseaseRate, contactDiseaseRate, happinessBase, happinessDecayRate, workSpeed, foodConsumption
    • Weighted random trait selection (2-4 traits per citizen)
    • Configurable via traits.json and origins.json
  • Visitor background support
    • Visitors now receive AI-generated backgrounds when spawned via MixinVisitorManager
    • Background data persists through recruitment (NBT transfer)
    • Missing backgrounds checked and generated on server startup
    • Debug window displays visitor backgrounds
  • Admin commands (/motc) - requires operator level 2
    • /motc language [lang] - Get or set NPC conversation language
    • /motc regenbackground <colonyId> <citizenId> - Regenerate a single citizen's background
    • /motc regenall <colonyId> - Regenerate all citizens' backgrounds in a colony
    • /motc regenvisitors <colonyId> - Regenerate all visitors' backgrounds in a colony
  • Disease modifier system
    • Job-based disease modifiers via disease_config.json
    • Trait-based disease modifiers that stack multiplicatively with job modifiers
    • Contact disease rate modifiers for disease spread
  • Citizen background and personality system (#1)
    • AI-generated backstories for citizens
    • Background data persistence via NBT serialization
    • Configurable backgrounds via JSON config files
    • Background display in citizen debug window
  • Colony events system (#2)
    • Real-time event detection from MineColonies (citizen deaths, births, hires, building completions, job changes, raids)
    • Randomly generated flavor events (traveling merchants, bumper harvests, festivals, strange noises, worker disputes)
    • Happiness modifiers based on events
    • Event context injection into citizen AI prompts
    • Configurable event types, durations, happiness modifiers, and generation intervals
  • NPC conversation history tracking (#4)
    • Persistent NPC memory across server restarts via UUID-based resume
    • NPC IDs stored in NBT compound tags for state persistence
    • Fixed game session ID for identity consistency
    • Conversation history continuity across reloads
  • Chat window UI improvements (#3)
    • Enter-to-send functionality in chat interface
    • Auto-scroll feature in chat history
    • Chat tab button in MineColonies citizen window
    • Dedicated chat interface for citizen conversations
  • Comprehensive Mixin integrations
    • MixinCitizenManager for automatic AI bridge lifecycle management
    • MixinCitizenData for background and conversation history persistence
    • MixinMainWindowCitizen for chat UI integration
    • MixinDebugWindowCitizen for background information display
  • Network messaging system
    • AIChatMessage and AIChatResponseMessage for chat communication
    • BackgroundRequestMessage and BackgroundResponseMessage for background data sync
    • ModNetworking for network protocol management
  • Configuration system
    • ModSettings for mod-wide configuration
    • BackgroundConfigLoader for loading custom background definitions
    • BackgroundConfigData for background data structures
  • Client-side functionality
    • ClientChatHandler for handling chat on client
    • ClientBackgroundCache for caching citizen backgrounds
    • ChatWindowCitizen for chat UI rendering
  • NeoForge 1.21.1 support
    • Migration from Forge to NeoForge
    • Updated mod metadata to neoforge.mods.toml
    • Gradle wrapper integration
  • Build automation
    • GitHub Actions workflow for automated builds
  • Automated release workflow (#10)
    • GitHub Actions for automated publishing to Modrinth and CurseForge
    • Builds and uploads on GitHub release publication
    • Uses CHANGELOG.md for release notes
  • Configurable disease system (#5)
    • Job-specific disease susceptibility modifiers (miners/quarriers 2.0x, healers 0.05x, etc.)
    • Configurable contact spread rates per job type
    • DiseaseConfig.java with TOML configuration
    • MixinCitizenDiseaseHandler.java for custom disease spread logic
  • Development tools
    • VSCode settings for project
    • Git attributes configuration

Changed

  • Refactored AI bridge architecture
    • Renamed CitizenAIManager to CitizenNpcManager for clarity
    • Replaced CitizenAIBridge with CitizenNpcBridge
    • Improved conversation management with client-server network protocol
    • Enhanced system prompt generation with contextual awareness
  • BackgroundRequestMessage now checks both citizen and visitor managers
  • MixinCitizenData updated for NeoForge's HolderLookup.Provider in NBT serialization
  • Improved citizen status reporting (#3)
    • Added Level 0 → 1 build phrasing in citizen AI prompts
    • Enhanced job/request status strings with work order and requester details
    • Added null safety guards for citizen status
  • Updated dependency management
    • Moved MineColonies and related libraries from local lib/ to Maven dependencies
    • Cleaned up build.gradle configuration
  • Enhanced .gitignore to exclude build artifacts and IDE files
  • Replaced hardcoded healer disease immunity with configurable low-susceptibility modifier (#5)

Removed

  • Local library JARs from repository
    • blockui-1.20.1-1.0.193.jar
    • domum_ornamentum-1.20.1-1.0.290-snapshot-universal.jar
    • minecolonies-1.20.1-1.1.989-snapshot.jar
    • multipiston-1.20-1.2.43-RELEASE.jar
    • structurize-1.20.1-1.0.777-snapshot.jar
  • Obsolete Player2 API service classes
    • HTTPUtils.java
    • Player2APIService.java
  • Old Forge metadata (META-INF/mods.toml)
  • pack.mcmeta file
  • ConversationHistory.java (functionality integrated into new bridge)
  • ChatEventHandler.java (replaced by NpcEventHandler.java)
v1.0.1Релиз1.21.1 · 2 февраля 2026 г.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Citizen background and personality system (#1)
    • 12 unique backstories for citizens (refugee farmer, disgraced noble, wandering trader, etc.)
    • 10 distinct personality traits (cheerful, grumpy, cautious, boastful, etc.)
    • 18 possible penalties across criminal, conversation secrets, social, and personal flaw categories
    • Background data persistence via NBT serialization
    • Configurable backgrounds via JSON config files
    • Background display in citizen debug window
  • Colony events system (#2)
    • Real-time event detection from MineColonies (citizen deaths, births, hires, building completions, job changes, raids)
    • Randomly generated flavor events (traveling merchants, bumper harvests, festivals, strange noises, worker disputes)
    • Happiness modifiers based on events
    • Event context injection into citizen AI prompts
    • Configurable event types, durations, happiness modifiers, and generation intervals
  • NPC conversation history tracking (#4)
    • Persistent NPC memory across server restarts via UUID-based resume
    • NPC IDs stored in NBT compound tags for state persistence
    • Fixed game session ID for identity consistency
    • Conversation history continuity across reloads
  • Chat window UI improvements (#3)
    • Enter-to-send functionality in chat interface
    • Auto-scroll feature in chat history
    • Chat tab button in MineColonies citizen window
    • Dedicated chat interface for citizen conversations
  • Comprehensive Mixin integrations
    • MixinCitizenManager for automatic AI bridge lifecycle management
    • MixinCitizenData for background and conversation history persistence
    • MixinMainWindowCitizen for chat UI integration
    • MixinDebugWindowCitizen for background information display
  • Network messaging system
    • AIChatMessage and AIChatResponseMessage for chat communication
    • BackgroundRequestMessage and BackgroundResponseMessage for background data sync
    • ModNetworking for network protocol management
  • Configuration system
    • ModSettings for mod-wide configuration
    • BackgroundConfigLoader for loading custom background definitions
    • BackgroundConfigData for background data structures
  • Client-side functionality
    • ClientChatHandler for handling chat on client
    • ClientBackgroundCache for caching citizen backgrounds
    • ChatWindowCitizen for chat UI rendering
  • NeoForge 1.21.1 support
    • Migration from Forge to NeoForge
    • Updated mod metadata to neoforge.mods.toml
    • Gradle wrapper integration
  • Build automation
    • GitHub Actions workflow for automated builds
  • Automated release workflow (#10)
    • GitHub Actions for automated publishing to Modrinth and CurseForge
    • Builds and uploads on GitHub release publication
    • Uses CHANGELOG.md for release notes
  • Configurable disease system (#5)
    • Job-specific disease susceptibility modifiers (miners/quarriers 2.0x, healers 0.05x, etc.)
    • Configurable contact spread rates per job type
    • DiseaseConfig.java with TOML configuration
    • MixinCitizenDiseaseHandler.java for custom disease spread logic
  • Development tools
    • VSCode settings for project
    • Git attributes configuration

Changed

  • Refactored AI bridge architecture
    • Renamed CitizenAIManager to CitizenNpcManager for clarity
    • Replaced CitizenAIBridge with CitizenNpcBridge
    • Improved conversation management with client-server network protocol
    • Enhanced system prompt generation with contextual awareness
  • Improved citizen status reporting (#3)
    • Added Level 0 → 1 build phrasing in citizen AI prompts
    • Enhanced job/request status strings with work order and requester details
    • Added null safety guards for citizen status
  • Updated dependency management
    • Moved MineColonies and related libraries from local lib/ to Maven dependencies
    • Cleaned up build.gradle configuration
  • Enhanced .gitignore to exclude build artifacts and IDE files
  • Replaced hardcoded healer disease immunity with configurable low-susceptibility modifier (#5)

Removed

  • Local library JARs from repository
    • blockui-1.20.1-1.0.193.jar
    • domum_ornamentum-1.20.1-1.0.290-snapshot-universal.jar
    • minecolonies-1.20.1-1.1.989-snapshot.jar
    • multipiston-1.20-1.2.43-RELEASE.jar
    • structurize-1.20.1-1.0.777-snapshot.jar
  • Obsolete Player2 API service classes
    • HTTPUtils.java
    • Player2APIService.java
  • Old Forge metadata (META-INF/mods.toml)
  • pack.mcmeta file
  • ConversationHistory.java (functionality integrated into new bridge)
  • ChatEventHandler.java (replaced by NpcEventHandler.java)

Комментарии

Загружаем…