角色系统 (Character) - 侧边栏图层

Estimated reading time: 7 minutes

基本介绍

Character 系统是框架提供的角色管理工具，允许模组制作者扩展和自定义游戏中的角色外观、图层、样式和效果。通过该系统，您可以添加新的面部样式、发型、服装图层，以及自定义渲染逻辑。

核心功能：use 方法

use 方法是扩展和自定义角色渲染的核心接口，支持三种调用方式：

maplebirch.char.use(layerMap);
maplebirch.char.use(layerMap, target);
maplebirch.char.use('pre', handler);
maplebirch.char.use('post', handler);
maplebirch.char.use('pre', handler, target);
maplebirch.char.use('post', handler, target);

use() 支持链式调用：

maplebirch.char.use(layers).use('pre', preHandler);

target 参数（画布模型定向）

默认情况下，use() 只作用于原版 main 模型。需要修改其它画布模型时，传入 target。

写法	说明
`'main'`	指定单个模型
`['main', 'clothes']`	指定多个模型
`(name, modelOrOptions) => boolean`	按模型名和模型/选项动态判断

常见模型名来自原版 Renderer.CanvasModels，例如 main、lighting 等。

// 1. 添加预处理/后处理函数
maplebirch.char.use("pre", preprocessFunction); // 在渲染前执行
maplebirch.char.use("post", postprocessFunction); // 在渲染后执行

// 2. 添加图层定义
maplebirch.char.use(layerDefinitions);

// 3. 链式调用
maplebirch.char.use(layer1).use("pre", preFunc).use(layer2);

1. 处理函数

预处理函数 (pre)

在角色渲染前执行，用于修改渲染选项、准备数据、添加自定义逻辑。

// 添加预处理函数
maplebirch.char.use("pre", (options) => {
  // 根据游戏状态修改选项
  if (V.has_magic_aura) {
    options.glow_intensity = 1.5;
    options.color_tint = "#ff5500";
  }
});

指定模型：

maplebirch.char.use(
  "pre",
  (options, model) => {
    options.myMod ??= {};
    options.myMod.modelName = model?.name;
  },
  ["main", "lighting"]
);

handler 的第二个参数是当前 CanvasModel 实例。只需要读写渲染选项时可以忽略它。

后处理函数 (post)

在角色渲染后执行，用于修改渲染结果、添加效果、执行清理工作。

// 添加后处理函数
maplebirch.char.use("post", (options) => {
  // 可以在这里操作 Canvas
  if (options.canvas && options.custom_effect) {
    addCustomEffect(options.canvas, options);
  }
});

2. 图层定义

图层定义是一个对象，键是图层名称，值是该图层的配置对象。

// 图层配置结构
{
  [layerName]: {
    srcfn?: (options) => string,           // 返回图片路径
    masksrcfn?: (options) => string|array, // 返回遮罩图片
    showfn?: (options) => boolean,         // 显示条件
    zfn?: (options) => number,             // Z轴顺序
    filtersfn?: (options) => array,        // 滤镜列表
    animation?: string,                    // 动画类型
    [key: string]: any                     // 其他属性
  }
}

示例：添加自定义头发图层

maplebirch.char.use({
  custom_hair: {
    srcfn: (options) => `img/custom/hair/${options.hair_style}.png`,
    showfn: (options) => options.has_custom_hair,
    zfn: () => maplebirch.char.ZIndices.hair,
    animation: "idle",
  },
});

指定模型

maplebirch.char.use(
  {
    my_mod_overlay: {
      srcfn: () => "img/myMod/overlay.png",
      showfn: () => true,
    },
  },
  "main"
);

匹配多个模型：

maplebirch.char.use(layers, ["main", "lighting"]);

动态匹配：

maplebirch.char.use(layers, (name) => name.startsWith("main"));

面部风格系统

文件夹结构

img/face/[style_name]/[variant_name]/[layer_name].png

路径说明:

style_name: 面部风格名称(如：default, cat, fox)
variant_name: 风格变体名称(如：gentle, sweet, aloof)
layer_name: 面部图层名称(如：eyes, mouth, brows)

路径查找优先级

系统按以下顺序查找图片，找到第一个存在的即使用：

img/face/[当前风格]/[当前变体]/[图层名].png
img/face/[当前风格]/[图层名].png
img/face/default/[当前变体]/[图层名].png
img/face/default/[图层名].png
img/face/default/default/[图层名].png

自动注册：

在模组加载时自动扫描 img/face/ 目录
检测到的样式和变体会自动添加到游戏选项
支持多语言显示名称

示例结构

img/face/
├── default/           # 默认风格
│   ├── gentle/       # 温柔变体
│   │   ├── eyes.png
│   │   ├── mouth.png
│   └── default/      # 默认变体
│       ├── eyes.png
└── cat/              # 猫风格
    ├── sweet/        # 甜美变体
    │   ├── eyes.png
    └── default/      # 默认变体
        └── eyes.png

Pet 模型

框架支持为 PC 派生一个独立的 pet 画布模型，用于在侧边栏旁边显示缩小版角色。pet 模型只保留角色本身体相关图层（基础、面部、头发、肢体等），不包含服装和装备。

Pet 模型通过 maplebirch.char.pet 命名空间管理，支持以下配置：

mask：遮罩参数
rotation：旋转角度
animated：是否播放动画
floating：是否浮动显示
scale：缩放比例（范围 0.5 ~ 1.0）

详见 Pet API 文档。

转化系统

转化系统允许模组制作者为角色添加自定义形态变化（如兽化、神圣化等）。通过 maplebirch.char.transformation.add 注册转化，可定义部件、特质、等级、消息和渲染图层。

详见转化系统。

内置辅助函数

faceStyleSrcFn

辅助函数，用于创建面部样式图片源函数。

// 创建眼睛图层源函数
const eyesSrc = maplebirch.char.faceStyleSrcFn("eyes");
const dynamicSrc = maplebirch.char.faceStyleSrcFn((options) => options.eye_type || "default");

// 在图层中使用
maplebirch.char.use({
  custom_eyes: {
    srcfn: eyesSrc,
  },
});

mask

创建遮罩图片，用于控制图层的可见区域。

签名：mask(x = 0, rotation = 0, swap = false, width = 256, height = 256)

参数	默认值	说明
`x`	0	分割线偏移（像素，相对中心），范围受 width 约束
`rotation`	0	旋转角度，范围 -90° ~ 90°
`swap`	false	是否左右交换遮罩
`width`	256	画布宽度
`height`	256	画布高度

选项来源：V.options.maplebirch.character.mask、V.options.maplebirch.character.rotation；NPC 侧边栏使用 V.options.maplebirch.npcsidebar.mask、V.options.maplebirch.npcsidebar.rotation。

// 中心分割，无旋转
maplebirch.char.mask(0);
// 向右偏移 50px，旋转 45°，反向遮罩
maplebirch.char.mask(50, 45, true);

补充说明

图层名称建议带模组名前缀，避免与原版或其它模组冲突。
不传 target 时默认只修改 main，避免意外影响其它画布模型。
如果要修改多个模型，优先使用数组；只有需要规则匹配时再使用函数。
showfn 只负责判断是否显示，不建议在里面修改游戏变量。
面部样式图片路径大小写应保持一致。

#角色系统 (Character) - 侧边栏图层

#基本介绍

#核心功能：use 方法

#target 参数（画布模型定向）

#1. 处理函数

#预处理函数 (pre)

#后处理函数 (post)

#2. 图层定义

#示例：添加自定义头发图层

#指定模型

#面部风格系统

#文件夹结构

#路径查找优先级

#示例结构

#Pet 模型

#转化系统

#内置辅助函数

#faceStyleSrcFn

#mask

#补充说明