Villager Chest Organizer: Chest sorter

You can support me through- https://ko-fi.com/knightmare61825

This mod adds hireable worker NPCs that automatically move items from a chosen source container into nearby labeled storage. Instead of building complicated automation lines, you can hire an Organizer, assign it to a source chest, barrel, shulker box, hopper, or other supported storage, and let it sort items by item frames, tags, and fallback rules.
Each Organizer is a dedicated custom entity with ownership, follow mode, synced status, real carried inventory, configurable behavior, and multiplayer-safe server-side logic. Organizers can walk items between containers, use doors, use nearby buttons and levers for iron doors, use ladders, remember destinations, and return to their source area when idle.
This mod is designed to work in both singleplayer and multiplayer.

## Main Features:
- Hire an Organizer from a villager using a configurable currency item and cost
- Each hired Organizer gets a unique name like Organizer 1, Organizer 2, and so on
- Hiring creates a linked signed book for that specific Organizer
- Assign a source container using a feather and the linked book
- Supports exact item sorting with item frames
- Supports grouped sorting with [tag] signs
- Supports fallback storage with [fallback] signs
- Uses a real carried inventory instead of fake transfers
- Shows status above the Organizer, such as Idle, Walking to source, To destination, Carrying,     Paused, Blocked, or Destination full
- Sneak-right-click to toggle follow mode
- Ownership protection for multiplayer
- Optional team access
- Chunk-safe behavior: pauses instead of breaking when required chunks are unloaded
- Configurable work range, carry size, hiring cost, currency item, path fail limits, and recovery behavior
- First-time players receive an in-game guide book

## How Hiring Works To hire an Organizer:
1. Hold a Book and Quill
2. Have the configured hiring item in your inventory
3. Right-click a villager
By default, hiring costs 20 minecraft:emerald.

**When hired:**
the villager is converted into an Organizer
it gets a unique name such as Organizer 1
your Book and Quill becomes a signed linked book for that Organizer
That book is important because it is used later to assign the Organizer’s source container.

## **How To Assign a Source Container To assign a source:**
1. Hold the linked Organizer book in your offhand
2. Hold a Feather in your main hand
3. Right-click the source container
Supported source containers include:
- chests
- double chests
- barrels
- shulker boxes
- hoppers
- many modded containers that expose a normal inventory
Once assigned, the Organizer will use that container as its pickup point.

### How Destination Sorting Works: The Organizer searches nearby containers around the source and decides where items should go based on labels.

## There are 3 destination rule types:

1. Exact item match with item frames
- Put an item frame on the destination container
- Put the item inside the frame
- That container will accept that exact item
Example:chest with a wheat item frame only accepts wheat
2. Tag-based sorting with signs
- Place a sign directly next to the destination container
- First line must be [tag]
- Second line must be a valid item tag id
Example:
[tag]
minecraft:logs
That container will accept all items in the minecraft:logs tag meaning all logs.
3. Fallback container
- Place a sign directly next to the container
- First line must be [fallback]
Example:
[fallback]
That container is used for items that do not match any exact item frame or [tag] rule.

### Destination Priority The Organizer uses destinations in this order:
1. exact item-frame match
2. [tag] match
3. [fallback]
*If multiple valid destinations exist for the same item, the Organizer prefers the fullest matching container.

**Example Setup Example storage room:**
- Source barrel contains mixed items
- Chest with wheat item frame for wheat
- Barrel with sign:
[tag]
minecraft:logs
for all logs
- Chest with sign:
[fallback]
for anything unmatched

**Result:**
wheat goes to the wheat chest
oak log, birch log, spruce log, etc. go to the log barrel
everything else goes to the fallback chest

Organizer Controls:
- Right-click Organizer: shows its current status
- Sneak-right-click Organizer: toggles follow mode
- Sneak-right-click again: stops follow mode and sends it back to its source if one is assigned
- /organizer info <target>: shows owner, source, target, status, follow mode, carried item, and scan radius
- Pathfinding and Movement Organizers are made to function inside real bases, not just flat test worlds.
They can:
- walk between source and destination containers (even pathfind to stairs)
- open normal doors
- return to their source area when idle
- pause safely when chunks are unloaded
- avoid breaking their behavior when paths fail repeatedly
- If no valid destination exists, they show Destination full instead of endlessly wandering.

### Multiplayer Features Organizer is built with multiplayer use in mind:
- each Organizer belongs to a player
- other players cannot use or reassign it unless allowed
- optional team-based access can be enabled in config
- important gameplay logic is server-side and authoritative
- synced state keeps status, owner, source, and follow mode reliable in multiplayer

**First-Join Guide Book When a player joins for the first time, they receive an in-game written guide book explaining:**
- how to hire an Organizer
- how to assign a source container
- how item frame sorting works
- how [tag] signs work
- how [fallback] works
- how to control an Organizer

**Configuration All main gameplay settings are server-side in:
world/serverconfig/organizer-server.toml**

Current config options:
frameScanRadius
default: 10
how far from the source the Organizer searches for labeled destinations

carryAmount
default: 64
maximum number of items the Organizer carries per trip

hiringCost
default: 20
number of currency items required to hire an Organizer

hiringCurrencyItem
default: "minecraft:emerald"
exact item id used as hiring currency
Example:
hiringCurrencyItem = "minecraft:diamond"
hiringCost = 5

maxWorkDistanceFromSource
default: 32
maximum distance from the source that an Organizer is allowed to use for destinations

pathFailLimit
default: 5
number of repeated path failures allowed before the Organizer becomes blocked

allowTeleportRecovery
default: true
if false, teleport-based recovery is disabled

teleportToSourceOnPathFailure
default: false
if true, the Organizer may teleport back to the source after repeated path failures

