Basics¶

Welcome to the scripting documentation of our game engine, where you’ll learn the fundamentals of writing and managing Lua scripts to enhance your game projects. This guide covers basic syntax, lifecycle methods, and event handling in Lua within our engine context.

Introduction to Lua Scripting¶

Lua is a powerful, efficient, and lightweight scripting language. It is designed to be embedded in applications, and our game engine leverages Lua to allow developers to script game behaviors, responses, and interactions.

Lua Syntax Basics¶

Lua scripts are made up of statements, which can include variable declarations, assignments, functions, and expressions. Here are some basic syntax rules in Lua:

• Variables: You can declare variables to store data. Lua is dynamically typed, so you do not need to declare the type of the variable.

local score = 10
local playerName = "Alex"

• Functions: Functions in Lua are declared using the function keyword. They can be named or anonymous.

function greet(name)
    print("Hello, " .. name)
end

• Control Structures: Lua supports typical control structures such as if, for, and while.

if score > 50 then
    print("Great job!")
else
    print("Keep trying!")
end

Find out more in the official Lua documentation

Entity Class¶

Every script need to create a class of type Entity and return it at the end of the script. This is what the engine will instantiate upon creating the object, the script is attached to. You can add lifecycle methods and all your code to this new class. Below is an example of how to create this.

local MyEntity = Class.new(Entity)

--- your code goes here

return MyEntity

Entity Lifecycle Methods¶

Entities in our game engine can implement several lifecycle methods to handle various stages of a script’s execution:

• `init()`: Called when the script is first loaded. Used for setup and initialization.

• `update()`: Called once per frame. Used for regular updates such as checking input or moving objects.

• `render()`: Called during the rendering phase. Used for custom drawing commands.

local MyEntity = Class.new(Entity)

function MyEntity:init()
    print("Script initialized")
end

function MyEntity:update()
    print("Frame update")
end

function MyEntity:render()
    print("Render call")
end

return MyEntity

Find more information about the lifecycle methods here: Lifecycle Methods

Event Handling¶

Our engine allows scripts to respond to various events, such as input from the keyboard and mouse, or collisions in the game world. Events are handled by registering a callback function.

local Events = require 'engine/events'

function MyEntity:init()
    Events.on('keydown', function(event)
        print("Key pressed: " .. event.key)
    end)
end

This function setup ensures that your game can react to player inputs or other significant game events dynamically.

Find more information about event handling here: Handling Events

Importing other scripts¶

There will be cases where a single script will grow too large or some functionality will be interesting for other scripts, too. In that case you will want to create a new script, let’s call it “CommonFunctions” that will contain all your commonly used functions. To actually use this script from another, there are two things you need to do:

local someVariable = 1

function myUsefulFunction()
    print("Hello")
end

function anotherNiceFunction(a, b)
    return a + b
end

return {
    myUsefulFunction: myUsefulFunction,
    anotherNiceFunction: anotherNiceFunction
}

You first need to make sure your common script returns something. In the above case, it will just return a set of functions that you defined. Any script that wants to use this will then add an import call to load it:

local commonFunctions = import('path/to/scripts/CommonFunctions')

commonFunctions.myUsefulFunction()

Unlike the require call that you already know from above, the import function is helping you load your own scripts instead of engine internal libraries. Important to note is that any script importing the CommonFunctions will get the very same instance of it. So be aware that modifying the variable “someVariable” above will change it for everyone. If you prefer every caller to have their own instance, return a class in your common script:

local Functions = Class.new()

Functions.someVariable = 1

function Functions:__new()
    -- any initialization happens here and will be called when
    -- creating a new instance of this class
end

function Functions:myUsefulFunction()
    print("Hello")
end

function Functions:anotherNiceFunction(a, b)
    return a + b
end

return Functions

local Functions = import('path/to/scripts/CommonFunctions')
local myFunctions = Functions.new()

myFunctions:myUsefulFunction()

Conclusion¶

This guide provides the basics you need to start scripting in Lua within our game engine. Understanding these fundamentals will enable you to create more complex and dynamic game behaviors. Continue to explore more detailed documentation to fully leverage all scripting capabilities of the engine.