Lua function list.txt

From Prison Architect Wiki
Jump to navigation Jump to search
Function List
____________________________________________

Object.GetProperty
    Format:
    (1) GetProperty( ObjectTable, PropertyName )
    (2) GetProperty( ObjectName, PropertyName )
            - Used to get the "objectName" table
    (3) GetProperty( PropertyName )
            - Used on the "me" object
    (4) objectTable.PropertyName
    
    Gets a property on an object's DataRegistry. If no object name is given, it defaults to the current object.
    If the property can not be found in the DataRegistry, and no ObjectName is given, then look for the property in the 
        object's ScriptState blackboard.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). PropertyName is then used as a table index, and can be used in the standard Lua ways. For example, this.Damage 
        or this[ "Damage" ]. 
        N.B. Any name that has a dot in it will be initialised as a lua table, with appropriate variables from the name. For
        example, the property name "Pos.x" can be called in the following manners:
            - local x = this.Pos.x
            - local x = this[ "Pos.x" ]
    
    ObjectTable/ObjectName:     Optional. Defaults to the object that the script is running on.
    PropertyName:               Required. Name of the property to set.
    
    Returns:        The value of the property on the named object, or nil
____________________________________________

Object.SetProperty
    Format:
    (1) Object.SetProperty( ObjectTable, PropertyName, Value )
    (2) Object.SetProperty( ObjectName, PropertyName, Value )
            - Used to get the "ObjectName" table
    (3) Object.SetProperty( PropertyName, Value )
            - Used on the "me" object
    (4) objectTable.PropertyName
             
    Sets a property in an object's DataRegistry. If no object name is given, it defaults to the current object.
    If the named property can not be found in the DataRegistry, and no ObjectName is given, then set the property in the 
        object's ScriptState blackboard.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). PropertyName is then used as a table index, and can be used in the standard Lua ways. For example, this.Damage 
        or this[ "Damage" ] 
        N.B. Any name that has a dot in it will be initialised as a lua table, with appropriate variables from the name. For
        example, the property name "Pos.x" can be called in the following manners:
            - this.Pos.x = x
            - this[ "Pos.x" ] = x
    
    ObjectTable/ObjectName:     Optional. Defaults to the object that the script is running on.
    PropertyName:               Required. Name of the property to set.
    Value:                      Required. The value to set to the named property.
    
    Returns:        N/A
____________________________________________

Object.Spawn
    Format:
    (1) Spawn( ObjectTypeName, X, Y )
    
    Spawns an object of type ObjectTypeName at position X,Y
    
    ObjectTypeName: Required. The name of an Object listed in materials.txt.
    X:              Required. The x-position of the spawned object.
    Y:              Required. The y-position of the spawned object.
    
    Returns:        The identifier name of the object spawned, or nil if no object is spawned.
____________________________________________

Object.Delete
    Format:
    (1) Object.Delete( ObjectTable )
    (2) Object.Delete( ObjectName )
            - Use to get the "objectName" table
    (3) Object.Delete()
            - Used to on the "me" table
    (4) objectTable.Delete()
    
    Deletes a named object.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.Delete()
    
    ObjectTable/ObjectName:     Optional. The table/name of an Object to be deleted. Defaults to the object the script
                                    is running on.
    
    Returns:        N/A
____________________________________________

Object.ApplyVelocity
    Format:
    (1) Object.ApplyVelocity( ObjectTable, X, Y[, Rotate] )
    (2) Object.ApplyVelocity( ObjectName, X, Y[, Rotate] )
            - Use to get the "ObjectName" table
    (3) Object.ApplyVelocity( X, Y[, Rotate] )
            - Used to on the "me" table
    (4) objectTable.ApplyVelocity( X, Y[, Rotate] )
             
    Applies an animation velocity to the named WorldObject
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.ApplyVelocity( 2.0, 5.0, false )
    
    ObjectTable/ObjectName:     Optional. The table/name of an Object. Defaults to the object the script is running on.
    X:                          Required. The x-velocity of the object.
    Y:                          Required. The y-velocity of the object.
    Rotate:                     Optional. Should the velocity cause some mild rotation? Defaults to true.
    
    Returns:        N/A
____________________________________________

Object.GetMaterial
    Format:
    (1) Object.GetMaterial( X, Y )
    
    Gets the material name for the cell X,Y
    
    X:              Required. The x-location of the cell.
    Y:              Required. The y-location of the cell.
    
    Returns:        The name of the material at cell X,Y.
____________________________________________

