# VillagerMind

**Repository Path**: cunmin18/VillagerMind

## Basic Information

- **Project Name**: VillagerMind
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VillagerMind 26.1 — AgentRuntime v2

Fabric 26.1.2 mod that gives bound villagers a unified LLM mission runtime and a public hot-reloadable WorldPatch v2 registry.

## Build

The project uses Java 25. `gradlew.bat` can use the repository-local JDK, so a global `JAVA_HOME` is not required.

```powershell
.\gradlew.bat build
.\gradlew.bat runClient
```

Version set:

- Minecraft `26.1.2`
- Fabric Loader `0.19.3`
- Fabric API `0.154.2+26.1.2`
- Loom `1.17-SNAPSHOT`

## Local profiles

Use `villager_mind:llm_handle` on a villager. Client profiles are atomically saved at:

```text
run/config/villager_mind/profiles.json
```

Endpoint, API key, model, chat/debug settings and the last selected profile are restored on the next `runClient`. API keys remain runtime-only on the logical server and are not written into world NBT.

## Automated development test

The opt-in development harness can quick-play a world, load the selected local profile, bind loaded villagers named `豆包A` and `豆包B`, force Debug logging for that test, and then leave the world running for log monitoring. It is disabled during every normal launch.

```powershell
$env:VILLAGER_MIND_AUTOTEST = '1'
$env:VILLAGER_MIND_AUTOTEST_WORLD = 'Test Agent (1)'
$env:VILLAGER_MIND_AUTOTEST_NAMES = '豆包A,豆包B'
.\gradlew.bat runClient --console=plain
```

The harness logs profile names, target UUIDs and binding results, but never logs endpoint credentials or API keys. In auto-test mode only, the normal eight-block binding distance is relaxed for loaded targets.

## AgentRuntime v2

The previous collection of independent cognition, plan, dialogue, project and defense controllers has been removed. One Agent now has one state object and one body owner:

```text
factual perception
    → one complete LLM mission (1–8 steps)
    → one Minecraft action executor
    → real world receipt
    → advance or replan from fresh perception
```

The LLM does not choose one unrelated tool every few seconds. It calls `mcp_commit_mission` once with a complete objective, rationale, success criteria and ordered steps. Minecraft then executes the mission without throwing away context.

Supported mission actions:

- `move`
- `look`
- `break_block`
- `place_block`
- `pickup_item`
- `craft_item`
- `use_item`
- `attack_entity`
- `install_patch`
- `invoke_patch`
- `delegate`
- `report`
- `wait`
- `observe`
- `speak`

Movement, breaking, placement, pickup and combat only succeed after observable Minecraft evidence. Breaking progress advances only while the villager is in range and looking at the block; leaving clears cracks, and normal drops are preserved. Dirt/stone bulk excavation requires an explicit construction-clearance need. Beds, doors, bells, workstations and storage are protected.

`look` only turns the head and `wait` only proves elapsed time; neither may claim that an item was found, food was eaten or health changed. `observe` can verify an exact item on the ground or in inventory. `use_item` visibly consumes an exact inventory item and records inventory and health before and after. Any failed action blocks the stale mission immediately so the next decision uses fresh perception instead of repeating the same impossible step three times.

Emergency survival can preempt a normal mission, but it never deletes the mission. The same executor handles fighting, fleeing, interception and extinguishing, so chat/project/defense code cannot fight over the body. Creepers are never engaged in melee, and targets are not pursued outside visible bounded range or into sealed caves.

The vanilla villager schedule Brain is suppressed for the entire lifetime of a bound Agent, so work, wandering and courtship cannot retake the body between remote decisions. Body physics, navigation, swimming support and door-capable pathfinding remain active under AgentRuntime ownership.

## Public chat and relationships

Player chat is a same-dimension public event. Every Agent updates its own relationship and threat evidence, while one reply owner answers to avoid spam. Creative/adventure/spectator or invisible players are not visually perceived and cannot be attacked merely because they typed something.

- Insults lower affinity.
- Praise and apologies raise affinity.
- One low-damage hit produces a warning, not forced retaliation.
- Repeated/severe attacks create immediate survival evidence.
- Explicit village threats cause physical interception; repeated hostility can authorize combat.
- Old asynchronous replies and plans are discarded when newer public evidence arrives.

Debug decision reasons and public Agent speech are separate settings. Public Agent speech is also recorded in the shared blackboard, so every Agent in the dimension receives recent conversation as planning context even when player-visible chat is disabled.

Non-secret affinity, attack incidents and recent social evidence are atomically persisted per world at:

```text
run/saves/<world-save>/villager_mind/agent_runtime_v2.json
```

## Multi-Agent collaboration

Free-form “we are discussing a project” loops have been removed. Collaboration requires:

- a `project_id`;
- a shared objective;
- a target Agent;
- a concrete deliverable;
- a final `report` containing evidence.

Assignments and reports are exposed through the public blackboard in every Agent snapshot. Agent-to-Agent delegation is also shown in public chat when Agent chat is enabled.

## WorldPatch v2

WorldPatch is a public world-level program registry. A patch is installed once and shared by every Agent. It is not private inventory logic.

Programs are stored atomically at:

```text
run/saves/<world-save>/villager_mind/world_patches_v2.json
```

WorldPatch documents use `schema_version: 2` with `id`, `goal`, `enabled`, `triggers`, `conditions`, and `actions`.

Supported triggers:

- `patch_installed`
- `agent_bound`
- `agent_invoke`
- `server_tick`
- `villager_hurt`
- `villager_death`
- `programmable_item_use`
- `custom_event`

Supported conditions:

- `health_below`
- `hostile_nearby`
- `entity_count`
- `time_between`
- `variable_compare`
- `random_chance`
- `goal_equals`

Supported actions:

- `apply_effect`
- `heal`
- `set_block`
- `set_blocks`
- `replace_region`
- `break_block`
- `spawn_entity`
- `broadcast_message`
- `give_programmable_item`
- `emit_event`
- `schedule_event`
- `set_variable`
- `add_variable`
- `give_item`
- `damage_entities`
- `repel_entities`
- `teleport_entities`
- `strike_lightning`
- `set_weather`

`patch_installed` is registration-only; terrain/entity mutations must run through invocation, item use or events. Multi-trigger programs require an explicit `when` scope on every action. `set_blocks` preflights all coordinates and rolls back if deployment fails. Success broadcasts are delayed until all preceding actions succeed.

Failures are tracked per patch and trigger. Three consecutive failures disable and persistently quarantine the program, with one public error message instead of an endless broadcast loop.

WorldPatch never exposes arbitrary JVM, filesystem, shell or network execution to the remote model. Minecraft registries freeze after startup, so runtime-defined “new items” use the pre-registered `villager_mind:programmable_item` carrier with patch-defined name, lore and behavior.