Game Object

From LuaSTG Wiki
Jump to navigation Jump to search
Following contents may not apply for LuaSTG and LuaSTG Boost
以下内容可能不适用于 LuaSTGLuaSTG Boost
以下の内容は LuaSTGLuaSTG Boost に適用されません
Game object is a core feature of LuaSTG engine. It is used to carry most game logic. A game object contains properties, callbacks and its own members. It is a Lua table and its properties are accessed through metatable.
游戏对象是LuaSTG引擎的核心功能之一,用于承载游戏的大多数逻辑。 一个游戏对象包含了属性回调函数,并可以具有自己的成员。其本质是一个Lua中的表,通过元表实现对属性的访问。
Game object is a core feature of LuaSTG engine. It is used to carry most game logic. A game object contains properties, callbacks and its own members. It is a Lua table and its properties are accessed through metatable.

Properties
属性
Properties

Properties are features provided by the engine. They are accessed by index. For example, the following code
游戏对象的属性是一些引擎内部功能的集合,以索引的形式进行使用。 例如,以下代码
Properties are features provided by the engine. They are accessed by index. For example, the following code
obj.x = obj.timer / 10
will read value of timer property, divide it by 10 and assign the result to x property.
将取出timer属性的值,然后除以10,将结果写入x属性。
will read value of timer property, divide it by 10 and assign the result to x property.

Common Properties
通用属性
Common Properties

Common properties apply to LuaSTGPlus, LuaSTGExPlus and LuaSTG-x.
通用属性适用于LuaSTGPlusLuaSTGExPlusLuaSTG-x
Common properties apply to LuaSTGPlus, LuaSTGExPlus and LuaSTG-x.
Name
名称
Name
Type
类型
Type
Description
描述
Description
x number
X coordinates
X坐标
X coordinates
y number
Y coordinates
Y坐标
Y coordinates
dx number
difference of X coordinates since last frame (read-only)
X坐标相对于上一帧的增量(只读)
difference of X coordinates since last frame (read-only)
dy number
difference of Y coordinates since last frame (read-only)
Y坐标相对于上一帧的增量(只读)
difference of Y coordinates since last frame (read-only)
rot number
orientation (in degrees)
朝向(角度)
orientation (in degrees)
omiga number
angular velocity of orientation
朝向的角速度
angular velocity of orientation
timer number
update counter
更新计数器
update counter
vx number
X-component of velocity
速度的X分量
X-component of velocity
vy number
Y-component of velocity
速度的Y分量
Y-component of velocity
ax number
X-component of acceleration
加速度的X分量
X-component of acceleration
ay number
Y-component of acceleration
加速度的Y分量
Y-component of acceleration
layer number
render layer
渲染层级
render layer
group number
collision group
碰撞组
collision group
hide boolean
if object will not be rendered
是否隐藏(跳过渲染回调)
if object will not be rendered
bound boolean
if object will be marked at boundary check
是否越界销毁
if object will be marked at boundary check
navi boolean
if orientation will be updated according to velocity
是否根据速度自动更新朝向
if orientation will be updated according to velocity
colli boolean
if object will be involved in collision check
是否参与碰撞检测
if object will be involved in collision check
status string
status of object, can be "del", "kill" or "normal"
对象状态,取值为 "del", "kill" 或 "normal"
status of object, can be "del", "kill" or "normal"
hscale number
horizontal scale for render
横向的渲染缩放
horizontal scale for render
vscale number
verticle scale for render
纵向的渲染缩放
verticle scale for render
class table
class of the object
对象的类
class of the object
a number
horizontal parameter of collision box
碰撞盒的水平参数
horizontal parameter of collision box
b number
verticle parameter of collision box
碰撞盒的垂直参数
verticle parameter of collision box
rect boolean
if collision box is rectangle
是否为矩形碰撞盒
if collision box is rectangle
img string
name of renderable resource on the object
绑定的可渲染资源的名称
name of renderable resource on the object
ani number
animation timer (read-only)
动画计数器(只读)
animation timer (read-only)

