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 runs immediately after script loaded

-- This is useful for defining local variables:
local foo = 'bar' -- Create local variable 'foo', set it's value to "bar"

function Create() -- event
   -- Code here runs after object is fully constructed on map
end

function Update( elapsedTime ) -- event
    -- Code here will be run every 'update' (dozens of times per second)
    -- It's strongly recommended to 'despam' this function
end

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).

##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...