Lua

From Prison Architect Wiki
Jump to navigation Jump to search
This article is about the Lua programming language and how it functions within Prison Architect. For the development of Mods, see Modding.

Lua controls how the game interacts. From creating grants to campaigns, every part of the game has some interaction with Lua. To learn more about lua, click here.

As a disclaimer, this article will contain many programming terms which define types of data, and are listed here for those who intend to create a scenario type mod. It is recommended to lookup any terms that you do not understand.

Lua Elements[edit]

Please note that while the game's own Lua scripts use the functions listed below, your own mod will not be able to use many of them. [verification needed]

See lua_function_list.txt inside main.dat for the documentation of the available functions.

Global. Elements[edit]

Element Description
Global.Game()

This object contains custom functions for use within Scenario LUA scripts. The Game object itself is Prison Architect Application.

Global.Objective()

This object contains custom functions for use with the game Objectives.

Global.Trigger()

This object contains custom functions for use with game Objectives. A trigger is a new lexical function scope within the loaded LUA scripts, that can contain other commands.

Game. Elements[edit]

Element Description
Game.DebugOut(string)

Outputs the string input to the debug log.

Game.SetChapter(string)

SetChapter is a function that takes a single string value that defines the start of a new chapter. This calls the function BeginChapter() which should be defined in that chapters LUA script files.

Game.SetMap(string)

SetMap is a function that takes a single string value that defines the map to be loaded. The filename omits the file extension (.prison) so for example if your prison map is called foo.prison you call this with the following code:

Game.SetMap("foo")
Game.SaveMap(string)

SaveMap is a function that takes a single string value that defines the map file to be used as the games progress save point for the Scenario. These files are stored in a campaign folder related to your scenario in the same folder as your saves folder.

Game.AdviserIncoming(string)

AdviserIncoming is a function that takes a single string value from a predetermined list. This will pause the script until you answer the call. The call will be a small red box centered on the screen.

Game.AdviserSay(string Adviser_Constant, string Sentence)

AdviserSay is a function that takes two string values. The first is a constant of the type labeled above as Adviser_Constant. The second can either be a sentence from the language file and is referenced by its variable name or it can be a static string.

