AI-Generated Content Disclosure

All content included in this mod (textures, models, code, sounds, etc.) is entirely generated by AI tools. The displayed images are actual in-game screenshots that accurately reflect the mod's effects, but all visual elements within them are AI-generated. If you have any questions, feel free to leave a comment.

---

KG Weight

KG Weight adds a configurable item weight system for Minecraft Forge 1.20.1. You can assign KG weights to different items. Items in the player's inventory, armor, offhand, expanded backpacks, and certain extended slots are all counted, and movement speed is reduced based on the carried weight.

Main Features

• Items have no weight by default; administrators can set weights in real-time within the game.
• Weight is distinguished by "item registry name + stable NBT fingerprint", supporting differences such as enchantments, custom names, and stable attachments.
• Stable NBT handling is applied to dynamic NBT items from mods like TaCZ, Zhuoyu Frontline, gun packs, and knife packs, preventing weight from becoming invalid due to changes like ammo count, reload status, fire mode, aiming state, experience, level, and kill counts.
• For modified TaCZ guns, weight is calculated as "gun base weight + installed attachment weights"; attachment weights can be set separately.
• Supports cosmetic weight: the item displays weight but does not contribute to this mod's slowdown, suitable for items whose weight penalty is already handled by another mod.
• Backpacks, armor, offhand, Forge ITEM_HANDLER extended slots, and items inside containers (internal inventories) are all counted.
• Attempts to be compatible with Curios slots without making Curios a hard dependency.
• An upper-right HUD shows total weight, slowdown weight, speed reduction, and Load Needle effects.
• HUD customization: press K by default to open the edit interface, allowing you to drag the position, resize, and adjust transparency.
• View other online players' weights and individually toggle whether a player is affected by this mod's slowdown.
• Adds 3 advancements: setting a weight for the first time, total weight exceeding 3000 KG, and crafting a Load Needle for the first time.
• Built-in Simplified Chinese and English texts.

Slowdown Modes

The mod provides three slowdown strategies:

• stage: Stage mode – for every full interval of KG, a slowdown increment is applied.
• linear: Linear mode – each additional KG reduces movement speed by a fixed amount.
• segmented: Segmented linear mode – different weight ranges can have different slowdown intensities.

The speed limiting method can also be switched:

• simple: Default method, only adjusts the player's movement speed attribute, offering better compatibility.
• complex: Additionally restricts horizontal speed in the air, used to reduce extra displacement from sprint-jumping.

Load Needles

The mod adds 5 levels of Load Needles that temporarily reduce effective weight. Load Needles do not use vanilla potion effects; at most one needle is active at a time. Using a Load Needle of any level will completely replace the current needle's effect and remaining duration, and the message "Potion used" will be displayed.

Default effects:

• Level 1: reduces 25 KG, lasts 60 seconds
• Level 2: reduces 50 KG, lasts 90 seconds
• Level 3: reduces 100 KG, lasts 120 seconds
• Level 4: reduces 200 KG, lasts 180 seconds
• Level 5: reduces 400 KG, lasts 240 seconds

Recipes primarily use minerals and glass bottles:

• Level 1: Glass Bottle, Copper Ingot, Iron Ingot, Redstone Dust
• Level 2: Glass Bottle, Iron Ingot, Gold Ingot, Redstone Dust
• Level 3: Glass Bottle, Lapis Lazuli, Diamond, Redstone Dust
• Level 4: Glass Bottle, Emerald, Diamond, Gold Ingot
• Level 5: Glass Bottle, Netherite Scrap, Diamond, Emerald

Load Needle effects, duration, and use time can be adjusted with commands.

Common Commands

All management commands require permission level 2.

/kgweight help
/kgweight setheld <kg> [affectsSlowdown]
/kgweight queryheld
/kgweight slowdownheld <true|false>
/kgweight mode <stage|linear|segmented>
/kgweight speedlimit <simple|complex>
/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight player query <player>
/kgweight player slowdown <player> <true|false>
/kgweight nbtignore list

Chinese alias:

/重量

For complete instructions, see the Full Usage Guide provided below.

Compatibility Notes

