Lua scripting

Lua script plugin provides an option to script using Lua. It provides a new type of component, which points to a lua script file. This file is executed when a game starts. Each component has lua sandboxed - it means that all variables and function are not accessible from other components unless they are put in the global table _G or accessed using Engine.getEnvironment.

Update function

Each script can contain function update(dt) and this function is called each frame.

API

Engine

Global variables

• Universe g_universe
• Engine g_engine

All scenes are visible to script as global variables, each with prefix "g_scene_" and ends with the name of a plugin, e.g.:

• g_scene_renderer
• g_scene_animation
• g_scene_audio
• g_scene_physics
• g_scene_lua_script

Constants

• Engine.INPUT_TYPE_DOWN
• Engine.INPUT_TYPE_PRESSED
• Engine.INPUT_TYPE_MOUSE_X
• Engine.INPUT_TYPE_MOUSE_Y
• Engine.INPUT_TYPE_LTHUMB_X
• Engine.INPUT_TYPE_LTHUMB_Y
• Engine.INPUT_TYPE_RTHUMB_X
• Engine.INPUT_TYPE_RTHUMB_Y
• Engine.INPUT_TYPE_RTRIGGER
• Engine.INPUT_TYPE_LTRIGGER

Properties

Every Vec3, color, decimal, integer and boolean property (you can see properties in the property grid in the editor) can be accessed from Lua. However name of a property is transformed in following way:

1. Remove all non-alphabetic characters,
2. If a character is after non-alphabetic character in the source name, it is uppercase in the Lua name.

For example:

-- property Fog color
GlobalLight.setFogColor(g_scene_renderer, cmp, {1, 0, 1})
local color = GlobalLight.getFogColor(g_scene_renderer, cmp) -- color == {1, 0, 1}

Types

Other than standard lua types there is one more - Vec3. It is just table with three numbers.

Functions

• Table Engine.getEnvironment(Scene scene, Entity entity) #620
• void Engine.setEntityPosition(Universe univ, Entity entity, Vec3 position)
• Vec3 Engine.getEntityPosition(Universe univ, Entity entity)
• void Engine.setEntityRotation(Universe univ, Entity entity, Vec3 axis, number angle)
• void Engine.setEntityLocalRotation(Universe univ, Entity entity, Vec3 axis, number angle)
• void Engine.setRenderablePath(Scene scene, Component cmp, string path)
• number Engine.getInputActionValue(Engine engine, number action)
• void Engine.addInputAction(Engine engine, number action, number type, number key)
• Component Engine.createComponent(Scene scene, string type, Entity entity)
• void Engine.logError(string text)
• void Engine.logInfo(string text)
• Vec3 Engine.multVecQuat(Vec3 vec, Vec3 axis, number angle)
• Component Engine.getRenderable(Scene scene, Entity entity)
• void Engine.destroyComponent(Scene scene, string type, Component component)

Physics

• void Physics.moveController(Scene scene, Component cmp, Vec3 velocity, number time_delta)
• number Physics.getActorSpeed(Scene scene, Component cmp)
• Component Physics.getActorComponent(Scene scene, Entity entity)
• void Physics.putToSleep(Scene scene, Component component)
• void Physics.applyForceToActor(Scene scene, Component component, Vec3 force)
• Entity Physics.raycast(Scene scene, Vec3 origin, Vec3 dir)

If two entities with a physical component collide, onContact function is called in script on both of them:

function onContact(entity)
  API_logError("not implemented - onContact(" .. entity .. ")")
end

Audio

• SoundHandle Audio.playSound(Scene scene, Entity entity, string clip_name, bool is_3d)
• void Audio.setSoundVolume(Scene scene, SoundHandle sound_id, number volume)
• void Audio.setEcho(IScene* scene, SoundHandle sound, number wet_dry_mix, number feedback, number left_delay, number right_delay)

Renderer

• string Renderer.getCameraSlot(Camera component)
• Camera Renderer.getCameraComponent(Entity entity)
• Renderable Renderer.getRenderableComponent(Entity entity)
• void Renderer.addDebugCross(Vec3 center, float size, number rgba_color, float life)
• Material Renderer.getTerrainMaterial(Terrain component)
• Texture Renderer.getMaterialTexture(Material material, number texture_index)
• void Renderer.setRenderableMaterial(Scene scene, Renderable component, number material_index, string path)
• void Renderer.setRenderablePath(Scene scene, Renderable component, string path)

Navigation

• bool Navigation.generateNavmesh()
• void navigate(Entity entity, Vec3 destination, float speed)
• void debugDrawCompactHeightfield()
• void debugDrawNavmesh()
• void debugDrawHeightfield()
• void debugDrawPaths()
• void debugDrawContours()
• number getPolygonCount()
• void generateTile(number x, number y, bool keep_data)
• bool save(string path)
• bool load(string path)
• void setGeneratorParams(float cell_size, float cell_height, float agent_radius, float agent_height, float walkable_angle, float max_climb)

Editor

Importing asset

Editor.importAsset(Editor.editor, 
{
	{ 
		src = "C:\\some\\path\\obj_part1.dae" ,
		materials = {
			{ 
				import = true,
				textures = {
					{
						import = true,
						to_dds = true,
						src = "c:\\some\\path\\a.png",
					},
					{
						import = true,
						to_dds = false,
						src = "c:\\some\\path\\a.tga",
					}
				},
			},
			
			{ 
				import = false
			}
		}
	},
	{ src = "C:\\some\\path\\obj_part2.dae" }
})