Instructions
说明
Instructions

  • "omiga" is a typo from old version, it should be "omega".
    "omiga"是旧版本遗留的拼写错误,应拼写为"omega"。
    "omiga" is a typo from old version, it should be "omega".
layer[edit | edit source]
Object with smaller layer property will be rendered first.
具有较小 layer 属性的游戏对象将会先渲染。
Object with smaller layer property will be rendered first.
group[edit | edit source]
group property is an integer from 0 to 15.
group 属性的取值为0至15的整数。
group property is an integer from 0 to 15.
rect[edit | edit source]
rect property behaves differently in LuaSTG-x, please refer to Hitbox.
rect 属性在LuaSTG-x中具有不同的行为,请参考碰撞盒
rect property behaves differently in LuaSTG-x, please refer to Hitbox.
img[edit | edit source]
img property accepts name of renderable game resource. In LuaSTGPlus/LuaSTGExPlus, it includes image resource, animation resource and particle resource. In LuaSTG-x, it also includes font resource and texture resource.
  • Once a resource is assigned to img property, the game object will hold a reference of the resource.
  • In LuaSTG-x, img property can be set to nil to release the reference.
  • In LuaSTG-x, img property can also accept resource object.
img 属性接受可渲染游戏资源的名称。在LuaSTGPlus/LuaSTGExPlus中,这包括图像资源,动画资源和粒子资源。在LuaSTG-x中,还包括字体资源和纹理资源。
  • 当一个资源被赋予 img 属性时,游戏对象将持有该资源的引用。
  • 在LuaSTG-x中,img 属性可以被设置为 nil 来释放引用。
  • 在LuaSTG-x中,img 属性还可以接受资源对象。
img property accepts name of renderable game resource. In LuaSTGPlus/LuaSTGExPlus, it includes image resource, animation resource and particle resource. In LuaSTG-x, it also includes font resource and texture resource.
  • Once a resource is assigned to img property, the game object will hold a reference of the resource.
  • In LuaSTG-x, img property can be set to nil to release the reference.
  • In LuaSTG-x, img property can also accept resource object.

Properties Extended by LuaSTG-x
LuaSTG-x扩展的属性
Properties Extended by LuaSTG-x

Following properties will be enabled when game object class is defined by xclass():
使用 xclass() 函数定义游戏对象类时,以下属性会被启用:
Following properties will be enabled when game object class is defined by xclass():
Name
名称
Name
Type
类型
Type
Description
描述
Description
res object
resource object
资源对象
resource object
rc object
resource component object
资源相关对象
resource component object
rm object
render mode
渲染模式
render mode
light object/number
light source object or light flag
光源对象或光照标志
light source object or light flag
color color object
blend color
混合颜色
blend color
A number
alpha component of blend color
混合颜色的透明度分量
alpha component of blend color
R number
red component of blend color
混合颜色的红色分量
red component of blend color
G number
green component of blend color
混合颜色的绿色分量
green component of blend color
B number
blue component of blend color
混合颜色的蓝色分量
blue component of blend color
Following properties will be enabled when game object class is defined by xclass() and inherits object3d:
使用 xclass() 函数定义游戏对象类且继承 object3d 时,以下属性会被启用:
Following properties will be enabled when game object class is defined by xclass() and inherits object3d:
Name
名称
Name
Type
类型
Type
Description
描述
Description
z number
Z coordinates
Z坐标
Z coordinates
dz number
difference of Z coordinates since last frame (read-only)
Z坐标相对于上一帧的增量(只读)
difference of Z coordinates since last frame (read-only)
vz number
Z-component of velocity
速度的Z分量
Z-component of velocity
az number
X-component of acceleration
加速度的Z分量
X-component of acceleration
zscale number
Z-axis scale for render
Z轴的渲染缩放
Z-axis scale for render
quat table
quaternion of 3D rotation
3D旋转的四元数
quaternion of 3D rotation