• Backpacks that provide internal inventory capabilities (such as Sophisticated Backpacks) are counted.
• If other mods directly expand player inventory slots, as long as they are exposed as a Forge ITEM_HANDLER, this mod will attempt to count them.
• Curios slots are read through optional reflection.
• If a mod uses entirely private data structures without exposing capabilities, individual adaptation is required.
• TaCZ, Zhuoyu Frontline, and their unofficial gun/knife packs can usually be adapted through stable NBT and NBT ignore rules; guns that inherit TaCZ attachment NBT will automatically accumulate the weights of installed attachments.

Environment

• Minecraft 1.20.1
• Forge 47.x
• Java 17
• Required on both client and server

---

Full Usage Guide

Environment:

• Minecraft 1.20.1
• Forge 47.x
• Java 17

Installation:

1. Place kgweight-3.0.0.jar into the mods folder of both client and server.
2. In multiplayer, the server and all clients that need to see the HUD and use Load Needles must install it.
3. After entering the world, use /kgweight help or /重量 to view in-game command help.

Basic Features

• Items have no weight by default; they count as 0 KG if not set.
• Weight unit is KG.
• Stacked items calculate as "single item weight × quantity".
• Inventory, armor, and offhand all count towards the player's total weight.
• The current version additionally reads the Forge ITEM_HANDLER capability, attempting compatibility when other mods directly expand the player inventory.
• The current version recursively reads items' own internal inventories, adapting to expanded backpack items like Sophisticated Backpacks that hold items inside.
• The current version attempts to read Curios slots via optional reflection; when Curios or decorative backpack slots are installed, Curios is not a hard dependency.
• To prevent infinite loops from backpack-in-backpack, the internal inventory recursion depth is limited to 4 layers.
• Items can be set with "cosmetic weight only": displayed in total weight but not contributing to this mod's slowdown.
• The screen HUD displays total weight, slowdown weight, speed reduction, and Load Needle effects.

Compatibility notes:

• Whether expanded backpacks and extended slots can be counted depends on whether the corresponding mod exposes those slots as Forge ITEM_HANDLER or Curios slots.
• Backpacks that properly provide internal inventory capabilities, such as Sophisticated Backpacks, are counted.
• If a backpack mod uses entirely private data structures without exposing capabilities, this mod cannot generically read them and requires separate adaptation.

K Key Visual Settings

HUD adjustments and some slowdown/speed limit configurations can be done through the UI, without entering commands.

Default key:

K

The UI has three tabs:

• Display: Drag the preview text to adjust position, use sliders to adjust size and transparency (minimum transparency limited to 1%).
• Slowdown Strategy: Switch between stage, linear, and segmented modes, and adjust the corresponding KG stages, step sizes, and slowdown percentages.
  • The segmented slowdown list supports mouse wheel and a right-side scrollbar, allowing you to view and edit all segments directly in the UI.
• Speed Limit: Switch between simple and complex, and adjust the complex mode's max speed factor, min speed factor, and curve.

Description:

• Display settings are client-side local settings, saved per client to config/kgweight-hud.json.
• Slowdown strategy and speed limit settings are server/world rules; they are only written when you click "Apply to Server".
• In multiplayer, modifying server/world rules requires permission level 2 (singleplayer with cheats enabled, or multiplayer server OP).
• If parkour, jumping, or movement mods behave abnormally, it is recommended to switch back to simple on the "Speed Limit" page.

If K conflicts with another mod, you can change the "Open KG Weight Settings" key in Minecraft's controls.

Full Commands

(The speed limit modes and their logic, as well as Load Needle customization, are now also available via the UI.)

All management commands require permission level 2 (singleplayer with cheats enabled, or multiplayer server OP).

Main command:

/kgweight

Chinese alias:

/重量

Complete list:

/kgweight help
/kgweight setheld <kg> [affectsSlowdown]
/kgweight slowdownheld <true|false>
/kgweight queryheld
/kgweight removeheld
/kgweight clear
/kgweight status
/kgweight player query <player>
/kgweight player slowdown <player> <true|false>
/kgweight mode <stage|linear|segmented>
/kgweight speedlimit <simple|complex>
/kgweight speedcap <maxFactor> <minFactor> <curve>
/kgweight slowdown <stageKg> <slowdownPerStage>
/kgweight linear <stepKg> <slowdownPerStep>
/kgweight segment list
/kgweight segment set <index> <endKg> <stepKg> <slowdownPerStep>
/kgweight segment remove <index>
/kgweight segment reset
/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight needle usetime <level> <useSeconds>
/kgweight nbtignore list
/kgweight nbtignore add <rule>
/kgweight nbtignore remove <rule>
/kgweight nbtignore reset

