English Tutorial

1. Set up Unity (2022.3* recommended, the game uses built-in render pipeline, please pay attention to the corresponding model materials), import MoreHead-Asset-Pack_v1.1.unitypackage.

   📥 Download unitypackage

2. Import your model and drag PlayerAvatar prefab into the scene.

   Make sure your model is compatible with Unity and properly rigged if animated.

3. Find the following parts in PlayerAvatar, where models will be placed:

   Name	Description	Tag
   Head decoration (Do Not Move)	Head part that raises when speaking	head
   Neck decoration (Do Not Move)	Chin/chest area	neck
   Body decoration (Do Not Move)	Body	body
   Hip decoration (Do Not Move)	Hip/lower body area	hip
   World decoration (Do Not Move)	Follows character position but maintains horizontal orientation	world

   ⚠️ These positions are anchor references. DO NOT modify coordinates, or your model will be misaligned in-game.
   💡 The world tag is useful for decorations that should maintain their horizontal orientation regardless of character movement.

4. Create an empty object under the target part (referred to as A) and name it.

   This name will be displayed in-game as your decoration's name.

5. Place your model inside A and adjust to a suitable position.

6. Drag A to the Project window to create a prefab.

7. Run Tools → Head Decorations Builder, drag your A prefab (or more, batch export is supported) into the script panel, and select the corresponding part from step 3, then click Add Model to List.

   Make sure to select the correct body part (head/neck/body/world) that matches where you placed your decoration.

8. Click Build All AssetBundle, then locate the [your decoration name].hhh file in the AssetBundles folder.

   Only the .hhh file is needed for installation. Other generated files can be ignored.

