Skip to content

自定义 ActionBlock 扩展教程 ​

CwcMontage 遵循面向对象的开闭原则(Open-Closed Principle):核心播放内核完全不需要了解具体的业务表现细节。所有的音效、粒子、相机震屏、受击盒激活均作为独立的 ActionBlock 实现。

系统采用 0-GC 纯只读配置与运行时状态外置架构:资产类只保存静态只读配置,所有运行时的临时变量由专用的 State 类持有,由内核通过类型对象池自动复用,做到单次播放绝对 0-GC 且支持任意多角色并发播放。


核心基类与架构选型 ​

在扩展动作块时,根据表现类型选择继承的泛型基类:

动作块基类状态约束适用场景
MontageActionBlockBase<TState>where TState : class, IMontageBlockState, new()纯逻辑表现(相机震屏、顿帧、音效、材质变色、后处理等)
MontageSpatialActionBlockBase<TState>where TState : MontageSpatialBlockState, new()空间位置型表现(特效粒子、生成预制体模型、武器残影等)

1. 运行时状态接口 (IMontageBlockState) ​

每个动作块的可变状态必须实现 IMontageBlockState 接口:

csharp
namespace Cwcbb.Tools.CwcMontage
{
    public interface IMontageBlockState
    {
        /// <summary>
        /// 当离开动作块区间、动画被打断或回池时调用,将所有可变变量重置归零。
        /// </summary>
        void Reset();
    }
}

内核对象池 MontageBlockStatePool 会在动作块离开区间或动画结束时自动调用 Reset(),并将该状态实例安全保存在专属栈中,供下次播放复用。


2. 实战示例:实现相机震屏动作块 (CameraShakeBlock) ​

csharp
using System;
using UnityEngine;
using Cwcbb.Tools.CwcMontage;

// 1. 定义运行时状态类(随槽位对象池常驻复用,杜绝装箱拆箱)
public class CameraShakeState : IMontageBlockState
{
    public float ElapsedTime;

    public void Reset()
    {
        ElapsedTime = 0f;
    }
}

// 2. 继承强类型泛型基类(动作块自身保持 100% 只读配置单例)
[Serializable]
[MontageCategory("Visual")]
[MontageColor("#9b59b6")]
[MontageDisplayName("Camera Shake")]
public class CameraShakeBlock : MontageActionBlockBase<CameraShakeState>
{
    #region Inspector 只读配置

    [SerializeField] private float _intensity = 0.5f;
    [SerializeField] private float _frequency = 25.0f;

    #endregion

    #region 强类型生命周期

    protected override void OnEnter(in MontageActionContext context, CameraShakeState state)
    {
        state.ElapsedTime = 0f;
        // 触发相机系统初始震冲(例如 Cinemachine Impulse)
    }

    protected override void OnUpdate(in MontageActionContext context, CameraShakeState state, float deltaTime)
    {
        state.ElapsedTime += deltaTime;
        // 随帧采样震动衰减...
    }

    protected override void OnExit(in MontageActionContext context, CameraShakeState state)
    {
        // 离开区间或被强行打断时平滑重置相机
    }

    #endregion
}

3. 空间型动作块 (MontageSpatialActionBlockBase) ​

如果表现需要跟随人形骨骼挂点(如左手、武器、胸口)或在触发时保持世界坐标固定: 继承 MontageSpatialActionBlockBase<TState>,且状态继承自 MontageSpatialBlockState,系统会自动处理目标骨骼解析与世界坐标跟随矩阵换算,且杜绝挂载为子节点造成的角色非等比缩放畸变。

csharp
using System;
using UnityEngine;
using Cwcbb.Tools.CwcMontage;

public class SparkEffectBlock : MontageSpatialActionBlockBase<SparkEffectBlock.SparkState>
{
    public class SparkState : MontageSpatialBlockState
    {
        public GameObject SpawnedInstance;

        public override void Reset()
        {
            base.Reset();
            SpawnedInstance = null;
        }
    }

    [SerializeField] private GameObject _sparkPrefab;

    protected override void OnEnter(in MontageActionContext context, SparkState state)
    {
        if (_sparkPrefab == null) return;

        // 1. 基类无 GC 解析骨骼与世界坐标换算(结果存入 state)
        ResolveTargetBone(context, state);
        CalculateWorldTransform(state, out Vector3 worldPos, out Quaternion worldRot);
        Transform attachParent = GetSpawnParent(context, isPreview: false);

        // 2. 从内置对象池生成实例并暂存至 state
        state.SpawnedInstance = MontageObjectPool.Spawn(_sparkPrefab, worldPos, worldRot, attachParent);
    }

    protected override void OnUpdate(in MontageActionContext context, SparkState state, float deltaTime)
    {
        // 外部动态跟随骨骼或按配置保持世界原地不动
        UpdateSpatialTransform(state.SpawnedInstance, in context, state);
    }

    protected override void OnExit(in MontageActionContext context, SparkState state)
    {
        if (state.SpawnedInstance != null)
        {
            MontageObjectPool.Recycle(state.SpawnedInstance);
            state.SpawnedInstance = null;
        }
    }
}

4. 编辑器时间轴视口透明兼容 ​

使用泛型基类 MontageActionBlockBase<TState> 编写的自定义动作块,在 Unity 编辑器中打开 Montage Editor 时间轴时:

  • 右键点击轨道直接自动识别并列入新建菜单;
  • 基类已自动内置编辑器视口专用预览状态,时间轴拖拽与播放头 Scrubbing 即刻生效,无需任何额外的编辑器适配代码。

Released under Cwc Tools Public License (Free for End Products).