Core_API_Manual - Xrysnow/LuaSTG-x GitHub Wiki

Introduction

This page shows documents of core API of LuaSTG, including Plus and X version.

To get original API manual of LuaSTGPlus, please visit here.

To get full API document of LuaSTG-x, please visit here. It's better for LuaSTG-x users to use this document since many functions are extended.

Legend

Mark Description
[P] This API is avalible in LuaSTGPlus.
[X] This API is avalible in LuaSTG-x.
[static] This API is a static function.
(P) Following descriptions only apply for LuaSTGPlus.
(X) Following descriptions only apply for LuaSTG-x.

Global Variables

lstg

[P] [X]

Holds API functions and many script stuff. Functions will be exported to global space at launch.

Type

table

args

[P]

Holds command line arguments as an array of string.

Type

table

_ARGS

[X]

Holds command line arguments as an array of string.

Type

table

Frame Control

SetWindowed(isWindowed)

[P] [X] [static] [deprecated in X]
Set the engine windowed or full-screen. true for windowed and false for full-screen. Default is true.

  • (P) Can only be invoked during launch instead of runtime.

Parameters

isWindowed boolean

SetFPS(targetFPS)

[P] [X] [static]
Set target FPS. Default is 60.

  • (P) Can only be invoked during launch instead of runtime.

Parameters

targetFPS number

GetFPS()

[P] [X] [static]
Get current FPS.

Returns

number

SetVsync(isEnable)

[P] [X] [static]
Set V-Sync. Default is true.

  • (P) Can only be invoked during launch instead of runtime.

Parameters

isEnable boolean

SetResolution(width, height)

[P] [X] [static]
Set window resolution (size) if game is windowed. Default is 640, 480.

  • (P) Can only be invoked during launch instead of runtime.

Parameters

width number

height number

ChangeVideoMode(width, height, windowed, vsync)

[P] [X] [static]
Change video parameters. Returns true if success, otherwise returns false and restore last parameters.

  • (P) Can only be invoked during runtime.

Parameters

width number

height number

windowed boolean

vsync boolean

Returns

boolean

SetSplash(boolean)

[P] [X] [static]
Set if the mouse cursor is displayed in game window.

  • (P) Default is false.
  • (X) Default is true.

Parameters

boolean

SetTitle(title)

[P] [X] [static]
Set the caption of window.

  • (P) Default is "LuaSTGPlus".
  • (X) Default is "LuaSTG-x".

Parameters

title string

SystemLog(string)

[P] [X] [static]
Write string to log file.

Parameters

string string

Print(...)

[P] [X] [static]

  • (P) Write values to log file.
  • (X) Print values to console on desktop platforms. Write values to log file on mobile platforms.

Parameters

...

LoadPack(path, password)

[P] [X] [static]
Load zip pack at path with an optional password.

Will throw an error if failed.

Detail

Zip pack loaded later will have higher priority. So you can override files in previous packs.

Zip file will be occupied after loaded.

Files required by engine will be searched in packs at first, then local path.

Parameters

path string

password string [optional]

UnloadPack(path)

[P] [X] [static]
Unload zip pack loaded at path.

Will NOT throw an error if failed.

Parameters

path string

ExtractRes(path, target)

[P] [X] [static]
Extract files in pack to local path.

Will throw an error if failed.

Parameters

path string

target string

DoFile(path)

[P] [X] [static]
Execute script at path. Similar to dofile() of Lua.

Will throw an error if script not exists, failed to compile or failed to execute.

Parameters

path string

ShowSplashWindow(path)

[P] [X] [static] [deprecated in X]

  • (P) Set the loading picture.

Will use default picture if failed or path not passed.

  • (X) Do nothing.

Parameters

path string [optional] Path of picture file.

Game Object Pool

GetnObj()

[P] [X] [static]
Get game object count.

Returns

number

ObjFrame()

[P] [X] [static]
Update all game objects.

Do not invoke in coroutine.

Detail

Update properties in the following order:

vx += ax

vy += ay

x += vx

y += vy

rot += omiga

Update paritle system if there is

ObjRender()

[P] [X] [static]
Render all game objects. Will invoke rander() callback one by one.

Object with smaller layer property will be rendered first.

Do not invoke in coroutine.

SetBound(left, right, bottom, top)

[P] [X] [static]
Set boundary of stage.

Parameters

left number

right number

bottom number

top number