Percentage parameters are uniformly entered as decimals:

• 0.01 means 1%
• 0.05 means 5%
• 0.20 means 20%

Item Weight Commands

/kgweight setheld <kg> [affectsSlowdown]

Sets the single item weight for the main hand item.

Examples:

/kgweight setheld 12.5
/kgweight setheld 12.5 false
/kgweight setheld 12.5 true

Description:

• If affectsSlowdown is omitted, it defaults to true, contributing to this mod's slowdown.
• affectsSlowdown=false makes it cosmetic weight only, displayed but not contributing to this mod's slowdown.
• Setting <kg> to 0 is equivalent to removing the current main hand item's weight rule.
• Rules are saved by "item registry name + stable NBT fingerprint".

/kgweight queryheld

Queries the weight rule matching the main hand item, whether it affects slowdown, the stable key, and stable NBT.

/kgweight removeheld

Removes the weight rule matching the current main hand item.

/kgweight slowdownheld <true|false>

Toggles whether the existing weight rule for the main hand item contributes to this mod's slowdown, without changing the weight value.

/kgweight clear

Clears all item weight rules in the current world. Slowdown mode, Load Needle configurations, and NBT ignore rules are not cleared.

Player Weight and Player Slowdown

/kgweight status

View your current total weight, slowdown weight, effective slowdown weight, current world slowdown configuration, and the number of NBT ignore rules.

/kgweight player query <player>

View an online player's weight.

Example:

/kgweight player query Steve

Outputs:

• Total weight
• Slowdown weight
• Effective slowdown weight
• Current movement speed reduction percentage
• Whether this player has this mod's slowdown enabled

/kgweight player slowdown <player> <true|false>

Sets whether a specific online player is affected by this mod's slowdown.

Examples:

/kgweight player slowdown Steve false
/kgweight player slowdown Steve true

Description:

• false: Weight is still counted and displayed, but this mod will not apply slowdown to the player.
• true: Restores this mod's slowdown.
• Settings are saved by player UUID and remain effective after name changes.

Slowdown Modes

The mod has three slowdown modes:

• stage: Stage mode – for every full interval of KG, a slowdown increment is applied.
• linear: Linear mode – continuous linear slowdown based on total weight.
• segmented: Segmented linear mode – different weight ranges use different linear slowdown rules.

Final movement speed is kept at a minimum of 5%, meaning a maximum reduction of 95%.

/kgweight mode <stage|linear|segmented>

Switches the slowdown mode.

/kgweight slowdown <stageKg> <slowdownPerStage>

Configures stage mode.

Example:

/kgweight mode stage
/kgweight slowdown 100 0.05

Meaning: for every full 100 KG, reduce movement speed by 5%.

/kgweight linear <stepKg> <slowdownPerStep>

Configures linear mode.

Example:

/kgweight mode linear
/kgweight linear 10 0.01

Meaning: for every additional 10 KG, reduce movement speed by 1%.

/kgweight segment set <index> <endKg> <stepKg> <slowdownPerStep>

Configures segmented mode.

Example:

/kgweight mode segmented
/kgweight segment set 1 100 10 0.01
/kgweight segment set 2 200 10 0.02
/kgweight segment set 3 350 10 0.04

Meaning:

• 0 to 100 KG: every 10 KG reduces 1%
• 100 to 200 KG: every 10 KG reduces 2%
• 200 to 350 KG: every 10 KG reduces 4%
• Above 350 KG continues with the last segment

Other segment commands:

/kgweight segment list
/kgweight segment remove <index>
/kgweight segment reset

Speed Limit Methods

/kgweight speedlimit <simple|complex>

• simple: Default method, only slows via the player MOVEMENT_SPEED attribute, better compatibility.
• complex: On top of attribute slowdown, additionally caps horizontal speed on both client and server to limit extra horizontal displacement from sprint-jumping.

If parkour, jumping, double-jump, or movement mods behave abnormally, it is recommended to use:

/kgweight speedlimit simple

/kgweight speedcap <maxFactor> <minFactor> <curve>

Sets the horizontal speed cap coefficients for complex mode.

Formula:

