Script

From Leadwerks Developer Wiki

The Lua programming language

Leadwerks Engine 2.3+ utlitizes the Lua scripting language. Lua is used in many games including Crysis, S.T.A.L.K.E.R.: Shadow of Chernobyl, and Garry's Mod.

Scripts can be run on both a global and per-model approach. Scripts can be combined with other programming languages, and will run in existing programs with no source code changes.

Tutorials

Getting Started with Lua

Entity Scripts

When a model is loaded, the engine will check in the same directory for a script file by the same name as the model. The engine will first check for a file with the extension "luac" (compiled Lua file). If no compiled script is found, the engine will attempt to load an uncompiled .lua file by the same name. If a script is loaded, predefined functions will be called from the script at certain points in the program. All of the entity script functions are optional, and none need to be present in the script.

Lua can be incorporated into any program with no code changes. The program only needs to load the model. All script behavior will be handled automatically by the engine. This is extremely useful for loading scenes made in the editor, or for creating complex physics objects that can be loaded as one object.

Script Hooks

Class Functions

Update(world)

This function is called once for every UpdateWorld call. Note that this function will be called for every world every time it updated.

UpdatePhysics(world)

This function is called once per physics update per world. This might seem the same as the Update function, but UpdatePhysics will be called at a constant framerate, and does not necessarily match screen refresh rate. Updates that require smooth motion each frame should not be performed here. Updates that require constant values can be performed here.

Cleanup

This function is called right before a script is unloaded. Typically this would happen when all instances of the model are freed, and the model reference is freed.

Instance Functions

Spawn(model)

This is called when the model is first loaded. This function can be used to perform preparatory steps that make the model ready to use.

Reset(model)

This is called any time the model is reset. In some situations joints need to be destroyed and re-created to avoid creating enormous physics forces when a model is suddenly moved to a new position.

SetKey(model,key,value)

This is called when a key is set with SetEntityKey. If the function returns 1, the key will be set, otherwise it won't be. This can be used to turn key values into useful actions.

GetKey(model,key,defaultvalue)

This is called whenever a key is retrieved with GetEntityKey. This can be used to override default key values.

ReceiveMessage(model,message,extra)

This function is called whenever a message is received by the model. Messages can be sent with the SendEntityMessage command.

Kill(model)

This function is killed whenever a model is freed. This can be used for performing cleanup actions.

Editor Functions

The following commands are only available when a script is run in Leadwerks Editor. Fortunately Lua allows us to have functions calls to undeclared commands in a script, as long as those lines are never executed.

PropertyGrid:AddGroup( name )

This adds a property category to the property editor. If the category already exists, the existing group will be returned.

PropertyGroup:AddProperty( key, style, extra, label )

name: the name of the key this item controls. This is the key value that will be passed to SetKey and GetKey(). style: The style of the item. extra: Extra information to control the look of the item. label: This optional parameter can be used to display text next to the control that is different than the key.

PROPERTY_CHOICE

Drop-down box.

PROPERTY_CHOICEEDIT

Editable drop-down box.

PROPERTY_INTEGER

Integer editor.

PROPERTY_BOOL

True/false value editor.

PROPERTY_PATH

File path editor.

PROPERTY_FLOAT

The extra parameter can be used to pass information in the following format: "min, max, resolution" If resolution is 1 the float value will be accurate to 0.1. If resolution is 2 the float value will be accurate to 0.01. If resolution is 0 the number will be treated as an integer.

PROPERTY_STRING

PROPERTY_FILE

The extra parameter can be used to indicate the file requester file pattern. For example "Material files (*.mat):mat" will allow the user to select .mat files, and the file requester will display the text "Material files (*.mat)".

PROPERTY_COLOR

If the extra parameter is set to "1" an alpha component will be shown in the color control.

PROPERTY_VEC2

Vec2 editor

PROPERTY_VEC3

Vec3 editor

PROPERTY_VEC4

Vec4 editor

Script Editor

Leadwerks Script Editor

A script editor with syntax highlighting and undo/redo functionality is provided. The script editor can open, edit, and save Lua files. The script editor can be used with the script interpreter to run script programs, or it can compile Lua scripts into precompiled byte code files.

Script Interpreter

The Leadwerks Engine SDK provides a script interpreter so that a program may be written entirely in script. The release version of the interpreter is called "Engine.exe" and the debug version is named "Engine.debug.exe". The debug version can be used to retrieve additional information about an application crash, but it will run much slower.

Commandline Arguments

The following arguments can be passed to the script interpreter via the command line:

+script <scriptfile>
<scriptfile>
-s (silent mode)

Examples:

engine.exe +script "mygame.lua"
engine.exe "mygame.lua"
engine.exe "mygame.lua" -s
engine.exe "mygame.lua" +s 1
engine.exe -s

Silent mode disables notification messages.

If no script is specified in the command line, the interpreter will attempt to load the file "start.luac". If this file is not found, the interpreter will attempt to load the file "start.lua". Example Lua script:

Examples

You can copy and paste any of these source codes into the script editor. Press F5 to run the program.

Hello World

Print("Hello World!")

Rendering Loop

--Register abstract path
RegisterAbstractPath("")
 
--Set graphics mode
if Graphics(1024,768)==0 then
	Notify("Failed to set graphics mode.",1)
	return
end
 
world=CreateWorld()
if world==nil then
	Notify("Failed to initialize engine.",1)
	return
end
 
gbuffer=CreateBuffer(GraphicsWidth(),GraphicsHeight(),1+2+4+8)
 
camera=CreateCamera()
camera:SetPosition(Vec3(0,0,-2))
 
light=CreateSpotLight(10)
light:SetRotation(Vec3(45,55,0))
light:SetPosition(Vec3(5,5,-5))
 
material=LoadMaterial("abstract::cobblestones.mat")
 
mesh=CreateCube()
mesh:Paint(material)
 
ground=CreateCube()
ground:SetScale(Vec3(10.0,1.0,10.0))
ground:SetPosition(Vec3(0.0,-2.0,0.0))
ground:Paint(material)
 
light=CreateDirectionalLight()
light:SetRotation(Vec3(45,45,45))
 
while AppTerminate()==0 do
 
	mesh:Turn(Vec3(AppSpeed()*0.5,AppSpeed()*0.5,AppSpeed()*0.5))
 
	UpdateAppTime()
	world:Update(AppSpeed())
 
	SetBuffer(gbuffer)
	world:Render()
	SetBuffer(BackBuffer())
	world:RenderLights(gbuffer)
 
	DrawText(UPS(),0,0)
	Flip(0)
end

External Links

Lua programming language documentation

Lua wiki