Skip to main content

Introduction

Pragma uses the programming language Lua 5.1 (with LuaJIT) for its scripting engine. If you're new to Lua, the PIL is a good starting point.

Any text editor suited for programming (Notepad++, Sublime, Visual Studio Code, etc.) can be used to write Lua scripts, however using the ZeroBrane IDE is highly recommended due to its powerful debugging capabilities specialized for Lua development.

Pragma has one Lua instance per game state. The game state is split into a serverside portion and a clientside portion. The client generally handles things like rendering and device inputs, while the server handles AI, game logic, etc. Some components (like physics) are simulated on both sides and may or may not be synchronized.

The game states (along with the Lua instances) are initialized once you're loading a map, which means Lua commands and scripts are not available in the main menu. Which game states are available depends on the situation:

  • Starting a local game/server: Both game states are initialized.
  • Connecting to a server: Only the clientside game state is initialized.
  • Starting a dedicated server: Only the serverside game state is initialized.

 

There are many ways to execute Lua code, but the easiest one is via console commands:

  • lua_run <code> / lua_run_cl <code>: Executes the specified Lua code serverside / clientside (if the game state is available)
  • lua_exec <code> / lua_exec_cl <code>: Executes the specified Lua file serverside / clientside (if the game state is available)

These Lua instances are completely independent and cannot communicate directly with each other (except via net messages). Any variables or functions you define in the serverside state will not be accessible in the clientside state and vice versa. Here are a few examples using the lua_run and lua_run_cl console commands:

lua_run var = "This is a serverside variable" -- Defines the global serverside variable 'var'
lua_run_cl print(var) -- Prints 'nil' (indicating an undefined variable) to the console, because 'var' was not defined clientside
lua_run print(var) -- Prints 'This is a serverside variable' to the console, because we're back in the serverside instance

 

You can also place Lua-files in one of the following autorun directories, in which case they will automatically be executed when the game is started:

  • "lua/autorun/<fileName>.lua": The Lua-file will be executed for both the serverside and clientside Lua instances.
  • "lua/autorun/server/<fileName>.lua": The Lua-file will be executed serverside.
  • "lua/autorun/client/<fileName>.lua": The Lua-file will be executed clientside.

API Documentation

You can find a list of all available Lua classes, libraries and functions in the API documentation. Some functions are only available serverside, some only clientside, which is indicated by the colored bars in front of the function names in the navigation:

api_color_codes.png

Anything with a blue bar is available serverside, and anything with a purple bar clientside. For instance, the client cannot trigger a map change, so game.change_map() can only be executed in the serverside Lua instance.

If you have configured ZeroBrane, all of the functions should also appear in the auto-complete list when typing the name of a library or class:

Zerobrane_autocomplete.gif

In-Engine Documentation

In addition to the online API documentation, you can also use the lua_help console command to retrieve the information ingame:

lua_help.png

 

Lua errors will also use this documentation to provide you with suggestions on how to correct the error:

lua_error_help.png

 

Hello World

 

 

 

Since the Lua state is part of the game state, that means that there is also a serverside Lua state and a clientside Lua state, which are c

 

 

 

Make sure map loaded

There are multiple ways to use Lua:

  • Console: You can use the "lua_run"

You can find a list of available libraries and classes for Pragma in the API documentation over here.

Tutorials will follow (if there is demand).

 

All Entities

Examples

Respawn all players (serrverside):
for ent in ents.iterator({ents.IteratorFilterComponent(ents.COMPONENT_PLAYER)}) do
	local playerC = ent:GetComponent(ents.COMPONENT_PLAYER)
	playerC:Respawn()
end
Registering a console command
console.register_command("custom_command",function(pl,...)
    if(pl ~= nil) then
		print("Command was initiated by player ",pl:GetEntity():GetName())
    end
    print("Command arguments: ",...)
    
    local arg1,arg2,arg3 = ...
    -- Do something with arguments
end)

Register a console variable and do something on change:

local cvHealth = console.register_variable("player_gravity_factor","1",bit.bor(console.FLAG_BIT_ARCHIVE,console.FLAG_BIT_REPLICATED),"Specifies barney's default health.")

local gravityFactor = cvHealth:GetInt()

console.add_change_callback("player_gravity_factor",function(old,new)

end)

Creating a prop and placing it in front of the player console command +physics

local ent = ents.create_prop()

 

Create a trigger +Touch Event

 

 

 

 

Creating a GUI element
local rect = gui.create("WIRect")
rect:SetColor(Color.Red)
rect:SetPos(Vector(32,32))
rect:SetSize(256,65)

local text = gui.create("WIText",rect)
text:SetColor(Color(0,255,64,255))
text:SetPos(5,5)
text:SetText("Hello World")
text:SizeToContents()
Creating a custom class

 

creating an image buffer

 

 

Creating a timer
-- Print "Hello" every 2 seconds
local numberOfRepetitions = -1 -- -1 = infinite
local timer = time.create_timer(2.0,numberOfRepetitions,function()
    print("Hello")
end)

-- Remove the timer after 15 seconds using a second timer
time.create_simple_timer(15,function()
    util.remove(timer)
end)

light source -> parent to player

Turn on flashlight, change intensity and color

3d gui element

 

create zombie

 

RenderComponent

CalcRayIntersection

 

Math examples

Ballistic Arc
Back to top