BoundCheck()

[P] [X] [static]
Do boundary check and mark objects outside boundary as del status.

An object will not be marked if bound property is false.

Do not invoke in coroutine.

CollisionCheck(A, B)

[P] [X] [static]
Do collision chekc on group A and B.

If an object (in group) A collides another object (in group) B, its colli() callback will be invoked and the other object will be passed as parameter.

  • (P) A and B are group IDs.

  • (X) A and B can be either group ID or object.

Do not invoke in coroutine.

Parameters

A number/object

B number/object

UpdateXY()

[P] [X] [static]
Update following properties of all objects: dx, dy, lastx, lasty, rot (when navi is true).

Do not invoke in coroutine.

AfterFrame()

[P] [X] [static]
Update following properties of all objects: timer, ani_timer. Trim objects marked as del or kill.

Do not invoke in coroutine.

Detail

You can set status property of an object to "normal" to preserve it.

New(class)

[P] [X] [static]
Create a game object.

Detail

Create a game object based on class and invoke init() callback.

Created object will have following properties:

Property Description
x, y coordinates
dx, dy difference of coordinates from last update (read-only)
rot orientation (in degrees)
omiga angular velocity of orientation
timer update counter
vx, vy velocity
ax, ay acceleration
layer render layer
group collision group
hide if object will not be rendered
bound if object will be marked at boundary check
navi if orientation will be updated according to velocity
colli if object will be involved in collision check
status status of object, can be "del", "kill" or "normal"
hscale, vscale scale of horizontal and verticle
class class of the object
a, b size of collision box
rect if collision box is rectangle
img name of renderable resource on the object
ani animation timer (read-only)

Index 1 and 2 of the object will be class and internal ID, do not modify them.

class should have following properties:

is_class = true

[1] = init(object, ...) callback

[2] = del(object, ...) callback

[3] = frame(object) callback

[4] = render(object) callback

[5] = colli(object, object) callback

[6] = kill(object, ...) callback

Callbacks will be invoked when corresponding event happens.

The upper limit of object count is 32768. An error will be thrown if it exceeds.

Parameters

class table

Del(object, ...)

[P] [X] [static]
Mark object as del status and invoke del() callback.

Parameters passed after object will be passed to del() callback.

Parameters

object

...

[optional]

Kill(object, ...)

[P] [X] [static]
Mark object as kill status and invoke kill() callback.

Parameters passed after object will be passed to kill() callback.

Parameters

object

...

[optional]

IsValid(object)

[P] [X] [static]
Check if object is valid (not trimmed).

Parameters

object

GetV(object)

[P] [X] [static]
Returns magnitude and direction (in degrees) of object velocity.

Parameters

object

Returns

number,number

SetV(object, magnitude, direction, updateRot)

[P] [X] [static]
Set magnitude and direction (in degrees) of object velocity. Will update rot property if updateRot is true.

Parameters

object object

magnitude number

direction number

updateRot boolean

SetImgState(object, blend, a, r, g, b)

[P] [X] [static]
Set parameters of the renderable resource bind to object.

Parameters

object

blend string

a number

r number

g number

b number

Angle(a, b)

[P] [X] [static]
Returns angle of two objects in degrees.

Parameters

a object

b object

Returns

number

Angle(x1, y1, x2, y2)

[P] [X] [static]
Returns angle of two points in degrees.

Parameters

x1 number

y1 number

x2 number

y2 number

Returns

number

Dist(a, b)

[P] [X] [static]
Returns distance between two objects.

Parameters

a object

b object

Returns

number

Dist(x1, y1, x2, y2)

[P] [X] [static]
Returns distance between (x1,y1) and (x2,y2).

Parameters

x1 number

y1 number

x2 number

y2 number

Returns

number

BoxCheck(object, left, right, top, bottom)

[P] [X] [static]
Check if position of object is in the given range.

Parameters

object

left number

right number

top number

bottom number

Returns

boolean

ResetPool()

[P] [X] [static]
Trim all game objects immediately.

DefaultRenderFunc(object)

[P] [X] [static]
Default render function for a game object.

Parameters

object

NextObject(groupid, id)

[P] [X] [static]
Iterates objects in a group if groupid is valid, otherwise iterates all objects.

This is manual version of ObjList().

Parameters

groupid number

id number

Returns

number,object

ObjList(groupid)

[P] [X] [static]
Returns an iterator that go through objects in a group.

