Home_EN - Xrysnow/LuaSTG-x GitHub Wiki

LuaSTG-x is an multi-platform game engine based on cocos2d-x and LuaSTGPlus (er+1.02). It is aimed at providing a powerful engine for building STG, especially bullet hell games.

LuaSTG-x provides nearly all C API of LuaSTGPlus and most of them are identical in feature. Lua scripts (THlib) is based on er+1.02 with a few changes. It's compatible with most games made for er+1.02 except those use custom shaders. See Core API Changes page for more information.

The foundation of the engine is cocos2d-x 4.0. Some codes are from LuaSTGPlus and fancy2D. Refer to github repo for all dependencies.

Main features:

• Multi-platform audio engine supports wav/flac/ogg/mp3 format, play from memory or file, seamless loop and OpenAL effects
• Multi-platform video engine supports basic playback
• Load scene made by Cocos Creator
• 3D model support from cocos
• Powerful particle system from cocos. A visual editor: http://particle2dx.com
• Live2D support from Cubism 4 SDK
• Full ImGui integration
• Console window on desktop platforms. print function in Lua will output there
• Window resizing and fullscreen toggling on desktop platforms
• Game resolution swiching

Small features:

• Latex doc rendering
• SVG image rendering
• utf8 library from Lua5.3
• Read/write of zip files
• MSAA
• Transparent window on desktop platforms
• Many collider shapes

Lua API document: https://xrysnow.github.io/lstgx_Doc

THlib API document: https://xrysnow.github.io/lstgx_THlib

• THlib comes from er+1.02
• Some old scripts were modified and many new scripts were added
• data and game can be loaded from both zip files and local folders (see src/core/loading.lua)
• Scripts in plugin folder will be loaded automatically (see src/core/loading.lua)
• lstg.world now has a metatable, do not replace it（see src/core/view.lua)
• Some native APIs are provided on android platform(see src/platform/android/native.lua)
• Provides i18n function

Game inspector provides many utilities. Now it will only show on desktop platforms. Use the grave key to toggle.

• Game info

  • Game Resource: Check loaded game resources and preview images and animations
  • THlib Info: Check info of player, replay, spell card, stage etc.
  • Performance: View real-time performance info

• Log

  • Check logs

• Console

  • Run Lua statement

• Watch

  • Watch the value of variables or statements

• Setting

  • Set style of UI

• The img property can also be set to:

  • nil to release game resource.
  • any acceptable game resource object. Font and texture is acceptable now.

• The rect property can also be set to string or number in the following form to change collider shape:

  String value	Number value	Shape	Instruction
  ‘circle’	0	Circle	a = radius
  ‘obb’	1	Rectangle	a,b = half width/height
  ‘ellipse’	2	ellipse	a,b = semi-axis
  ‘diamond’	3	diamond	a,b = half diagonal
  ‘triangle’	4	isosceles triangle	a,b = half height/base
  ‘point’	5	point

  Note that the rot property always means the direction of a axis.

• New properties: res, rc, rm, color, A, R, G, B, light. Only enabled when game class is defined with xclass.

• New properties: z, dz, vz, az, zscale, quat. Only enabled when game class is defined with xclass and inherits object3d.

• res: Returns resource object bind to the game object. Same as the img property when assigned.

• rc: reaource component, readonly. Returns when a font/particle/texture resource is bind to the game object.

  • font resource: returns cocos::Label object. See doc at doc/cocos/cc_2d/Label.lua.
  • particle resource: returns ParticlePool object. See doc at doc/lstg/particle_pool.lua.
  • texture resource: returns cocos::V3F_C4B_T2F*. See doc at doc/cocos/lua.lua.

• rm: render mode for default rendering. Will override render mode of bind resource. Returns RenderMode object. Can assign RenderMode object or its name.

• color: blend color for default rendering. Will override blend color of bind resource. Returns Color object. Can assign Color object. Note that it's a copy of 'real' value.

• A, R, G, B: a/r/g/b component of color. Returns number in [0, 255]. Can assign number.