Instructions
说明
Instructions

res[edit | edit source]
Returns resource object no game object when accessed. Same as img when assigned.
读取时返回绑定的资源对象。赋值时与 img 属性相同。
Returns resource object no game object when accessed. Same as img when assigned.
rc[edit | edit source]
Readonly. Returns an object when game object holds a font/particle/texture resource. The object is hold by game object.
  • When holding a font resource, returns cocos::Label object.
  • When holding a particle resource, returns lstg::ParticlePool object.
  • When holding a texture resource, returns a pointer point to an array of cocos::V3F_C4B_T2F. Note that there is no protection on the pointer.
只读。绑定字体/粒子/纹理资源时返回一个对象,该对象由游戏对象持有。
  • 绑定字体资源时,返回cocos::Label对象。
  • 绑定粒子资源时,返回lstg::ParticlePool对象。
  • 绑定纹理资源时,返回顶点数据指针,指向一个cocos::V3F_C4B_T2F数组。注意:该指针没有越界保护。
Readonly. Returns an object when game object holds a font/particle/texture resource. The object is hold by game object.
  • When holding a font resource, returns cocos::Label object.
  • When holding a particle resource, returns lstg::ParticlePool object.
  • When holding a texture resource, returns a pointer point to an array of cocos::V3F_C4B_T2F. Note that there is no protection on the pointer.
rm[edit | edit source]
Render mode used for default rendering. Will override render mode of holding resource.
  • Accepts lstg::RenderMode object or its name.
  • Returns lstg::RenderMode object.
默认渲染时使用的渲染模式。会覆盖所持有资源的渲染模式。
  • 接受lstg::RenderMode对象或其名称。
  • 返回lstg::RenderMode对象。
Render mode used for default rendering. Will override render mode of holding resource.
  • Accepts lstg::RenderMode object or its name.
  • Returns lstg::RenderMode object.
light[edit | edit source]
Light source object or light flag.
  • When assigned a number, light flag will be set to the value. Default light flag is 0.
  • When assigned a cocos::BaseLight object (light source object), game object will hold it.
  • Mark flag of the light source object as A, light flag of another game object as B. When result of A AND B is not 0, light parameters will be calculated and assigned to uniforms of the shader on the game object.
  • Default flag of light source object is 1. Please refer to here to check its usage.
  • Returns nil if not assigned.
  • Returns the object if assigned light source object.
  • Returns the number if assigned light flag.
  • Returns the light source object if both assigned.
  • A light shader is provided by the engine. It can be used by assign "lstg.light" to rm property.
光源对象或光照标志。
  • 设置数字时,会将游戏对象的光照标志设置为该值,默认的光照标志为0。
  • 设置cocos::BaseLight对象(光源对象)时,游戏对象会持有该对象并成为光源。
  • 当某一游戏对象的光照标志与光源对象的标志做与运算不为0时,则计算光照参数并设置该游戏对象使用的着色器中的uniform变量。
  • 光源的默认光照标志为1,用法请参考此处
  • 若未设置光源或光照标志,返回 nil
  • 若已设置光源对象,返回设置的光源对象。
  • 若已设置光照标志,返回光照标志的值。
  • 若均设置则返回光源对象。
  • 引擎提供了基于法线贴图的光照着色器,将rm属性设置为"lstg.light"即可使用。
Light source object or light flag.
  • When assigned a number, light flag will be set to the value. Default light flag is 0.
  • When assigned a cocos::BaseLight object (light source object), game object will hold it.
  • Mark flag of the light source object as A, light flag of another game object as B. When result of A AND B is not 0, light parameters will be calculated and assigned to uniforms of the shader on the game object.
  • Default flag of light source object is 1. Please refer to here to check its usage.
  • Returns nil if not assigned.
  • Returns the object if assigned light source object.
  • Returns the number if assigned light flag.
  • Returns the light source object if both assigned.
  • A light shader is provided by the engine. It can be used by assign "lstg.light" to rm property.