Example

for _, obj in ObjList(GROUP_ITEM) do ... end

Parameters

groupid number

Returns

function

ParticleFire(object)

[P] [X] [static]
Start particle emitter on object.

Parameters

object

ParticleStop(object)

[P] [X] [static]
Stop particle emitter on object.

Parameters

object

ParticleGetn(object)

[P] [X] [static]
Returns current particle count on object.

Parameters

object

Returns

number

ParticleGetEmission(object)

[P] [X] [static]
Get particle emit frequency on object (count per second).

Detail

Particle emitter will always step by 1/60 seconds.

Parameters

object

ParticleSetEmission(object, count)

[P] [X] [static]
Set particle emit frequency on object (count per second).

Parameters

object

count

Game Resource

There are two resource pool provided by engine: global and stage. They are managed separately.

A resource is identified by its name (a string). Name should be unique in a pool.

All load function will load resource into current activated pool. Resource will be find in stage pool first, then global pool.

(P) Resource types:

  1. Texture
  2. Image
  3. Animation
  4. Music
  5. Sound
  6. Particle
  7. Texture font
  8. TTF font
  9. Shader

(X) Resource types:

  1. Texture
  2. Image
  3. Animation
  4. Music
  5. Sound
  6. Particle
  7. Font
  8. Shader
  9. Render target

Shader

(P) Shaders are in FX format of D3D9, written in HLSL. They use "binding" annotations to accept variables from lua scripts.

(X) Shaders can be fragment and/or vertex shader in GLSL. They use uniforms to accept variables from lua scripts.

Acceptable lua variables:

string: interpreted as (name of) texture

number: interpreted as a float value

lstg::Color: interpreted as a float4 value

(P) Shader can only be used for post effect.

(X) Shader can be used for post effect and RenderMode of each object.

RenderTarget

RenderTarget will always be the same size as game resolution.

Note that a RenderTarget can be both input and output of rendering. Do input and output at the same time may cause error and the engine dose not check that.

RemoveResource(poolType)

[P] [X] [static]
Clear a resources pool. poolType can be "global" or "stage".

If a resource is in use, it will not be released until all usages are end.

Parameters

poolType string

RemoveResource(poolType, resType, name)

[P] [X] [static]
Remove a resource from a pool. poolType can be "global" or "stage".

If a resource is in use, it will not be released until all usages are end.

Parameters

poolType string

resType number Resource type code

name string

CheckRes(type, name)

[P] [X] [static]
Returns name of the pool where a resource is located. Usually used to check if a resource exists.

Detail

Will search in global pool at first, then stage pool.

Returns nil if resource not exists.

Parameters

type number

name string

Returns

string

EnumRes(type)

[P] [X] [static]
Returns arrays of all resource names in global and stage pool.

Parameters

type number Resource type code

Returns

table, table

GetTextureSize(name)

[P] [X] [static]
Returns width and height of a texture resource.

Parameters

name string

Returns

number, number

LoadTexture(name, path, mipmap)

[P] [X] [static]
Load a texture resource from file.

Parameters

name string

path string

mipmap boolean [optional] Default is false

LoadImage(name, tex_name, x, y, w, h, a, b, rect)

[P] [X] [static]
Load a image resource from a texture resource.

  • x, y specifies left-top of the image in texture coordinates (in pixels).

  • w, h specifies width and height of the image (in pixels).

  • a, b, rect specifies parameters of the collision box.

Detail

When a image is assigned to img property of an object, collision box parameters will be assigned to the object.

Parameters

name string

tex_name string

x number

y number

w number

h number

a number [optional]

b number [optional]

rect boolean [optional]

SetImageState(name, blendMode, vertexColor1, vertexColor2, vertexColor3, vertexColor4)

[P] [X] [static]
Set parameters of a image resource. Optional vertex color parameters can be 1 or 4.

Available blendMode:

"" default, equals to "mul+alpha", default mode

"mul+add" multiplication for vertex color, addition for blend

"mul+alpha" multiplication for vertex color, alpha for blend

"mul+sub" multiplication for vertex color, subtraction for blend

"mul+rev" multiplication for vertex color, reverse subtraction for blend

"add+add" addition for vertex color, addition for blend

"add+alpha" addition for vertex color, alpha for blend

"add+sub" addition for vertex color, subtraction for blend

"add+rev" addition for vertex color, reverse subtraction for blend

Parameters

