ARNode

场景中物体的节点类。

is_empty_node

API起始版本：190

bool is_empty_node();

判断节点是否为空

sample:
local node = get_node_by_name(nodename)    
local is_empty = node:is_empty_node()

get_sub_node_by_name

API起始版本：190

ARNode& get_sub_node_by_name(string& name);

获取该名称的子节点

Parameter

• string | name : 要获取的子节点名称

return

• ARNode : 返回子节点对象（不为空）

sample:
local node = get_sub_node_by_name(nodename)  

sub_node_with_name

API起始版本：190

ARNode* sub_node_with_name(string& name);

获取该名称的子节点

Parameter

• string | name : 要获取的子节点名称

return

• ARNode : 返回子节点对象

replace_texture

API起始版本：190

void replace_texture(string &texture_dir,string &texture_name);

更换节点对应材质使用的texture

Parameter

• string | texture_dir : texture的相对路径
• string | texture_name : texture在shader中名字

get_texture_id

API起始版本：190

int get_texture_id(string &texture_name);

获取节点的材质id

Parameter

• string | texture_name : texture在shader中名字

update_webview_texture

API起始版本：190

bool update_webview_texture(int update_id);

更新webview的材质

Parameter

• int | update_id : 材质的id

set_event_handler

API起始版本：190

void set_event_handler(int event_type, int handler_id);

设置手势交互事件处理

Parameter

• int | event_type : 手势交互事件类型。0：click，1：long-press，2：scroll，4：pinch，5：unpinch， 100： node updated，1-5暂不支持
• int | handler_id : 回调函数id

sample: 

local handler = lua_handler:register_handle("on_click")
local node = current_scene:get_node_by_name("node_name")
node:set_event_handler(0, handler)
--点击事件
function on_click()
    io.write("on click")
end

set_position(float x, float y, float z)

API起始版本：190

设置节点位置

Parameter

• float | x y z : 三轴坐标

sample: 

local node = current_scene:get_node_by_name("savage")
node:set_position(1.0,1.0,1.0)

set_scale(float x, float y, float z)

API起始版本：190

设置节点缩放

Parameter

• float | x y z : 三轴方向缩放

sample: 

local node = current_scene:get_node_by_name("savage")
node:set_scale(0.5,0.5,0.5)

set_rotation(float x, float y, float z, float w)

API起始版本：190

设置节点旋转

Parameter

• float | x y z : 三轴方向
• float | w : 旋转角度

set_euler_angles(float x, float y, float z)

API起始版本：190

设定节点欧拉角，按照节点全局坐标系xyz的顺序设定

Parameter

• float | x y z :绕三轴方向旋转欧拉角

set_visible(bool visible)

API起始版本：190

设置节点是否可见

Parameter

• bool | visible : true or false

set_touchable(bool touchable)

API起始版本：190

设置节点是否可以点击

Parameter

• bool | touchable : true可以点击，false不可点击

get_position

API起始版本：190

string get_position();

获取节点位置

return

• string : 返回节点位置，值为字符串类型，分别对应x、y、z的坐标值

sample: 

local node = current_scene:get_node_by_name("savage")
local position = node:get_position()

get_scale

API起始版本：190

string get_scale();

获取节点缩放值

return

• string : 返回节点缩放值，值为字符串类型，分别对应x、y、z方向的放大倍数

sample: 

local node = current_scene:get_node_by_name("savage")
local scale = node:get_scale()

get_world_scale

API起始版本：190

string get_world_scale();

获取节点在世界坐标系中缩放信息

return

• string : 返回值为字符串类型， "x,y,z"分别对应x、y、z方向

get_world_position

API起始版本：190

string get_world_position();

获取节点在世界坐标系中坐标信息。

return

• string : 返回值为字符串类型，"x,y,z"分别对应x、y、z方向

set_flag

API起始版本：190

void set_flag(int type, bool value);

设置节点的属性

Parameter

• int | type : 0：visible，1：transparent，2：touchable，3：select， 4：local_rotation，5: local_translation， 6: local_scale
• bool | value : true|false

set_light_direction(float x, float y, float z)

API起始版本：190

