NPC Logistics

Tired of running between chests yourself? NPC Logistics lets you hire worker NPCs and put them to work — collecting, crafting, and delivering items along programmable routes, or hand them a tool and a couple of tokens and they'll take on an autonomous Role, like farming a plot completely on their own.

---

How it works

Routes and roles are both built from Location Tokens — small craftable items you place at the spots you care about. Each token marks what should happen there:

Token	Colour	Purpose
Collect Token	🔵 Blue	Pick up items from this container
Craft Token	🟡 Amber	Craft a recipe at this station
Deposit Token	🟢 Green	Drop off items into this container
Jobsite Token	🟣 Purple	Centre point of a Role worker's job area
Bed Token	🩵 Light blue	Assigns where a Role worker sleeps at night

Hand a Work Order Scroll to a worker NPC, configure the route in their GUI, and they'll walk the loop autonomously — collecting, processing, and depositing without any further input from you. Or equip a worker with a tool, a Jobsite Token, and a Deposit Token instead, and they'll work a Role continuously with no scroll required at all.

---

Features

• Programmable delivery routes — chain any combination of Collect → Craft → Deposit stops, with per-item quantity filters (All / Full Stacks / Partial)
• Autonomous Roles — equip a worker with a tool + Jobsite Token + Deposit Token and they take over a job area on their own
• Farmer role — tills, plants, harvests, and restocks seeds from a linked chest, no input needed once set up
• Shepherd role — shears sheep within range of a jobsite/pen and deposits the wool automatically
• Work Goggles — a helmet that overlays a worker's route in-world (green = collect, red = deliver, gold = both)
• Night-time sleep — Role workers find their assigned Bed Token (or shelter) after dark; toggle it off per-worker if you want them working around the clock
• Five-tab worker GUI — Equipment, Orders, Cargo, Role, and Tasks, all from one screen
• Crafting Tasks — full gather → craft → deposit pipelines, up to 8 rows per worker
• No pipes, no power — logistics run on NPC labour; fits vanilla-adjacent modpacks

---

Getting started

For delivery routes:

1. Craft a Work Order Scroll — this becomes the worker's instruction sheet
2. Craft Location Tokens for each stop on the route (Collect, Craft, or Deposit)
3. Place the tokens at each chest, crafting station, or storage block
4. Right-click a Worker NPC to open their GUI, add the Scroll in the Orders tab
5. Close the GUI — the worker starts their route immediately

For an autonomous Role (e.g. Farmer):

1. Craft a Jobsite Token and place it at the centre of the work area
2. Craft a Deposit Token and place it at a chest for the harvest/output
3. Right-click a Worker NPC, open the Role tab, and fill the Tool, Jobsite Token, and Deposit Token slots
4. Close the GUI — the kit activates and the worker starts working the role on their own

Workers are persistent, survive server restarts, and resume their last active order or role on load.

---

Worker GUI

Tab	What you do here
Equipment	Armour, tools, Work Order Scroll slots, rename, custom skin URL
Orders	View and manage active Work Order Scrolls and their stops
Cargo	Take-only 18-slot view of everything the worker is carrying
Role	3-slot kit (Tool / Jobsite Token / Deposit Token) that grants an autonomous Role, plus a Sleep at Night toggle
Tasks	Up to 8 crafting task rows — Collect, Recipe, Craft, and Deposit slots per row

---

Location Tokens & Recipes

Item	Recipe
Work Order Scroll	Paper + Paper + Feather + Ink Sac
Collect Token	Gold Ingot + Lapis Lazuli
Craft Token	Gold Ingot + Blaze Powder
Deposit Token	Gold Ingot + Emerald
Jobsite Token	Gold Ingot + Compass
Bed Token	Gold Ingot + Feather
Work Goggles	2× Glass Pane + Iron Ingot + Gold Ingot

---

Admin commands

Command	Effect
/workorder spawn [x y z]	Spawn a Logistics Worker
/workorder addstop <worker> <x y z> collect|deliver|both	Add a stop to a worker's route
/workorder startorder <worker> "Route Name"	Start a named route
/workorder cancel <worker>	Cancel the worker's current order
/workorder status <worker>	Report a worker's current status
/workorder setrepeating <worker> true|false	Toggle whether a route repeats

---

Requirements

• Minecraft 1.20.1
• Fabric Loader ≥ 0.15.0
• Fabric API 0.92.6+1.20.1
• Java 17+ (runtime) — building from source requires JDK 21

---

Compatibility

NPC Logistics is storage-agnostic — workers interact with any block that exposes a standard inventory. It works alongside storage mods (Tom's Simple Storage, Refined Storage, AE2) without conflict.

---

Roadmap

• Additional roles: Miner, Woodcutter, Fisher
• Multi-dimension pathfinding
• Footstep and work-complete sounds
• Location Token visual beam at stamped position
• Double-chest support
• 3rd-party storage block compatibility

---

MIT licensed · Source on GitHub · Report issues on the issue tracker