ssRender Lua API

引言

本文档旨在介绍和解释一系列 Lua 接口函数/方法的使用方法和功能。这些接口为 Lua 开发者提供了一组强大的工具，以便在 Lua 环境中进行各种操作和计算。

Lua API 概览

以下是本文档涵盖的主要 API 接口列表：

属性

ssr.set_property
ssr.set_property_table
ssr.get_property 
ssr.get_property_table 
ssr.register_property_change

计时器

ssr.timer_create
ssr.timer_start
ssr.timer_stop
ssr.timer_destory

动画

ssr.animation_create
ssr.animation_add_step
ssr.animation_destory
ssr.animation_trigger

多语言

ssr.language_set_type
ssr.language_get_type

加载多工程

ssr.container_set_file

移动节点层级

ssr.move_page_child
ssr.move_child

事件

ssr.event_binding
ssr.event_regist
ssr.event_send

Box2D物理引擎相关

ssr.setBodyPos
ssr.createWorld
ssr.createBody
ssr.createJoint
ssr.setBodyAwake
ssr.DestroyBody
ssr.DestroyJoint
ssr.createStaticBody
ssr.createBayingaill
ssr.setBodyApplyForce
ssr.setBodyApplyImpulse
ssr.connectJoint
ssr.registContactInfo
ssr.setBodyParam

获取路径

ssr.get_root_path

退出程序

ssr.exit

Lua API 详解

ssr.set_property(key,value)

功能描述：

设置节点的属性值

参数：

key：字符串类型，要更改的属性变量名
value：字符串类型，要更改的属性变量设值

返回值：

NONE

示例：

function lua_fun()
    --Item节点的X属性："Layer/Item/X"
    ssr.set_property("Layer/Item/X","10")
end

ssr.set_property_table(table)

功能描述：

设置多个节点的属性值

参数：

table：table是一个表，其中包含要更改的属性变量名作为键，更改的属性变量值作为键值

返回值：

NONE

示例：

function lua_fun()
    local data_table = {}
    data_table["Layer/Item/X"] = "10" --Item节点的X属性设置为10
    data_table["Layer/Item/Y"] = "10" --Item节点的Y属性设置为10
    ssr.set_property_table(data_table)
end

ssr.get_property(key)

功能描述

获取节点的属性值

参数：

key:字符串类型，要获取的属性变量名

返回值：

string类型，返回一个要获取的属性变量值

示例：

function lua_fun()
    --Item节点的X属性："Layer/Item/X"
    local strVal = ssr.get_property("Layer/Item/X")
end

ssr.get_property_table(table)

功能描述

获取多个节点的属性值

参数：

table:table是一个表，其中包含要获取的属性变量名

返回值：

table类型，返回一个表包含要获取的变量值

示例：

function lua_fun()
    --Item节点的X属性："Layer/Item/X"
    --Item节点的Y属性："Layer/Item/Y"
    local table = {"Layer/Item/X", "Layer/Item/Y"}
    local retTbale = ssr.get_property_table(table)
    local retval = retTbale["Layer/Item/X"]
end

ssr.register_property_change(table,cb_function)

功能描述

获取注册的属性值变化

参数：

table:返回一个表，其中包含要获取的属性变量名
cb_function:注册一个回调函数，函数参数包含变化的属性值

返回值：

table类型，返回一个表,包含变化的属性变量值

示例：

function onPropertyChange(table)
    for k, v in pairs(table) do
        ssr.luaPrint(k.." "..v)
    end     
end

function lua_fun()
    --Item节点的X属性："Layer/Item/X"
    --Item节点的Y属性："Layer/Item/Y"
    local table = {"Layer/Item/X", "Layer/Item/Y"}
    ssr.register_property_change(table,"onPropertyChange")
end

ssr.timer_create(interval,count,function)

功能描述

创建一个计时器，每隔"interval"时间触发一次，执行function

参数：

interval:计时器触发的时间间隔
count:计时器执行的次数
function：计时器触发时调用的函数

返回值：

int类型，返回一个计时器的标志位

示例：

function cb_function()
    ssr.luaPrint("cb_function")
end

--创建一个计时器,1s执行1次一共执行3次
function lua_fun()
    local timer_id = ssr.timer_craete(1000, 3, cb_function)
    ssr.timer_start(timer_id)
end

ssr.timer_start(timer_id)

功能描述

开始一个计时器

参数：

timer_id:创建计时器时返回的标志位

返回值：

NONE

示例：

function cb_function()
    ssr.luaPrint("cb_function")
end

--创建一个计时器，1s执行1次一共执行5次
function lua_fun()
    local timer_id = ssr.timer_craete(1000, 5, cb_function)

    --用创建计时器时返回的timer_id作为参数开始计时器
    ssr.timer_start(timer_id)
