序列帧动画物品

序列帧动画物品可以让物品贴图在游戏中自动播放帧动画，实现动态视觉效果。序列帧分为两种应用场景：手持与掉落贴图和 UI 界面贴图。

前置条件

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

概述

序列帧动画不是一个独立的 custom_item_type，而是一种外观增强。任何自定义物品都可以添加序列帧动画，让图标在手持、掉落和 UI 界面中动起来。

场景	配置位置	组件/文件
手持 + 掉落物	资源包物品 JSON	netease:frame_anim_in_scene
UI 界面（背包/快捷栏）	资源包 textures/	flipbook_textures_items.json

手持与掉落贴图序列帧

通过资源包物品 JSON 中的 netease:frame_anim_in_scene 组件，让物品在手持和掉落状态下播放序列帧。

字段	类型	说明
texture_path	string	序列帧贴图路径（不含扩展名），指向一张竖向平铺的图片
ticks_per_frame	int	每帧持续的 tick 数（20 tick = 1 秒）

贴图制作规范

序列帧贴图是一张由上往下竖向平铺的图片：

• 图片宽度 = 单帧宽度
• 图片高度 = 单帧宽度 × 帧数
• 例如：16×16 的 4 帧动画 → 贴图尺寸为 16×64

┌────┐ ← 帧 1
│    │
├────┤ ← 帧 2
│    │
├────┤ ← 帧 3
│    │
├────┤ ← 帧 4
│    │
└────┘

UI 界面贴图序列帧

通过 resource_pack/textures/flipbook_textures_items.json 配置物品在 UI 界面（背包、快捷栏等）中的序列帧动画。

[
  {
    "flipbook_texture": "textures/items/magic_orb_ui_anim",
    "atlas_tile": "magic_orb",
    "ticks_per_frame": 4,
    "blend_frames": true
  }
]

字段	类型	说明
flipbook_texture	string	序列帧贴图路径（竖向平铺图片）
atlas_tile	string	对应 item_texture.json 中的贴图资源名
ticks_per_frame	int	每帧持续 tick 数
blend_frames	bool	是否在帧之间进行混合过渡

完整案例：闪烁魔法球

一个在手持和 UI 界面中都有动态贴图的物品。

行为包

behavior_pack/netease_items_beh/magic_orb.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:magic_orb",
      "category": "items"
    },
    "components": {
      "minecraft:max_stack_size": 64
    }
  }
}

资源包物品 JSON

resource_pack/netease_items_res/magic_orb.json：

{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:magic_orb",
      "texture": "magic_orb"
    },
    "components": {
      "netease:frame_anim_in_scene": {
        "texture_path": "textures/items/magic_orb_anim",
        "ticks_per_frame": 4
      }
    }
  }
}

item_texture.json

{
  "resource_pack_name": "mymod",
  "texture_data": {
    "magic_orb": {
      "textures": "textures/items/magic_orb"
    }
  }
}

flipbook_textures_items.json

[
  {
    "flipbook_texture": "textures/items/magic_orb_anim",
    "atlas_tile": "magic_orb",
    "ticks_per_frame": 4,
    "blend_frames": true
  }
]

本地化

item.mymod:magic_orb.name=魔法球

贴图文件

• textures/items/magic_orb.png — 静态图标（16×16）
• textures/items/magic_orb_anim.png — 序列帧贴图（16×64，4 帧）

蓄力物品序列帧

蓄力物品（如弓）使用另一套序列帧组件 netease:frame_animation，配合 item_texture.json 中的贴图数组实现蓄力进度动画。详见 自定义蓄力物品 和 自定义远程武器。

常见问题

序列帧贴图不播放

确认贴图是竖向平铺的单张图片（高度 = 宽度 × 帧数），且 ticks_per_frame 值大于 0。

UI 和手持动画不同步

这是正常行为。手持序列帧和 UI 序列帧是独立的两套系统，分别由 netease:frame_anim_in_scene 和 flipbook_textures_items.json 控制。

下一步

• 自定义基础物品 — 回顾基础物品注册流程
• 自定义蓄力物品 — 蓄力进度序列帧
• 物品组件速查 — 所有物品组件一览