horizontal cap = current movement speed attribute × (minFactor + (maxFactor - minFactor) × current slowdown multiplier ^ curve)

Default:

/kgweight speedcap 2.35 1.00 1.00

Load Needles

The mod provides 5 Load Needle items:

• kgweight:load_needle_1
• kgweight:load_needle_2
• kgweight:load_needle_3
• kgweight:load_needle_4
• kgweight:load_needle_5

All recipes are shaped crafting in a crafting table, primarily using minerals and glass bottles; each craft produces 2 needles:

Level 1 Load Needle

Level 2 Load Needle

Level 3 Load Needle

Level 4 Load Needle

Level 5 Load Needle

Default effects:

• Level 1: reduces 25 KG, lasts 60 seconds, use time 1 second
• Level 2: reduces 50 KG, lasts 90 seconds, use time 1.5 seconds
• Level 3: reduces 100 KG, lasts 120 seconds, use time 2 seconds
• Level 4: reduces 200 KG, lasts 180 seconds, use time 2.5 seconds
• Level 5: reduces 400 KG, lasts 240 seconds, use time 3 seconds

Rules:

• Does not use vanilla potion effects.
• At most one needle is active per player at a time.
• Using a Load Needle of any level completely replaces the current needle's effect and remaining time.
• Consumes 1 needle upon use and displays the message "Potion used".
• There is no longer a "wasted Load Needle" mechanic.

Commands:

/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight needle usetime <level> <useSeconds>

TaCZ, Zhuoyu Frontline, Gun Packs, Knife Packs, and NBT Ignore

This mod no longer uses full NBT directly as the weight key. Instead, it uses a "stable NBT fingerprint":

• Retains stable info like enchantments, custom names, TaCZ weapon identity, attachments, skins, etc.
• Ignores dynamic fields like ammo, magazine, reload, cooldown, firing status, timestamps by default.
• Ignores dynamic fire mode fields such as GunFireMode, SelectedFireMode, FireMode, ShootMode by default, preventing weight rule invalidation when switching between full-auto and semi-auto.
• Ignores experience, level, kill count, shots fired, hits, and usage count fields like Exp, Level, KillCount, ShotsFired by default, adapting to guns from mods like Zhuoyu Frontline that write dynamic progression NBT.
• Ignores temporary aiming, scoping, and zooming fields like Aim, Aiming, ADS, Scoped, Zooming by default, preventing weight rules from temporarily failing while aiming down sights.

The current version provides additional handling for TaCZ modified guns:

• When setting weight for a gun, installed attachments are automatically stripped from the gun's base key.
• Actual gun weight = gun base weight + installed attachment weights.
• To set attachment weights: hold the attachment item and run /kgweight setheld <kg>.
• Whether an attachment contributes to slowdown follows its own affectsSlowdown setting.
• If an already configured gun shows 0 KG in a certain state after updating, hold the gun in that state and run /kgweight setheld <kg> [affectsSlowdown] again to write a new stable key.

NBT ignore rule format:

• contains:ammo – ignores fields whose path contains ammo.
• name:Damage – ignores fields whose name exactly equals Damage.
• path:tag.gun.current_round – ignores the exact full path.

Commands:

/kgweight nbtignore list
/kgweight nbtignore add <rule>
/kgweight nbtignore remove <rule>
/kgweight nbtignore reset

remove supports Tab auto-completion for existing rules.

Gun mod troubleshooting flow:

1. Hold a gun and execute /kgweight queryheld.
2. Make the gun undergo changes like reloading, firing, getting a kill, leveling up, switching fire mode, aiming/un-aiming.
3. Execute /kgweight queryheld again.
4. Compare the stable NBT to see if any new dynamic fields appeared.
5. If dynamic fields appear, add an ignore rule, for example:

/kgweight nbtignore add current_round
/kgweight nbtignore add Exp
/kgweight nbtignore add Level
/kgweight nbtignore add Aiming
/kgweight setheld <kg>

TaCZ attachment weight example:

# Hold the gun body and set its base weight
/kgweight setheld 4.5

# Hold an attachment (scope, muzzle, grip, etc.) and set its weight
/kgweight setheld 0.8

When that attachment is installed, the gun's total weight will automatically increase by 0.8 KG.

Modifying Names and Tooltip Text

Language file paths:

src/main/resources/assets/kgweight/lang/zh_cn.json
src/main/resources/assets/kgweight/lang/en_us.json

You can modify:

• Item names
• HUD text
• Key binding names
• Command feedback text
• Load Needle tooltips

If overriding via a resource pack, place files using the same path inside the resource pack.

---

人工智能生成内容披露

本模组包含的所有内容（贴图、模型、代码、音效等）均完全由AI工具生成。展示图片为游戏内实际截图，能真实反映模组效果，但其中的所有视觉元素皆为 AI 产物。如有疑问，欢迎留言交流。**

KG重量

KG重量为 Minecraft Forge 1.20.1 添加了可配置的物品重量系统。你可以给不同物品设置 KG 重量，玩家背包、护甲、副手、拓展背包和部分扩展槽位中的物品都会参与统计，并根据负重降低移动速度。

主要功能

• 物品默认无重量，管理员可在游戏内实时设置。
• 按“物品注册名 + 稳定 NBT 指纹”区分重量，支持区分附魔、命名、稳定配件等差异。
• 针对 TaCZ、卓驭前线、枪包、刀包等动态 NBT 物品做了稳定 NBT 处理，避免弹药数量、换弹状态、开火模式、开镜状态、经验、等级和击杀统计等变化导致重量失效。
• TaCZ 枪械改装后会按“枪械本体重量 + 已安装配件重量”计算，配件重量可单独设置。
• 支持装饰重量：物品显示重量，但不参与本模组减速，适合已经由其他模组处理负重惩罚的物品。
• 背包、护甲、副手、Forge ITEM_HANDLER 扩展槽位、物品内部背包都会计入重量。
• 尝试兼容 Curios 槽位，不把 Curios 作为硬依赖。
• 右上角 HUD 显示总负重、减速负重、移速减缓和负载针效果。
• HUD 可视化调整，默认按 K 打开编辑界面，可拖动位置、调整大小和透明度。
• 支持查看其他在线玩家负重，并可单独开关某个玩家是否受本模组减速影响。
• 添加 3 个进度：第一次设置重量、总重超过 3000 KG、第一次合成负载针。
• 内置简体中文和英文文本。

减速模式

模组提供三种减速策略：

• stage：阶段模式，每满一定 KG 增加一次减速。
• linear：线性模式，每增加一定 KG 降低一定移速。
• segmented：分段线性模式，不同重量范围可设置不同减速强度。

限速方式也可切换：

• simple：默认方式，只调整玩家移动速度属性，兼容性更好。
• complex：额外限制空中水平速度，用于减少疾跑跳跃带来的额外位移。

负载针

模组添加 5 个等级的负载针，可以临时减少有效负重。负载针不使用原版药水效果，同一时间最多只有一针生效；任意等级负载针使用完成后都会直接替换当前针剂效果和剩余时间，并提示“药剂已使用”。

默认效果：

• 1级：减少 25 KG，持续 60 秒
• 2级：减少 50 KG，持续 90 秒
• 3级：减少 100 KG，持续 120 秒
• 4级：减少 200 KG，持续 180 秒
• 5级：减少 400 KG，持续 240 秒

配方主要使用矿物和玻璃瓶：

• 1级：玻璃瓶、铜锭、铁锭、红石粉
• 2级：玻璃瓶、铁锭、金锭、红石粉
• 3级：玻璃瓶、青金石、钻石、红石粉
• 4级：玻璃瓶、绿宝石、钻石、金锭
• 5级：玻璃瓶、下界合金碎片、钻石、绿宝石

负载针效果、持续时间和使用时间都可以用指令调整。

常用指令

所有管理指令需要 2 级权限。

/kgweight help
/kgweight setheld <kg> [affectsSlowdown]
/kgweight queryheld
/kgweight slowdownheld <true|false>
/kgweight mode <stage|linear|segmented>
/kgweight speedlimit <simple|complex>
/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight player query <player>
/kgweight player slowdown <player> <true|false>
/kgweight nbtignore list

中文别名：

/重量

完整说明请查看下文提供的 完整使用说明。

兼容说明

• 精妙背包这类提供物品内部物品栏能力的背包物品会被统计。
• 如果其他模组直接扩展玩家背包格数，只要暴露为 Forge ITEM_HANDLER，本模组会尝试统计。
• Curios 槽位会通过可选反射尝试读取。
• 如果某个模组完全使用私有数据结构且不暴露能力，则需要单独适配。
• TaCZ、卓驭前线及其非官方枪包/刀包通常可通过稳定 NBT 和 NBT 忽略规则适配；沿用 TaCZ 配件 NBT 的枪械会自动累加已安装配件重量。

