Village Kingdom

# Village Kingdom Mod
Mod ID: `villagekingdom`
Supported Version: Minecraft 1.20.1 (Forge 47.4.18)

Features: Citizens autonomously build cities, dynamic job‑switching system, natural population growth, specialized occupation system, autonomous combat and inventory management.

## Entities & Occupation System
All citizens inherit the base entity `SurvivorEntity`. They come with a 27‑slot inventory, auto‑pickup, auto‑equipment, autonomous pathfinding, door‑opening and group‑aid behaviour. They drop all items upon death.

Each occupation uses distinct vanilla‑style skins, dedicated work blocks and unique production mechanics.

### Occupation List & Mechanics
1. **Survivor**
ID: `survivor`
Function: Unassigned starting citizen; source entity for all job conversions.

2. **Builder**
ID: `builder`
Capability: Automatically construct up to 2 buildings per in‑game day.
Logic: Fetch logs, cobblestone and emeralds from nearby containers. Structures spawn instantly and auto‑fill ground dirt blocks to prevent floating builds.

3. **Lumberjack**
ID: `lumberjack`

4. **Miner**
ID: `miner`
Work Block: Stonecutter
Work Tick Rate: Every 10 seconds
Output: Cobblestone
Storage Logic: Automatically deposit cobblestone into nearby barrels once inventory holds 32 cobblestone.

5. **Cook**
ID: `cook`
Work Block: Smoker
Work Tick Rate: Every 10 seconds
Consumption: 1 Oak Log (as fuel)
Function: Fetch raw food automatically and cook it into edible food.

6. **Merchant**
ID: `merchant`
Work Tick Rate: Every 10 seconds
Consumption: All items except oak logs, cobblestone, emeralds, food and equipment.
Function: Convert useless items into emeralds.

7. **Soldier (Combat Unit)**
ID: `soldier`
Ranged Attack: Crossbow range of 32 blocks.
Melee Trait: Jump‑strike deals 1.5× critical damage.
Growth Mechanic: Permanently gain +1 max health and +1 attack damage per mob kill (unbounded growth).
Current Status: Entity implemented; job conversion method not yet added.

8. **Blacksmith**
ID: `blacksmith`
Work Block: Smithing Table
Daily Work Limit: 5 forging operations.
Level System (Level 1‑4):
- Level 2: Forge a total of 10 items
- Level 3: Forge a total of 30 items
- Level 4: Forge a total of 60 items
Emerald cost scales with level; outputs tools and armor matching the smith’s tier.

9. **Farmer**
ID: `farmer`
Work Block: Composter
Work Tick Rate: Every 10 seconds
Fixed Output: 1 Bread.

## Building System (Consumption, Weight & Functions)
All buildings are automatically generated by Builders. Each building occupies one unique chunk. Dirt blocks are auto‑placed downward (up to 10 blocks deep) to eliminate floating structures.

|Building|Oak Logs|Cobblestone|Emeralds|Notes|
|---|---|---|---|---|
|Initial Camp|‑|‑|‑|Spawn point; generates starting citizens and supplies|
|Small House|5|3|1|Residential building for population expansion|
|Large House|10|6|2|High‑capacity residence|
|Farm|8|4|1|Job conversion point for Farmers|
|Warehouse|12|8|3|Public community storage|
|Lumberjack Hut|8|4|2|Job conversion point for Lumberjacks|
|Builder Hut|6|8|4|Job conversion point for Builders|
|Stonemason Hut|5|12|5|Job conversion point for Miners|
|Kitchen|10|6|2|Job conversion point for Cooks|
|Small Market|15|10|8|Job conversion point for Merchants|
|Blacksmith Hut|10|6|5|Job conversion point for Blacksmiths|

> Important: Every occupational building must contain its corresponding work block, otherwise the occupation will stop functioning.

## Core Game‑Tick Mechanics
1. **Initial Camp Spawning**
When a player first enters a world, the mod searches for a suitable chunk and spawns the Initial Camp.
Fixed spawns: 3 Survivors + 2 Builders.
Starting Supplies: 5 sets of leather armor, 2 stone pickaxes, 5 baked potatoes; 128 oak logs, 128 cobblestone, 128 emeralds each.
> Note: Known inventory‑desync bug: some stacks may occasionally fail to spawn.

2. **Daily Automatic Job Assignment (24000 ticks = one Minecraft day)**
The system compares current occupation counts against the number of occupational buildings. Unassigned Survivors get converted into needed professions.
Job conversion preserves inventory contents and entity status.

3. **Natural Population Growth (Updated each in‑game day)**
New citizen formula: `Total Buildings × 0.1` (rounded to integer).
Guaranteed minimum: +1 new citizen; hard maximum: +10 new citizens.
Fresh Survivors spawn within the safe camp boundary.

4. **Intelligent Construction Logic**
Builders have a hard cap of 2 buildings per day.
If materials are insufficient, builders pull resources from containers within a 16‑block radius.
Structures snap to terrain and auto‑generate dirt foundation blocks.

5. **General Citizen‑AI Behaviour**
- Can open doors; prefer dirt‑path navigation within a 16‑block pathfinding range.
- Auto‑pickup of item drops within 16 blocks.
- Inventory auto‑sort every 6000 ticks (¼ of an in‑game day).
- Automatically equip best‑in‑slot weapons and armor; switch between melee and ranged combat dynamically.
- Call nearby allies for support when taking damage.
- Drop every item upon death.

6. **Mob‑Aggro Rules**
Hostile mobs will actively target Village Kingdom citizens. Soldiers receive exclusive combat bonuses and permanent stat growth.

## World‑Save Data System
The mod maintains its own independent saved‑data files:
- `BuildingPlacementSavedData`: Chunk‑occupation tracker to prevent duplicate building generation.
- `InitialCampSavedData`: Global storage for initial‑camp position.
- `VillageStatsSavedData`: Core save file for building counters, population values and job‑assignment data.

## Future Development Roadmap
These are planned features for future updates.
1. **Kingdom Tier‑Up System (Tier 1 → Tier 2 Kingdom)**
When total building count, population and resource thresholds are met, your kingdom can advance to Tier 2 and unlock new gameplay phases.
2. **Tier‑2 exclusive buildings**
Unlocks advanced structures: Manors, barracks, more medieval decorative pieces and wall‑related fortifications.
3. **Camp Guardian NPC for Early‑game Defence**
A dedicated lord‑guardian NPC will spawn alongside the starting camp, to provide protection before Soldiers become available.