allowTeamAccess
default: false
if true, players on the owner’s team can control the Organizer

You can support me through- https://ko-fi.com/knightmare61825

This mod adds hireable worker NPCs that automatically move items from a chosen source container into nearby labeled storage. Instead of building complicated automation lines, you can hire an Organizer, assign it to a source chest, barrel, shulker box, hopper, or other supported storage, and let it sort items by item frames, tags, and fallback rules. Each Organizer is a dedicated custom entity with ownership, follow mode, synced status, real carried inventory, configurable behavior, and multiplayer-safe server-side logic. Organizers can walk items between containers, use doors, use nearby buttons and levers for iron doors, use ladders, remember destinations, and return to their source area when idle. This mod is designed to work in both singleplayer and multiplayer.

Main Features:

• Hire an Organizer from a villager using a configurable currency item and cost
• Each hired Organizer gets a unique name like Organizer 1, Organizer 2, and so on
• Hiring creates a linked signed book for that specific Organizer
• Assign a source container using a feather and the linked book
• Supports exact item sorting with item frames
• Supports grouped sorting with [tag] signs
• Supports fallback storage with [fallback] signs
• Uses a real carried inventory instead of fake transfers
• Shows status above the Organizer, such as Idle, Walking to source, To destination, Carrying, Paused, Blocked, or Destination full
• Sneak-right-click to toggle follow mode
• Ownership protection for multiplayer
• Optional team access
• Chunk-safe behavior: pauses instead of breaking when required chunks are unloaded
• Configurable work range, carry size, hiring cost, currency item, path fail limits, and recovery behavior
• First-time players receive an in-game guide book

How Hiring Works To hire an Organizer:

1. Hold a Book and Quill
2. Have the configured hiring item in your inventory
3. Right-click a villager By default, hiring costs 20 minecraft:emerald.

When hired: the villager is converted into an Organizer it gets a unique name such as Organizer 1 your Book and Quill becomes a signed linked book for that Organizer That book is important because it is used later to assign the Organizer’s source container.

How To Assign a Source Container To assign a source:

1. Hold the linked Organizer book in your offhand
2. Hold a Feather in your main hand
3. Right-click the source container Supported source containers include:

• chests
• double chests
• barrels
• shulker boxes
• hoppers
• many modded containers that expose a normal inventory Once assigned, the Organizer will use that container as its pickup point.

How Destination Sorting Works: The Organizer searches nearby containers around the source and decides where items should go based on labels.

There are 3 destination rule types:

1. Exact item match with item frames

• Put an item frame on the destination container
• Put the item inside the frame
• That container will accept that exact item Example:chest with a wheat item frame only accepts wheat

1. Tag-based sorting with signs

• Place a sign directly next to the destination container
• First line must be [tag]
• Second line must be a valid item tag id Example: [tag] minecraft:logs That container will accept all items in the minecraft:logs tag meaning all logs.

1. Fallback container

• Place a sign directly next to the container
• First line must be [fallback] Example: [fallback] That container is used for items that do not match any exact item frame or [tag] rule.

Destination Priority The Organizer uses destinations in this order:

1. exact item-frame match
2. [tag] match
3. [fallback] *If multiple valid destinations exist for the same item, the Organizer prefers the fullest matching container.

Example Setup Example storage room:

• Source barrel contains mixed items
• Chest with wheat item frame for wheat
• Barrel with sign: [tag] minecraft:logs for all logs
• Chest with sign: [fallback] for anything unmatched

Result: wheat goes to the wheat chest oak log, birch log, spruce log, etc. go to the log barrel everything else goes to the fallback chest

Organizer Controls:

• Right-click Organizer: shows its current status
• Sneak-right-click Organizer: toggles follow mode
• Sneak-right-click again: stops follow mode and sends it back to its source if one is assigned
• /organizer info : shows owner, source, target, status, follow mode, carried item, and scan radius
• Pathfinding and Movement Organizers are made to function inside real bases, not just flat test worlds. They can:
• walk between source and destination containers (even pathfind to stairs)
• open normal doors
• return to their source area when idle
• pause safely when chunks are unloaded
• avoid breaking their behavior when paths fail repeatedly
• If no valid destination exists, they show Destination full instead of endlessly wandering.

Multiplayer Features Organizer is built with multiplayer use in mind:

• each Organizer belongs to a player
• other players cannot use or reassign it unless allowed
• optional team-based access can be enabled in config
• important gameplay logic is server-side and authoritative
• synced state keeps status, owner, source, and follow mode reliable in multiplayer

First-Join Guide Book When a player joins for the first time, they receive an in-game written guide book explaining:

• how to hire an Organizer
• how to assign a source container
• how item frame sorting works
• how [tag] signs work
• how [fallback] works
• how to control an Organizer

Configuration All main gameplay settings are server-side in: world/serverconfig/organizer-server.toml

Current config options: frameScanRadius default: 10 how far from the source the Organizer searches for labeled destinations

carryAmount default: 64 maximum number of items the Organizer carries per trip

hiringCost default: 20 number of currency items required to hire an Organizer

hiringCurrencyItem default: "minecraft:emerald" exact item id used as hiring currency Example: hiringCurrencyItem = "minecraft:diamond" hiringCost = 5

maxWorkDistanceFromSource default: 32 maximum distance from the source that an Organizer is allowed to use for destinations

pathFailLimit default: 5 number of repeated path failures allowed before the Organizer becomes blocked

allowTeleportRecovery default: true if false, teleport-based recovery is disabled

teleportToSourceOnPathFailure default: false if true, the Organizer may teleport back to the source after repeated path failures

allowTeamAccess default: false if true, players on the owner’s team can control the Organizer

You can support me through- https://ko-fi.com/knightmare61825