📌 CNPC MMDSkin Extension

[简体中文] | [English]

---

简体中文

💡 关于本 Mod / About

本 Mod 是 CustomNPCs (CNPC) 的高性能扩展，旨在将 MMDSkin 的模型与动作系统完美引入到自定义 NPC 实体中。

它允许每一个 NPC 独立配置、导入外部的 MMD 模型与动画。除了可以通过专属的 GUI 面板进行常驻动画配置外，更提供了强大的脚本方法（Script API），让你可以通过代码动态控制 NPC 的模型更换与动画播放（如执行特定的舞蹈或动作演出）。

⚠️ 局限性说明：

• 暂不支持“舞台模式（Stage Mode）”。
• 非脚本模式下，NPC 面板中可选的模型与动作数量，完全取决于玩家自己当前动作面板中已有的数量（通过脚本方法调用则不受此数量限制）。

---

💻 脚本方法 (Script API)

开发人员和地图制作者可以使用以下全新的脚本方法来动态控制 NPC 的 MMD 状态：

• setMmdSkin(modelName, player) 为 NPC 绑定指定的 MMD 模型，并实时网络同步给指定的玩家。
• setMmdSkinLocal(modelName) 仅在本地为 NPC 绑定 MMD 模型（不进行网络同步）。
• playMmdAnimation(animName) 让 NPC 立即播放指定名称的 MMD 动画。
• clearMmdSkin() 解除当前 NPC 的 MMD 模型绑定，将其恢复为默认的 Minecraft 渲染模式。
• hasMmdSkin() 返回布尔值，检查当前 NPC 是否已经绑定了 MMD 模型。
• getMmdSkinName() 获取当前 NPC 所绑定的 MMD 模型名称。

---

🎮 可视化功能与特性 (Features)

• 独立面板配置： 默认情况下，玩家只需对着 NPC 按下 N 键即可打开专用面板，为该 NPC 单独挑选一个 MMDSKIN 模型。
• 千人千面： 支持为不同的 NPC 穿戴和配置完全不同的 MMD 模型。
• 常驻动作选择： 允许在面板中为 NPC 选择一段特定的动画并让其一直保持播放。
• 运动动态触发： 优化了基础运动逻辑，NPC 默认走路时会直接触发并播放 MMDSkin 的跑步动画。
• 支持外部导入： 与玩家系统一致，完全支持从外部导入你自定义的 MMD 模型与动作文件。

---

English

💡 About The Mod

This mod is a high-performance extension for CustomNPCs (CNPC) that brings the MMDSkin model and motion system to NPC entities.

It allows each individual NPC to load, configure, and import external MMD models and animations independently. Beyond standard GUI configurations, it features a robust Script API that empowers developers to dynamically swap models and trigger custom motion performances (like custom dances or cutscene actions) via code.

⚠️ Technical Limitations:

• Stage Mode is currently NOT supported for NPCs.
• In Non-Script Mode, the number of available models and animations in the NPC panel is directly linked to the amount available in the player's own motion panel (Scripted triggers are completely exempt from this limitation).

---

💻 Script API

Developers and map makers can utilize the following new methods to control NPC MMD states programmatically:

• setMmdSkin(modelName, player) Binds a specified MMD model to the NPC and syncs it to the targeted player over the network.
• setMmdSkinLocal(modelName) Binds the MMD model to the NPC locally only (no network synchronization).
• playMmdAnimation(animName) Triggers the NPC to play a specific MMD animation by its name.
• clearMmdSkin() Unbinds the MMD skin, restoring the NPC to its default Minecraft rendering.
• hasMmdSkin() Returns a boolean checking whether the NPC currently has an active MMD model bound.
• getMmdSkinName() Retrieves the name of the MMD model currently bound to the NPC.

---

🎮 Visual Features

• Dedicated GUI Configuration: By default, players can aim at an NPC and press the N key to open a configuration panel to assign an MMDSKIN model.
• Independent Models: Supports configuring entirely different MMD models for different NPCs simultaneously.
• Persistent Animations: Allows you to select a specific animation from the GUI that the NPC will keep playing constantly.
• Dynamic Movement Mapping: The movement logic is remapped so that when an NPC walks by default, it automatically triggers the running animation.
• External Imports: Fully supports external loading of custom MMD models and motion assets, just like the player counterpart system.