• light:

  • When assigned a number value, it will set the light flag of game object. Default light flag is 0, which means it will not affected by light sources.
  • When assigned a cocos::BaseLight object, the game object will hold it and become a light source. Light effect will only apply when bitwise AND of light flags of source and game object is not 0. Default light flag of source is 1. See here for more information.
  • Returns light object if assigned, or light flag if assigned. Returns the former if both assigned or nil if neither.
  • The engine provides a light shader based on normal map. Set rm property to 'lstg.light' to use it.

• z, dz, vz, az, zscale: translation value on z axis. dz is readonly.

• quat: quaternion of 3D transform.

  • Returns a table with x/y/z/w components.
  • Can assign a table with with x/y/z/w components or x/y/z components. If without w component, (x, y, z) means the rotate axis and rot means the rotate angle. If with w component, it means the quaternion and rot will be updated. Normalization is not needed.

• All game resource classes have lua binding now. A resource object will be returned when it's loaded. See doc/x for documentation.

• The engine manages how a game object is rendered by render mode, or specifically, RenderMode objects. It replaced blend mode in LuaSTGPlus. See doc/x/RenderMode.lua for documentation.
• All internal render modes are created by lua codes now. Custom render modes can be created easily.
• A render mode is compose by shder program(fragment+vertex), blend factor and blend operation.
• Any API accepts RenderMode object can also accept its name.

• Bent laser is rewrited and can provide more functions now.

• GameObjectBentLaser class has full lua binding, see doc at doc/x/GameObjectBentLaser.lua.

• Main features:

  • Bidirectional stretching.
  • Get/set position/width/color of each node.
  • Limitation on node count or total length.
  • Separate collision check functions.
  • Per-node coloring.

• When get/set node properties, index is 1-based and can be negative. -1 means the last node.

• Node will be removed from the other side to satisfy the count limitation when now node is added to head or tail. The max count limitation is 512.

• Render function (member function) has an overload:

  Render function
  render(resSprite)
  render(resTexture, renderMode, color, tex_left, tex_top, tex_width, tex_height)

• How a bent laser is colored is controlled by 2 parameters: ColorMode and ColorMixMode. They can be set by setColorMode function. Default values are 0.

  ColorMode	Value	Instruction
  Normal	0	Ignore node color
  Node	1	Use node color without transition
  NodeSmooth	2	Use node color with transition

  ColorMixMode	Value	Instruction
  None	0	Ignore node color
  Multi	1	Multiply node color and render color
  Add	2	Add node color and render color

• There are 3 functions for collision checking, each has an overload. When passed a game object, the collider of it will be used. When passed coordinates, the point will be used.

• collisionCheck will take each node as a circle collider witch diameter is its width.

• collisionCheckExtendWidth is like collisionCheck, but will extend each radius of circles.

• strictCollisionCheck will take each node as a rectangle that extends to next node. This is stricter but much slower.

  Collision check function
  collisionCheck(GameObject)
  collisionCheck(x, y)
  collisionCheckExtendWidth(GameObject, extend)
  collisionCheckExtendWidth(x, y, extend)
  strictCollisionCheck(GameObject)
  strictCollisionCheck(x, y)

• Random number generator is rewrited refer to Random library of Python. Old functions are reserved.

	Function	Instruction
Integer number
	range(start)	Same as `below`
	range(start, stop, step = 1)	Random integer in [start, stop) with interval of `step`
	below(start)	Random integer in [0, start)
Real number
	uniform(a, b)	Uniform distribution
	triangular()	Triangular distribution
	triangular(low, high)
	triangular(low, high, mode)
	normal(mu, sigma)	Normal distribution
	log_norml(mu, sigma)	Log-normal distribution
	expo(lambda)	Exponential distribution
	vonMises(mu, kappa)	Von Mises distribution
	gamma(alpha, beta)	Gamma distribution
	gauss(mu, sigma)	Same as `normal`
	beta(alpha, beta)	Beta distribution
	pareto(alpha)	Pareto distribution
	weibull(alpha, beta)	Weibull distribution

• Docs at doc/x/l2d_Model.lua.
• Main features:
  • Play actions.
  • Set click/drag parameters and callbacks.
  • Set physic parameters, model parameters and blend color.

• Docs at doc/x/LogSystem.lua.
• Main features:
  • Write string to log file.
  • Get/set log file path.

• Reload scripts while keep resouces.
• Shortcut is Ctrl+R.

• Controller support is rewrite and support all platforms.