name string

blendMode string

vertexColor1 lstg::Color [optional]

vertexColor2 lstg::Color [optional]

vertexColor3 lstg::Color [optional]

vertexColor4 lstg::Color [optional]

SetImageCenter(name, x, y)

[P] [X] [static]
Set center of an image resource to (x, y) relative to its left-top.

Parameters

name string

x number

y number

LoadAnimation(name, tex_name, x, y, w, h, n, m, interval, a, b, rect)

[P] [X] [static]
Load an animation resource.

  • x, y specifies top-left coordinates of the first frame.

  • w, h specifies width and height of one frame.

  • n, m specifies number of columns and rows.

  • interval specifies played interval in frames.

  • a, b, rect specifies parameters of the collision box.

Animations are always played repeatedly.

Parameters

name string

tex_name string

x, y number, number

w, h number, number

n, m number, number

interval number

a, b, rect number, number, boolean [optional]

SetAnimationState(name, blend_mode, vertex_color1, vertex_color2, vertex_color3, vertex_color4)

[P] [X] [static]
Similar to SetImageState.

Parameters

name string

blend_mode string

vertex_color1 lstg::Color [optional]

vertex_color2 lstg::Color [optional]

vertex_color3 lstg::Color [optional]

vertex_color4 lstg::Color [optional]

SetAnimationCenter(name, x, y)

[P] [X] [static]
Similar to SetImageCenter.

Parameters

name string

x number

y number

LoadPS(name, def_file, img_name, a, b, rect)

[P] [X] [static]
Load a particle resource.

  • def_file specifies path of definition file.

  • img_name specifies name of image resource.

  • a, b, rect specifies parameters of the collision box.

Supports HGE format.

Parameters

name string

def_file string

img_name string

a number [optional]

b number [optional]

rect boolean [optional]

LoadFont(name, def_file, bind_tex [optional], mipmap)

[P] [X] [static]
Load a texture font resource.

  • def_file specifies path of definition file.

  • (P) bind_tex specifies texture path, only used by fancy2d format.

Detail

(P) Supports HGE format and fancy2d format.

(X) Supports HGE format.

For HGE format, texture file will be searched at the same directory of def_file.

Parameters

name string

def_file string

bind_tex [optional] string

mipmap boolean [optional] Default is true.

SetFontState(name, blendMode, color)

[P] [X] [static]
(P) Set status of a texture font resource.

(X) Set status of a font resource.

Parameters

name string

blendMode string

color lstg::Color [optional]

LoadTTF(name, path, width, height)

[P] [X] [static]
Load a TTF font resource.

  • path specifies path of font file.

  • (P) width, height specifies width and height of font.

  • (X) width specifies size of font.

Parameters

name string

path string

width number

height number

LoadSound(name, path)

[P] [X] [static]
Load a sound resource.

  • (P) Supports WAV and OGG format. WAV format is recommended.

  • (X) Supports WAV, OGG, MP3 and FLAC format. WAV format is recommended.

Detail

Sound will be loaded into memory entirely. Please avoid using big audio files.

WAV file of non-standard or compressed format is not supported.

Parameters

name string

path string

LoadMusic(name, path, loop_end, loop_duration)

[P] [X] [static]
Load a music resource.

  • loop_end, loop_duration specifies end time and length of looping in seconds. The loop range will be loop_end-loop_duration to loop_end.

  • (P) Supports WAV and OGG format. OGG format is recommended.

  • (X) Supports WAV, OGG, MP3 and FLAC format. OGG format is recommended.

Detail

Music will not be loaded into memory entirely.

The looping function is implemented by decoder so it's completely seamless.

Parameters

name string

path string

loop_end number

loop_duration number

LoadFX(name, path)

[P] [static]
Load a shader resource.

path specifies path of FX format file.

Parameters

name string

path string

LoadFX(name, fShader, vShader, isString)

[X] [static]
Load a shader resource.

  • fShader specifies path or content of fragment shader. Will be default fragment shader if got nil.

  • vShader specifies path of content of vertex shader. Will be default vertex shader if got nil.

  • isString specifies if fShader and vShader is string content rather than path.

Parameters

name string

fShader string [optional]

vShader string [optional]

isString boolean [optional]

CreateRenderTarget(name)

[P] [X] [static]
Create a RenderTarget.

  • (P) Will be treated as texture resource.

Parameters

name string

IsRenderTarget(name)

