角色

提示

主角对象，可以通过 引擎.地图.主角快捷访问。

属性

x

类型：整数
读写：读写
说明：地图坐标x 改写只会影响显示效果,逻辑位置并没有发生变化

y

类型：整数
读写：读写
说明：地图坐标y 改写只会影响显示效果,逻辑位置并没有发生变化

z

类型：整数
读写：读写
说明：锚点Y的显示偏移

提示

z值不会改变显示位置,只会影响在地图上的排序层次。
z值越大越先显示。例如：引擎.地图.主角.z = 10000

技能冷却

类型：小数
读写：读写
说明：用于控制角色全部技能的冷却速度倍数,默认值：1.0,越小越快。

光影效果

类型：table
读写：读写
说明：动态改变角色光影效果。

系统事件 = {

	点击 = function(按钮对象)



		引擎.地图.环境色 = RGBA(80,80,80,255)



		if (引擎.地图.主角.光影效果 == nil) then

			引擎.地图.主角.光影效果 = {锚点x=0.5,锚点y=0.5,水平缩放=1.5,垂直缩放=1.5,颜色=RGBA(255, 255, 255,255)} -- 整理改变

		else 

			引擎.地图.主角.光影效果.颜色 = RGBA(255,255,0,255)  -- 单独属性改变

			引擎.地图.主角.光影效果.水平缩放 = 引擎.地图.主角.光影效果.水平缩放 * 1.1

			引擎.地图.主角.光影效果.垂直缩放 = 引擎.地图.主角.光影效果.垂直缩放 * 1.1

		end	

		

  	end,

}

锁定目标

类型：逻辑
读写：读写
说明：是否锁定目标，效果为右键移动后不取消正在攻击的目标。

自动拾取距离

类型：整数
读写：读写
说明：当前道具允许自动拾取时,会在道具自动拾取的基础距离上增加拾取距离。单位：格子默认为0。

尸体可见

类型：逻辑
读写：读写
说明：如果角色已经死亡,当前尸体是否可见,设置false表示立即消失。

图标名

类型：文本
读写：读写
说明：配合地图框控件使用,可以动态改变小地图显示的图标,填写角色图标中的图标名。

优先级

类型：整数
读写：读写
说明：敌方主动攻击时,会被优先作为目标。默认值：0,值越大优先级越高。

附加

类型：table
读写：读写
说明：自定义变量集合。

引擎.地图.主角.附加.死亡次数 = 1

引擎.地图.主角.附加.暴击几率 = 10

ver-14 天气扩展读取主角的附加.天气脚印标记：设为 false 禁止产生新雪地脚印，nil/true 恢复默认允许，已有脚印按原寿命消散。仅在当前地图下雪且启用脚印时生效，可由项目用于飞行/悬浮角色，不自动识别动作。完整条件见地图天气。该自定义标记不修改角色属性运算或原生移动规则。ver-17 普通地面等待积雪网格覆盖达到 0.2 后留印，雪地=true 跳过覆盖判定；脚印仍为 22 世界像素压痕贴片，不是实时挖除积雪高度。清除或切换天气一并释放雪面和脚印。新区域及视距换级继承本天气的地图积雪进度，因此普通地面不再因镜头换区重新等待留印阈值。角色仍在地面雪之上绘制，但随后受到前景雪幕/雾/可选氛围层影响；这不是角色或宝箱顶面的积雪蒙版，也不改变角色原型。

更新记录

日期	版本	简易记录
2026-09-13	ver-14	记录天气对主角附加.天气脚印的读取语义；真实主角关闭/恢复留印测试通过，完整项目观感待验收。
2026-09-13	ver-15	雪地脚印改用压痕和薄雪亮边，默认显示框 22 世界像素、深浅 0.85；附加.天气脚印的开关语义与主角行走规则不变，详见地图天气。
2026-09-13	ver-16	主角脚印依据连续积雪覆盖阈值生成，保留雪地标记和飞行排除，不改角色原型。
2026-09-13	ver-17	主角留印阈值继承地图积雪进度，补充前景雪幕/氛围与物体积雪的区别；角色原型和脚印开关语义不变。

属性表

类型：table
读写：读写
说明：当前角色的所有属性，包括附加。方便给其他组件配置数据源时使用。

