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 mosteasiest commonone ones areis via console commands, or autorun-scripts: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)

IfThese you're connecting to a server, only the clientside state/instance will exist locally. TheseLua 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

 

BothYou 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 statesinstances.
  • "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 afterserverside, 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 gameblue hasbar beenis startedavailable (i.e.serverside, and anything with a purple bar clientside. For instance, the client cannot trigger a map haschange, beenso loaded),game.change_map() whichcan meansonly thebe Lua console commands will have no effect if you have launched Pragma, but haven't started a game yet.
The Lua states are destroyed when the game ends, e.g. upon disconnecting from a server, or when the current map is changed.

. That means that any variables definedexecuted in the serverside state are not accessable in the clientside state and vice versa. Most functions and classes are available for either state, some are, however, restricted to either one. For instance, since the GUI is entirely clientside, GUI functions and classes are only available for the clientside Lua state.

 TODO: Refer to documentation colors

Pragma has two game states, one serverside and one clientside. If you're running a local game, both states will be part of the same Pragma instance. If you're connecting to a server, only the clientside state will exist locally.

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