编写自定义效果（C#）

除了使用 内置效果 或 从检视器创建自定义效果, 你也可以通过 C# 轻松编写自定义效果.

附注：确保你已阅读 高级概念 页面！

效果有三部分关键组成（可以写在同一文件中）。

参数类/结构体

包含关于你将在效果中使用的数据/数值的信息（状态）

状态 结构体

主效果类。给定参数和字符，会随时间修改它。同时处理 修饰符

可脚本化包装器

将前面的元素统一在一起并允许你将内容保存到磁盘。几行代码让我们完成其余工作！

这些名称只是约定，但 你可以按照自己的喜好命名它们!

只要知道你需要：

• 用于存储效果变量的东西

• 负责修改字母的结构体

• 将这两者连接起来并允许你将信息保存到磁盘的可脚本化对象

编写你的自定义脚本

在本例中，我们制作一个使字符按可变量向上移动的效果。

首先，确保导入必要的命名空间（无论如何你的 IDE 都会提醒你 <3）

using UnityEngine;

// 导入 Text Animator 的命名空间
using Febucci.TextAnimatorCore;
using Febucci.TextAnimatorCore.Text;
using Febucci.Parsing;
using Febucci.TextAnimatorForUnity.Effects;

参数

创建你将用来修改字符的数据（这也是你将在检视器中看到并编辑的内容）。

// 可以是 struct 或 class
// 后者允许你拥有默认值
[System.Serializable]
class CustomEffectParameters
{
    public float amount = 1.5f;
}

状态

效果的“核心”部分。根据参数和预先计算的 Text Animator 数据修改字母。

• 该结构体必须继承自 IEffectState.

// 必须是 struct！
struct CustomEffectState : IEffectState
{
    readonly float defaultAmount;
    float amount;


    public CustomEffectState(CustomEffectParameters data)
    {
        // 从参数类获取默认数值
        this.defaultAmount = data.amount;
        this.amount = defaultAmount;
    }

    public void UpdateParameters(RegionParameters parameters)
    {
        // 自动处理用户在富文本标签中写入的情况， 
        // 在此例中为 "a"
        // （例如 <tagID a=5> 会将 "amount" 设为 5，而 
        // a*2 会使 "amount" 成为 defaultAmount 的两倍）
        amount = parameters.ModifyFloat("a", defaultAmount);
    }

    public void Apply(ref CharacterData character, in ManagedEffectContext context)
    {
        // 使用 "amount" 将字符向上移动
        // 具有清晰且易用的 API
        character.MovePosition(
            Vector3.Up * amount * context.progressionRange * context.intensity,
            context.isUpPositive
            );
        // 1. 注意 context.progressionRange -> 它是 
        //     你在编辑器中分配的曲线！
        //     允许你得到阶跃、正弦、弹跳等效果
        // 2. 也注意 context.intensity，必要用于实现 
        //     阶段之间的平滑过渡。
        }
}

可脚本化对象包装器

创建将自定义效果挂接到 Text Animator 所需的逻辑，同时将其保存到 Assets 文件夹中。

[System.Serializable] // <-- 使其可序列化！！
[CreateAssetMenu(fileName = "Your Custom Effect")]
class CustomEffectScriptable : ManagedEffectScriptable<CustomEffectState, CustomEffectParameters>
{
    // 简单地根据参数（已由 Text Animator 管理）创建一个新的 State
    protected override CustomEffectState CreateState(CustomEffectParameters parameters)
        => new CustomEffectState(parameters);
}

还有另一种接受更多类型的 "ManagedEffectScriptable" 版本，以及 "Referenced" 效果实现，但我们将在未来版本中介绍！

这些脚本就是 Text Animator 所需的一切，以确保你获得：

• 自动管理的曲线、播放和修饰符

• 无竞争条件的优化效果

• 在 AOT 平台上兼容的效果（无需使用反射）

• 我们强大的预览编辑器

• 在 UI Toolkit 和 Text Mesh Pro 上表现一致的效果，包括动态缩放

以及更多！<3

---

完成！ 你已完成所有必要步骤，耶！ 你添加的效果越多，这个过程就会越熟悉和简单。

记得在检视器中为你的效果添加标签并将其加入数据库！否则它将无法被识别。你可以在这里阅读更多： 效果数据库

祝你在应用效果时玩得开心！

---

关于创建“Referenced”效果的指南即将发布，我们仍在调整 UX/API 部分。