环境

• Minecraft 1.20.1
• Forge 47.x
• Java 17
• 客户端和服务端都需要安装

---

完整使用说明

适用环境：

• Minecraft 1.20.1
• Forge 47.x
• Java 17

安装方式：

1. 把 kgweight-3.0.0.jar 放进客户端和服务端的 mods 文件夹。
2. 多人游戏中，服务端和所有需要看到 HUD、使用负载针的客户端都要安装。
3. 进入世界后可用 /kgweight help 或 /重量 查看游戏内指令帮助。

基础功能

• 物品默认没有重量，不设置就按 0 KG 计算。
• 重量单位为 KG。
• 堆叠物品按“单件重量 × 数量”计算。
• 背包、护甲、副手都会计入玩家总重量。
• 当前版本会额外读取 Forge ITEM_HANDLER 能力，尽量兼容玩家背包被其他模组直接扩容的情况。
• 当前版本会递归读取物品自身的内部物品栏，适配精妙背包这类“背包里装物品”的拓展背包物品。
• 当前版本会尝试用可选反射读取 Curios 槽位，装了 Curios/饰品背包槽时，不需要把 Curios 作为硬依赖。
• 为避免背包套背包造成死循环，内部物品栏递归深度限制为 4 层。
• 可给物品设置“仅装饰重量”：显示在总重量里，但不参与本模组减速。
• 屏幕 HUD 显示总负重、计入减速重量、移速减缓和负载针效果。

兼容说明：

• 扩展背包和扩展槽位是否能被统计，取决于对应模组是否把槽位暴露为 Forge ITEM_HANDLER 或 Curios 槽位。
• 精妙背包这类正常提供物品内部物品栏能力的背包物品会被统计。
• 如果某个背包模组完全使用私有数据结构且不暴露能力，本模组无法通用读取，需要单独适配。

K 键可视化设置

HUD 调整和部分减速/限速配置可以通过 UI 完成，不必输入指令。

默认按键：

K

UI 分为三个选项卡：

• 显示：鼠标拖动预览文字调整位置，使用滑条调整大小和透明度，最低透明度限制为 1%。
• 减速策略：切换 stage、linear、segmented，并调整对应 KG 阶段、步长和减速百分比。
• 分段减速列表支持滚轮和右侧滚动条，可以在 UI 中查看并编辑全部分段。
• 限速：切换 simple、complex，并调整 complex 的最大限速系数、最小限速系数和曲线。

说明：

• 显示设置是客户端本地设置，每个客户端单独保存到 config/kgweight-hud.json。
• 减速策略和限速设置是服务器/世界规则，点击“应用到服务器”后才会写入。
• 多人游戏中，修改服务器/世界规则需要 2 级权限，也就是单人开启作弊或多人服务器 OP。
• 如果跑酷、跳跃或移动类模组出现异常，建议在“限速”页切回 simple。

如果 K 和其他模组冲突，可以在 Minecraft 控制设置里修改“打开KG重量设置”按键。

完整指令

（现已UI化限速模式和每个模式下的限速逻辑以及负载针的自定义）

所有管理指令需要 2 级权限，也就是单人开启作弊或多人服务器 OP。

主指令：

/kgweight

中文别名：

/重量

完整列表：

/kgweight help
/kgweight setheld <kg> [affectsSlowdown]
/kgweight slowdownheld <true|false>
/kgweight queryheld
/kgweight removeheld
/kgweight clear
/kgweight status
/kgweight player query <player>
/kgweight player slowdown <player> <true|false>
/kgweight mode <stage|linear|segmented>
/kgweight speedlimit <simple|complex>
/kgweight speedcap <maxFactor> <minFactor> <curve>
/kgweight slowdown <stageKg> <slowdownPerStage>
/kgweight linear <stepKg> <slowdownPerStep>
/kgweight segment list
/kgweight segment set <index> <endKg> <stepKg> <slowdownPerStep>
/kgweight segment remove <index>
/kgweight segment reset
/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight needle usetime <level> <useSeconds>
/kgweight nbtignore list
/kgweight nbtignore add <rule>
/kgweight nbtignore remove <rule>
/kgweight nbtignore reset