[P] [X] [static] [deprecated in X]
(P) Check if a texture resource is RenderTarget.

(X) Check if a render target resource exists.

Parameters

name string

Render

  • LuaSTG uses Cartesian coordinate system as screen coordinate system, which means right and up are positive direction. The original point is the left-bottom of screen.

  • There is a global scale factor for rendering. It will affect some render functions.

  • Z-buffer will not be enabled by default.

  • All render functions must be invoked in RenderFunc (render() callback of game class).

RenderTarget cannot be rendered when under using.

BeginScene()

[P] [X] [static]
Notice engine the beginning of rendering. Must invoked in RenderFunc.

All render functions should be invoked between BeginScene and EndScene.

EndScene()

[P] [X] [static]
Notice engine the ending of rendering. Must invoked in RenderFunc.

RenderClear(lstg::Color)

[P] [X] [static]
Clear screen with specified color. Will also clear z-buffer if enabled.

Parameters

lstg::Color

SetViewport(left, right, bottom, top)

[P] [X] [static]
Set viewport. Will affect clipping and rendering.

Parameters

left number

right number

bottom number

top number

SetOrtho(left, right, bottom, top)

[P] [X] [static]
Set orthogonal projection.

Detail

(P) Z range will be [0, 1].

(X) Z range will be [-1024, 1024].

Parameters

left number

right number

bottom number

top number

SetPerspective(eyeX, eyeY, eyeZ, atX, atY, atZ, upX, upY, upZ, fovy, aspect, zn, zf)

[P] [X] [static]
Set perspective projection.

  • (eyeX, eyeY, eyeZ) specifies eye position.

  • (atX, atY, atZ) specifies target position.

  • (upX,upY,upZ) specifies up vector.

  • fovy specifies field of view in radians.

  • aspect specifies aspect ratio.

  • zn, zf specifies z-near and z-far plane.

Parameters

eyeX, eyeY, eyeZ number, number, number

atX, atY, atZ number, number, number

upX, upY, upZ number, number, number

fovy number

aspect number

zn number

zf number

Render(image_name, x, y, rot, hscale, vscale, z)

[P] [X] [static]
Render an image.

  • (x, y) specifies center position.

  • rot specifies rotation in radians.

  • (hscale, vscale) specifies horizontal and verticle scale. vscale will be same as hscale if only hscale is assigned.

  • z specifies z position.

Will be affected by the global scale factor.

Parameters

image_name string

x number

y number

rot number [optional] Default is 0.

hscale number [optional] Default is 1.

vscale number [optional] Default is hscale or 1.

z number= [optional] Default is 0.5.

RenderRect(image_name, left, right, bottom, top)

[P] [X] [static]
Render an image in the specified rectangle. Z position will be 0.5.

Parameters

image_name string

left number

right number

bottom number

top number

Render4V(image_name, x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)

[P] [X] [static]
Render an image in specified vertex positions.

Parameters

image_name string

x1, y1, z1 number, number,number

x2, y2, z2 number, number,number

x3, y3, z3 number, number,number

x4, y4, z4 number, number,number

SetFog()

[P] [X] [static]
Clear fog effect.

SetFog(near, far, color)

[P] [X] [static]
Set fog effect.

  • If near is -1, EXP1 algorism will be used and far will be density parameter.

  • If near is -2, EXP2 algorism will be used and far will be density parameter.

  • Otherwise, linear algorism will be used and near, far will be range parameter.

Parameters

near number

far number

color lstg::Color [optional] Default is 0x00FFFFFF.

RenderText(name, text, x, y, scale, align)

[P] [X] [static]
Render a texture font resource.

  • text specifies text to render.

  • (x, y) specifies position.

  • scale specifies scale.

  • align specifies alignment.

Will be affected by the global scale factor.

Detail

Values for align:

LT: 0 / MT: 1 / RT: 2

LM: 4 / MM: 5 / RM: 6

LB: 8 / MB: 9 / RB: 10

  • This function is overwritten in core script and has different parameters.

Parameters

name string

text string

x number

y number

scale number [optional] Default is 1.

align number [optional] Default is 5.

RenderTexture(tex_name, blend, vertex1, vertex2, vertex3, vertex4)

[P] [X] [static]
Render a texture resource.

Detail

vertex1-4 specify vertices and shoudl have following fields:

[1] = X coordinate

[2] = Y coordinate