设置灯光的方向

Parameter

• float | x y z : 灯的方向在x、y、z轴的分量

set_light_intensity(float intensity)

API起始版本：190

设置灯光的强度

Parameter

• float | intensity : 灯光的强度

sample: 

light:set_light_intensity(0.8)

set_material_property(string &key, float value)

API起始版本：190

设置节点的材质属性。会影响使用这个材质的所有节点

Parameter

• string | key : 属性的名称

  ​ [roughness|metalness|clearCoat|clearCoatRoughness|reflectivity|refractionRatio|emissiveIntensity|shininess|opacity|aoMapIntensity|lightMapIntensity|envMapIntensity|displacementScale|displacementBias |bumpScale]

• float | value : 属性的值

sample: 

node:set_material_property("roughness", 0.8)

set_material_vector_property

API起始版本：190

void set_material_vector_property(string &key, string value);

设置节点的材质属性。会影响使用这个材质的所有节点

Parameter

• string | key : 属性的名称[offsetRepeat|normalScale|diffuse|specular|emissive]
• float | value : 属性的值

sample: 

node:set_material_vector_property("offsetRepeat", "0,0,1,1")

get_visible

API起始版本：190

bool get_visible();

获取节点可见状态

return

• bool : 返回节点是否可见属性，true可见，false不可见

sample: 

local node = current_scene:get_node_by_name("savage")
local visible = node:get_visible()
io.write("node: savage visible:" .. visible)

get_touchable

API起始版本：190

bool get_touchable();

获取节点是否可点击状态

return

• bool : true可点击，false不可点击

sample: 

local node = current_scene:get_node_by_name("savage")
local touchable = node:get_touchable()
io.write("node: savage visible:" .. touchable)

play_frame_animation

API起始版本：190

unsigned int play_frame_animation(int repeat_count = 0, float delay = 0);

播放帧动画，在Json配置中指定帧位置

Parameter

• int | repeat_count : 重复次数
• float | delay : 延迟时间，单位毫秒

return

• int : 返回播放动画动作的id值，通过此值可以绑定播放完成后的回调

set_hud_position

API起始版本：190

void set_hud_position(float pos_left, float pos_top, bool relative = true);

修改hud节点位置

Parameter

• float | pos_left : hud节点的x
• float | pos_top : hud节点的y
• bool | relative : 是否相对位置

set_rotate_with_world_axis

API起始版本：190

void set_rotate_with_world_axis(int world_axis);

设置节点旋转所绕轴。不开启热区时，仅配置场景根节点生效；开启热区时，配置场景中子节点生效

Parameter

• int | world_axis : 世界坐标系的轴：-1-全自由度旋转、0-绕x轴、1-绕y轴、2-绕z轴

set_rotate_angle_limit

API起始版本：190

void set_rotate_angle_limit(int world_axis, float min_angle, float max_angle);

设置节点关于世界坐标系的旋转角度限制。不开启热区时，仅配置场景根节点生效；开启热区时，配置场景中子节点生效

Parameter

• int | world_axis : 世界坐标系的轴：0-x轴、1-y轴、2-z轴
• float | min_angle : 对应轴上的最小旋转角度(单位：°)，有效范围[-180,0]
• float | max_angle : 对应轴上的最小旋转角度(单位：°)，有效范围[0,180]

add_sub_node

API起始版本：190

void add_sub_node(ARNode& node);

为节点添加子节点

Parameter

• ARNode |node : 子节点的对象

sample: 

local new_node = scene:clone_node("node", "clone1")
node:add_sub_node(new_node)

remove_sub_node

API起始版本：190

 void remove_sub_node(string& name);

移除指定名称的子节点，对应的子节点不会被销毁，只是从场景树中移除

Parameter

• ARNode |stiring : 要移除的子节点的名称

sample:

scene:remove_sub_node("(clone1)node")

parent_node

API起始版本：190

ARNode* parent_node();

获取节点对应的父节点的指针，如果对一个节点的父节点不存在，将返回nil

Return

• ARNode* : 节点对应的父节点的指针

sample: 

local parent = node:parent_node()
io.write(parent:description())

reset_transform

