Escape From Somewhere Heavy

Minecraft 1.21.1 / NeoForge mod that applies a carry-capacity system to every non-creative, non-spectator player. The server calculates load, applies the movement modifier, and controls the status effects. Item weights are supplied by server data packs; capacity and load-tier boundaries are common TOML configuration.

Carry calculation

Every 20 server ticks (one second), the mod calculates:

total weight = sum(unit weight × stack count) for all carried stacks
load ratio   = total weight / carrying capacity

Counted slots and contents:

• Main inventory, including hotbar;
• Armor slots;
• Off-hand slot;
• Contents of every carried item using Minecraft's container data component, recursively. Supported vanilla containers, such as shulker boxes and bundles, therefore do not hide their contents' weight.

Both a container's own weight and every contained stack's weight are counted. Ender-chest storage and other inventories not physically carried by the player are excluded.

Every stack with a non-zero total weight shows that total in its item tooltip. The value includes the stack count and recursively included vanilla container contents.

TACZ 1.21.1 is also supported without a hard dependency: loaded rounds in guns, rounds in non-creative ammo boxes, and installed attachments are included. TACZ stores variants in item data, so define their weights with a custom_data selector.

The development runtime includes TACZ through Modrinth. Its bundled test weights set only the AWM (GunId: "tacz:ai_awp") to 6 kg and only .338 ammunition (AmmoId: "tacz:338") to 0.1 kg, so an AWM loaded with five .338 rounds weighs 6.5 kg before attachments.

An item with no valid weight definition is always 0 kg. Other non-vanilla attachment, magazine, or inventory data is not inspected unless its mod stores those contents in the vanilla container component; the parent item's own weight is still counted.

Capacity and load states

Base capacity and the three tier boundaries are common TOML configuration. Their defaults are 40 kg, 0.3, 1.0, and 1.5 respectively. Numeric capacity bonuses on equipped armor are added to the base capacity. Movement multipliers are fixed in code:

Load ratio	State	Visible effect	Movement speed	Jump strength
≤ 30%	輕盈 / Lightweight	Yes	×1.2	×1.0
>30% and ≤100%	普通 / Normal	No	×1.0	×1.0
>100% and ≤150%	負重 / Burdened	Yes	×0.5	×0.5
>150%	超重 / Overloaded	Yes	×0	×0

The mod uses transient modifiers on vanilla MOVEMENT_SPEED and JUMP_STRENGTH. At ×0 movement speed or jump strength, normal walking or jumping is stopped. It does not separately cancel flight, riding, knockback, teleportation, or movement provided by other mechanics. 輕盈、負重、超重 are applied with infinite duration and are replaced only when the calculated load tier changes. They have no particles and have English, Traditional Chinese, and Simplified Chinese names. Their icons reuse vanilla resources: Speed for 輕盈, Slowness for 負重, Weakness for 超重, and Strength for Carry Capacity Boost. Creative and spectator players are ignored; this mod's modifiers and effects are removed from them.

Common configuration

The generated config/escapefromsomewhereheavy-common.toml contains these values:

Key	Default	Meaning
capacity.base	40.0	Base carrying capacity in kg.
threshold.lightweightMaxRatio	0.3	Maximum ratio for 輕盈.
threshold.normalMaxRatio	1.0	Maximum ratio for 普通.
threshold.overburdenedMaxRatio	1.5	Maximum ratio for 負重; greater values are 超重.

Armor capacity component

The mod registers the persistent numeric data component escapefromsomewhereheavy:carry_capacity_bonus. When an item in an armor slot has this component, its finite numeric value is added directly to the player's carrying capacity in kg. The main inventory, hotbar, and off-hand do not grant this bonus.

For example, the following gives a chestplate with +20 kg capacity:

/give @s minecraft:leather_chestplate[escapefromsomewhereheavy:carry_capacity_bonus=20.0]

Item definitions or other mods can set the same component. Negative values are allowed and reduce capacity; final capacity is clamped to at least 0.1 kg.

Carry Capacity Boost effect

The beneficial escapefromsomewhereheavy:carry_capacity_boost effect increases carrying capacity by 50%. The multiplier is applied after the base capacity and all equipped-armor component bonuses have been added, before the load ratio is calculated. Its amplifier does not change the 50% value.

For example:

/effect give @s escapefromsomewhereheavy:carry_capacity_boost 60

Item-weight data pack

Create one JSON file per weighted item at:

data/<your namespace>/carry_capacity/weights/<file name>.json

Example path and contents:

data/my_pack/carry_capacity/weights/iron_ingot.json

{
  "item": "minecraft:iron_ingot",
  "weight": 0.25
}

Field	Type	Meaning
item	item ID	Exact target item. Item tags are not supported.
weight	non-negative number	Unit weight in kg; stack count multiplies it.
custom_data	object, optional	Partial match against the item's minecraft:custom_data. Every supplied field must match; extra fields are allowed.
data_components	object, optional	Exact component-value matches, keyed by data-component ID. Every supplied component must be present and equal its JSON codec value.

When multiple entries match, the entry with more conditions wins; an unconditional entry is the fallback. Files may use any data-pack namespace. Do not define the same item and condition selector more than once: it is a duplicate and logs an error. To replace an existing definition, override that exact resource path in a higher-priority pack. Invalid JSON objects, unknown item IDs or data components, and negative weights are ignored.

For example, this targets only TACZ .338 ammunition, even though all TACZ ammo variants share tacz:ammo as their registered item:

{
  "item": "tacz:ammo",
  "custom_data": {
    "AmmoId": "tacz:338"
  },
  "weight": 0.1
}

The mod currently ships an example weight for iron ingots at data/escapefromsomewhereheavy/carry_capacity/weights/example_iron_ingot.json. Override that exact path in a higher-priority data pack—using "weight": 0 if iron ingots should be weightless—if it is not part of your balance plan.

Reload behavior

On server start and every /reload, item-weight resources are read again. Changes apply on the next carry check, within 20 server ticks. When a reload removes an item's valid weight definition, that item immediately returns to 0 kg.

Current scope

Implemented:

• Exact per-item data-pack weights;
• Recursive vanilla-container weight calculation;
• Configurable base capacity and tier boundaries;
• Four load tiers, fixed movement-speed changes, and three status effects;
• English, Traditional Chinese, and Simplified Chinese effect names.

Not implemented:

• A HUD showing current weight, capacity, or load ratio;
• Player progression, professions, talents, quests, drugs, teammate abilities, map rules, and temporary capacity sources;
• Dedicated backpack or tactical-vest slots;
• Integration with non-vanilla inventory systems or weapon attachment data other than TACZ;
• Item-tag weight definitions.