My Discord Group：https://discord.gg/rSaFbj89Te
CNPC OBJ Models
English
CNPC OBJ Models adds static OBJ model support to CustomNPCs for Minecraft
It supports OBJ + MTL + PNG models for NPCs, NPC armor, scripted blocks, scripted items, and arbitrary items through commands.
No JSON model configuration is required.
Supported Features
- Static OBJ model loading and rendering
- OBJ models with optional MTL files
- PNG textures
- Resource pack model support
- OBJ models for NPCs
- OBJ armor for NPCs
- OBJ models for scripted blocks
- OBJ models for scripted items
- OBJ models for arbitrary items through commands
- XYZ model scaling
- XYZ model rotation
- Model position offsets
- Inventory GUI position and scale adjustment
- Independent armor position offsets
- Optional vanilla armor rendering
- Back-face culling control
- Custom NPC OBJ hitbox settings
- Configuration inspection through /cnpcobj info
- Tab completion for OBJ, MTL and PNG resource paths
Resource Paths
All model and texture paths use Minecraft ResourceLocation format:
namespace:path
Examples:
cnpcobj:models/dream_sphere.obj cnpcobj:models/dream_sphere.mtl cnpcobj:models/texture.png
Custom resources can be placed in a resource pack using:
assets/your_namespace/models/example.obj assets/your_namespace/models/example.mtl assets/your_namespace/models/texture.png
Resource paths must follow Minecraft ResourceLocation naming rules.
Do not use Chinese characters in file names or paths.
Texture Priority
Texture selection uses the following priority:
- Explicitly specified PNG texture
- The first map_Kd texture specified by the MTL file
- White fallback texture
MTL is optional.
OBJ + PNG works without an MTL file.
OBJ + MTL can load its texture through map_Kd.
If both MTL and PNG are specified, the explicitly specified PNG takes priority.
If no texture is available, the model is still rendered using a white fallback texture.
NPC Script API
NPC OBJ configuration is accessed through event.npc.
The NPC must first have "OBJ Models" selected in its model settings.
Available methods:
npc.setObjModel(String path) Sets the OBJ model path.
npc.getObjModel() Returns the current OBJ model path.
npc.setObjMtl(String path) Sets the MTL path. The MTL file is optional. Passing an empty string clears the MTL path.
npc.getObjMtl() Returns the current MTL path.
npc.setObjTexture(String path) Sets the PNG texture path.
npc.getObjTexture() Returns the current PNG texture path.
npc.setObjScale(float x, float y, float z) Sets the model scale on the X, Y and Z axes.
npc.setObjRotation(float x, float y, float z) Sets the model rotation on the X, Y and Z axes. The values use degrees. Rotation is performed around the OBJ model's own center and does not change the model position.
npc.setObjHitbox(float width, float height) Sets the NPC collision box width and height. A value of 0 means that the corresponding value is not overridden and the original CustomNPCs collision box calculation is used.
npc.setObjCullBackface(boolean cull) Enables or disables back-face culling. Default: true.
npc.clearObjModel() Clears all OBJ configuration from the NPC.
Scripted Block Script API
OBJ models can be assigned to CustomNPCs scripted blocks through event.block.
Available methods:
block.setObjModel(String path) Sets the OBJ model path.
block.getObjModel() Returns the current OBJ model path.
block.setObjMtl(String path) Sets the MTL path. The MTL file is optional.
block.getObjMtl() Returns the current MTL path.
block.setObjTexture(String path) Sets the PNG texture path.
block.getObjTexture() Returns the current PNG texture path.
block.setObjScale(float x, float y, float z) Sets the model scale on the X, Y and Z axes.
block.getObjScaleX() Returns the X scale.
block.getObjScaleY() Returns the Y scale.
block.getObjScaleZ() Returns the Z scale.
block.setObjRotation(float x, float y, float z) Sets the model rotation on the X, Y and Z axes in degrees.
block.getObjRotationX() Returns the X rotation.
block.getObjRotationY() Returns the Y rotation.
block.getObjRotationZ() Returns the Z rotation.
block.setObjCullBackface(boolean cull) Enables or disables back-face culling. Default: true.
block.clearObjModel() Clears all OBJ configuration from the scripted block.
Scripted Block Synchronization
Scripted block OBJ changes use CustomNPCs' needsClientUpdate synchronization mechanism.
TileScripted checks for changes every 10 ticks (0.5 seconds).
Because of this, changing the model every script tick does not result in a smooth per-tick visual update. Visual changes are synchronized according to CustomNPCs' own update interval.
This is a CustomNPCs synchronization behavior, not an OBJ renderer bug.
The OBJ model replaces the scripted block's normal appearance.
When holding the CustomNPCs wand or scripter, the original CustomNPCs scripted block icon is temporarily displayed. This behavior is intentional and makes scripted blocks easier to locate.
The six scripted block text planes, text1 through text6, continue to work normally.
Scripted Item Script API
OBJ models can be assigned to CustomNPCs scripted items (customnpcs:scripted_item).
After obtaining an IItemScripted, the following methods are available.
item.setObjModel(String path) Sets the OBJ model path.
item.getObjModel() Returns the current OBJ model path.
item.setObjMtl(String path) Sets the MTL path. The MTL file is optional.
item.getObjMtl() Returns the current MTL path.
item.setObjTexture(String path) Sets the PNG texture path.
item.getObjTexture() Returns the current PNG texture path.
item.setObjScale(float x, float y, float z) Sets the model scale on the X, Y and Z axes.
item.setObjRotation(float x, float y, float z) Sets the model rotation on the X, Y and Z axes in degrees. Rotation is performed around the OBJ model's own center.
item.setObjGuiOffset(float x, float y) Sets the X and Y position offset of the OBJ model when displayed in an inventory GUI.
item.setObjGuiScale(float x, float y) Sets the X and Y display scale of the OBJ model when displayed in an inventory GUI.
item.getObjGuiOffsetX() Returns the inventory GUI X offset.
item.getObjGuiOffsetY() Returns the inventory GUI Y offset.
item.getObjGuiScaleX() Returns the inventory GUI X scale.
item.getObjGuiScaleY() Returns the inventory GUI Y scale.
item.setObjOffset(float x, float y, float z) Sets the XYZ model-space position offset for non-inventory rendering.
This offset is used for first-person held items, third-person held items, dropped items, item frames and head displays.
All three axes allow negative values.
1.0 represents one Minecraft block in model space.
This is the offset that should normally be used to correct the position of a model in the player's hand.
item.getObjOffsetX() Returns the X model offset.
item.getObjOffsetY() Returns the Y model offset.
item.getObjOffsetZ() Returns the Z model offset.
item.setObjArmorOffset(float x, float y, float z) Sets the XYZ offset used when the OBJ item is rendered as armor.
Armor offset is independent from the normal item offset.
Vanilla armor is displayed by default.
item.setObjArmorOffset(float x, float y, float z, boolean showVanillaArmor) Sets the armor XYZ offset and controls whether the original vanilla armor is displayed.
true = display vanilla armor false = display only the OBJ model
item.getObjArmorOffsetX() Returns the armor X offset.
item.getObjArmorOffsetY() Returns the armor Y offset.
item.getObjArmorOffsetZ() Returns the armor Z offset.
item.setObjShowVanillaArmor(boolean show) Controls whether vanilla armor is rendered together with the OBJ armor model.
Default: true.
item.getObjShowVanillaArmor() Returns the current vanilla armor display state.
item.setObjCullBackface(boolean cull) Enables or disables back-face culling. Default: true.
item.clearObjModel() Clears all OBJ configuration from the scripted item.
GUI Offset and Model Offset
setObjGuiOffset and setObjGuiScale only affect the model when it is displayed inside an inventory GUI.
setObjOffset affects all non-inventory item rendering situations, including:
- First-person held items
- Third-person held items
- Dropped items
- Item frames
- Head displays
The normal model offset and the armor offset are independent.
Use setObjOffset to correct the position of a model in the player's hand.
Use setObjArmorOffset to correct the position of the model when worn as armor.
Item Synchronization
Scripted item OBJ configuration uses CustomNPCs' updateClient mechanism.
ScriptPlayerEventHandler checks inventory items every 10 ticks (0.5 seconds).
Therefore, changes to a scripted item's OBJ configuration may take up to approximately 0.5 seconds to become visible on the client.
Command API
The command is:
/cnpcobj <subcommand> [arguments]
Permission level: 2.
All subcommands only affect the item currently held in the command executor's main hand.
There is no slot argument.
The command never modifies another inventory slot.
Supported Items
The command system works with arbitrary ItemStacks.
This includes:
- Vanilla armor
- Modded armor
- Weapons
- Tools
- Blocks
- CustomNPCs scripted items
- Other modded items
OBJ configuration is stored in the ItemStack's CnpcObjModel NBT data and does not require item-specific mod integration.
Available Commands
/cnpcobj model <path> Sets the OBJ model.
/cnpcobj mtl <path> Sets the MTL file.
/cnpcobj texture <path> Sets the PNG texture.
/cnpcobj scale <x> <y> <z> Sets XYZ model scale.
/cnpcobj rotation <x> <y> <z> Sets XYZ model rotation in degrees.
/cnpcobj guipos <x> <y> Sets the OBJ model's inventory GUI X and Y position.
/cnpcobj guisize <x> <y> Sets the OBJ model's inventory GUI X and Y size.
/cnpcobj offset <x> <y> <z> Sets the XYZ model-space position offset for non-inventory rendering.
Negative values are supported.
This can be used to correct the model position in the player's hand, on the ground, or in an item frame.
/cnpcobj armoroffset <x> <y> <z> [true|false] Sets the XYZ armor-wearing offset.
The optional final boolean controls whether vanilla armor is displayed.
true = display vanilla armor false = display only the OBJ model
If omitted, the value defaults to true.
/cnpcobj vanillaarmor <true|false> Controls whether vanilla armor is displayed together with the OBJ armor model.
Default: true.
/cnpcobj cull <true|false> Enables or disables back-face culling.
Default: true.
/cnpcobj clear Clears all OBJ configuration from the main-hand item.
/cnpcobj info Displays the current OBJ configuration of the main-hand item.
Command Tab Completion
The model, mtl and texture path arguments support Tab completion.
The completion system scans loaded resource packs for files inside models/ and filters them according to the required file extension.
For example, entering part of a model name and pressing Tab can be used to filter the available model paths.
In single-player and LAN-hosted worlds, resource scanning works normally because the client and server run in the same JVM.
On a dedicated server, the server does not have access to the client's resource-pack resources in the same way.
Therefore, Tab completion may be empty on dedicated servers.
The complete ResourceLocation can always be entered manually.
NPC Armor Support
Items configured with OBJ models can also be worn as armor by CustomNPCs NPCs.
When an NPC uses the OBJ Models model type, both the NPC's OBJ model and compatible OBJ armor can be rendered.
Armor uses the independent armor offset configured through armoroffset / setObjArmorOffset.
The normal item hand offset is not used for armor rendering.
Armor models follow the corresponding NPC body parts:
- Head
- Chest / body
- Legs
- Feet
NPC GUI
To configure an NPC through the GUI:
- Right-click the NPC and open the Model settings.
- Find OBJ Models in the model list.
- Select OBJ Models.
- An "OBJ Model: [Edit]" button will appear.
- Open the editor to configure the model.
The OBJ editor provides the following settings:
OBJ File Required OBJ model path.
MTL File Optional MTL file path.
PNG Texture Optional PNG texture path.
Scale X / Y / Z Independent XYZ model scaling.
Rotation X / Y / Z Independent XYZ rotation in degrees.
Hitbox Width / Height Custom NPC collision box size. A value of 0 keeps the original CustomNPCs collision box behavior.
Back-face Culling Controls whether back-facing triangles are discarded.
Clear Model Clears all OBJ model configuration.
The resource selection buttons list loaded resources found inside models/.
Double-click a resource to select it.
If no resources are found, the path can always be entered manually.
Model Scale
OBJ units do not necessarily match Minecraft block units.
One Minecraft block corresponds to 1.0 model-space unit.
Depending on the modeling software and export settings, a model may require a significantly smaller scale.
For example, models exported from Blockbench may sometimes require a scale around 0.0625 (1/16).
Back-face Culling
Back-face culling is enabled by default.
For closed models such as spheres, keeping culling enabled is normally recommended.
For single-sided planes such as flags, banners or billboards, disable back-face culling if the model must remain visible from both sides.
Known Limitations
CNPC OBJ Models is designed for static OBJ models.
It does not provide skeletal animation or animated OBJ models.
For animated models, use a GeckoLib-based solution such as CNPC-Gecko-Addon instead.
Compatibility with Gecko Addon
CNPC OBJ Models and Gecko-based NPC model addons can be installed together.
They do not need to replace each other.
A single NPC model slot can only use one model type at a time.
When the NPC uses OBJ Models, it uses the OBJ renderer.
When the NPC uses a Gecko model, it uses the Gecko renderer.
Therefore, the two model types are naturally exclusive for an individual NPC rather than being a direct conflict.
Troubleshooting
Model appears fragmented, has holes, or looks corrupted:
Make sure you are using a version containing the OBJ face handling fix.
OBJ files containing complex polygons, especially concave polygons with more than four vertices, may not triangulate correctly.
Triangulate complex faces in your modeling software before exporting the OBJ.
The inside of the model can be seen from the back:
Enable back-face culling.
Use:
setObjCullBackface(true)
or:
/cnpcobj cull true
A single-sided flag or billboard is invisible from the back:
Disable back-face culling.
Use:
setObjCullBackface(false)
or:
/cnpcobj cull false
The model is completely white:
Check the MTL map_Kd path.
Check the explicitly configured PNG path.
Use:
/cnpcobj info
to inspect the current OBJ configuration.
The model is too large or too small:
Adjust the model scale.
OBJ units vary depending on the modeling software and export settings.
A Blockbench-exported model may require a scale around 0.0625 (1/16).
Scripted block or scripted item changes are delayed:
CustomNPCs synchronizes these changes approximately every 10 ticks (0.5 seconds).
Wait for the next client update.
The NPC has OBJ Models selected but nothing is rendered:
Make sure an OBJ model path has been configured.
An NPC with OBJ Models selected but without an OBJ file intentionally displays no OBJ model.
This makes it possible to distinguish an NPC that has selected the model type but has not yet been configured.
============================================================
中文
CNPC OBJ Models 为 Minecraft 的 CustomNPCs 提供静态 OBJ 模型支持。
本 Mod 支持使用 OBJ + MTL + PNG 为 NPC、NPC 盔甲、脚本方块、脚本物品以及任意物品添加自定义模型。
无需编写任何 JSON 模型配置。 支持内容
- 静态 OBJ 模型加载与渲染
- OBJ、MTL、PNG 支持
- MTL 可选
- 支持资源包中的自定义模型
- NPC OBJ 模型
- NPC OBJ 盔甲
- 脚本方块 OBJ 模型
- 脚本物品 OBJ 模型
- 通过指令为任意物品添加 OBJ 模型
- XYZ 独立缩放
- XYZ 独立旋转
- 模型位置偏移
- 物品栏 GUI 中的模型位置与大小调整
- 独立的盔甲穿戴位置偏移
- 可控制是否显示原版盔甲
- 背面剔除控制
- NPC OBJ 模型碰撞箱设置
- 通过 /cnpcobj info 查看当前配置
- OBJ、MTL、PNG 路径支持 Tab 补全
资源路径
所有模型和贴图路径均使用 Minecraft ResourceLocation 格式：
namespace:path
例如：
cnpcobj:models/dream_sphere.obj cnpcobj:models/dream_sphere.mtl cnpcobj:models/texture.png
自定义资源包可以按照以下结构放置：
assets/your_namespace/models/example.obj assets/your_namespace/models/example.mtl assets/your_namespace/models/texture.png
资源路径必须符合 Minecraft ResourceLocation 的命名规则。
文件名和路径不能使用中文等不受支持的字符。
贴图优先级
模型贴图按照以下优先级选择：
- 显式指定的 PNG 贴图
- MTL 文件中的第一个 map_Kd 贴图
- 白色兜底贴图
MTL 文件不是必须的。
OBJ + PNG 可以在没有 MTL 的情况下正常工作。
OBJ + MTL 可以从 MTL 中的 map_Kd 自动读取贴图。
如果同时指定 MTL 和 PNG，则显式指定的 PNG 优先。
如果没有任何贴图，模型仍然会被渲染，只是使用白色兜底贴图。
NPC 脚本 API
NPC OBJ 模型通过 event.npc 进行配置。
使用 API 前，NPC 必须先在模型设置中选择「OBJ Models」。
可用方法：
npc.setObjModel(String path) 设置 OBJ 模型路径。
npc.getObjModel() 获取当前 OBJ 模型路径。
npc.setObjMtl(String path) 设置 MTL 路径。 MTL 文件是可选的。 传入空字符串可以清除 MTL 路径。
npc.getObjMtl() 获取当前 MTL 路径。
npc.setObjTexture(String path) 设置 PNG 贴图路径。
npc.getObjTexture() 获取当前 PNG 贴图路径。
npc.setObjScale(float x, float y, float z) 设置模型 XYZ 缩放。
npc.setObjRotation(float x, float y, float z) 设置模型 XYZ 旋转。 单位为角度。 旋转围绕 OBJ 模型自身中心进行，不会因此改变模型位置。
npc.setObjHitbox(float width, float height) 设置 NPC 碰撞箱宽度和高度。 传入 0 表示不覆盖对应配置，继续使用 CustomNPCs 原本的碰撞箱计算方式。
npc.setObjCullBackface(boolean cull) 设置是否启用背面剔除。 默认值：true。
npc.clearObjModel() 清除 NPC 的全部 OBJ 配置。
脚本方块脚本 API
可以通过 event.block 为 CustomNPCs 脚本方块设置 OBJ 模型。
可用方法：
block.setObjModel(String path) 设置 OBJ 模型路径。
block.getObjModel() 获取当前 OBJ 模型路径。
block.setObjMtl(String path) 设置 MTL 路径。 MTL 文件是可选的。
block.getObjMtl() 获取当前 MTL 路径。
block.setObjTexture(String path) 设置 PNG 贴图路径。
block.getObjTexture() 获取当前 PNG 贴图路径。
block.setObjScale(float x, float y, float z) 设置模型 XYZ 缩放。
block.getObjScaleX() 获取 X 轴缩放。
block.getObjScaleY() 获取 Y 轴缩放。
block.getObjScaleZ() 获取 Z 轴缩放。
block.setObjRotation(float x, float y, float z) 设置模型 XYZ 旋转，单位为角度。
block.getObjRotationX() 获取 X 轴旋转。
block.getObjRotationY() 获取 Y 轴旋转。
block.getObjRotationZ() 获取 Z 轴旋转。
block.setObjCullBackface(boolean cull) 设置是否启用背面剔除。 默认值：true。
block.clearObjModel() 清除脚本方块的全部 OBJ 配置。
脚本方块同步机制
脚本方块 OBJ 配置使用 CustomNPCs 自身的 needsClientUpdate 同步机制。
TileScripted 每 10 tick（0.5 秒）检查一次变化。
因此，如果在脚本中每 tick 修改模型，客户端并不会每 tick 平滑显示变化，而是按照 CustomNPCs 自身的同步间隔更新。
这是 CustomNPCs 的同步机制，并不是 OBJ 渲染器的问题。
OBJ 模型会替代脚本方块原本的外观。
手持 CustomNPCs 的 wand 或 scripter 时，脚本方块仍会临时显示 CustomNPCs 原本的脚本方块图标。
这是刻意保留的行为，可以方便定位和编辑脚本方块。
脚本方块原本的六个文本平面 text1 到 text6 仍然正常工作。
脚本物品脚本 API
可以为 CustomNPCs 的脚本物品（customnpcs:scripted_item）设置 OBJ 模型。
获取 IItemScripted 后，可以使用以下方法。
item.setObjModel(String path) 设置 OBJ 模型路径。
item.getObjModel() 获取当前 OBJ 模型路径。
item.setObjMtl(String path) 设置 MTL 路径。 MTL 文件是可选的。
item.getObjMtl() 获取当前 MTL 路径。
item.setObjTexture(String path) 设置 PNG 贴图路径。
item.getObjTexture() 获取当前 PNG 贴图路径。
item.setObjScale(float x, float y, float z) 设置模型 XYZ 缩放。
item.setObjRotation(float x, float y, float z) 设置模型 XYZ 旋转，单位为角度。 旋转围绕 OBJ 模型自身中心进行。
item.setObjGuiOffset(float x, float y) 设置模型在物品栏 GUI 中的 XY 位置偏移。
item.setObjGuiScale(float x, float y) 设置模型在物品栏 GUI 中的 XY 显示大小。
item.getObjGuiOffsetX() 获取物品栏 GUI X 轴偏移。
item.getObjGuiOffsetY() 获取物品栏 GUI Y 轴偏移。
item.getObjGuiScaleX() 获取物品栏 GUI X 轴大小。
item.getObjGuiScaleY() 获取物品栏 GUI Y 轴大小。
item.setObjOffset(float x, float y, float z) 设置非物品栏场景下使用的 XYZ 模型空间位置偏移。
该偏移会影响：
- 第一人称手持
- 第三人称手持
- 地面掉落
- 展示框
- 头顶显示
三个轴均允许使用负数。
1.0 代表模型空间中的一个 Minecraft 方块单位。
通常应该使用该方法调整模型在玩家手中的位置。
item.getObjOffsetX() 获取 X 轴模型偏移。
item.getObjOffsetY() 获取 Y 轴模型偏移。
item.getObjOffsetZ() 获取 Z 轴模型偏移。
item.setObjArmorOffset(float x, float y, float z) 设置 OBJ 作为盔甲渲染时使用的 XYZ 偏移。
盔甲偏移与普通物品偏移相互独立。
默认情况下会显示原版盔甲。
item.setObjArmorOffset(float x, float y, float z, boolean showVanillaArmor) 设置盔甲 XYZ 偏移，同时控制是否显示原版盔甲。
true = 显示原版盔甲 false = 只显示 OBJ 模型
item.getObjArmorOffsetX() 获取盔甲 X 轴偏移。
item.getObjArmorOffsetY() 获取盔甲 Y 轴偏移。
item.getObjArmorOffsetZ() 获取盔甲 Z 轴偏移。
item.setObjShowVanillaArmor(boolean show) 控制 OBJ 盔甲模型是否与原版盔甲一起显示。
默认值：true。
item.getObjShowVanillaArmor() 获取当前原版盔甲显示状态。
item.setObjCullBackface(boolean cull) 设置是否启用背面剔除。 默认值：true。
item.clearObjModel() 清除脚本物品的全部 OBJ 配置。
GuiOffset、GuiScale 与 Offset 的区别
setObjGuiOffset 和 setObjGuiScale 只影响模型在物品栏 GUI 中的显示。
setObjOffset 影响所有非物品栏场景，包括：
- 第一人称手持
- 第三人称手持
- 地面掉落
- 展示框
- 头顶显示
普通模型偏移和盔甲偏移相互独立。
调整模型在玩家手中的位置时，应使用 setObjOffset。
调整模型穿戴为盔甲时的位置，应使用 setObjArmorOffset。
脚本物品同步机制
脚本物品 OBJ 配置使用 CustomNPCs 的 updateClient 机制。
ScriptPlayerEventHandler 每 10 tick（0.5 秒）检查一次背包物品。
因此，修改脚本物品 OBJ 配置后可能需要最多约 0.5 秒才能在客户端看到变化。
指令 API
指令格式：
/cnpcobj <子指令> [参数]
权限等级：2。
所有子指令都只作用于执行者当前主手上的物品。
没有槽位参数。
指令不会修改其他物品栏槽位。
适用物品
指令系统可以处理任意 ItemStack。
包括：
- 原版盔甲
- Mod 盔甲
- 武器
- 工具
- 方块
- CustomNPCs 脚本物品
- 其他 Mod 的物品
OBJ 配置直接保存于 ItemStack 的 CnpcObjModel NBT 数据中，不依赖特定物品 Mod 的能力或接口。
可用指令
/cnpcobj model <path> 设置 OBJ 模型。
/cnpcobj mtl <path> 设置 MTL 文件。
/cnpcobj texture <path> 设置 PNG 贴图。
/cnpcobj scale <x> <y> <z> 设置 XYZ 缩放。
/cnpcobj rotation <x> <y> <z> 设置 XYZ 旋转，单位为角度。
/cnpcobj guipos <x> <y> 设置 OBJ 模型在物品栏 GUI 中的 XY 位置。
/cnpcobj guisize <x> <y> 设置 OBJ 模型在物品栏 GUI 中的 XY 大小。
/cnpcobj offset <x> <y> <z> 设置非物品栏场景下的 XYZ 模型空间位置偏移。
允许使用负数。
可以用于调整模型在玩家手中、地面或展示框中的位置。
/cnpcobj armoroffset <x> <y> <z> [true|false] 设置 XYZ 盔甲穿戴位置偏移。
最后一个可选的布尔参数控制是否显示原版盔甲。
true = 显示原版盔甲 false = 只显示 OBJ 模型
省略该参数时默认为 true。
/cnpcobj vanillaarmor <true|false> 控制是否显示原版盔甲。
默认值：true。
/cnpcobj cull <true|false> 设置是否启用背面剔除。
默认值：true。
/cnpcobj clear 清除主手物品的全部 OBJ 配置。
/cnpcobj info 查看主手物品当前的 OBJ 配置。
指令 Tab 补全
model、mtl 和 texture 的路径参数支持 Tab 补全。
补全系统会扫描已加载资源包中的 models/ 目录，并根据当前需要的文件类型进行筛选。
例如输入部分模型名称后按 Tab，可以筛选可用模型路径。
单人游戏和局域网主机中，客户端与服务端运行在同一个 JVM，因此资源扫描可以正常工作。
专用服务器无法以相同方式访问客户端资源包中的资源。
因此，在专用服务器环境下 Tab 补全可能为空。
此时可以直接手动输入完整 ResourceLocation 路径。
NPC 盔甲支持
通过 OBJ 配置过的物品可以作为盔甲穿戴在 CustomNPCs NPC 身上。
当 NPC 使用 OBJ Models 模型类型时，NPC 自身的 OBJ 模型以及符合条件的 OBJ 盔甲都可以一起渲染。
盔甲使用 armoroffset / setObjArmorOffset 设置的独立偏移。
不会使用普通物品的手持偏移。
盔甲模型会跟随对应的 NPC 身体部位：
- 头部
- 胸部 / 身体
- 腿部
- 脚部
NPC 图形界面
通过 GUI 配置 NPC：
- 右键 NPC，打开模型设置。
- 在模型列表中找到 OBJ Models。
- 选择 OBJ Models。
- 右上角会出现「OBJ 模型：[编辑]」按钮。
- 点击编辑进入 OBJ 配置界面。
OBJ 编辑器包含以下设置：
OBJ 文件 必填的 OBJ 模型路径。
MTL 文件 可选的 MTL 文件路径。
PNG 贴图 可选的 PNG 贴图路径。
缩放 X / Y / Z 独立的 XYZ 模型缩放。
旋转 X / Y / Z 独立的 XYZ 模型旋转，单位为角度。
碰撞箱 宽 / 高 NPC 自定义碰撞箱大小。 设置为 0 时使用 CustomNPCs 原本的碰撞箱逻辑。
背面剔除 控制是否剔除模型背面的三角面。
清除模型 清除全部 OBJ 配置。
资源选择按钮会列出已加载资源包中 models/ 目录下的资源。
双击资源即可选择。
如果列表为空，也可以直接在输入框中手动输入路径。
模型缩放
OBJ 的单位不一定与 Minecraft 的方块单位一致。
一个 Minecraft 方块对应 1.0 的模型空间单位。
根据建模软件和导出设置的不同，模型可能需要进行较大幅度的缩放。
例如，Blockbench 导出的部分模型可能需要使用约 0.0625（1/16）的缩放比例。
背面剔除
背面剔除默认开启。
对于球体等闭合模型，通常建议保持开启。
对于旗子、广告牌等单面模型，如果需要从正反两面都能看到模型，应关闭背面剔除。
已知限制
CNPC OBJ Models 主要用于静态 OBJ 模型。
目前不提供骨骼动画或动画 OBJ 模型支持。
如果需要动画模型，请使用基于 GeckoLib 的方案，例如 CNPC-Gecko-Addon。
与 Gecko Addon 的兼容性
CNPC OBJ Models 与 Gecko 模型相关的 Mod 可以同时安装。
两者不需要互相替代。
一个 NPC 的模型槽位一次只能使用一种模型类型。
NPC 使用 OBJ Models 时使用 OBJ 渲染器。
NPC 使用 Gecko 模型时使用 Gecko 渲染器。
因此，两种模型类型对于同一个 NPC 来说是互斥的，但并不是两个 Mod 之间的直接冲突。
常见问题
模型出现碎片化、破洞或渲染异常：
请确认使用的版本已经包含 OBJ 面处理相关修复。
包含复杂多边形的 OBJ，尤其是超过四个顶点的凹多边形，可能无法正确进行三角化。
建议在建模软件中先将复杂面三角化，再导出 OBJ。
从模型背面可以看到模型内部：
开启背面剔除。
使用：
setObjCullBackface(true)
或者：
/cnpcobj cull true
旗子、广告牌等单面模型从背面看不见：
关闭背面剔除。
使用：
setObjCullBackface(false)
或者：
/cnpcobj cull false
模型完全是白色的：
检查 MTL 中的 map_Kd 路径。
检查显式指定的 PNG 路径。
使用：
/cnpcobj info
查看当前 OBJ 配置。
模型太大或太小：
调整模型缩放。
OBJ 的单位会根据建模软件和导出设置有所不同。
部分 Blockbench 导出的模型可能需要约 0.0625（1/16）的缩放。
脚本方块或脚本物品修改后没有立即生效：
CustomNPCs 大约每 10 tick（0.5 秒）同步一次这些变化。
等待下一次客户端同步即可。
NPC 选择了 OBJ Models，但是没有显示模型：
请确认已经设置 OBJ 模型路径。
NPC 选择 OBJ Models 但没有配置 OBJ 文件时，本身就不会显示 OBJ 模型。
这样可以方便区分「已经选择 OBJ 模型类型」和「已经完成 OBJ 模型配置」的 NPC。
The CNPC OBJ Models Compat Team
