Skip to content

Lua scripting

Jump to bottom
Mikulas Florek edited this page Mar 10, 2016 · 150 revisions

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

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)

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

  • void Renderer.setFogDensity(Scene scene, GlobalLight component, number density)
  • number Renderer.getFogDensity(Scene scene, GlobalLight component)
  • void Renderer.setFogBottom(Scene scene, GlobalLight component, number bottom)
  • number Renderer.getFogBottom(Scene scene, GlobalLight component)
  • void Renderer.setFogHeight(Scene scene, GlobalLight component, number height)
  • number Renderer.getFogHeight(Scene scene, GlobalLight component)
  • void Renderer.setFogColor(Scene scene, GlobalLight component, Vec3 color)
  • Vec3 Renderer.getFogColor(Scene scene, GlobalLight component)
  • 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, int material_index, string path)
  • void Renderer.setRenderablePath(Scene scene, Renderable component, string path)

Clone this wiki locally