[3] = Z coordinate

[4] = U coordinate (in pixels)

[5] = V coordinate (in pixels)

[6] = color

Parameters

tex_name string

blend string

vertex1 table

vertex2 table

vertex3 table

vertex4 table

RenderTTF(name, text, left, right, bottom, top, format, color, scale)

[P] [X] [static]
Render a TTF font resource.

  • name specifies name of font resource.

  • text specifies text to render.

  • left, right, bottom, top specifies a box that text will be rendered into.

  • format specifies how text is aligned in the box.

  • color specifies blend color.

  • scale specifies scale. This value will be multiplied by 0.5 in the engine.

(X) Will use values from resource if format and subsequent parameters are omitted.

Will be affected by the global scale factor.

  • This function is overwritten in core script and has different parameters.

Parameters

name string

text string

left number

right number

bottom number

top number

format number

color lstg::Color

scale number [optional] Default is 1.

Post Effect

PushRenderTarget(name)

[P] [X] [static]
Push a render target into render target stack and use it as render output.

Detail

Render targets are managed by a stack so it's possible to use them nestedly.

Usages should satisfy:

PushRenderTarget(name)

...

PopRenderTarget()

Parameters

name string

PopRenderTarget()

[P] [X] [static]
Pop a render target from render target stack.

PostEffect(name, fx_name, blend, args)

[P] [X] [static]
Apply post effect and render result to screen. Values in args will be passed to shader.

blend specifies how result will be rendered.

Detail

(P) Only the first 'technique' will be used in the shader.

(P) Preset values can be get by following annotations:

(X) Preset values can be get by following uniform names:

(P) POSTEFFECTTEXTURE: texture to apply effect (texture2d)

(X) u_texture: texture to apply effect (sampler2D)

VIEWPORT: size of viewport (float4)

SCREENSIZE: size of screen (float4)

Parameters

name string

fx_name string

blend string

args table [optional]

PostEffectCapture()

[P] [X] [static] [deprecated in X]
A shortcut to begin post effect.

Equivalent to:

PushRenderTarget(InternalRenderTarget)

PostEffectApply(fx_name, blend, args)

[P] [X] [static] [deprecated in X]
A shortcut to finish post effect. An internal render target is used.

Equivalent to:

PopRenderTarget(InternalRenderTarget)

PostEffect(InternalRenderTarget, fx_name, blend, args) Usages should satisfy:

PostEffectCapture()

...

PostEffectApply(...)

Parameters

fx_name string

blend string

args table [optional]

Sound

PlaySound(name, vol, pan)

[P] [X] [static]
Play a sound resource.

  • vol specifies volume, the range is [0, 1].

  • pan specifies channel balance, the range is [-1, 1].

Detail

A sound will be interrupted if it's played again.

Parameters

name string

vol number

pan number [optional] Default is 0.

StopSound(name)

[P] [X] [static]
Stop a sound resource.

Parameters

name string

PauseSound(name)

[P] [X] [static]
Pause a sound resource.

Parameters

name string

ResumeSound(name)

[P] [X] [static]
Resume a sound resource.

Parameters

name string

GetSoundState(name)

[P] [X] [static]
Returns status of a sound resource. Will return "paused", "playing" or "stopped".

Parameters

name string

Returns

string

PlayMusic(name, vol, position)

[P] [X] [static]
Play a music resource.

  • vol specifies volume, the range is [0, 1].

  • position specifies start position in seconds.

Parameters

name string

vol number [optional] Default is 1.

position number [optional] Default is 0.

StopMusic(name)

[P] [X] [static]
Stop a music resource. Will set playback position to the beginning.

Parameters

name string

PauseMusic(name)

[P] [X] [static]
Pause a music resource.

Parameters

name string

ResumeMusic(name)

[P] [X] [static]
Resume a music resource.

Parameters

name string

GetMusicState(name)

[P] [X] [static]
Returns status of a music resource. Will return "paused", "playing" or "stopped".

Parameters

name string

Returns

string

SetSEVolume(vol)

[P] [X] [static]
Set global volume factor for sound resources. The value will be multiplied to vol parameter of PlaySound. Will not affect playing sounds.

  • (P) vol should in range [0, 1].

Parameters

vol number

SetSEVolume(name, vol)

[X] [static]
Set volume of specified sound. Will affect playing sounds.

  • vol should in range [0, 1].

Parameters

name string

vol number