API起始版本：190

void reset_transform();

重置节点相对父节点的transform矩阵

sample:  

node:reset_transform()

get_bounding_box

API起始版本：190

BoundingBox get_bounding_box();

获取当前节点的AABB包围盒

Return

• BoundingBox : 一个表示AABB包围盒的数据对象

sample:

camera = scene:get_active_camera()  
local bounding_box = node1:get_bounding_box() 
local visible = camera:is_visible_in_frustum(bounding_box) 
io.write("is node1 visible in the frusum now? "..tostring(visible))

set_interaction_event_handler

API起始版本：190

void set_interaction_event_handler(string &event_name, ARLuaFunction handler);

设置节点的交互响应回调

Parameter

• string |event_name : 交互事件名称，可用的交互事件名称如下表
• LUA_FUNCTION | handler : 一个Lua原生的Function，带一个参数，用作对应的交互响应的回调

sample:

function on_interaction(event_name)
	io.write("event"..event_name.."triggered")
end

node:set_interaction_event_handler(on_interaction)

set_update_handler

API起始版本：190

void set_update_handler(ARLuaFunction handler);

设置节点每帧渲染update()调用之前的回调

Parameter

• LUA_FUNCTION | handler : 一个Lua原生的Function，将在节点每次渲染update前被调用

sample code:

function on_update()
     ARLOG("before node:update()")
end

node:set_update_handler(on_update)

pin_to_node

API起始版本：190

void pin_to_node(ARNode &non_hud_node, ARVec3 offset, ARVec3 rotation_align_vec);

将一个HUD节点绑定在一个非HUD节点上，通常用于引导Tips等

Parameter

• ARNode | non_hud_node : 一个非HUD节点，作为将要绑定到的节点
• ARVec3 | offset : 相对x、 y、 z三个坐标轴的偏移量，用于调整HUD节点和非HUD节点之间的相对位置
• ARVec3 |rotation_align_vec : 一个三维向量，用于对齐HUD节点和非HUD节点的旋转，HUD的y坐标将和此向量在屏幕上的投影保持平行

unpin

API起始版本：190

void unpin();

解除绑定，与pin_to_node相对

sample:

local hud_node = scene:get_node_by_name("hud_tip")
local node3d = scene:get_node_by_name("cube")
local offset = ARVec3:new_local(0, 0, 0)
lcoal rotation_align = ARVec3:new_local(0, 1, 0)
hud_node:pin_to_node(node3d, offset, |rotation_align)

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

hud_node:unpin()

create_physics_body

API起始版本：190

void create_physics_body(float mass, float restitution, float friction, string body_type, string shape_type, float shape_scale = 1.0)

为该节点创建一个物理碰撞体

Parameters

• mass | float : 物体的质量
• restitution | float : 弹性系数
• friction | float : 摩擦系数
• body_type | string : 碰撞体类型，包括：dynamic、kinematic、static
• shape_type | string : 碰撞体形状，包括：box、sphere、capsule、cylinder、cone、mesh
• shape_scale | float : 形状放缩系数

Returns

• void

sample:
node:create_physics_body(0.0, 0.5, 0.3,"kinematic", "box");

get_physics_body

API起始版本：190

ARPhysicsBody& get_physics_body()

获取该节点的物理碰撞体

（调用这个接口时必须保证已经调用了create_physics_body接口， 不然程序会退出！！！）

Parameters

• 无

Returns

• ARPhysicsBody& : 返回该节点的物理碰撞体

sample:
node:create_physics_body(10, 0.5, 0.5,"dynamic", "box")
local physics_body = node:get_physics_body()

get_media_controller

API起始版本：190

ARMediaController & get_media_controller();

获取节点对应的媒体播放控制器对象

Return

• ARMediaController : 返回当前节点的媒体播放控制器对象。

get_animation_controller

API起始版本：190

ARAnimationController & get_animation_controller();

获取节点对应的动画播放控制器对象

Return

• ARAnimationController : 返回当前节点的动画控制器对象。

description

API起始版本：190

string description()

获取当前节点相关的属性信息

Return

• string : 当前节点的调试信息。

Key-Value Coding support