名称	类型	说明
系统属性...	整数	系统的默认属性
扩展属性...	整数	自定义的扩展属性
x	数值	角色的地图坐标x
y	数值	角色的地图坐标y
格子x	整数	角色的地图格子x
格子y	整数	角色的地图格子y
名称	文本
显示名	文本
攻击间隔	整数	加上所有道具属性后角色总的攻击间隔单位：毫秒
攻击进度	整数	由`攻击间隔`产生的冷却时间进度 100-0 `0:冷却结束`,修改可改变进度例：`角色对象.属性表.攻击进度 = 0`
施法进度	整数	> `0` 表示施法正在进行,`100`为完成,修改可打断施法例：`角色对象.属性表.施法进度 = 0`
地图	地图对象	当前所在的地图对象
附加	通用	自定义的数据

调试输出(引擎.地图.主角.属性表.攻击)

调试输出(引擎.地图.主角.属性表.附加)

掉落表

类型：table {{道具名称,掉落数量,最大几率},...}
读写：读写
说明：读写角色配置的掉落表,!注意如果修改,全部相同名称角色的掉落配置都会变。

掉落几率

类型：整数
读写：读写
说明：可以随时修改角色的掉落几率。

目标

类型：角色对象
读写：只读
说明：获得当前角色的攻击目标。

local 当前目标 = 引擎.地图.主角.目标

if (当前目标) then

  调试输出(当前目标.名称,当前目标.hp,当前目标.mp)

end

地图

类型：角色对象
读写：只读
说明：获得当前角色所在的地图对象。

装备

类型：table
说明：你可以在脚本中使用 角色.装备.位置名称 快速读写角色当前身上的装备的道具对象。

if (引擎.地图.主角.装备.武器) then

  引擎.地图.主角.装备.武器.攻击 = 引擎.地图.主角.装备.武器.攻击 + 50

--	引擎.地图.主角.装备.武器.掉落()

end

技能

类型：table
说明：你可以在脚本中使用 角色.技能.技能名称 快速读写当前角色存在的技能对象。

if (引擎.地图.主角.技能.雷电术 == nil) then

  引擎.信息框("你还没学习 #R雷电术")

  return

end



if (引擎.地图.主角.技能.火球术) then

  引擎.地图.主角.技能.火球术.mp = 6

end

宠物信息

类型：table
读写：读写
说明：当前角色宠物相关的信息。

名称	类型	读写	说明
宠物	角色对象 {}	只读	宠物对象数组
主人	角色对象	只读	无主人返回 nil
指令	文本	读写	对当前拥有的所有宠物下达的指令可选： `停留` `跟随` `攻击`
同步死亡	逻辑	读写	主人死亡时是否同步死亡默认：true
协助优先	逻辑	读写	是否优先攻击主人目标默认：true
跟随距离	整数	读写	离主角最远格子距离默认：1
瞬移距离	整数	读写	超出多少格子后瞬移到主人身边默认：20

仇恨信息

类型：table
读写：读写
说明：当前角色仇恨相关的信息。

名称	类型	读写	说明
角色	角色对象	只读	产生伤害的目标角色
仇恨	整数	只读	累计的仇恨值
伤害	整数	只读	累计的伤害值

方法

添加技能

说明：给角色添加技能。

参数名称

值的类型

是否必填

说明描述

技能名称

整数

true

属性表

table

false

成员	类型	必填	说明
显示名	文本	false
气泡提示	文本	false
攻击距离	整数	false
间隔	整数	false	详见技能配置项
hp	整数	false
mp	整数	false
优先级	整数	false
自动释放	逻辑	false
附加	table	false

示例

系统事件 = {

    创建 = function (角色对象)

        角色对象.添加技能("火球术",{mp=1})

    end

}

提示

属性表会替换掉原始技能组件中的属性。

删除技能

说明：删除已经学习的技能。

参数名称	值的类型	是否必填	说明描述
技能名称	文本	true

示例

调试输出(引擎.地图.主角.删除技能("火球术"))

返回值	值的类型	说明描述
是否成功	逻辑

发动技能

说明：让角色发动一次技能。

参数名称	值的类型	是否必填	说明描述
技能名称	文本	true
目标对象	角色对象/{格子x=?,格子y=?}	false	是否指定目标或是指定格子
切换目标	逻辑	false	是否将当前攻击目标,切换为指定的目标
移动施法	逻辑	false	移动施法会立即发动技能,且不会播放技能动作
攻击速度	整数	false	只在本次施法生效,攻速倍数。默认：1.0

示例

local 治疗术 = 引擎.地图.主角.技能.治疗术