百分比参数统一用小数填写：

• 0.01 表示 1%
• 0.05 表示 5%
• 0.20 表示 20%

物品重量指令

/kgweight setheld <kg> [affectsSlowdown]

设置主手物品的单件重量。

示例：

/kgweight setheld 12.5
/kgweight setheld 12.5 false
/kgweight setheld 12.5 true

说明：

• 不填 affectsSlowdown 时默认 true，参与本模组减速。
• affectsSlowdown=false 时仅作为装饰重量显示，不参与本模组减速。
• <kg> 填 0 等同于移除当前主手物品重量规则。
• 规则按“物品注册名 + 稳定 NBT 指纹”保存。

/kgweight queryheld

查询主手物品当前匹配到的重量规则、是否参与减速、稳定 key 和稳定 NBT。

/kgweight removeheld

移除主手物品当前匹配的重量规则。

/kgweight slowdownheld <true|false>

切换主手物品已有重量规则是否参与本模组减速，不改变重量数值。

/kgweight clear

清空当前世界所有物品重量规则。减速模式、负载针配置和 NBT 忽略规则不会被清空。

玩家重量和玩家减速

/kgweight status

查看自己当前总重量、计入减速重量、有效减速重量、当前世界减速配置和 NBT 忽略规则数量。

/kgweight player query <player>

查看在线玩家的重量。

示例：

/kgweight player query Steve

输出内容：

• 总重量
• 计入减速重量
• 有效减速重量
• 当前移速减缓比例
• 该玩家是否启用本模组减速

/kgweight player slowdown <player> <true|false>

设置指定在线玩家是否受本模组减速影响。

示例：

/kgweight player slowdown Steve false
/kgweight player slowdown Steve true

说明：

• false：仍然统计和显示重量，但本模组不会对该玩家施加减速。
• true：恢复本模组减速。
• 设置按玩家 UUID 保存，玩家改名后仍然生效。

减速模式

模组有三种减速模式：

• stage：阶段模式，每满一段重量增加一次减速。
• linear：线性模式，按总重量连续线性减速。
• segmented：分段线性模式，不同重量范围使用不同线性减速规则。

最终移速最低保留 5%，也就是最多降低 95%。

/kgweight mode <stage|linear|segmented>

切换减速模式。

/kgweight slowdown <stageKg> <slowdownPerStage>

配置 stage 模式。

示例：

/kgweight mode stage
/kgweight slowdown 100 0.05

含义：每满 100 KG 降低 5% 移速。

/kgweight linear <stepKg> <slowdownPerStep>

配置 linear 模式。

示例：

/kgweight mode linear
/kgweight linear 10 0.01

含义：每增加 10 KG 降低 1% 移速。

/kgweight segment set <index> <endKg> <stepKg> <slowdownPerStep>

配置 segmented 分段线性模式。

示例：

/kgweight mode segmented
/kgweight segment set 1 100 10 0.01
/kgweight segment set 2 200 10 0.02
/kgweight segment set 3 350 10 0.04

含义：

• 0 到 100 KG：每 10 KG 降低 1%
• 100 到 200 KG：每 10 KG 降低 2%
• 200 到 350 KG：每 10 KG 降低 4%
• 350 KG 以上沿用最后一段

其他分段指令：

/kgweight segment list
/kgweight segment remove <index>
/kgweight segment reset

限速方式

/kgweight speedlimit <simple|complex>

• simple：默认方式，只通过玩家 MOVEMENT_SPEED 属性减速，兼容性更好。
• complex：在属性减速基础上额外限制客户端和服务端水平速度上限，用于限制疾跑跳跃带来的额外水平位移。

如果跑酷、跳跃、二段跳或移动类模组出现异常，建议使用：

/kgweight speedlimit simple

/kgweight speedcap <maxFactor> <minFactor> <curve>

设置 complex 模式水平限速系数。

公式：

水平上限 = 当前移速属性 × (minFactor + (maxFactor - minFactor) × 当前减速倍率 ^ curve)

默认：

/kgweight speedcap 2.35 1.00 1.00

负载针

模组提供 5 个负载针物品：

• kgweight:load_needle_1
• kgweight:load_needle_2
• kgweight:load_needle_3
• kgweight:load_needle_4
• kgweight:load_needle_5