Object.CreateJob
    Format:
    (1) Object.CreateJob( ObjectTable, JobName )
    (2) Object.CreateJob( ObjectName, JobName )
            - Use to get the "objectName" table
    (3) Object.CreateJob( JobName )
            - Used to on the "me" table
    (4) objectTable.CreateJob( JobName )
    
    Create a custom job on the given object.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.CreateJob( "MyJob" )
    
    ObjectTable/ObjectName:     Optional. The table/name of an Object. Defaults to the object the script is running on.
    JobName:                    Required. The name of the job.
    
    Returns:        N/A
____________________________________________

Object.GetNearbyObjects
    Format:
    (1) Object.GetNearbyObjects( ObjectTable, TypeName, SearchDistance )
    (2) Object.GetNearbyObjects( ObjectName, TypeName, SearchDistance )
            - Use to get the "objectName" table
    (3) Object.GetNearbyObjects( TypeName, SearchDistance )
            - Used to on the "me" table
    (4) objectTable.GetNearbyObjects( TypeName, SearchDistance )
             
    Gets a table of all entities of type TypeName that are within SearchDistance of the calling object.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.GetNearbyObjects( "Guard", 50.0 )
    
    ObjectTable/ObjectName:     Optional. The table/name of an Object. Defaults to the object the script is running on.
    TypeName:                   Required. The type of entity to search for.
    SearchDistance:             Required. The distance from this scripted object to search within.
    
    Returns:        A table of object tables and their distance to the calling object. 
                    N.B. Both name and distance values will be returned as strings.
____________________________________________

Object.NavigateTo
    Format:
    (1) Object.NavigateTo( ObjectTable, X, Y )
    (2) Object.NavigateTo( ObjectName, X, Y )
            - Use to get the "objectName" table
    (3) Object.NavigateTo( X, Y )
            - Used to on the "me" table
    (4) objectTable.NavigateTo( X, Y )
             
    Navigates ObjectTable/ObjectName to the point (X,Y). The object must be an Entity. If no object name is given, 
        it defaults to the current object.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.NavigateTo( 25.0, 50.0 )
    
    ObjectTable/ObjectName:     Optional. Must be an entity. Defaults to the object that the script is running on.
    X:                          Required. The x-location of the cell.
    Y:                          Required. The y-location of the cell.
    
    Returns:        N/A
____________________________________________

Object.ClearRouting
    Format:
    (1) Object.ClearRouting( ObjectTable )
    (2) Object.ClearRouting( ObjectName )
            - Use to get the "objectName" table
    (3) Object.ClearRouting()
            - Used to on the "me" table
    (4) objectTable.ClearRouting()
    
    Clears any routing that the ObjectTable/object called ObjectName has. The object must be an Entity. If no object 
        name is given, it defaults to the current object.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.ClearRouting()
    
    ObjectTable/ObjectName:     Optional. Must be an entity. Defaults to the object that the script is running on.
    
    Returns:        N/A
____________________________________________

Object.Sound
    Format:
    (1) Object.Sound( ObjectTable, SoundGroup, SoundId )
    (2) Object.Sound( ObjectName, SoundGroup, SoundId )
            - Use to get the "objectName" table
    (3) Object.Sound( SoundGroup, SoundId )
            - Used to on the "me" table
    (4) objectTable.Sound( SoundGroup, SoundId )
             
    Triggers a sound event at the given object's position.
    In format 4, objectTable can refer to a return object's table or the "this" table (for the object the script is running 
        on). For example, this.Sound( soundGroupName, soundIdName )
    
    ObjectTable/ObjectName:     Optional. Defaults to the object that the script is running on.
    SoundGroup:                 Sound group name (defined by OBJECT in sounds.txt)
    SoundId:                    Sound name (defined by EVENT in sounds.txt)
    
    Returns:        N/A
____________________________________________

prisonerTable.ReoffendingChance
	Only works on a prisoner's objectTable. Returns a number between 0 and 1 indicating the chance of that prisoner reoffending.
	N.B. This is a cfunction call, which can be expensive. Try not to call it every tick.
    
    Returns:        The reoffending chance, from 0 to 1, of a prisoner.
____________________________________________

objectTable.Tooltip = "language_string_id"
objectTable.Tooltip = { "language_string_id", 
							"replacement_string_id", flag1, 
							"some string", flag2, 
							4, flag3, 
							... }
							
	Sets the tooltip extra of an objectTable, and optionally allows marker replacement from the language string.
	N.B. This is a cfunction override for the previous Object.SetProperty call to "Tooltip". SetProperty will still work, but won't
		allow marker replacements.
		
	The first version of this call takes a single language string id as it's parameter. The tooltip is set from the language 
		file, or (if this string id does not exist in the language file) the string itself.
		
	The second version takes a table containing (first) the language string id (or a string literal if it does not exist in the 
		language file), followed by any number of replacement strings with their flag character to replace. The replacement 
		strings can be string literals, language string ids, or numbers. The flag must be a string (eg "X"), the first character 
		of which is used to match a flag (eg, "*X") in a language string (eg "My *X string"). The markers must be unique to the 
		replacement string, as all occurences of a marker will be replaced with the first replacement string found.
    
    Returns:        N/A