color[edit | edit source]
Blend color for default rendering. Will override blend color of holding resource.
  • Accepts color object.
  • Returns color object.
默认渲染的混合颜色。会覆盖所持有资源的混合颜色。
  • 接受颜色对象。
  • 返回颜色对象。
Blend color for default rendering. Will override blend color of holding resource.
  • Accepts color object.
  • Returns color object.

Callbacks
回调函数
Callbacks

Callbacks are defined by game object class. They will be invoked by engine when corresponding event happens.
回调函数由游戏对象类定义,它们会在相应事件发生时被引擎调用。
Callbacks are defined by game object class. They will be invoked by engine when corresponding event happens.
Name
名称
Name
ID
Parameters
参数
Parameters
init 1 object, ...
del 2 object, ...
frame 3 object
render 4 object
colli 5 object, object
kill 6 object, ...
  • The engine will use IDs of these callbacks instead of their names.
    引擎会使用这些回调函数的ID而非它们的名称。
    The engine will use IDs of these callbacks instead of their names.

init[edit | edit source]

init callback will be invoked when a game object is created. This happens in New() function.
  • Extra parameters passed to New() function will be passed to init callback. For example, New(cls, 1, 2, 3) will pass 1, 2, 3 to init callback defined by cls.
init 回调在游戏对象被创建时调用。这发生在 New() 函数内部。
  • 传递给 New() 函数的额外参数将被传递给 init 回调。例如,New(cls, 1, 2, 3) 将会传递 1, 2, 3cls 定义的 init 回调。
init callback will be invoked when a game object is created. This happens in New() function.
  • Extra parameters passed to New() function will be passed to init callback. For example, New(cls, 1, 2, 3) will pass 1, 2, 3 to init callback defined by cls.

del[edit | edit source]

del callback will be triggered by Del() and BoundCheck().
  • status property will be set to "del" before it is invoked.
  • This callback will not be triggered by Del() when status property is not "normal".
  • Extra parameters passed to Del() function will be passed to del callback.
del 回调会被 Del()BoundCheck() 函数触发。
  • 在被调用前,status 属性会被设置为 "del"。
  • status 属性不为 "normal" 时,Del() 函数不会触发该回调。
  • 传递给 Del() 函数的额外参数将被传递给 del 回调。
del callback will be triggered by Del() and BoundCheck().
  • status property will be set to "del" before it is invoked.
  • This callback will not be triggered by Del() when status property is not "normal".
  • Extra parameters passed to Del() function will be passed to del callback.

kill[edit | edit source]

kill callback will be triggered by Kill().
  • status property will be set to "kill" before it is invoked.
  • This callback will not be triggered by Kill() when status property is not "normal".
  • Extra parameters passed to Kill() function will be passed to kill callback.
kill 回调会被 Kill() 函数触发。
  • 在被调用前,status 属性会被设置为 "kill"。
  • status 属性不为 "normal" 时,Kill() 函数不会触发该回调。
  • 传递给 Kill() 函数的额外参数将被传递给 kill 回调。
kill callback will be triggered by Kill().
  • status property will be set to "kill" before it is invoked.
  • This callback will not be triggered by Kill() when status property is not "normal".
  • Extra parameters passed to Kill() function will be passed to kill callback.

frame[edit | edit source]

frame callback will be triggered by ObjFrame().
  • frame callback of all game objects will be invoked in order of created time in ObjFrame().
frame 回调会被 ObjFrame() 函数触发。
  • ObjFrame() 函数中,所有游戏对象将按照被创建的顺序依次调用 frame 回调。
frame callback will be triggered by ObjFrame().
  • frame callback of all game objects will be invoked in order of created time in ObjFrame().

render[edit | edit source]