SetBGMVolume(vol)

[P] [X] [static]
Set global volume factor for music resources. The value will be multiplied to vol parameter of PlayMusic. Will not affect playing musics.

  • (P) vol should in range [0, 1].

Parameters

vol number

SetBGMVolume(name, vol)

[P] [X] [static]
Set volume of specified sound. Will affect playing musics.

  • vol should in range [0, 1].

Parameters

name string

vol number

Input

(P) Gamepad input is mapped to code 0x92 - 0xB1.

(X) Gamepad input is mapped dynamically to existing codes.

GetKeyState(code)

[P] [X] [static]
Check if key corresponding to code is pressed.

Detail

  • (P) code is VK_CODE defined by microsoft.
  • (X) code is EventKeyboard::KeyCode defined by cocos.

Parameters

code number

Returns

boolean

GetLastKey()

[P] [X] [static]
Returns code of last pressed key.

Returns

number

GetLastChar()

[P] [X] [static] [deprecated in X]

  • (P) Returns last input char.
  • (X) Do nothing.

Returns

string

GetMousePosition()

[P] [X] [static]
(P) Get mouse position in pixels starts from the bottom left of the window.

(X) Get mouse position in screen coordinates starts from the bottom left of the window.

Returns

number,number

GetMouseState(button)

[P] [X] [static]
Check if mouse button is pressed.

  • button specifies button to check. 0/1/2 correspond to left/middle/right.

Parameters

button number

Returns

boolean

Misc

Snapshot(file_path)

[P] [X] [static]
Take a snapshot of screen and save to file_path in PNG format.

Parameters

file_path string

Execute(path, arguments, directory, wait)

[P] [static]
Execute an external program at path.

Returns true on success, false on failure.

Parameters

path string

arguments string [optional]

directory string [optional]

wait boolean [optional] Default is true.

Returns

boolean

Math

The following trigonometric functions accept degree values.

sin(ang)

[P] [X] [static]

Parameters

ang

cos(ang)

[P] [X] [static]

Parameters

ang

asin(v)

[P] [X] [static]

Parameters

v

acos(v)

[P] [X] [static]

Parameters

v

tan(ang)

[P] [X] [static]

Parameters

ang

atan(v)

[P] [X] [static]

Parameters

v

atan2(y,x)

[P] [X] [static]

Parameters

y,x

Class Constructor

Rand()

[P] [X] [static]
Create a RNG object.

Returns

RNG

Color(argb)

[P] [X] [static]
Create a Color object.

Parameters

argb number

Returns

lstg::Color

Color(a, r, g, b)

[P] [X] [static]
Create a Color object.

Parameters

a number

r number

g number

b number

Returns

lstg::Color

BentLaserData()

[P] [X] [static]
Create a BentLaserData object.

Returns

BentLaserData

Debug

ObjTable()

[P] [X] [static]
Returns the table where game objects are stored.

Returns

table

Global Callback

Following functions should be defined in global namespace and will be invoked by the engine. They are already defined in the core script.

GameInit()

[P] [X] [static]
Will be invoked after the initialization of engine finished.

FocusLoseFunc()

[P] [X] [static]
Will be invoked when the window lose focus.

FocusGainFunc()

[P] [X] [static]
Will be invoked when the window get focus.

FrameFunc()

[P] [X] [static]
Will be invoked every frame to process all frame logic.

Game will exit if it returns true.

Returns

boolean

RenderFunc()

[P] [X] [static]
Will be invoked every frame to process all render instructions.

Color Class

lstg::Color (Color for short) class is used to represent a 32-bit color. The a/r/g/b component represents alpha/red/green/blue value.

  • Color object can be constructed by Color().
  • Components a, r, g, b are in range [0, 255].
  • Components will be clamped to [0, 255] when performing arithmetic operation if not specified.
  • (X) Components can be accessed and assigned by field a, r, g, b.
  • (X) 32-bit value can be accessed and assigned by field argb.
  • (X) Other methods and custom constructor are extended in Lua scripts. Please refer to the document or source code of LuaSTG-x.
  • A Color object is a Lua userdata.

ARGB()

[P] [X]
Returns a, r, g, b components respectively.

Returns

number, number, number, number

unpack()

[X]
Returns r, g, b, a components respectively.

Returns

number, number, number, number

unpackFloat()

[X]
Returns r, g, b, a components scaled to [0, 1] respectively.

Returns