____________________________________________

Game.Time()
    Returns the current game time in seconds. Useful for timing events and checks.
    
    Returns:        A string of the current game time.
____________________________________________

Game.DebugOut( Message )
    Prints a debug message to the script debugger window. Opens the window if it is not yet opened.
    N.B. As this functions opens a debug window, you should only use this function for testing purposes
        and remove any calls before publishing your mod.
        
    Message:        A string to print to the debug window.
    
    Returns:        N/A
____________________________________________

World.GetCell( x, y )
    Returns a WorldCell table for the given xy position. If the position is out of bounds, an empty table is returned.
    
    x:              CellX position
    y:              CellY position
    
    Returns:        A table for the given position, or an empty table for an invalid position.
____________________________________________

World.NumPrisoners
    Returns a table containing category names to the total number of known prisoners in that category. This number may be
		incorrect on level loading until the simulation has caught up with the world state.
	N.B. This is a cfunction call, which can be expensive. Try not to call it every tick. Cache the result and only update 
		it every now and then.
    
    Returns:        A table listing prisoner category names to the number of prisoners of that category.
____________________________________________

World.Capacity
    Returns a table security level names linked to the number of cells available in that sector. This number may be incorrect
		on level loading until the simulation has caught up with the world state.
	N.B. This is a cfunction call, which can be expensive. Try not to call it every tick. Cache the result and only update 
		it every now and then.
    
    Returns:        A table listing security level names to the number of cells of that security category.
____________________________________________

Interface.AddComponent( objectTable, componentName, componentType, captionId, [args] )
objectTable.AddInterfaceComponent( componentName, componentType, captionId, [args] )

    Adds a dialog component to the BiographyWindow of an object that will cause a callback on that object's script when clicked.

    objectTable:    The table of an Object.
    componentName:  String for a unique component name
    componentType:  String for the component type to create. Valid types are just "Button" and "Caption" at the moment
    captionId:      Id of a string in the language table, or (if it doesn't exist) just a string
    [args]:         Can optionally be followed by a list of strings (or numbers that will be converted to strings) and 
                        chars used to replace flags in the language string.
                        
    N.B. strings will be looked up in the language table first, and if available, converted to language strings 
    before being inserted. This will allow localised strings to be placed into either other. Otherwise the plain 
    string (in the case of a number or similar) will be inserted.
    
    Returns:        N/A
____________________________________________

Interface.RemoveComponent( objectTable, componentName, componentType, captionId, [args] )
objectTable.RemoveInterfaceComponent( componentName, componentType, captionId, [args] )

    Removes a named dialog component from the BiographyWindow of an object.

    objectTable:    The table of an Object.
    componentName:  String for a unique component name 
    
    Returns:        N/A
____________________________________________

Interface.SetCaption( objectTable, componentName, captionId, [args] )
objectTable.SetInterfaceCaption( componentName, captionId, [args] )

    objectTable:    The table of an Object.
    componentName:  String for a unique component name.
    captionId:      Id of a string in the language table
    [args]:         Can optionally be followed by a list of strings (or numbers that will be converted to strings) and 
                        chars used to replace flags in the language string.
    
    N.B. strings will be looked up in the language table first, and if available, converted to language strings 
    before being inserted. This will allow localised strings to be placed into either other. Otherwise the plain 
    string (in the case of a number or similar) will be inserted.
    
    Returns:        N/A
____________________________________________

WorkQueue.Request( RequestTypeStr, args )

    RequestTypeStr:	A string name of the required request type (see below).
    args:         	List of arguments for the given request type (see below).
    
	Request types:
	- "Construction":       materialType, X, Y
	- "PlaceObject":        objectType, X, Y[, OrientationX=0, OrientationY=1]
	- "MoveObject":         objectTable, X, Y
	- "DismantleObject":    objectTable
	- "DumpObject":         objectTable
	- "SellObject":         objectTable
	- "RepairObject":       objectTable
	- "SearchObject":       objectTable
	- "EscortPrisoner":     prisonerTable, X, Y
	
	N.B. Orientation X and Y on PlaceObject default to 0 and 1 respectively, so are optional. All other args are required.
	materialType and objectType can be string names from materials.txt or integers.
    
    Returns:        N/A
____________________________________________