if (治疗术 and 治疗术.进度 == 100) then

  引擎.地图.主角.发动技能("治疗术")

end



------------------------------------------------------

local 位置组 = {

  { 0, -1},{ 1, -1 },

  { 1, 0 },{ 1, 1 },

  { 0, 1 },{ -1, 1 },

  { -1, 0 },{ -1, -1 },

};



local 主角对象 = 引擎.地图.主角

local x,y

for i=1,3 do

  for n=1,#位置组 do

    x = 主角对象.格子x + 位置组[n][1] * i

    y = 主角对象.格子y + 位置组[n][2] * i

    主角对象.发动技能("雷电术",{格子x=x,格子y=y})

  end

end

提示

* 技能必须已经学习。

重置目标

说明：清除或者改变当前角色的目标。

参数名称	值的类型	是否必填	说明描述
目标对象	角色对象/nil	false	nil表示清除当前的攻击目标

示例

引擎.地图.主角.重置目标()

添加状态

说明：给角色添加状态。

参数名称	值的类型	是否必填	说明描述
状态名称	文本/table	true	支持直接填写状态配置项生成新状态
来源角色	角色对象	false	如果不填默认为自身
属性表	table	false
网络同步	逻辑	false	是否在网络地图中同步,默认：true

成员	类型	必填	说明
显示名	文本	false
气泡提示	文本	false
持续时间	整数	false
触发间隔	整数	false
唯一	逻辑	false	如果目标已经存在这个状态则不会添加
dt	整数	false	触发时钟起始时间，默认：0
拖尾	整数	false	同 `状态配置项`
变身	table	false	同 `状态配置项`
hp	整数	false
hp_百分比	整数	false
自定义属性	整数	false
自定义属性_百分比	整数	false
...	整数	false

示例

系统事件 = {

    创建 = function (角色对象)

        角色对象.添加状态("持续恢复",角色对象,{hp=5})





        角色对象.添加状态(

          {

            类型 = "状态",

            名称 = "血影吸血",

            几率 = 100,

            持续时间 = 0,

            触发间隔 = 0,	

          },角色对象,{hp_百分比=30}

        )



    end

}

返回值	值的类型	说明描述
状态	状态对象/nil	添加失败返回nil

提示

属性表会替换掉原始状态组件中的属性。

检测状态

说明：检测状态是否存在。

参数名称	值的类型	是否必填	说明描述
状态名称	文本	true

示例

调试输出(引擎.地图.主角.检测状态("治疗术"))

返回值	值的类型	说明描述
是否存在	逻辑

取出状态

说明：取出状态对象。

参数名称	值的类型	是否必填	说明描述
状态名称	文本/nil	false	不填表示取出所有状态,返回状态数组。

示例

local 状态对象 = 引擎.地图.主角.取出状态("持续恢复")

if (状态对象) then

	调试输出(状态对象.名称,状态对象.持续时间,状态对象.触发间隔)

end



local 状态列表 = 引擎.地图.主角.取出状态() -- 取出全部

