Repository navigation
1.20.1 Configuration
Version: This guide applies to Minecraft 1.20.1 (Forge).
Two config files. Every gameplay value is in the server config, so the same mod fits singleplayer, servers and story modpacks without code changes.
Located in saves/<world>/serverconfig/ratworker-server.toml (or defaultconfigs/ratworker-server.toml for modpacks). Forge sends it to clients when they join. Every key is read when it is used, so changes apply at once; /ratworker config set and /ratworker config reload change values without a restart.
general.preset picks a set of defaults. Keys marked [P] default to PRESET (or -1 for numbers) and then take the preset's value; any explicit value wins.
| Key | CUSTOM | SANDBOX | SURVIVAL | THEMED |
|---|---|---|---|---|
unlocking.mode |
TOMES | FREE | TOMES | TOMES |
needs.hungerEnabled |
true | false | true | true |
needs.thirstEnabled |
true | false | true | true |
needs.needsKill |
false | false | false | false |
death.permaDeath |
true | false | true | true |
acquisition.requireStageToRecruit |
false | false | false | true |
general.maxWorkersPerPlayer |
3 | 10 | 3 | 3 |
general.maxWorkersPerChunk |
6 | 16 | 6 | 4 |
general.maxActiveWorkersPerServer |
64 | 200 | 60 | 40 |
SANDBOX is the easy singleplayer setup (everything unlocked, no needs). THEMED is meant for story modpacks.
| Key | Default | Notes |
|---|---|---|
preset |
CUSTOM | CUSTOM, SANDBOX, SURVIVAL, THEMED. |
enabled |
true | Master switch. Off = workers stand idle and contracts do nothing. |
maxWorkersPerPlayer |
-1 [P] | Counts unloaded workers and workers waiting to respawn. |
maxWorkersPerChunk |
-1 [P] | Checked when a worker is recruited. |
maxActiveWorkersPerServer |
-1 [P] | Workers running a task at the same time. Checked when a task starts. |
workOffline |
false | Keep working while the owner is offline (only in loaded chunks). |
opBypass |
true | Operators can command any worker. In TOMES mode it does not unlock tasks. |
teamSharing |
TEAM | Who can command: OWNER, TEAM (FTB Teams; without it same as OWNER), EVERYONE. |
allowCommands |
true | Non-operators may use /ratworker task, stop, needs get, supply on workers they command. |
| Key | Default | Notes |
|---|---|---|
contractEnabled |
true | |
contractRequiresSpot |
false | The contract only works on blocks in the tag ratworker:recruit_spots (default: beds). |
requireStageToRecruit |
PRESET [P] | Recruiting needs the stage in recruitStage. |
recruitStage |
ratworker_recruit | KubeJS stage, scoreboard tag or /ratworker unlock record. |
nameMode |
PLAYER_CHOSEN | POOL = random first name; CUSTOM = only named contracts work; PLAYER_CHOSEN = anvil name, else the pool. |
namePool |
[] | First names; empty = datapack pools. |
skinPool |
[] |
namespace:textures/....png, optionally with ;slim; empty = datapack pools. |
Meters go from 0 to 20; drain values are points per minute.
| Key | Default | Notes |
|---|---|---|
hungerEnabled / thirstEnabled
|
PRESET [P] | Thirst is always off without Thirst Was Taken. |
hungerDrainIdle / hungerDrainWorking
|
0.3 / 1.0 | Working rate is multiplied by the task's hungerCost. |
thirstDrainIdle / thirstDrainWorking
|
0.4 / 1.2 | Working rate is multiplied by the task's thirstCost. |
drainMultiplier |
1.5 | Multiplies every loss (time and effort). Higher = harder to keep workers going. |
actionExhaustion |
0.1 | Share of the effort a simulated action charges a player (1 = as hard as for a player). |
thirstExhaustionRatio |
1.0 | Water lost per point of effort, relative to food. |
eatBelow / drinkBelow
|
14 / 14 | Auto eat and drink below these values. |
lowThreshold |
6 | Below this a need is low: slower work. |
lowSlowdown |
1.5 | Cooldown multiplier while low. |
starvationDamage / starvationInterval
|
1.0 / 10 | Damage and seconds between hits at 0. |
needsKill |
PRESET [P] | Off = starvation stops at 1 HP. |
foodTag |
"" | Item tag accepted as food; empty = anything edible. |
drinkTag |
ratworker:drinks | Extra drinks (value 4). |
purityEffects |
true | Low purity drinks give an effect. |
dirtyEffect / dirtyEffectSeconds
|
minecraft:poison / 15 | Purity 0. Empty = none. |
unsafeEffect / unsafeEffectSeconds
|
minecraft:poison / 4 | Purity 1. Empty = none. |
regenAbove / regenInterval / regenExhaustion
|
18 / 4 / 6.0 | Heal 1 HP every interval seconds while food (and water) are at least this; effort per HP. |
supplyRange |
32 | Max distance worker to supply container. |
supplyTake |
4 | Food items and drink items taken per supply run. |
| Key | Default | Notes |
|---|---|---|
permaDeath |
PRESET [P] | Off = the worker comes back next to its owner after respawnCooldown seconds. |
dropInventory |
true | Off (with respawn) = it keeps its items. |
ownerFriendlyFire / teamFriendlyFire
|
false / false | Whether the owner / teammates can hurt it. Creative players always can. |
respawnCooldown |
300 | Seconds. |
Reserved for the guard task and radiation (not active yet): radiation, hazmatProtects, fleeHealth (6.0), threatBehaviour (FLEE, DEFEND, PASSIVE), hostileTag. Workers never attack anything on their own.
| Key | Default | Notes |
|---|---|---|
maxBlockScansPerTick |
256 | Blocks a scanning task (farm) checks per tick. |
pathRecomputeTicks |
20 | Path refresh toward a moving target. |
taskTickInterval |
2 | Task logic runs every N ticks. |
stuckTicks / maxPathFailures
|
100 / 5 | No progress for N ticks counts as one failure; after N failures in a row the task stops. |
holdIntervalTicks |
4 | Repeat rate of held inputs when a task gives none (the crank uses its own holdInterval). |
maxFakeInteractionsPerTick |
32 | Simulated interactions per server tick, all workers together. |
| Key | Default | Notes |
|---|---|---|
mode |
PRESET [P] | TOMES = per worker, from training manuals (Training); STAGES = per player, from a KubeJS stage, a scoreboard tag or /ratworker unlock; OPS_ONLY; FREE; NONE = only /ratworker unlock. |
stageTemplate |
ratworker_ | STAGES mode stage name of a task. |
levelStageTemplate |
ratworker__ | Reserved. |
scoreboardTags |
true | STAGES mode accepts /tag names too. |
leveling |
false | Reserved. |
| Key | Default | Notes |
|---|---|---|
xpFromWork |
true | Off = only scripts and commands give XP. |
xpPerMinute |
5.0 | Times the task's xpRate. |
innateTasks |
[ratworker:follow, ratworker:stay] | Known without a manual. |
health.* |
max 5, base 20, growth 1.5, per level 2.0 | +HP per level. |
strength.* |
max 5, base 20, growth 1.5, per level 1.0 | +damage per level. |
hunger.* / thirst.*
|
max 5, base 15, growth 1.5, per level 0.1 | Fraction of loss removed per level, per task. |
speed.* |
max 6, base 15, growth 1.5, per level 2.0 | Crank: ticks removed per level. Farm and scripts: -10 % per level. |
Each branch has maxLevel, baseCost, costGrowth, perLevel. Cost of level n+1 = baseCost x costGrowth^n.
One section for each built-in task (follow, stay, crank, farm, and the reserved guard and haul). Every number is -1 = use the datapack value or the default.
| Key | Meaning |
|---|---|
enabled |
Task can be used. |
unlockStage |
STAGES mode: stage name; empty = stageTemplate. |
hungerCost / thirstCost
|
Drain multipliers while running. |
speedMultiplier |
Walking speed multiplier. |
range |
Task radius (see Tasks). |
learnXp / xpRate
|
XP needed with a manual / XP gain multiplier. |
levels |
Reserved. |
follow: stopDistance, teleportDistance
|
2.5 / 24 |
crank: holdInterval, minHoldInterval, reverse
|
16 / 4 / 0 |
farm: actionCooldown, till, depositAt
|
20 / 1 / 16 |
Visual settings only.
| Key | Default | Notes |
|---|---|---|
hud.jadeTooltip |
true | Worker lines in Jade. |
colors.accent / warn / danger
|
"" |
RRGGBB; empty = built-in palette. |
defaultconfigs/ratworker-server.toml, missing keys keep their defaults:
[general]
preset = "THEMED"
[acquisition]
contractRequiresSpot = true
nameMode = "POOL"
[needs]
drainMultiplier = 2.0
[skills]
xpPerMinute = 4.0Rat Worker is released under the MIT license. Author: Stefano Manca.
Guides & Reference
Scripting & Mod API
Version Overviews