合成配方均为工作台有序合成，主要使用矿物和玻璃瓶；每次合成产出 2 根：

1级负载针

2级负载针

3级负载针

4级负载针

5级负载针

默认效果：

• 1 级：减少 25 KG，持续 60 秒，使用时间 1 秒
• 2 级：减少 50 KG，持续 90 秒，使用时间 1.5 秒
• 3 级：减少 100 KG，持续 120 秒，使用时间 2 秒
• 4 级：减少 200 KG，持续 180 秒，使用时间 2.5 秒
• 5 级：减少 400 KG，持续 240 秒，使用时间 3 秒

规则：

• 不走原版药水效果。
• 每名玩家同一时间最多只有一针生效。
• 任意等级负载针使用完成后都会直接替换当前针剂效果和剩余时间。
• 使用完成后消耗 1 根，并提示“药剂已使用”。
• 不再存在“浪费负载针”机制。

指令：

/kgweight needle list
/kgweight needle set <level> <reductionKg> <durationSeconds> [useSeconds]
/kgweight needle usetime <level> <useSeconds>

TaCZ、卓驭前线、枪包、刀包和 NBT 忽略

本模组不再直接用完整 NBT 作为重量 key，而是使用“稳定 NBT 指纹”：

• 保留附魔、自定义名、TaCZ 武器身份、配件、皮肤等稳定信息。
• 默认忽略弹药、弹匣、换弹、冷却、射击状态、时间戳等动态字段。
• 默认忽略 GunFireMode、SelectedFireMode、FireMode、ShootMode 等开火模式动态字段，避免全自动/半自动切换导致重量规则失效。
• 默认忽略 Exp、Level、KillCount、ShotsFired 等经验、等级、击杀、射击、命中、使用次数统计字段，适配卓驭前线这类会写入动态成长 NBT 的枪械。
• 默认忽略 Aim、Aiming、ADS、Scoped、Zooming 等开镜、瞄准、缩放临时字段，避免开镜期间重量规则暂时失效。

当前版本会对 TaCZ 改装枪械做额外处理：

• 给枪械设置重量时，会自动把枪内已安装配件从枪械本体 key 中剥离。
• 枪械实际重量 = 枪械本体重量 + 已安装配件重量。
• 给配件设置重量的方法：手持对应配件物品执行 /kgweight setheld <kg>。
• 配件是否参与减速同样遵守该配件自身的 affectsSlowdown 设置。
• 如果更新后某把已经设置过重量的枪仍在某个状态下显示 0 KG，请手持该状态下的枪重新执行一次 /kgweight setheld <kg> [affectsSlowdown]，写入新的稳定键。

NBT 忽略规则格式：

• contains:ammo：忽略路径中包含 ammo 的字段。
• name:Damage：忽略字段名正好等于 Damage 的字段。
• path:tag.gun.current_round：忽略完整路径等于该值的字段。

指令：

/kgweight nbtignore list
/kgweight nbtignore add <rule>
/kgweight nbtignore remove <rule>
/kgweight nbtignore reset

remove 支持 Tab 自动补全当前已有规则。

枪械模组排查流程：

1. 手持枪械执行 /kgweight queryheld。
2. 让枪械发生换弹、开火、击杀、升级、切换模式、开镜/取消开镜等变化。
3. 再执行 /kgweight queryheld。
4. 对比稳定 NBT 是否多了动态字段。
5. 如有动态字段，添加忽略规则，例如：

/kgweight nbtignore add current_round
/kgweight nbtignore add Exp
/kgweight nbtignore add Level
/kgweight nbtignore add Aiming
/kgweight setheld <kg>

TaCZ 配件重量示例：

# 手持枪械本体，设置枪本体重量
/kgweight setheld 4.5

# 手持瞄具、枪口、握把等配件，设置配件重量
/kgweight setheld 0.8

安装该配件后，枪械总重量会自动增加 0.8 KG。

修改名称和提示文本

语言文件路径：

src/main/resources/assets/kgweight/lang/zh_cn.json
src/main/resources/assets/kgweight/lang/en_us.json

可修改：

• 物品名称
• HUD 文本
• 按键名称
• 指令返回文本
• 负载针提示 如果做资源包覆盖，也按同样路径放入资源包即可。