9. Move the .hhh file to BepInEx\plugins (the game will load all .hhh files in the plugins folder. If you're not sure where to put it, you can place it in \MoreHead\Decorations for better organization).

   ⚠️ For multiplayer visibility: You and your friends must have the same .hhh file installed to see the correct decorations.
   ⚠️ Do not package the MoreHead.dll file into your Mod, only the .hhh file and this mod are needed to enjoy the decorations.

10. Start the game and enjoy!

    Press ESC in-game and find "MoreHead" in the bottom left to access your new decoration.

中文教程

1. 部署 Unity（推荐 2022.3* 版本，游戏使用的是内置渲染管线，请注意对应的模型材质），导入 MoreHead-Asset-Pack_v1.1.unitypackage。

   📥 下载 unitypackage

2. 导入模型，并将 PlayerAvatar 预制体拖入场景。

   确保您的模型与Unity兼容，如果有动画需要正确绑定骨骼。

3. 找到 PlayerAvatar 中的以下部位，对应模型将会摆放的位置：

   名称	描述	标签
   Head decoration (Do Not Move)	说话时会上抬的头部	head
   Neck decoration (Do Not Move)	下巴/胸口	neck
   Body decoration (Do Not Move)	身体	body
   Hip decoration (Do Not Move)	臀部/下半身	hip
   World decoration (Do Not Move)	跟随角色位置移动但保持水平方向	world

   ⚠️ 这些位置是坐标锚点参考。请勿修改坐标，否则您的模型在游戏中会错位。
   💡 world 标签适用于需要保持水平方向的装饰品，无论角色如何移动。

4. 在目标部位下创建一个空对象（称为A），并命名。

   此名称将在游戏中显示为您的装饰品名称。

5. 将模型放入A，并调整到合适位置。

6. 拖动A到Project窗口，创建预制体。

7. 运行Tools → Head Decorations Builder，拖入A预制体（或更多，支持批量导出），并选择第3步中对应的部位，随后点击Add Model to List。

   确保选择正确的身体部位（头部/颈部/身体/世界空间），与您放置装饰的位置相匹配。

8. 点击Build All AssetBundle，然后在AssetBundles文件夹中找到[你的装饰品名].hhh文件。

   安装时只需要.hhh文件，其他生成的文件可以忽略。

9. 将.hhh文件移动至BepInEx\plugins（启动游戏会加载plugins下所有的.hhh文件。如果不知道往哪放，可以放入\MoreHead\Decorations便于管理）。

   ⚠️ 多人游戏可见性：您和您的朋友必须安装相同的.hhh文件才能互相看到正确的装饰。
   ⚠️ 不要打包MoreHead.dll文件到您的Mod中，只需.hhh文件和该mod就能畅玩饰品。

10. 启动游戏，享受装饰！

    在游戏中按ESC，在左下角找到"MoreHead"即可访问您的新装饰。

English Documentation

Starting from version 1.2.4, MoreHead provides public APIs for extension. These interfaces allow developers to programmatically load AssetBundle resources, inject custom scripts, and enhance decoration functionality.

Public APIs

The following public interfaces are available in the HeadDecorationManager class:

Integration Methods

There are two primary ways to leverage MoreHead's API for extended functionality:

1. Embedding AssetBundles as Resources

You can embed your AssetBundle (.hhh) files directly into your DLL as embedded resources:

1. Create AssetBundles following standard procedures outlined in the "How to Add Models" section
2. In Visual Studio (or your preferred IDE):
   • Add the .hhh files to your project
   • Set their "Build Action" to "Embedded Resource"
3. In your plugin's initialization code:

   // Load all embedded .hhh resources from your assembly
   Assembly assembly = Assembly.GetExecutingAssembly();
   MoreHead.HeadDecorationManager.LoadExternalAssetBundlesFromAssembly(assembly);
   MoreHead.HeadDecorationManager.RecreateUI();
   

Note: Embedding resources into your DLL is not mandatory. You can also use MoreHead's standard methods to load local .hhh files and simply use your DLL for script injection and functionality implementation.

2. Programmatic Script Injection

You can write scripts that access and modify decorations, regardless of whether they were loaded from your DLL or other sources:

1. Use the provided API to access decoration prefabs
2. Add custom components/scripts to enhance functionality
3. Implement your own logic for decoration behavior

Implementation Example

using BepInEx;
using BepInEx.Logging;
using System.Reflection;
using UnityEngine;
using System.Collections.Generic;

namespace MyCustomDecorations
{
    [BepInPlugin("com.yourname.customdecorations", "Custom Decorations Mod", "1.0.0")]
    [BepInDependency("Mhz.REPOMoreHead", BepInDependency.DependencyFlags.HardDependency)]
    public class CustomDecorationsPlugin : BaseUnityPlugin
    {
        public static CustomDecorationsPlugin Instance { get; private set; }
        private ManualLogSource _logger;
        private const string TARGET_MODEL_NAME = "Cigar"; // Target model name

        private void Awake()
        {
            Instance = this;
            _logger = Logger;
            _logger.LogInfo("Custom Decorations Mod loaded");
            
            // Load decorations and set up handlers
            LoadDecorations();
        }

        private void LoadDecorations()
        {
            try
            {
                // Get current assembly
                Assembly assembly = Assembly.GetExecutingAssembly();
                
                // Load all .hhh resources from current DLL
                MoreHead.HeadDecorationManager.LoadExternalAssetBundlesFromAssembly(assembly);
                
                // Recreate UI to display newly loaded models
                MoreHead.HeadDecorationManager.RecreateUI();
                
                // Find specific models matching the target name
                List<MoreHead.DecorationInfo> targetDecorations = 
                    MoreHead.HeadDecorationManager.FindDecorationsByPartialName(assembly, TARGET_MODEL_NAME);
                
                if (targetDecorations.Count > 0)
                {
                    _logger.LogInfo($"Found {targetDecorations.Count} models matching '{TARGET_MODEL_NAME}'");
                    
                    // Add component to each found target model
                    foreach (var decoration in targetDecorations)
                    {
                        if (decoration.Prefab != null && decoration.Prefab.GetComponent<SpaceKeyHandler>() == null)
                        {
                            _logger.LogInfo($"Adding SpaceKeyHandler to {decoration.DisplayName}");
                            decoration.Prefab.AddComponent<SpaceKeyHandler>();
                        }
                    }
                }
            }
            catch (System.Exception ex)
            {
                _logger.LogError($"Error processing decorations: {ex.Message}");
            }
        }
        
        // Class for handling decoration behavior
        public class SpaceKeyHandler : MonoBehaviour
        {
            private void Awake()
            {
                // Log when the component is initialized
                Instance._logger.LogInfo($"SpaceKeyHandler initialized on {gameObject.name}");
            }
            
            private void Update()
            {
                // Check for space key press directly in the component
                if (Input.GetKeyDown(KeyCode.Space))
                {
                    // Simply log the message when triggered
                    Instance._logger.LogInfo($"Space key pressed on decoration: {gameObject.name}");
                }
            }
        }
    }
}

⚠️ Important Notes

Scripts don't necessarily need to be attached to the corresponding model - implement them as needed for proper functionality. For example, the sample code above only responds to space key presses when the character is displayed in the menu.

Why is this happening?

Because in first-person view, the game sets the local character's [RIG] GameObject to inactive (SetActive(false)).

• [RIG] is the parent object containing the character model, and MoreHead decorations are also mounted under this hierarchy.
• When [RIG] is disabled, according to Unity's mechanics, all components of child objects will not have their Update, FixedUpdate and other lifecycle methods called.
• Custom decoration models are also placed under the [RIG] hierarchy, so when you directly attach scripts to the model, once you enter first-person view, these scripts cannot execute normally because the parent object is disabled.
• However, in the game menu interface, the character model always remains active, so scripts attached to decorations can work normally, as Unity only executes component methods on active GameObjects.

This difference in activation states is the key point that explains why the same script behaves differently in different scenarios.

Important Notes About Multiplayer Synchronization

Although in first-person view you cannot see your own decoration model (because the local [RIG] is disabled), the game still synchronizes your state over the network. This means that as long as you properly handle multiplayer synchronization logic, other players can still see the changes and actions of your decoration model.

Therefore, even if local scripts don't execute due to [RIG] being disabled, you can still implement interactive effects through global managers or network synchronization mechanisms, allowing all players to see changes to your decoration model. This creates possibilities for interactive decorations.

Points to Consider When Implementing Model Behavior Logic:

1. Script Mounting Strategy - Consider using global managers or event systems as alternatives
2. Differences Between Scene Character and Menu Character - Some scripts may only work in specific contexts
3. Multiplayer Synchronization Issues - Ensure consistent behavior across network clients
4. Component Activation State - Components on disabled GameObjects won't execute Update/FixedUpdate methods
5. Resource Management - Properly initialize and clean up resources to avoid memory leaks
6. Network Authority - Consider which operations should be executed locally and which need network synchronization
   
   

中文文档

从1.2.4版本开始，MoreHead提供了公开API接口，用于扩展功能。这些接口允许开发者以编程方式加载AssetBundle资源、注入自定义脚本，并增强装饰物功能。

公开API接口

以下是HeadDecorationManager类中可用的公共接口：

集成方法

有两种主要方式利用MoreHead的API进行功能扩展：

1. 将AssetBundle作为资源嵌入

您可以将AssetBundle（.hhh）文件直接嵌入到DLL中作为嵌入式资源：

1. 按照"如何添加模型"部分的标准流程创建AssetBundle
2. 在Visual Studio（或您选择的IDE）中：
   • 将.hhh文件添加到您的项目
   • 将它们的"生成操作"设置为"嵌入式资源"
3. 在您的插件初始化代码中：

   // 从您的程序集加载所有嵌入的.hhh资源
   Assembly assembly = Assembly.GetExecutingAssembly();
   MoreHead.HeadDecorationManager.LoadExternalAssetBundlesFromAssembly(assembly);
   MoreHead.HeadDecorationManager.RecreateUI();
   

注意：将资源嵌入到DLL中不是必须操作。您也可以使用MoreHead的标准方法加载本地.hhh文件，只用您的DLL注入脚本和实现功能。

2. 程序化脚本注入

您可以编写脚本访问和修改装饰物，无论它们是从您的DLL还是其他来源加载的：

1. 使用提供的API访问装饰物预制体
2. 添加自定义组件/脚本以增强功能
3. 实现您自己的装饰物行为逻辑

实现示例

using BepInEx;
using BepInEx.Logging;
using System.Reflection;
using UnityEngine;
using System.Collections.Generic;

namespace MyCustomDecorations
{
    [BepInPlugin("com.yourname.customdecorations", "自定义装饰MOD", "1.0.0")]
    [BepInDependency("Mhz.REPOMoreHead", BepInDependency.DependencyFlags.HardDependency)]
    public class CustomDecorationsPlugin : BaseUnityPlugin
    {
        public static CustomDecorationsPlugin Instance { get; private set; }
        private ManualLogSource _logger;
        private const string TARGET_MODEL_NAME = "Cigar雪茄"; // 目标模型名称

        private void Awake()
        {
            Instance = this;
            _logger = Logger;
            _logger.LogInfo("自定义装饰MOD已加载");
            
            // 加载装饰物并设置处理脚本
            LoadDecorations();
        }

        private void LoadDecorations()
        {
            try
            {
                // 获取当前程序集
                Assembly assembly = Assembly.GetExecutingAssembly();
                
                // 加载当前DLL中的所有.hhh资源
                MoreHead.HeadDecorationManager.LoadExternalAssetBundlesFromAssembly(assembly);
                
                // 重建UI以显示新加载的模型
                MoreHead.HeadDecorationManager.RecreateUI();
                
                // 查找匹配目标名称的特定模型
                List<MoreHead.DecorationInfo> targetDecorations = 
                    MoreHead.HeadDecorationManager.FindDecorationsByPartialName(assembly, TARGET_MODEL_NAME);
                
                if (targetDecorations.Count > 0)
                {
                    _logger.LogInfo($"找到 {targetDecorations.Count} 个匹配 '{TARGET_MODEL_NAME}' 的模型");
                    
                    // 为每个找到的目标模型添加组件
                    foreach (var decoration in targetDecorations)
                    {
                        if (decoration.Prefab != null && decoration.Prefab.GetComponent<SpaceKeyHandler>() == null)
                        {
                            _logger.LogInfo($"为 {decoration.DisplayName} 添加 SpaceKeyHandler");
                            decoration.Prefab.AddComponent<SpaceKeyHandler>();
                        }
                    }
                }
            }
            catch (System.Exception ex)
            {
                _logger.LogError($"处理装饰物时出错: {ex.Message}");
            }
        }
        
        // 用于处理装饰物行为的类
        public class SpaceKeyHandler : MonoBehaviour
        {
            private void Awake()
            {
                // 组件初始化时记录日志
                Instance._logger.LogInfo($"在 {gameObject.name} 上初始化了 SpaceKeyHandler");
            }
            
            private void Update()
            {
                // 直接在组件中检测空格键按下
                if (Input.GetKeyDown(KeyCode.Space))
                {
                    // 触发时简单记录消息
                    Instance._logger.LogInfo($"空格键在装饰物上按下: {gameObject.name}");
                }
            }
        }
    }
}

⚠️ 重要提示

脚本不一定非要绑定在对应模型上，按需处理才能完善功能。例如上面的示例代码，只能在菜单里显示角色时响应空格输出日志。

为什么会这样？

因为游戏在第一人称视角下会将本地角色的[RIG]游戏对象设为非激活状态（SetActive(false)）。

• [RIG]是包含角色模型的父级对象，MoreHead的装饰模型也被挂载在这个层级下。
• 当[RIG]被禁用时，根据Unity的工作机制，其下所有子对象的组件的Update、FixedUpdate等生命周期方法都不会被调用。
• 自定义装饰模型同样放置在[RIG]层级下，因此当您在模型上直接挂载脚本时，一旦进入第一人称视角，这些脚本就会因为父对象被禁用而无法正常执行。
• 而在游戏菜单界面中，角色模型始终保持激活状态，此时挂载在装饰上的脚本可以正常工作，这是因为Unity只会执行激活状态游戏对象上的组件方法。

这种激活状态的差异是关键点，它解释了为什么同样的脚本在不同场景下表现不一致。

关于多人同步的重要说明

虽然在第一人称视角下您看不到自己的装饰模型（因为本地[RIG]被禁用），但游戏依然会在网络中同步您的状态。这意味着只要您正确处理多人同步逻辑，其他玩家仍然可以看到您装饰模型的变化和动作。

因此，即使本地脚本因[RIG]禁用而不执行，您仍然可以通过全局管理器或网络同步机制来实现交互效果，让所有玩家都能看到您的装饰模型发生的变化。这为创造交互式装饰提供了可能性。

实现模型行为逻辑时需要注意以下几点：

1. 脚本挂载策略 - 考虑使用全局管理器或事件系统等替代方法
2. 场景角色和菜单角色的区别 - 某些脚本可能只在特定上下文中工作
3. 多人同步问题 - 确保在网络客户端间行为一致
4. 组件激活状态 - 禁用的游戏对象上的组件不会执行Update/FixedUpdate方法
5. 资源管理 - 正确初始化和清理资源，避免内存泄漏
6. 网络权限 - 考虑哪些操作应该在本地执行，哪些需要网络同步