自定义蓄力物品

蓄力物品（Chargeable Item）允许玩家通过长按右键进行蓄力操作，蓄力完成后触发自定义事件。与远程武器不同，蓄力物品不会自动发射抛射物，而是通过事件回调让开发者自行决定蓄力完成后的逻辑。

前置条件

请先阅读 自定义基础物品 了解通用注册流程（步骤 1-6）。format_version 使用 1.10。

概述

蓄力物品适用于需要"蓄力 → 释放"交互模式的物品，比如法杖、技能道具等。核心机制是通过 netease:chargeable 组件定义蓄力参数，配合 minecraft:use_duration 控制最大持续使用时间。

netease:chargeable 组件

字段	类型	默认值	说明
charge_on_draw	bool	true	右键按下时是否立即开始蓄力
charge_complete_time	float	1.0	蓄力完成所需时间（秒）
charge_complete_event	string	""	蓄力完成时触发的事件名

必要搭配

蓄力物品必须配合 minecraft:use_duration 组件使用，该组件的值决定物品最大持续使用时间（单位 tick，20 tick = 1 秒）。建议设为 72000（1 小时），确保不会因超时而中断蓄力。

蓄力流程

右键按下 → 开始蓄力 → 蓄力到达 100% → 触发 charge_complete_event
                    → 右键中途松开    → 触发 ItemReleaseUsingServerEvent

与远程武器的区别

特性	蓄力物品	远程武器
custom_item_type	不要求（或其他类型）	ranged_weapon
自动发射抛射物	否	是
蓄力完成行为	触发自定义事件	发射抛射物
第三人称动画	无特殊动画	弓瞄准动画

相关事件

事件	说明
ItemStartUsingServerEvent	蓄力开始（右键按下）
ItemReleaseUsingServerEvent	蓄力释放（右键抬起），参数中包含 useDuration（已蓄力 tick 数）
ItemStopUsingServerEvent	使用中断

完整案例：蓄力法球

行为包

behavior_pack/netease_items_beh/charge_orb.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:charge_orb",
      "category": "equipment"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:use_animation": "bow",
      "minecraft:use_duration": 72000,
      "netease:chargeable": {
        "charge_on_draw": true,
        "charge_complete_time": 2.0,
        "charge_complete_event": "mymod:charge_complete"
      },
      "netease:frame_animation": {
        "frame_count": 4,
        "texture_name": "charge_orb_anim",
        "animate_in_toolbar": false
      }
    }
  }
}

资源包

resource_pack/netease_items_res/charge_orb.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:charge_orb",
      "texture": "charge_orb"
    }
  }
}

本地化

item.mymod:charge_orb.name=蓄力法球

服务端脚本

import server.extraServerApi as serverApi
ServerSystem = serverApi.GetServerSystemCls()

class ChargeOrbServer(ServerSystem):
    def __init__(self, namespace, systemName):
        super(ChargeOrbServer, self).__init__(namespace, systemName)
        self.ListenForEvent(
            serverApi.GetEngineNamespace(),
            serverApi.GetEngineSystemName(),
            'ItemReleaseUsingServerEvent',
            self, self.OnRelease
        )

    def OnRelease(self, args):
        playerId = args['playerId']
        itemDict = args.get('itemDict', {})
        useDuration = args.get('useDuration', 0)
        if itemDict.get('itemName') == 'mymod:charge_orb':
            # useDuration 为已蓄力的 tick 数（2 秒 = 40 tick）
            chargePercent = min(useDuration / 40.0, 1.0)
            # 根据蓄力百分比决定法球威力
            self.CastSpell(playerId, chargePercent)

    def CastSpell(self, playerId, power):
        # 蓄力越满，爆炸威力越大
        radius = 2.0 + power * 4.0
        msgComp = serverApi.GetEngineCompFactory().CreateMsg(self.levelId)
        msgComp.NotifyOneMessage(
            playerId,
            "法球释放！威力: {:.0%}".format(power),
            "§b"
        )

常见问题

蓄力没有反应

检查是否配置了 minecraft:use_duration 组件。蓄力物品必须有使用持续时间，否则无法进入蓄力状态。

蓄力动画不播放

需要配合 netease:frame_animation 或 minecraft:use_animation 组件。前者提供贴图序列帧效果，后者使用原版动画（bow/eat/drink 等）。

下一步

• 自定义远程武器 — 如需自动发射抛射物，使用远程武器
• 序列帧动画物品 — 为物品添加动态贴图效果
• 物品组件速查 — 所有物品组件一览