角色
更新记录
| 日期 | 适用版本 | 变化 |
| 2026-09-16 | ver-29 | 增加可选敌方受击/击杀血液视觉及附加.喷血排除说明；原受伤/死亡事件语义不变，完整画面待用户实测。 |
介绍
角色组件
配置项
| 名称 | 类型 | 必填 | 说明 |
| 类型 | 文本 | true | 固定值： |
| 名称 | 文本 | true | 全局唯一标识 |
| 显示名 | 文本 | false | |
| 默认主角 | 逻辑 | false | 是否是可操控的主角，同时只能存在一个主角 |
| 等级 | 整数 | false | 配合成长组件使用 |
| 经验值 | 整数 | false | 被其他角色杀死后，对方可以获得的经验值 |
| 成长 | 文本 | false | 填写成长组件名称，可以自动获得对应等级的基础属性。 |
| hp | 整数 | false | 生命值 |
| maxhp | 整数 | false | 最大生命值 |
| mp | 整数 | false | 法力值 |
| maxmp | 整数 | false | 最大法力值 |
| 命中 | 整数 | false | 默认值：100 |
| 躲避 | 整数 | false | 默认值：0 |
| 暴击 | 整数 | false | 默认值：0 |
| 威望 | 整数 | false | 低威望角色无法发现,攻击高威望角色。默认：0 |
| 扩展属性... | 整数 | false | 可配置自己的扩展属性值 |
| 内观 | table {} | false | 会自动显示到角色框控件中 |
| 外观 | table {} | false | 地图上的角色动画外观 |
| 外观次序 | table {} | false | |
| 包围盒 | table | false | {宽度,高度,x偏移,y偏移} 用于鼠标焦点判断,高度会影响技能命中位置 F12可以查看 |
| 移动帧速 | 整数 | false | 默认值：100 配合角色移动动画设置一个基础值,设定后不再改变,后续移速相关的属性都将以他为基础。 |
| 攻击间隔 | 整数 | false | 默认值：3000 单位：毫秒 <0 无法攻击 |
| 移动间隔 | 整数 | false | 默认值：1500 单位：毫秒 <0 无法移动 |
| 攻击速度 | 整数 | false | 默认值：0 百分比增幅,正值表示加速,负值表示减速 |
| 移动速度 | 整数 | false | 默认值：0 百分比增幅,正值表示加速,负值表示减速 |
| 跑动 | 逻辑 | false | 是否允许跑动，一次移动2格 |
| 方向 | 整数 | false | 出生时的方向 0为上 8个方向按顺时针为0-7 -1为随机 |
| 动作模式 | 整数 | false | 0：8方向 1：2方向 默认：0 |
| 智能等级 | 整数 | false | 默认：0 |
| 巡逻范围 | 整数/table | false | 角色巡逻功能 |
| 自动隐藏 | 文本 | false | 角色是否会自动隐藏 |
| 视野范围 | 整数 | false | 追击,寻找目标最远距离 |
| 保持距离 | 整数 | false | 与敌方保持一定距离。 |
| 主动攻击 | 逻辑 | false | 是否主动寻怪 |
| 自动战斗 | 逻辑 | false | 主角的自动战斗开关 |
| 锁定目标 | 逻辑 | false | 启用后右键移动不会取消正在攻击的目标 |
| 自动反击 | 整数 | false | |
| 尸体保留时间 | 整数 | false | 死亡倒地后后开始计时 |
| 出生效果 | 整数 | false | |
| 死亡效果 | 整数 | false | |
| 重生间隔 | 整数 | false | <0 不重生 |
| 重生范围 | 整数 | false | 以刷新点为中心的范围 |
| 战斗警戒 | 整数 | false | 0：攻击后转停止动作 1：攻击后停留在攻击动作第一帧 |
| 出现音效 | table {} | false | 触发后随机播放数组中的音效标识 |
| 攻击音效 | table {} | false | 触发后随机播放数组中的音效标识 |
| 命中音效 | table {} | false | 触发后随机播放数组中的音效标识 |
| 受伤音效 | table {} | false | 触发后随机播放数组中的音效标识 |
| 死亡音效 | table {} | false | 触发后随机播放数组中的音效标识 |
| 血条效果 | table | false | |
| 掉血效果 | table | false | |
| 名称效果 | table | false | |
| 光影效果 | table | false | |
| 影子效果 | table | false | {比例=1,x=0,y=0},设置影子的缩放比例,x,y偏移,如果配置角色脚底会有一个影子效果 |
| 角色大小 | 数值 | false | 角色外观的缩放的比例,默认：1.0 |
| 图标名 | 文本 | false | 配合地图框控件使用,填写角色图标中的图标标识 |
| 装备 | table | false | |
| 掉落 | table {} | false | |
| 掉落几率 | 整数 | false | 百分比属性 为掉落表中的几率进行增幅 默认：100 |
| 技能表 | table {} | false | |
| 附加 | table | false | 自定义变量 |
| 资源表 | table | false | {
{标识="",文件=""}, {标识="",文件=""}, .. } |
| 系统事件 | table | false |
威望
1. 角色无法发现和攻击高于自身威望的敌对阵营目标。 2. 角色组件的配置项中可以设置默认威望,状态组件可以改变状态时间内角色威望。 3. 当攻击目标的威望发生变动,威望高于自身时仇恨会被清0。 4. 利用好威望和仇恨,可以丰富扩展游戏玩法。
扩展属性
这里可以配置 在App.lua入口配置项中设置的扩展属性的具体数值。
{
hp = 100,
maxhp = 100,
mp = 100,
maxmp = 100,
攻击 = 10,
防御 = 0,
...
...
},
内观
当角色框控件显示模式为内观时显示在控件中。
内观 = {{位置="衣服",图片="图集_内观|00300",x=-216,y=-180},{位置="发型",图片="图集_内观|00401",x=-216,y=-180,颜色=RGBA(66,66,66,255)}},
| 名称 | 类型 | 必填 | 说明 | |
位置 | 文本 | true | 位置为-1时，表示图片置底显示 | |
图片 | 文本 | true | ||
动画 | 文本 | false | ||
x | 整数 | false | 显示坐标偏移x | |
y | 整数 | false | 显示坐标偏移y | |
颜色 | RGBA | false |
外观
角色地图上显示的效果，可以是动画也可以是图片，当角色绑定了角色框控件，并且显示模式为外观时显示。
外观 = {{位置="衣服",动画="角色动画_男布衣"},{位置="染色",动画="角色动画_男布衣染色"}},
外观 = {{位置="衣服",图片="角色卡片_男默认",缩放=0.6,x=0,y=-40}},
| 名称 | 类型 | 必填 | 说明 | |
位置 | 文本 | true | 通常为子类名称 | |
动画/图片 | 文本 | true | ||
颜色 | RGBA | false | ||
缩放 | 文本 | false | ||
x | 数值 | false | 显示偏移x | |
y | 数值 | false | 显示偏移y |
外观次序
- 用于设置不同位置的外观在每个方向下的显示排序。从上开始顺时针8个方向。
- 如果你有其他位置的纸娃娃，需要填到配置里面去，显示效果为一层一层的叠加，{"内裤","秋裤","外裤",....}，缺省默认次序设置如下：
外观次序 = {
{"武器","衣服","染色","发型"},
{"衣服","染色","武器","发型"},
{"衣服","染色","武器","发型"},
{"衣服","染色","武器","发型"},
{"衣服","染色","武器","发型"},
{"武器","衣服","染色","发型"},
{"武器","衣服","染色","发型"},
{"武器","衣服","染色","发型"}
}
动作模式
- 是否让角色外观只显示
左,右两个方向。 08方向。角色外观是动画模式时,显示8个方向动作。12方向。角色外观只显示左,右(2,6)两个方向。图片型外观时,8方向和2方向动画效果不同,2方向偏向与横版游戏。
智能等级
- 用于增强自动战斗时的追击效果。
0无寻路默认效果。1开启自动寻路模式。
巡逻范围
tabs
@tab 随机移动 配置为整数时,单位是地图格子范围 * > 0 以出生地为中心范围内随机移动,超出范围后往出生地移动。 * = 0 不限制范围的四处随机移动。 * < 0 不巡逻。 ``lua 巡逻范围 = 6, ` @tab 路径移动 * 配置为table时,表明按指定格子路径循环移动。 { {格子x,格子y,停留时间},{格子x,格子y,停留时间},... } | 配置 | 说明 | | --- | --- | | 格子x | 目标格子 | | 格子y | 目标格子 | | 停留时间 | 单位：毫秒 | `lua local 角色组 = 引擎.地图.创建角色("半魔人",40,72,"敌方",0,1); 角色组[1].巡逻范围 = {{40,72,5000},{49,81,5000},{56,75,5000}} 角色组[1].移动间隔 = 0 ``
自动隐藏
- 主动攻击型的角色如果
视野范围内没有敌方时,可以设置自动消失。如：资源库中的食人花 - 填写一个动作名,角色隐藏和出现时会播放这个动作过渡。"动作名,反向播放" 动作名后面,配置
1时表示这个动作隐藏时反向播放。
自动隐藏 = "出生,1",
出生效果
角色在地图上出现时的效果。三种效果可选：0,1,2
| 配置 | 说明 | |
| 0 | 无效果 | |
| 1 | 渐隐渐入 | |
| 2 | 空中落下 |
死亡效果
角色的死亡效果。四种效果可选：0,1,2,3
| 配置 | 说明 | |
| 0 | 渐隐消失 | |
| 1 | 直接消失 | |
| 2 | 爆炸消失 | |
| 3 | 溶解消失 |
自动反击
设定角色被攻击后的反击逻辑。四种效果可选：0,1,2,3
| 配置 | 说明 | |
| -1 | 不自动反击 | |
| 0 | 目标自动变更为距离更近的角色 | |
| 1 | 目标始终固定为第一次的造成伤害角色 | |
| 2 | 目标变更为最后一次造成伤害的角色 | |
| 3 | 目标变更为仇恨值更大的角色 |
血条效果
角色是否显示自带的血条效果，支持多个血条效果同时显示。
| 名称 | 类型 | 说明 | |
皮肤 | 文本 | 皮肤标识，可参考 App.lua 中的通用血条皮肤编写自己的血条皮肤 | |
显示偏移 | 整数 | 相对与角色脚底坐标的Y轴偏移 | |
血条颜色 | RGBA | ||
过渡色 | RGBA | 血量减少时产生过渡效果 | |
血条显示 | 整数 | -1 不显示 0 焦点显示 1 持续显示 2 受伤显示 3 非0时显示 | |
血量偏移 | 整数 | 相对血条的Y轴偏移 | |
血量模式 | 整数 | 0 实际 1 百分比 | |
血量显示 | 整数 | -1 不显示 0 焦点显示 1 持续显示 2 受伤显示 3 非0时显示 | |
属性绑定 | {最小值,最大值} | 支持基础,扩展属性名绑定，默认值：{"hp","maxhp"} , 其他支持：施法进度 |
血条效果 = {
{
皮肤 = "通用血条",
显示偏移 = -110,
血条颜色 = RGBA(0,222,0,255),
血条显示 = 1,
血量显示 = 1,
属性绑定= {"hp","maxhp"}
},
{
皮肤 = "通用血条",
显示偏移 = -116,
血条颜色 = RGBA(0,100,222,255),
血条显示 = 1,
血量显示 = -1,
属性绑定= {"mp","maxmp"}
},
},
掉血效果
角色受伤时弹出一个艺术字效果。
| 名称 | 类型 | 说明 | |
艺术字 | 文本 | 资源标识 | |
字体颜色 | RGBA | ||
字体间距 | 整数 | ||
缩放 | 小数/table{基础值,放大值} | 默认缩放倍数 默认：1.0 ,设置成table时,会影响动态缩放效果。例：{0.75,1} | |
平滑 | 逻辑 | 缩放时是否启用平滑效果 默认：false | |
动画效果 | 整数 | 0-4 内置5种效果 | |
暴击颜色 | RGBA | ||
暴击缩放 | 小数/table{基础值,放大值} | 默认：1.0 ,设置成table时,会影响动态缩放效果。例：{0.85,1.8} | |
显示偏移 | 整数 | 相对于角色中心的Y轴偏移 |
名称效果
让角色显示一个名称。
| 名称 | 类型 | 说明 | |
颜色 | RGBA | ||
显示偏移 | 整数 | 相对于角色中心的Y轴偏移 | |
名称显示 | 整数 | 0 焦点显示 1 持续显示 |
光影效果
让角色增加一个光影效果。
| 名称 | 类型 | 说明 | |
锚点x | 小数 | 光源效果锚点x | |
锚点y | 小数 | 光源效果锚点y | |
水平缩放 | 小数 | 光影的水平缩放倍数 | |
垂直缩放 | 小数 | 光影的垂直缩放倍数 | |
颜色 | RGBA | 光影的色调 |
光影效果 = {锚点x=0.5,锚点y=0.5,水平缩放=2.0,垂直缩放=2.0,颜色=RGBA(255, 220, 180,255)},
装备
- 为角色增加一些初始装备，增强角色属性，还可以关联
装备格子控件，格子道具发生变化时角色属性同步变化， - 位置数量和位置名称都没有限制，可以随意填写。
| 名称 | 类型 | 说明 | |
名称 | 文本 | 道具的名称 | |
显示外观 | 逻辑 | 如果道具有外观，会替换角色的纸娃娃 | |
格子 | 文本 | 格子控件的url 写法："窗口名称/控件名称" | |
附加 | table | 默认：{} 会传递到道具的创建事件中 |
装备 = {
武器 = {名称="八荒刀",显示外观=true,格子="角色窗口/主角武器"},
衣服 = {名称="",显示外观=true,格子="角色窗口/主角衣服"},
左手镯 = {名称="",显示外观=true,格子="角色窗口/主角手镯1"},
右手镯 = {名称="",显示外观=true,格子="角色窗口/主角手镯2"},
戒指1 = {名称="",显示外观=true,格子="角色窗口/主角戒指1"},
戒指2 = {名称="",显示外观=true,格子="角色窗口/主角戒指2"},
稻草人的配饰 = {名称="木剑",显示外观=false},
青铜兽的牙齿 = {名称="铜戒指",显示外观=false},
...
...
},
掉落
- 角色死亡后是否触发道具掉落。格式为 {"道具名称 掉落数量/最大几率","道具名称 掉落数量/最大几率",...}
- 物品掉落前会触发道具事件创建，可以在这里实现随机属性。
掉落 = {"八荒刀 1/2","粗布衣 1/2","金创药小 1/2","金币100 1/2"}
掉落几率
- 为
掉落表中的所有道具进行统一的掉落增幅。默认值：100 - 假设
木剑 1/10掉落几率 = 200,此时 木剑的实际效果是1/5 - 假设
木剑 1/10掉落几率 = 50,此时 木剑的实际效果是1/20 - 假设
木剑 1/10掉落几率 = 0,此时 木剑 不会掉落
技能表
- 角色自带的技能，你可以填完整的技能对象配置，也可以使用已经加入系统的公共技能组件。版本号 > 0.1
- 使用公共技能组件，可以设置不同的属性
自动释放优先级间隔hpmp
技能表 = {
{
名称 = "火球术",
自动释放 = true,
优先级 = 1,
间隔 = 2000,
mp = 5,
},
{
类型 = "技能",
名称 = "普通攻击",
显示名 = "普通攻击",
图标 = "",
攻击距离 = 1,
动作 = "攻击",
目标阵营 = "敌方",
目标位置 = 0,
伤害延迟 = 500,
伤害公式 = "a.攻击 ^ 2 / ( a.攻击 + b.防御 ) * (0.8 + math.random()*0.2)", -- a 我方 b 敌方
受伤效果 = {几率=100,动作=true,音效=true},
},
},
系统事件
🔹 创建
角色在地图中创建后触发
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 |
示例
系统事件 = {
创建 = function (角色对象)
调试输出(角色对象.名称)
end
}
🔹 出生
角色出生,重生时触发
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 重生次数 | 整数 |
示例
系统事件 = {
出生 = function (角色对象,重生次数)
调试输出(角色对象.名称,重生次数)
end
}
🔹 移动
- 角色对象
移动时触发。 信号：0角色准备移动 返回false可以拦截移动信号：1角色开始移动 返回false可以拦截移动信号：2角色移动完成 返回false可以拦截移动并返回上个位置。
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| x | 整数 | 信号：0,1时，x,y是将要移动到的目标格子 |
| y | 整数 | 信号：2时，x,y是已经抵达的地图格子 |
| 信号 | 整数 | 移动信号 0：准备移动 1：开始移动 2：移动完成 |
| 方向 | 整数 | 移动方向 |
| 步距 | 整数 | 移动的距离 |
示例
系统事件 = {
移动 = function (角色对象,x,y,信号,方向,步距)
-- 信号 0 准备移动 1 开始移动 2 完成移动
local 地图对象 = 角色对象.地图
if (地图对象.名称 == "地图1") then
if (信号 == 2 and x == 7 and y == 5) then
--角色对象.瞬移(2,5,2,"地图2")
return false -- 拦截 回到上一个格子
end
end
end,
}
🔹 受伤
- 角色对象
受伤时触发。
ver-29 可通过战斗血液效果启用敌方实际扣血后的定向喷溅。只作用于满足过滤条件的敌方角色，不修改本事件参数或返回值；躲避、治疗、拦截及无来源/状态伤害不生成血滴。使用 角色对象.附加.喷血=false 可排除石像等对象。原伤害链中的致死命中同时尝试一处主要地面血迹，不额外调用死亡事件；直接删除/设置死亡不触发。完整条件、资源和验证范围见该模块文档。
- 返回数值可以修改掉血结果。
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 掉血值 | 整数 | |
| 剩余血量 | 整数 | |
| 总血量 | 整数 | |
| 伤害来源 | 角色对象 | |
| 伤害类型 | 文本 | 默认 躲避 暴击 其他：通过受伤接口传递进来的类型 |
| 伤害组件 | 技能对象/状态对象/nil | 哪种组件产生的伤害 |
| 命中效果名称 | 文本 | 命中效果名称 |
示例
系统事件 = {
受伤 = function (角色对象,掉血值,剩余血量,总血量,伤害来源,伤害类型,伤害组件,命中效果名称)
if (掉血值 <= 0) then -- 无伤害 躲避
引擎.弹出文字(角色对象.x,角色对象.y-角色对象.角色高度 * 0.5,"躲" ,"艺术字2",角色对象.地图,{动效=3});
return
end
if (伤害类型 == "暴击") then
引擎.弹出文字(角色对象.x,角色对象.y-角色对象.角色高度 * 0.5,"暴" ,"艺术字2",角色对象.地图,{动效=3});
end
if (伤害组件 and 伤害组件.类型 == "技能" and 伤害类型 ~= "连伤") then
if (伤害组件.名称 == "基本剑术") then
local 半血 = math.ceil(掉血值 * 0.5)
角色对象.受伤(半血,伤害来源,"连伤", {掉血效果 = 3},伤害组件)
角色对象.受伤(半血,伤害来源,"连伤", {掉血效果 = 3},伤害组件)
end
end
end,
}
🔹 死亡
- 角色死亡后触发
- ver-29 的血液视觉由实际伤害链触发，不在此事件重复喷血；原死亡效果和回调语义保持，参见战斗血液效果。
- 允许通过返回值动态更新死亡效果。例：
return {死亡效果 = 2,重生间隔 = 1000,尸体时间 = 0}
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 伤害来源 | 角色对象 | 只有被角色对象杀死才会有伤害来源 |
示例
系统事件 = {
死亡 = function(角色对象,伤害来源)
调试输出("死亡了", 角色对象.名称)
end,
}
🔹 倒地
- 如果角色
死亡时有死亡动作,那么倒地后触发。
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| x | 整数 | 角色倒地后图片中心x |
| y | 整数 | 角色倒地后图片中心y |
示例
系统事件 = {
倒地 = function(角色对象,x,y)
角色对象.添加节点(
{
名称 = "拾取特效",
类型 = "动画",
x = x,
y = y,
动画 = "地面闪光_动画",
动作 = "地面光效1",
}
)
end,
}
🔹 点击
角色被鼠标点击时触发,返回true可以拦截角色移动事件。
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 键值 | 整数 | 0：左键 1：右键 2：中键。 |
| 功能键 | 整数 | 1：Ctrl 2：Shift 3：Alt 是否处于按下状态 |
示例
系统事件 = {
点击 = function(角色对象,键值,功能键)
if (键值 == 1) then -- 右键点击
return
end
引擎.对话(0,0,"",
[[
你要干什么？
#Y#@传送@去下个地图@
#Y#@exit@没事@
]])
return true -- 拦截移动
end,
传送 = function ()
if (引擎.地图.名称 == "暗殿密室2") then
引擎.地图.主角.瞬移(22,19,0,"泡点图")
else
引擎.地图.主角.瞬移(24,26,0,"暗殿密室2")
end
return true
end,
}
🔹 升级
角色等级发生变化时触发
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 等级 | 整数 |
示例
系统事件 = {
升级 = function(角色对象,等级)
引擎.屏幕提示("#G升到" .. 等级 .. "级了!")
end
}
🔹 目标变化
角色的攻击目标发生变化时候触发
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 目标角色 | 角色对象 |
示例
系统事件 = {
目标变化 = function (角色对象,目标角色)
if (目标角色 == nil) then
L系统.选中目标(nil)
else
L系统.选中目标(目标角色)
end
end
}
🔹 获得经验
从其他角色身上获得经验后触发，可以返回整数值修改
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 经验值 | 整数 |
示例
系统事件 = {
获得经验 = function(角色对象,经验值)
引擎.屏幕提示("#G经验 +" .. 经验值)
-- return 经验值 * 2 -- 双倍经验
end
}
🔹 移动完成
角色调用接口 移动到 抵达目标点触发
| 回调参数 | 类型 | 说明描述 |
| 角色对象 | 角色对象 | |
| 格子x | 整数 | |
| 格子y | 整数 |
示例
系统事件 = {
移动完成 = function (角色对象,x,y)
调试输出(角色对象.名称,x,y)
end
}