end

ssr.timer_stop(timer_id)

功能描述

停止一个已经运行的计时器，暂停的计时器timer_id可以继续使用

参数：

timer_id:创建计时器时返回的标志位

返回值：

NONE

示例：

local timer_id
function cb_function()
    ssr.luaPrint("cb_function")
end

--创建一个计时器，1s执行1次一共执行5次
function lua_fun()
    timer_id = ssr.timer_craete(1000, 5, cb_function)

    --用创建计时器时返回的timer_id作为参数开始计时器
    ssr.timer_start(timer_id)
end

--暂停一个计时器
function cb_stop_timer()
    ssr.timer_stop(timer_id)
end

ssr.timer_destory(timer_id)

功能描述

销毁一个已经存在的计时器，销毁的计时器timer_id不可继续使用

参数：

timer_id:创建计时器时返回的标志位

返回值：

NONE

示例：

local timer_id
function cb_function()
    ssr.luaPrint("cb_function")
end

--创建一个计时器，1s执行1次一共执行5次
function lua_fun()
    timer_id = ssr.timer_craete(1000, 5, cb_function)

    --用创建计时器时返回的timer_id作为参数开始计时器
    ssr.timer_start(timer_id)
end

--销毁一个计时器
function cb_destory_timer(timer_id)
    ssr.timer_destory(timer_id)
end

ssr.animation_create()

功能描述

创建一个动画，它将返回一个动画ID

参数：

NONE

返回值：

int类型，在以后调用的动画中所使用的ID

示例：

function animation_create()
    lcoal animation_id = ssr.animation_create()
    --定义动画所需的步骤
    local animation_step_table = {}
    animation_step_table["node"] = "Layer0/Item0"
    animation_step_table["propertyType"] = "X"
    animation_step_table["from"] = "0"
    animation_step_table["to"] = "1000"
    animation_step_table["duration"] = "1000"
    animation_step_table["delay"] = "0"
    animation_step_table["easingType"] = "None"
    animation_step_table["cbkFunName"] = ""

    --添加动画所需的步骤
    ssr.animation_add_step(animation_id, animation_step_table)

    --触发动画开始
    ssr.animation_trigger(animation_id)
end

ssr.animation_add_step(animation_id,table)

功能描述

为已创建的动画添加步骤，animation_id是ssr.animation_create()返回的动画id,table定义动画的参数

参数：

animation_id：动画id
table：一个动画的参数，其中包括：
    node:节点的路径
    propertyType:节点的属性名
    from:动画的起始值
    to:动画的结束值
    delay:延时开始动画的时间(msec)
    duration：动画执行的时间(msec)
    easingType:动画执行的缓动曲线
    cbkFunName:动画结束后执行的函数

返回值：

NONE

示例：

function animation_create()
    lcoal animation_id = ssr.animation_create()
    --定义动画所需的步骤
    local animation_step_table = {}
    animation_step_table["node"] = "Layer0/Item0"
    animation_step_table["propertyType"] = "X"
    animation_step_table["from"] = "0"
    animation_step_table["to"] = "1000"
    animation_step_table["duration"] = "1000"
    animation_step_table["delay"] = "0"
    animation_step_table["easingType"] = "None"
    animation_step_table["cbkFunName"] = ""

    --添加动画所需的步骤
    ssr.animation_add_step(animation_id, animation_step_table)

    --触发动画开始
    ssr.animation_trigger(animation_id)
end

ssr.animation_destory(animation_id)

功能描述

销毁一个已经创建的动画

参数：

animation_id：销毁的动画id

返回值：

NONE

示例：

function animation_create()
    lcoal animation_id = ssr.animation_create()
    --定义动画所需的步骤
    local animation_step_table = {}
    local animation_step_table = {}
    animation_step_table["node"] = "Layer0/Item0"
    animation_step_table["propertyType"] = "X"
    animation_step_table["from"] = "0"
    animation_step_table["to"] = "1000"
    animation_step_table["duration"] = "1000"
    animation_step_table["delay"] = "0"
    animation_step_table["easingType"] = "None"
    animation_step_table["cbkFunName"] = ""

    --添加动画所需的步骤
    ssr.animation_add_step(animation_id, animation_step_table)

    --销毁动画
    ssr.animation_destory(animation_id)
end

ssr.animation_trigger(animation_id)

功能描述

触发一个已经创建的动画

参数：

animation_id：动画id

返回值：

NONE

示例：