number, number, number, number

set(R, G, B, A)

[X]
Set values of components. Alpha component is optional. Returns self.

Parameters

R number

G number

B number

A number [optional]

Returns

Color

setFloat(R, G, B, A)

[X]
Set values of components in range [0, 1]. Alpha component is optional. Returns self.

Parameters

R number

G number

B number

A number [optional]

Returns

Color

clone()

[P] [X] [static]
Returns a clone of the color.

Returns

Color

(meta)__eq(lhs, rhs)

[P] [X] [static]
Returns whether two color values are equal.

Parameters

lhs Color

rhs Color

Returns

boolean

(meta)__add(lhs, rhs)

[P] [X] [static]
Add two color values component-wise.

Parameters

lhs Color

rhs Color

Returns

Color

(meta)__sub(lhs, rhs)

[P] [X] [static]
Subtract two color values component-wise.

Parameters

lhs Color

rhs Color

Returns

Color

(meta)__mul(lhs, rhs)

[P] [X] [static]
When passed with two Color objects:

Multiply two color values component-wise as if components are in range [0, 1].

When passed with a Color object and a number:

Multiply components with a number.

Parameters

lhs Color/number

rhs Color/number

Returns

Color

(meta)__tostring(self)

[P] [X] [static]
Returns decription of the color value.

Parameters

self Color

Returns

string

RNG Class

RNG (random number generator) class is used for generating pseudo random number.

  • RNG object can be constructed by Rend().
  • RNG class uses WELL512 algorithm.

Default global RNG object is implemented by lstg::Random class in LuaSTG-x and has other methods. Please refer to the document or source code of LuaSTG-x.

Seed(seed)

[P] [X]
Set seed. seed shoule in range [0, 2^32-1].

Parameters

seed number

GetSeed()

[P] [X]
Returns the seed.

Returns

number

Int(min, max)

[P] [X]
Returns a random integer in range [min, max]. min should not be bigger than max.

Parameters

min number

max number

Returns

number

Float(min, max)

[P] [X]
Returns a random float in range [min, max]. min should not be bigger than max.

Parameters

min number

max number

Returns

number

Sign()

[P] [X]
Returns 1 or -1 randomly.

Returns

number

BentLaserData Class

BentLaserData class is used to control bent laser (aka curvy laser) function provided by the engine.

For the sake of brevity, we call the first node of bent laser "head", the last node "tail".

  • BentLaserData object can be constructed by BentLaserData().
  • (P) There are 1024 bent lasers at most.
  • Bent laser is composed by nodes.
  • Each bent laser can have 512 nodes at most. You can limit it to a smaller number for each one.
  • (P) A new node can only be added as head.
  • (X) A new node can only be added as head or tail.
  • When node count exceeds limit as you add a node in one side, the node on the other side will be deleted.
  • (P) Properties of a node: position, width.
  • (X) Properties of a node: position, width, color.
  • (P) Property of a node can not be changed once it's added.

BentLaserData is implemented by lstg::GameObjectBentLaser class in LuaSTG-x and has different methods. Please refer to the document or source code of LuaSTG-x.

Update(obj, length, width)

[P]
Add a new node to bent laser. Its position will be (obj.x, obj.y).

  • length specifies the limit of node count.

  • width specifies the width property of node.

Parameters

obj object

length number

width number

Release()

[P]
Legacy of old version. Do nothing.

Render(texName, blend, color, texLeft, texTop, texWidth, texHeight, scale)

[P]
Render bent laser.

  • texName specifies name of texture resource.

  • blend specifies name of blend mode.

  • color specifies color property of all vertices.

  • texLeft, texTop, texWidth, texHeight specifies texture coordinates in range [0, 1].

  • scale specifies the scale apply to each node's width.

Will be affected by the global scale factor.

Parameters

texName string

blend string

color lstg::Color

texLeft number

texTop number

texWidth number

texHeight number

scale number

CollisionCheck(x, y, rot, a, b, rect)

[P]
Do collision check with a fake object as if it has given properties.

Returns true is there is collision.

Detail

Each node will be treated as a circle whose radius is half of the width.

Parameters

x number

y number

rot number [optional] Default is 0.

a number [optional] Default is 0.

b number [optional] Default is 0.

rect boolean [optional] Default is false.

Returns

boolean

BoundCheck()

[P]
Check if all nodes' position are in the range set by SetBound().

Returns

boolean