if (#状态列表 > 0) then

	for n=1,#状态列表 do

		调试输出(状态列表[n].名称,状态列表[n].持续时间,状态列表[n].触发间隔)

	end

end

返回值	值的类型	说明描述
状态/状态数组/nil	状态对象/table {}	指定状态名取出时,若状态不存在返回nil

删除状态

说明：删除指定/全部状态。

参数名称	值的类型	是否必填	说明描述
状态名称	文本/nil	false	nil：删除全部状态

示例

引擎.地图.主角.删除状态("治疗术")



引擎.地图.主角.删除状态() -- 一次清空所有状态

添加宠物

说明：为当前角色添加一个宠物角色。

参数名称	值的类型	是否必填	说明描述
名称	文本/角色对象	true	文本型时填角色组件的名称
最大数量	整数	false	相同名称的宠物携带最大数量

示例

local 宠物对象 = 角色对象.添加宠物("稻草人",6)  -- 最多带6个稻草人 超出会删除最先添加的稻草人

if (宠物对象) then

    宠物对象.宠物信息.同步死亡 = false

    宠物对象.宠物信息.协助优先 = true

end

返回值	值的类型	说明描述
宠物对象	角色对象	成功返回角色对象

提示

1. 主角瞬移到新地图时,宠物会跟随瞬移到新地图。 2. 直接将目标角色变成宠物时,目标角色阵营自动变更,无法重生。

更新外观

说明：重置角色的默认外观配置。

参数名称	值的类型	是否必填	说明描述
配置项	table	true

示例

引擎.地图.主角.更新外观({{位置="衣服",动画="角色动画_魔力长袍",x=0,y=-4}})

更新内观

说明：重置角色的默认内观配置。

参数名称	值的类型	是否必填	说明描述
配置项	table	true

示例

引擎.地图.主角.更新内观({{位置="衣服",图片="_道具内观|人物_女"}})

移动到

说明：移动到指定地图格子或是取出路径。

参数名称	值的类型	是否必填	说明描述
格子x	整数	true
格子y	整数	true
范围	整数	false	距离目标格子多少范围内算移动完成
立即移动	逻辑	false	默认:true ,只取路径不移动可以填写false

示例

local 角色组 = 引擎.地图.创建角色("稻草人",50,50,"友方",0,3); 

for n=1,#角色组 do

  角色组[n].移动到(54,40,1)

end

返回值	值的类型	说明描述
结果	逻辑/table{}	无有效路径返回false,否则返回格子路径数组

提示

抵达目标点会触发移动完成

边走边打到

说明：边走边打到指定地图格子。

参数名称	值的类型	是否必填	说明描述
格子x	整数	true
格子y	整数	true
范围	整数	false	距离目标格子多少范围内算移动完成

示例

local 角色组 = 引擎.地图.创建角色("稻草人",50,50,"友方",0,3,{主动攻击=true}); 

for n=1,#角色组 do

  角色组[n].边走边打到(25,25,1)

end

返回值	值的类型	说明描述
结果	逻辑	无有效路径返回false

提示

抵达目标点会触发移动完成

瞬移

说明：瞬移主角到指定地图的指定坐标，不填地图名时表示在当前地图瞬移。

参数名称	值的类型	是否必填	说明描述
格子x	整数	true
格子y	整数	true
角色面向	整数	false
地图名称	文本	false
清空地图	逻辑	false	是否清空地图
保留角色组	角色对象 {}	false	若清空地图这些角色会被保留

示例

if (引擎.地图.名称 == "暗殿密室2") then

    引擎.地图.主角.瞬移(22,19,0,"泡点图")

else

    引擎.地图.主角.瞬移(24,18,0,"暗殿密室2")

end

受伤

说明：让角色受伤。

参数名称

值的类型

是否必填

说明描述

掉血值

整数

true

伤害来源

角色对象/nil

false

伤害类型

文本

false

会传递到角色[受伤]事件中

伤害效果

table

false

成员	类型	必填	说明
受伤动作	逻辑	false	是否播放受伤动作
受伤闪烁	RGBA	false	闪烁色
掉血效果	整数	false	-1：不显示掉血数字其他：0-4
掉血颜色	RGBA	false	默认：RGBA(255,255,255,255)
掉血缩放	小数	false	缩放倍数默认：1.0

附加

table

false

会作为[伤害组件]参数，传递到角色[受伤]事件中

示例

角色对象.受伤(math.random(99),角色对象.地图.主角,"脚本", {掉血效果 = 3})

注意事项

1、此接口产生伤害100%命中，且不会触发暴击。
2、未指定伤害来源不会触发反击和获得经验相关逻辑。

重生

说明：角色死亡后才可以使用。如果不指定位置和范围，默认在原地重生。

参数名称	值的类型	是否必填	说明描述
格子x	整数	false	重生格子x
格子y	整数	false	重生格子x
范围	整数	false	半径范围

示例

引擎.地图.主角.重生()

执行

说明：让角色按顺序执行动作队列。

参数名称值的类型是否必填说明描述

动作队列

table/nil

true

行为配置项说明

移动

名称	类型	说明
方向	整数
面向	整数	可以不填
距离	整数

朝一个方向移动指定格子距离

方向

名称	类型	说明
方向	整数	顺时针 0-7

改变方向

等待

名称	类型	说明
时间	整数	毫秒

等待一段时间

动作

名称	类型	说明
名称	文本	动作名称
方向	整数	顺时针 0-7
倒序	逻辑	是否反向播放

播放指定动作

CALL

名称	类型	说明
Call	function(dt,tbl)	dt：当前帧时间，tbl：附加
附加	通用	填写会传递到Call中

执行自定义函数,return true会结束当前动作

示例

local 主角 = 引擎.地图.主角



local 气泡对话 = function(dt,tbl)

  if (tbl.进度 == 0) then

    引擎.屏幕提示(tbl.内容,{y=-90,动画效果=0,停留时间=2000,清空分组=true},主角) 

    tbl.进度 = 1

  end

  tbl.time = tbl.time + dt

  if(tbl.time >= 1000) then

    return true

  end

end



主角.执行(

  {

    {"动作",{名称 = "攻击",方向= 2,倒序 = false}},

    {"等待",{时间 = 200}},

    {"动作",{名称 = "攻击",方向 = 6}},

    {"等待",{时间 = 200}},

    {"动作",{名称 = "死亡",方向 = 0}},

    {"方向",{方向 = 4}},

    {"移动",{方向 = 2,距离 = 1}},

    {"移动",{方向 = 0,距离 = 1}},

    {"移动",{方向 = 1,距离 = 2}},

    {"等待",{时间 = 200}},

    {"方向",{方向 = 2}},

    {"等待",{时间 = 500}},

    {"方向",{方向 = 6}},

    {"等待",{时间 = 500}},

    {"方向",{方向 = 4}},

    {"等待",{时间 = 500}},

    {"CALL",{Call=气泡对话,附加={进度=0,内容="#W小喵咪不见了！",time=0}}},

    {"移动",{方向 = 6,距离 = 2}},

    {"移动",{方向 = 0,距离 = 4}},

    {"CALL",{Call=气泡对话,附加={进度=0,内容="#W难道是跑出去了？",time=0}}},

  }

)

返回值	值的类型	说明描述
动作数量	整数	剩余队列动作数量

注意事项

1、系统优先执行角色动作队列。
2、执行动作中无法控制角色。

销毁

销毁
说明：销毁当前角色,如果有宠物宠物也会一同被销毁。
示例 `角色对象.销毁()`

注册帧事件

说明：注册一个事件，让角色动画播放到指定帧时触发回调。

参数名称	值的类型	是否必填	说明描述
动作名称	文本	true	角色的动作名称，无需填写方向。例："移动"、"攻击"等
帧号	整数	true	动作的帧序号。每个动作帧从1开始计数。
回调事件	function/nil	false	`function(角色对象,附加)` nil表示删除帧事件。
附加	通用	false	回调事件的附加参数，会作为参数传递到回调中。

示例

角色对象.注册帧事件("移动",1,function(角色对象,tbl) -- 动作 第几帧



    调试输出(tbl)



end,{信息="播放了移动动作"})

添加节点

说明：在角色对象上添加一个节点，成功返回节点对象。

参数名称	值的类型	是否必填	说明描述
组件配置	table	true	`文本,动画...等基石组件`
图层	整数	false	`0：身后1：身前` 默认：1

示例



角色对象.添加节点(

    {

        名称 = "称号",

        类型 = "精灵",

        x = 0,

        y = 0,

        图片 = "传送门_图标",

        锚点x = 0.5,

        锚点y = 0.5,

    }

)

返回值	值的类型	说明描述
组件对象	对象对象 / nil	失败返回 nil

取出节点

说明：从节点名称取出节点对象。

参数名称	值的类型	是否必填	说明描述
组件名称	文本	false

示例

local 角色称号 = 角色对象.取出节点("称号")

角色称号.图片 = "初级技师"

返回值	值的类型	说明描述
组件对象	对象 / nil	取出失败返回 nil

清除节点

说明：清除节点。销毁模式，清除后不可再次调用！

参数名称	值的类型	是否必填	说明描述
组件名称	文本/组件对象	false

示例

角色对象.清除节点("称号")

返回值	值的类型	说明描述
是否成功	逻辑

加入事件

说明：往角色对象中加入一个自定义事件。

参数名称	值的类型	是否必填	说明描述
事件名称	文本	true	触发的事件名称
附加信息	table	false	事件触发时可以取出
延迟时间	数值	false	延迟执行
自动销毁	逻辑	false	是否只执行一次，默认：true

示例

系统事件 = {

  创建 = function(角色对象)

      角色对象.加入事件("时钟事件",{},1000,false)

  end,



  时钟事件 = function (角色对象,tbl,dt,time)

      调试输出(tbl,dt,time)

  end,

}

删除事件

说明：删除指定自定义事件。

参数名称	值的类型	是否必填	说明描述
事件名称	文本	true

示例

系统事件 = {

  时钟事件 = function (角色对象,tbl,dt,time)

    角色对象.删除事件("时钟事件")

  end,

}