function animation_create()
    lcoal animation_id = ssr.animation_create()
    --定义动画所需的步骤
    local animation_step_table = 
    {
        {node = "Layer0/Item0", propertyType = "X", from = 0,   to = 1000, delay = 0, duration = 16, easingType = "NONE", cbkFunName = ""},
        {node = "Layer0/Item0", propertyType = "X", from = 1000,   to = 0, delay = 0, duration = 16, easingType = "NONE", cbkFunName = ""},         
    }

    --添加动画所需的步骤
    for k, v in pairs(animation_step_table) do
        ssr.animation_add_step(animation_id, v)
    end

    --触发动画开始
    ssr.animation_trigger(animation_id)
end

ssr.language_set_type(type)

功能描述

设置语言类型

参数：

type：int类型，设置当前的语言类型(类型通过多语言工具获取)

返回值：

NONE

示例：

function set_language_fun()

    --设置第一个语言类型
    ssr.set_language_type(0)
end

ssr.language_get_type()

功能描述

设置语言类型

参数：

NONE

返回值：

type：int类型，获取当前的语言类型(类型通过多语言工具获取)

示例：

function set_language_fun()

    --获取当前的语言类型
    local type = ssr.get_language_type()
end

ssr.event_binding(path, event, cb_function)

功能描述

给某个节点绑定一个ssr系统自带的事件，当触发该事件时会调用回调函数

参数：

path: 节点的路径
event: 节点要绑定的事件类型
cb_function: 事件触发时调用的函数

返回值：

NONE

示例：

function onReleaseEvent()
    ssr.luaPrint("onReleaseEvent")
end
function event_binding_fun()
    --添加一个"Touch0"节点，绑定"Release"事件，注册一个回调函数"onReleaseEvent"
    ssr.event_binding("Layer0/Item0/Touch0","Released","onReleaseEvent")
end

ssr.event_regist(eventtable, cbfunction)

功能描述

自定义一个事件，配合ssr.send()使用

参数：

event_table: lua table类型，存储节点以及需要订阅的节点的事件类型
cb_function: 定义一个回调函数，当有eventName消息发送时会调用cb_function函数

返回值：

NONE

示例：

function cb_function(table)
    ssr.luaPrint(table["name"].." , "..table["event"])
    --table["name"]： 事件响应关联的节点
    --table["event"]：事件类型："Pressed", "Moving", "Released", "Clicked"
end

function event_define_fun()
    --table：存储节点和事件的数据
    --cb_function：回调的函数
    local table = {}
    table["Layer0/Touch0"] = {"Pressed", "Released"}
    table["Layer0/Touch1"] = {"Pressed", "Moving"}
    table["Layer0/Touch2"] = {"Pressed", "Clicked"}

    ssr.event_regist(table, "cb_function")
end

ssr.container_set_file(containerPath, containerProjName)

功能描述

设置一个container工程

参数：

path：container工程的路径
containerProjName：container的工程名字

返回值：

int类型，返回0代表设置成功，返回-1代表设置失败

示例：

function lua_fun()
    --Container0:表示container的路径
    --ContainerProName：表示container的工程名字
    ssr.container_set_file("Container0","ContainerProName")
end

ssr.move_page_child(nodePath, index)

功能描述

移动Layer节点和Page节点的显示层级

参数：

nodePath:string类型，Layer节点或者Page节点的路径(用于多个container的显示层级处理)
index:int类型，节点的显示层级，0表示显示层级在最底层，-1表示显示层级在最顶层

返回值：

int类型，返回0代表设置成功，返回-1代表设置失败

示例：

function lua_fun()
    --Container0:表示container的路径
    --index：表示container的工程名字
    ssr.move_page_child("Container0",index)
end 

ssr.move_child(nodeParentPath, nodeSubPath, index)

功能描述

移动Layer下的节点显示层级

参数：

nodePath:string类型，父节点的路径
nodeSubPath：string类型，子节点的路径
index:int类型，节点的显示层级，0表示显示层级在最底层，-1表示显示层级在最顶层

返回值：

int类型，返回0代表设置成功，返回-1代表设置失败

示例：

function lua_fun()
    --layer0:表示父节点的路径
    --Item0：表示子节点的路径
    ssr.move_child("layer0","layer0/Item0",0)
end 

ssr.get_root_path()

功能描述

获取主工程的根目录路径

参数：

NONE

返回值：

string类型，返回主工程所在的路径

示例：

function lua_fun()
    --path表示返回的当前工程所在的路径
    local path = ssr.get_root_path()
    ssr.luaPrint(path)
end

ssr.exit()

功能描述

强制关闭ssRender应用程序

参数：

NONE

返回值：

NONE

示例：

function exit_fun()
    --强制关闭当前的应用程序
    ssr.exit()
end

版本历史

版本1.0.0：[20240913] - 初始版本，包含Animation函数、Timer函数和get函数等。
版本1.0.1：[20250528] - 删除ssr.event_send接口，修改ssr.event_regist接口使用和定义。