scripts

Getting Started

All Objects defined in materials.txt can be scripted, but first you have to tell PA that you want them scripted; to do this, add Properties Scripted to your BEGIN Object ... definition block in materials.txt:

    Properties           Scripted

Next, you need to create the script file. It should be in the following folder within your mod:

YourModFolder/data/scripts/

The filename is should be the <objectId> (with same capitalisation as you used in materials.txt, otherwise it will not work on Linux) with an extension of .lua.

For example, if your object's Name in materials.txt is MyFirstObject then PA will expect to find the script here:

YourModFolder/data/scripts/MyFirstObject.lua

Each time a scripted object is placed on the map, a new instance of it's script will be created in a sandboxed (isolated) Lua environment.

data/scripts/<objectId>.lua

A brief outline of the structure of a script file is shown below:

-- Code outside of functions will run immediately when the script is loaded
-- This is useful for defining local variables

local foo = "bar" -- Creates a local variable 'foo' and set it's value to "bar"

function Create()
   -- The game will run code here when your object has been fully constructed on the map
end

function Update( elapsedTime )
    -- Code here will be run every update (very, very regularly)
    -- It's strongly recommended to 'despam' this function (see later)
end

-- Helper functions are usually defined at the bottom of the script

function Boo()
  -- Some stuff
end

-- Note that such functions won't be available until the whole script has been compiled;
-- if you tried to access the function Boo() at top of script (outside of a function)
-- you'd get an error (function doesn't exist yet). This doesn't affect Create() and
-- Update() as they won't get called until after the whole script has been compiled.

All top-level code (such as variable and function declarations) will be run straight away, but to do anything meaningful on an ongoing basis you'll have to use [Object Events](Object Events).

##Despamming Update

A script's Update function gets called many times per second, and if it regularly does computationally expensive operations, then your game will begin to slow down and lag. For tips on how to prevent this, see Update()

##Debugging

Every scripted object on the map has its own debugging console. For example, if you have a scripted object called Foo and you place two Foo on the map, each of them will have their own scripting console.

Opening the console

There are two ways to open the scripting console for an object:

• Select one of your scripted objects on the map and press the F3 key to view that objects' debugger
• Force an error in your script (see below) to automatically open the debugger for the object that caused the error

The easiest way to force an error is to call the non-existent print() function:

-- top level code

function Create()
  -- code
end

function Update()
  -- code
end

print() -- throw the error here

-- any code below the error will never get run

You can have multiple consoles open at the same time, and you can drag them round the screen, resize them, etc.

Printing to the console

As you can see from the example above, Lua's print() function isn't exposed to your script. Instead you have to use a function from the scripting api: Game.DebugOut()

Game.DebugOut( <string> )

-- example
Game.DebugOut( tostring( this.Pos.x ) )

Where <string> is, amazingly, a string value. Unlike Lua's print() function, Game.DebugOut() can only handle a single parameter. *sigh*

Console features

There's a little drop-down at the bottom left of each console with three options:

• Output - any error messages, and trace from Game.DebugOut()
• Stack - not much use to us modders
• Explore - very useful!

The "Explore" option lets you inspect the local scripting environment (each scripted object on the map gets its own scripting environment). Starting from _G (the global scope) it let's you see all non-local variables and their properties.

You'll also notice that all three modes of the debugger (it's not a debugger, it's a console..ish) have a text box near the bottom of the window. You can type Lua script directly in to that and hit Enter to run it in the scope of your script. It is, however, very limited and - as with all things Introversion - heaving with bugs. For example, you can call a function but try giving it parameters and it breaks.

Test cycle

You'll be glad to know that you don't need to restart the whole app to make script changes take effect. All you need to do is start a new prison (or load a saved prison) and the latest version of your script will be used for the duration of that prison. In fact, it's possible the latest version is used for every scripted object that's spawned, I've not tested because I assumed no app could be written that badly, but...