Note: If you do not use a variable and the language file, your MOD cannot receive multilingual patches.
Game.AdviserSayBatch(string Adviser_Constant, string BatchDialogName()

AdviserSayBatch is a function that takes two string values. The first is a constant of the type labeled above as Adviser_Constant. The BatchDialogName value refers to a series of sentences inside the base-language.txt file. It will pick them up in incremental order starting at _1. For example:

myDialog_1 foo
myDialog_2 bar
This will show 2 sentences separately one after the other the first saying foo the second saying bar.

Adviser_Constants: Possible values are Ceo, Chief, Doctor, EdwardShooter, EdwardsWife, EdwardSinner, EdwardInmate, Priest & Warden. Governer and KingPin have registered names in the language file, but they do not have a texture. Any name that is not associated with a texture will appear like the file advisers/blank.bmp.

Advisers: As of Alpha 15 and earlier, it isn't possible to create your own Advisers. However you can go over the defined images from the Deathrow campaign and re-appropriate what is there. These can be any of the Adviser_Constants from above.
Game.CamMove(float x, float y, float x1, float y1, float speed, bool tweenMode)

The camera is defined by its view-port (x,y) -> (x1,y1). The speed is the amount of pixels per second the camera will move. If tweenMode is true then the Camera will continue moving to the new view-port. If set to false then the Camera will move for the duration of a following Game.Pause(int Seconds) command or until it reaches its destination, whichever comes first. A cameras view-port can only be modified if the game is paused. Setting to true will automatically pause game play.

Game.CamZoom(float zoom, float speed, bool tweenMode)

The camera zoom is based upon the cameras current view-port size which can be set by Game.CamMove. The zoom is a multiplier value of a floating point decimal value. The speed is the amount of pixels per second the camera will move. If tweenMode is true then the Camera will continue zooming to the new view-port. If set to false then the Camera will zoom for the duration of a following Game.Pause(int Seconds) command or until it reaches its destination, whichever comes first. Setting to true will automatically pause game play.

Game.CamMoveAndZoom (float x, float y, float x1, float y1, float zoom, float speed, bool tweenMode)

This function and its values act exactly as the two above functions.

Game.CamTrack(string ObjectID, float Zoom, float time)

This function will track an object as defined by its Object Name for the amount of time defined in seconds. Zoom determines how close the view-port is. For example, a value of 0.025 will zoom onto the object and its immediate surroundings.

Game.CamMoveToObject(string ObjectID, float x, float y, float x1, float y1, float speed, bool tweenMode)

This function moves the camera to the target. The values should in theory be the same as other CamMove functions.

(Untested and parameters are theory crafted from known information)
Game.CamWait()

Implementation unknown...

Game.Unlock(string type, string Identifier)

This function unlocks a type of Object or System for the player to use. These are identified by their sub ID. For example, PowerCable, Capacitor, or Electricity.

Game.Polaroid(string PolaroidID, string imagePath, float x, float y, float size_x, float size_y)

A Polaroid is a decal that is place on the map to help tell a story. The PolaroidID makes a new Polaroid object which you can reference in your code in other Polaroid commands. The Polaroid can be placed by top-left x, y coordinates and it is sized by the same coordinate system.

Game.MovePolaroidTo()

Implementation unknown...

Game.HidePolaroid()

Implementation unknown...

Game.HideArea(string hideValue, float x, float y, float x1, float y1)

At the moment the only value known for hideValue is Hide. The area is a bounding box defined by (x,y) -> (x1,y1). For example, ("hide", 0, 0, 99, 99)

Game.Show(string GameElement()

This function takes a single string identifier that shows a prison architect window/user interface element.

Game.Hide(string GameElement()

This function takes a single string identifier that hides a prison architect window/user interface element.

Game.SendEntityToRoom(string EntityID, string RoomName)

The lexical structure of the parameters is unknown at this time. However using known function calls you can ascertain the structure of this call.

(Untested)
Game.SendEntityToPos(string EntityID, float x, float y, float Orientation x, float Orientation y, Speed)

The entityID is the named NPC that you have in your scenario. For example, from Deathrow these values are Edwards, Priest, Guard1 etc.

Note: these are not the names of sprites.

The co-ordination system is the same top-left x,y Cartesian system that is in place for other function calls. Orientation co-ordinates determine the direction the entity is facing. For example, ( -1, 0 ) would orientate the entity to face left. The final value speed determines how fast the entity moves towards the target. It is suggested to keep the values between 0 and 1, such as 0.5 for a slow walk. Although you could set a higher value, it is more likely to mess with the tracking of the entity and cause it to bump into walls and act silly.

Game.SendEntityToObject(string NamedObject, string NamedObject, Speed)

Sends a named object to another named object. A named object could be a named entity, like Edward. It is suggested to keep the speed value between 0 and 1, such as 0.5 for a slow walk. For example, ("Priest", "Edward", 0.6)

Game.SetFlag(string EntityID, string FlagID, bool Value)

This sets an internal flag of an entity of the game. For example, this can set a prisoner's Shackled flag to true, meaning that they will be handcuffed. The first value is the Entity string identifier.

Game.SetSprite()

Implementation unknown...

Game.GetProperty()

Implementation unknown...

Game.PowerOn(string EntityID)

This function activates the power to a target entity. This can be any component that has the options to turn on or off. For example, Electric Chair or Power Switch.

Game.PowerOff(string EntityID)

This function deactivates the power to a target entity. This can be any component that has the options to turn on or off. For example, Electric Chair or Power Switch.

Game.FadeToBlack(float speed, bool tweenMode)

This function fades the screen to black from its current view. The speed of the fade effect is determined by the first value where larger is faster. The second is the tweenMode, true allows the view-port to fade to black before continuing the script, false continues the script, however it will only fade when using a Pause() afterwards.

Game.FadeUp(float speed, bool tweenMode)

This function is the inverse of FadeToBlack and will fade into a scene.

Game.FadeToColour(float Red, float Green, float Blue, float AlphaTransparency, float speed, bool tweenMode)

This function is the same as FadeToBlack however it accepts a float RGBa parameter in the lead. The RGBa values are an intensity coefficient and take the form of a decimal or floating point value. (0,0,0,1) is black and (1,1,1,1) is white and (0.5,0.5,0.5,0.5) is middling gray which is 50% transparent.

Game.Pause(int time)

The pause value suspends game play for the amount of seconds shown. If a tweenMode is set to false this pause is used to determine the exact length of the transition or transform in progress.

Game.Sound(string SoundType, string SoundID)

The Sounds.txt file contains the definitions of how OGG files from the sound folder are played. They are in a two level structure Begin SoundType Begin SoundID End End. The Sound function references the sound files in this manner.

Game.StopSound(string SoundType, string SoundID)

This function stops an already executing sound file.

Game.Delivery(string DeliveryID, int quantity, string ObjectID)

This summons a delivery truck which gives the player the quantity of a certain object. This could be Capacitors, Prisoners etc. The DeliveryID is to identify that individual Delivery Truck.

Game.Misconduct()

Implementation unknown...

(It may be the same structure as the save file)
Game.Spawn ()

Game.Spawn(string ObjectID, string EntityID, float x, float y) This function creates a new entity from an object type. The new ObjectID is the first parameter followed by the EntityID and its x,y spawning coordinates.

Game.SpawnPrisoners()

Implementation unknown...

Game.SpawnDecal(float, float, float, int, int, int, int)

Implementation unknown...

(It is used in murder.lua in Deathrow)
Game.Damage(string TargetEntity, int DamageDone, string ActingEntity)

The Acting Entity attacked the TargetEntity for the amount of DamageDone. If it is over the TargetEntitys Toughness points, they will die.

Game.GiveEquipment(string EntityID, string EquipmentID)

This equips the target entity with a piece of equipment as defined in objects.

Game.DropEquipment(string EntityID)

This drops the currently equipped item on the target entity.

Game.LoseEquipment()

Implementation unknown...

(It may be the same as DropEquipment except the item is destroyed)
Game.Pickup()

Implementation unknown...

(It may have the same implementation as GiveEquipment except the item must be available to be picked up)
Game.Drop()

Implementation unknown...

Game.GameOver()

This function ends the current scenario.

Objective. Elements[edit]

Element Description
Objective.Create(string ObjectiveID)

Creates a new blank objective with the ID set. All proceeding function calls apart from Exists (Still under testing) requires an objective. An objective is a stack, so any functions that follow this directly will act on this objective. When a new objective is created then all objective functions then act on this new objective instead, and so on and so forth. Once defined it cannot be altered.

Objective.CreateGrant()

Implementation unknown...

(This may be a single string parameter that points to the grant file definition)
Objective.Exists()

Implementation unknown...

Objective.Invert()

Takes no parameters and acts on the last objective set. It inverts the requirements of the objective, for example if you set for a wall to be required, if inverted it is required that the wall is removed. This can be useful for demolishing objects, or as in the example of Deathrow, it defines that an area can have any floor type except concrete by setting the requirement as concrete then inverting it.

Objective.SetFlags(bool hideOnMap, bool hideOnTodoList)

Sets the flags for displaying an objective visually to the user.

Syntax

Objective.SetFlags(bool, bool)

Parameters

hideOnMap
Type: bool
Is the objective hidden on the map; true | false.
hideOnTodoList
Type:Bool
Is the objective hidden on the To-Do list; true | false. This value will only take effect if the map is also hidden.

Examples

-- To hide the objective on the map, but show it on the To-Do list.
Objective.Create ( "foo" )
Objective.SetFlags ( true, false )

-- To hide the objective on the map and the To-Do list.
Objective.Create ( "foo" )
Objective.SetFlags ( true, true )

-- However this will not hide it on the map, as this is bad usability.
-- It will be hidden on the To-Do list.
Objective.Create ( "foo" )
Objective.SetFlags ( false, true )

-- This won't hide anything.
Objective.Create ( "foo" )
Objective.SetFlags ( false, false )

Objective.SetParent( string Parent ObjectiveName )

Used to make sub-objectives (like with grants).

Usage: LUA Objective.SetParent( "ParentObjective" )
Objective.SetPayment()

Implementation unknown...

Objective.Complete()

Implementation unknown...

Objective.TargetZone(float x, float y, float x1, float y1)

(x,y) -> (x1,y1) Bounding box of the target zone of the objective.

Objective.TargetObject(string ObjectID)

This a location for the objective to happen. For example, the Electric Chair in the Deathrow campaign: Objective.TargetObject("DeathRow_ExecutionChamber_ElectricChair")

Objective.TargetRoom()

Implementation unknown...

Objective.RequireBuilding(bool BuildingUnderway)

This determines if building is underway in the target zone.

Objective.RequireObjects(string ObjectID, int Quantity)

This determines if the specified object is in the target zone at the specified quantity. This is useful if you want, for example, 4 Cookers made in the Kitchen to pass the objective.

Objective.RequireNamedObject(string EntityID)

This requires the specified named entity to be in the target zone for the object to be met.

Objective.RequireMaterials(string MaterialID, int Quantity)

This function defines the amount of Materials to be required in the target zone specified by its MaterialID. For example, BrickWall.

Objective.RequireRoom(string RoomID, bool CompletedRoom)

This function sets the requirement for a room to be made and if it is completed (true = completed, false = items are allowed to be required).

Objective.RequireFlag(string FlagID, bool FlagValue, int Unknown)

This determines if a flag value has been activated in the target zone. The third value is unknown at this time, but may determine the value for an amount of time for that flag to have been set or tertiary flag for entities such as power capacity for example.

Objective.RequireRoomsAvailable()

Implementation unknown...

Objective.RequirePrisonerCapacity(int Capacity)

Implementation unknown...

Objective.RequirePrisonerInCell()

Implementation unknown...

Objective.RequireObjectPower()

Implementation unknown...

Objective.RequireObjectOn(string ObjectID)

This function creates an objective requirement that the target object be switched on. This only applies to objects that have the Power flag.

Objective.RequireObjectOff(string ObjectID)

This function creates an objective requirement that the target object be switched off. This only applies to objects that have the Power flag.

Objective.RequirePowerCapacity()

Implementation unknown...

(It is probably a integer value that relates to the power capacity)
Objective.RequireMaterialsAvailable()

Implementation unknown...

Objective.RequireObjectsInRoom()

Implementation unknown...

Objective.RequireSecurityInRoom()

Implementation unknown...

Objective.RequirePrisonersUnderControl()

Implementation unknown...

Objective.RequireGangControl()

Implementation unknown...

Objective.RequireResearched()

Implementation unknown...

Trigger. Elements[edit]

Element Description
Trigger.Create(string TriggerID)

This created a new trigger with a new ID. The trigger refers directly to another LUA lexical function scope, which will execute once the linked objective is complete. A trigger like an objective can only be acted on by its proceeding function calls. Once defined it cannot be altered.

Trigger.RequireObjective(string ObjectiveID)

This links a trigger to a previous Objective by the ObjectiveID.

Trigger.PreserveObjectives()

Implementation unknown...

Entity ID Reference[edit]

Rooms[edit]

None, Cell, HoldingCell, Canteen, Kitchen, Shower, Yard, Storage, Deliveries, Garbage, Execution, Workshop, Security, Office, MedicalWard, Morgue, CommonRoom, Laundry, CleaningCupboard, Visitation, Solitary, Armoury, Exports, Library

People[edit]

Workman, Guard, RiotGuard, Prisoner, Doctor, Paramedic, Cook, Gardener, Janitor, Fireman, Avatar, Actor, Visitor, Warden, Chief, Foreman, Psychologist, Accountant, Lawyer, Armed Guard, Dog Handler.

External Staff[edit]

Teacher, Driver (Helps with deliveries.) National Guard(Prison Failure)

Objects[edit]

Bed, Toilet, Table, Chair, Bench, Bin, Sink, ServingTable, ShowerHead, Bookshelf, OfficeDesk, FilingCabinet, MedicalBed, MorgueSlab, WeightsBench, PhoneBooth, PoolTable, VisitorTable, IroningBoard, LaundryBasket, Sprinkler, Drain,

Doors[edit]

JailDoor, JailDoorLarge, Door, StaffDoor, SolitaryDoor, Remote Door

Door Controls[edit]

Door Control System, Servo, Logic Circuit, Logic Bridge, Door Timer, Pressure Pad, Status Light

Windows[edit]

Window, WindowLarge

Flora[edit]

Tree, GrassTurf

Electronics[edit]

ElectricChair, Light, Cooker, Fridge, MetalDetector, Tv, LargeTv, Cctv, CctvMonitor, LaundryMachine, WorkshopSaw, WorkShopPress,

Utilities[edit]

PowerStation, Capacitor, ElectricalCabl, PowerSwitch, WaterPumpStation, PipeValve, PipeLarge, PipeSmall

Vehicles[edit]

SupplyTruck, FireEngine, RiotVan, Ambulance

Items / Miscellaneous / Unknown[edit]

None, Box, Stack, Fire, Garbage, Rubble, Equipment, Prop, Dummy, Polaroid, Brick, Concrete, Steel, Bleach, SheetMetal, LicensePlateBlank, LicensePlate, Ingredients, IngredientsCooking, IngredientsCooked, Meal, FoodTray, FoodTrayDirty, PrisonerUniform, DirtyPrisonerUniform, CrumpledPrisonerUniform, DismantleObject, DismantleUtility

Materials[edit]

Dirt, Concrete

Flooring[edit]

Dirt, PavingStone, Grass, Gravel, Road, RoadMarkings, RoadMarkingsLeft, RoadMarkingsRight, Stone, ConcreteTiles, ConcreteFloor, WoodenFloor, CeramicFloor, MosaicFloor, MetalFloor, MarbleTiles, WhiteTiles, FancyTiles, BurntFloor

Walls[edit]

Fence, ConcreteWall, BrickWall, BurntWall, PerimeterWall

Miscellaneous[edit]

None, Building, Demolish, DemolishWalls, Roof, BuildingFrame