API起始版本：190

set_property

void set_property_int(string &key, int value); void set_property_bool(string &key, bool value); void set_property_float(string &key, float value); void set_property_string(string &key, string value); void set_property_vec2(string &key, ARVec2 value); void set_property_vec3(string &key, ARVec3 value); void set_property_vec4(string &key, ARVec4 value); void set_property_mat44(string &key, ARMat44 value); void set_property_quat(string &key, ARQuat value); void set_property_boundingbox(string &key, BoundingBox value);

通过给定的Key和Value设置当前节点对应Key和类型的属性的值

 sample：
 node:set_property_bool("key", value)
 node:set_property_int("key", value)
 node:set_property_float("key", value)
 node:set_property_string("key", value)

get_property

int get_property_int(string &key); bool get_property_bool(string &key); float get_property_float(string &key); string get_property_string(string &key); ARVec2 get_property_vec2(string &key); ARVec3 get_property_vec3(string &key); ARVec4 get_property_vec4(string &key); ARMat44 get_property_mat44(string &key); ARQuat get_property_quat(string &key); BoundingBox get_property_boundingbox(string &key);

通过给定的Key来获取当前节点对应属性的值

 sample：
 node:get_property_bool("key")
 node:get_property_int("key")
 node:get_property_float("key")
 node:get_property_string("key")

可用的Key和对应的类型如下：

KVO支持（Key-Value Observing）

API起始版本：190

上述表格中支持get_property的key才支持KVO机制，对于只支持set的key不适用。

add_observer_for_property

 void add_observer_for_property(string &key, ARLuaFunction on_observer);

为指定的property设置观察者回调，当对应的property值发生改变时，会触发所注册的回调，并将改变前和改变后的数据以参数形式传递到对应的回调函数中

Parameters

• string | key : 要设置监听的的property的名字
• LUA_FUNCTION | on_observer : 观察者回调，需要包含3个参数，key、old_value和new_value

sample code:

function on_observer(key, old_value, new_value)
     ARLOG("property"..key.."changed from"..old_value.."to new value"..new_value)
end

node:add_observer_for_property("visible", on_observer)

remove_observer_for_property

 void remove_observer_for_property(string &key);

删除指定的property已设置的观察者回调，删除不存在的Observer或者重复删除将会被忽略

Parameters

• string | key : 要删除监听设置的的property的名字

node:remove_observer_for_property("visible")

Deprecated methods（建议不再使用的方法）

过期的方法将在若干个版本后停止维护。

play_audio

unsigned int play_audio(string &path, int repeat_count = -1, float delay = 0);

unsigned int play_audio(ActionPriorityConfig &config, string &path,

​ int repeat_count = -1, float delay = 0);

旧版本中，在当前节点上关联播放音乐的方法，新版本中请使用 ARMediaController & ARMediaSession中的方法替代

play_texture_video

unsigned int play_texture_video(string &path, int repeat_count = -1, float delay = 0);

unsigned int play_texture_video(ActionPriorityConfig &config, string &path, \

int repeat_count = -1, float delay = 0);

旧版本中，在当前节点上关联播放视频纹理的方法，新版本中请使用 ARMediaController & ARMediaSession中的方法替代

play_rigid_anim

unsigned int play_rigid_anim(TranslateMotionParam &p, ActionPriorityConfig &cfg);

unsigned int play_rigid_anim(RotateMotionParam &p, ActionPriorityConfig &cfg);

unsigned int play_rigid_anim(ScaleMotionParam &p, ActionPriorityConfig &cfg)

unsigned int play_rigid_anim(TranslateMotionParam &tp, RotateMotionParam &rp,

​ ScaleMotionParam &sp, ActionPriorityConfig &tcfg,

​ ActionPriorityConfig &rcfg, ActionPriorityConfig &scfg);

旧版本中，用于在当前节点上播放刚体动画的方法，新版本中请使用 ARAnimationController & ARAnimationSession 中的方法替代

play_rigid_anim(Fade)

unsigned int play_rigid_anim(FadeMotionParam &p, ActionPriorityConfig &cfg);