render callback will be triggered by ObjRender().
  • render callback of all game objects will be invoked in ascending order of layer property in ObjFrame().
  • This callback will not be triggered when hide property is true.
render 回调会被 ObjRender() 函数触发。
  • ObjRender() 函数中,所有游戏对象将按照 layer 属性从小到大的顺序依次调用 render 回调。
  • hide 属性为 true 时将不会触发该回调。
render callback will be triggered by ObjRender().
  • render callback of all game objects will be invoked in ascending order of layer property in ObjFrame().
  • This callback will not be triggered when hide property is true.

colli[edit | edit source]

colli callback will be triggered by CollisionCheck().
  • This callback will not be triggered when colli property is false.
colli 回调会被 CollisionCheck() 函数触发。
  • colli 属性为 false 时将不会触发该回调。
colli callback will be triggered by CollisionCheck().
  • This callback will not be triggered when colli property is false.

Members
成员
Members

As a Lua table game, a object can have its own members (aka fields) accessed through index. Index of a member can not be same as name of property.
  • Index 1 and 2 are used by engine internally. Do not use them.
  • In LuaSTG-x, if the game object class is defined by xclass() and instantiated as obj = cls(), then its non-callback methods will become members of the game object.
作为Lua表,游戏对象可以拥有自己的成员(也称为域),通过索引来访问。成员的索引不能与属性名称相同。
  • 索引 12 被用于引擎内部,请勿使用。
  • 在LuaSTG-x中,如果游戏对象类由 xclass() 函数定义,且由 obj = cls() 的形式实例化,则游戏对象类的非回调方法会成为游戏对象的成员。
As a Lua table game, a object can have its own members (aka fields) accessed through index. Index of a member can not be same as name of property.
  • Index 1 and 2 are used by engine internally. Do not use them.
  • In LuaSTG-x, if the game object class is defined by xclass() and instantiated as obj = cls(), then its non-callback methods will become members of the game object.

Game Object Class
游戏对象类
Game Object Class

Game object class is a template for objects, which defines callbacks for them.
  • The engine only create objects and invoke callbacks. Other OOP features such as inheritance and override are provided by core scripts.

A game object class is a Lua table. Its index "is_class" is true and index 1 to 6 are callbacks.

For example, the following code
游戏对象类是游戏对象的模板,它定义了对象所共有的回调函数。
  • 引擎只负责创建游戏对象和调用回调函数,继承、重写等其他面向对象编程特性是由核心脚本提供的。

游戏对象类的本质是一个Lua表,其 "is_class" 索引为 true,索引 16 为对应的回调函数。

例如,以下代码
Game object class is a template for objects, which defines callbacks for them.
  • The engine only create objects and invoke callbacks. Other OOP features such as inheritance and override are provided by core scripts.

A game object class is a Lua table. Its index "is_class" is true and index 1 to 6 are callbacks.

For example, the following code
local cls = { is_class = true }
for i = 1, 6 do
    cls[i] = function() end
end
defines a game object class cls whose callbacks are empty functions.

Core scripts provide Class() function. It allows user to define a game object class in script conveniently. Callbacks are defined through their names instead. Refer to here for more information.

After game object classes are defined, the engine will process them with an operation called register. The engine will throw an error when a game object class that defined after register operation is used.
定义了一个游戏对象类 cls,其回调函数均为空函数。

核心脚本提供了 Class() 函数,使用户可以方便地在脚本中定义游戏对象类,且回调函数改为以名字进行定义。更多信息请参考此处

在游戏对象类定义完成后,引擎会对它们进行一个称为注册的操作。如果一个游戏对象类在注册操作后被定义,则引擎会在使用它时抛出错误。
defines a game object class cls whose callbacks are empty functions.

Core scripts provide Class() function. It allows user to define a game object class in script conveniently. Callbacks are defined through their names instead. Refer to here for more information.

After game object classes are defined, the engine will process them with an operation called register. The engine will throw an error when a game object class that defined after register operation is used.