旧版本中，用于在当前节点上播放淡入/淡出动画的方法，新版本中请使用 ARAnimationController & ARAnimationSession中的create_alpha_animation 方法替代

play_pod_animation_all

unsigned int play_pod_animation_all(float speed, bool repeat, int start = -1, int end = -1);

unsigned int play_pod_animation_all(float speed, unsigned int repeat_count, int start = -1, int end = -1);

unsigned int play_pod_animation_all(float speed, bool repeat, string animation_name);

unsigned int play_pod_animation_all(float speed, unsigned int repeat_count, string animation_name);

int play_pod_animation_all(PodAnimationParam &p, ActionPriorityConfig &cfg);

旧版本中，用于在当前节点上播放对应模型动画的方法（pod&gLTF），新版本中请使用 ARAnimationController & ARAnimationSession中的 方法替代

pause_action

void pause_action(unsigned int action_id);

旧版本中，用于暂停某一个（动画/音乐/视频）播放操作的方法，新的版本中，动画相关请使用ARAnimationSession:pause() 代替, 媒体播放相关请使用ARMediaSession:pause() 代替

resume_action

void resume_action(unsigned int action_id);

旧版本中，用于恢复某一个（动画/音乐/视频）播放操作的方法，新的版本中，动画相关请使用ARAnimationSession:play() 代替, 媒体播放相关请使用ARMediaSession:play() 代替

stop_action

void stop_action(unsigned int action_id);

旧版本中，用于恢复某一个（动画/音乐/视频）播放操作的方法，新的版本中，动画相关请使用ARAnimationSession:stop() 代替, 媒体播放相关请使用ARMediaSession:stop() 代替

set_action_completion_handler

void set_action_completion_handler(unsigned int action_id, int handler_id);

旧版本中，用于设置一个（动画/音乐/视频）播放操作完成时的回调。新版本中请在ARAnimationController /ARMediaController中通过设置complete_handler 来替代

get_audio_play_info

MapData &get_audio_play_info();

旧版本中用于获取音频播放（播放状态、缓冲状态、播放进度、缓冲进度）信息的接口。新版本中请使用ARMediaSession的get_property 来替代

get_video_play_info

MapData &get_video_play_info();

旧版本中用于获取视频播放（播放状态、缓冲状态、播放进度、缓冲进度）信息的接口。新版本中请使用ARMediaSession的get_property 来替代

set_rotation_by_xyz

void set_rotation_by_xyz();

旧版本中中用于将节点绕三轴旋转的接口，节点绕坐标轴的旋转角度，绕节点局部坐标系按照xyz顺序转动对应角度。新版本中使用kvc接口来实现旋转，建议使用rotation_quat和rotation_vec代替

set_rotation_by_xyz

void rotate_by_xyz();

旧版本中用于将节点绕三轴旋转的接口，在节点已有的旋转基础上，添加局部坐标系按照xyz顺序对应角度的旋转。新版本中kvc接口尚无该功能接口

reset_rts

void reset_rts();

旧版本中用于重置节点变换矩阵的状态。新版本中使用ARNode的reset_transform来代替

set_particle_system_property

void set_particle_system_property();

旧版本中用于设置粒子系统属性，不建议再使用。新版本中使用ARNode的set_property_particle来代替

get_world_rotation

void get_world_rotation();

旧版本中用于获取节点相对世界坐标系的旋转四元数。新版本中请使用kvc接口来使用，接口属性名称为world_rotation_quat

set_world_rotation

void set_world_rotation();

旧版本中用于设置节点相对世界坐标系的旋转四元数。新版本中请使用kvc接口来使用，接口属性名称为world_rotation_quat

attach_hud_to_node

void attach_hud_to_node();

旧版本中用于将HUD附着在节点上。新版本中请使用ARNode的pin_to_node接口

remove_hud_attach

void remove_hud_attach();

旧版本中用于将节点上的HUD移除。新版本中请使用ARNode的unpin接口

refresh_texture

void refresh_texture(string &texture_type);

刷新纹理

get_corners

OBB get_corners();

获取模型obb

set_entity_touch_zone_radius

void set_entity_touch_zone_radius(float zone);

设置物体手势热区范围