Materials.txt – Objects and Utilities – Prison Architect

This guide shows how to define Objects and Utilites in materials.txt...

Introduction

As their name suggests, Objects and Utilities are things that appear on the Objects and Utilities menu in the game.

Note: This is an add-on to the main Materials.txt – Overview guide – if you are new to modding PA, it's recommended that you read that guide first to get a basic understanding of how materials.txt works.

There are actually several more flavours of "Object", but this guide only focusses on those which appear on the Objects or Utilities menu. You can find information on the other types in the Overview guide linked above.

Example Object Definition

To give a quick overview, here's an example of an object definition from a mod I'm working on:

BEGIN Object
    Name                 WarningLight
    ConstructionTime     4.00000
    Toughness            10.00000
    Price                -50
    RenderDepth          2
    AttachToWall         true
    Group                StaticObject
    BlockedBy            StaticObject
    BlockedBy            UtilityStation
    MadeOf               Composite
    Properties           Scripted
    Properties           SlowDelivery
    Properties           StaticObject
    Properties           Electrical
    Properties           Wired
    Properties           DontAvoid
    Width                1
    Height               1
    BEGIN  Sprite        x 6  y 2  h 2  w 2  RotateType 4  END
END

There are a few other applicable properties that we'll mention later, but the example above covers most of the basics.

Objects vs. Utilities Menu

In order to get your object to appear on a menu, you'll need to define at least the Name, Price and ConstructionTime properties.

    Name                 WarningLight
    Price                -50
    ConstructionTime     4.00000

These properties are discussed in more detail later in the guide.

Objects Menu

By default the game will pur your object on the Objects menu.

This menu has a special feature that allows items to be hidden by default, and then optionally show them when hovering over applicable rooms or by clicking the "+" button in the bottom right corner of the menu. To enable this feature you'll need to use the RoomSpecfiic property:

    Properties           RoomSpecific

More information on that property can be found in the "Placement Attributes" section later in this guide.

Utilities Menu

If you want it to appear on the utilities menu, you'll have to define your object to be Wired or a UtilityStation.

For more information on how to do that, see the "Utilities" section later in this guide.

Both menus?

It's not currently possible to have your object appear in both menus at the same time (similar to how Door Control and CCTV works), however you could potentially define two objects – one for each menu – and have one of the objects be scripted so it can automatically spawn the other object and then delete itself. Clunky, but it's the only working solution at present if you want something on both menus.

Physical Attributes

Width and Height

These properties define the size of the object (in map tiles).

• Optional: Defaults to 1
  
• Value type: Integer >=1
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    Width                1
    Height               1

It's common to always specify the width and height, even if your object is using a default size of 1x1 (an exception to this rule is Entity objects).

BlockMovement

This property only applies to Materials, not Objects. For more information see Materials.txt – Materials. (not written yet)

For Objects, use the following property instead...

Properties – BlockMovement

Does this object block movement?

• Optional: Defaults to not blocking movement
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

By default your objects won't block movement. A good example is the serving table in the canteen - people can walk straight throuh it. To stop people walking through your object add the following:

    Properties           BlockMovement

See also: Properties – DontAvoid (later in this section)

BlockVisibility

Does this object block vision (clearing fog of war) of Entity objects?

• Optional: Defaults to false
  
• Value type: Boolean (true or false)
  
• Singleton: Can be used only once per object definition
  
• Lua script: Not accessible

Example:

   BlockVisibility      true

See also: ViewRange property in Materials.txt – Entities.

Properties – DontAvoid

Should the patfinder ignore this object?

• Optional: Defaults to people avoiding the object
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           DontAvoid

Even if your object doesn't block movement (in which case the pathfinder will always avoid it), the pathfinder will generally try and avoid it if there are alternate routes available. By adding this property you tell the pathfinder that people can freely walk over, through or under your object (pressure pads, shower heads and sprinklers are good examples).

MadeOf

What is the object made of?

• Optional: Defaults to None
  
• Value type: Enum
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    MadeOf               Wood

Valid values are: None (not sure what effect this has), Wood (highly flammable), Composite (slightly flammable), HollowMetal (not sure what effect this has), SolidMetal (detected by metal detectors).

MoveSpeedFactor

How does the object affect movement speed?

• Optional: Defaults to 1
  
• Value type: Numeric between 0 and 1 (eg. 0.95 = 95% of normal speed)
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    MoveSpeedFactor      0.96

If your object is an entity, this property will define the default walking speed of your entity.

If your object is anything else, the property will affect the speed of anyone carrying the object (eg. workers will walk slower when carrying a power generator), and also the speed of anyone who walks through or over the object (eg. people will walk slower when passing through a metal detector).

Note: For Materials (see Materials.txt – Materials) use the MoveCost property to define whether they are slow, normal or fast.

Properties – ShelfObject

Does this object have shelves (like a library bookshelf)?

• Optional: Defaults to not having shelves
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties          ShelfObject

I've not used this property yet, but from what I can tell it needs to be used in conjuction with a StackSprite.

Properties – StaticObject

Can this object be dismantled/dumped (most objects are defined as StaticObject)?

• Optional: Defaults to not being a static object
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           StaticObject

When the object is selected on the map, it's info panel will have "Dismantle" and "Dump" options. If the object is dismantled, it will be taken to the storage room. If it's dumped, it will be taken to the garbage area.

Note: It's possible this property is required to make an object appear on the Objects menu (not tested - if you know please comment with details).

Toughness

How robust is the object?

• Optional: Defaults to 1.00
  
• Value type: Number >= 1.00
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    Toughness            1

Most objects have a toughness between 1 (eg. power switch) and 50 (eg. water pump). A solitary door has toughness of 300. The tougher something is, the harder it is for prisoners to destroy.

Group – Wall

Is this object a Wall?

• Optional: Defaults to not being a wall
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Group" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Group               Wall

I've never seen this used, even in the games' materials.txt. I suspect that a Material (see Materials.txt – Materials) with a name starting with "Wall" is automagically put in to this group. The primary purpose of the group seems to be in relation to object placement, where objects can be "BlockedBy Wall".

Delivery Attributes

These properties define object cost and delivery method.

MaxStackSize

How many of units of the object can be stacked in to a crate or box?

• Optional: Defaults to 1
  
• Value type: Integer >= 1
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    MaxStackSize         10

This can help speed up deliveries; rather than having trucks deliver units one by one, they can be stacked in to a box or crate. A good example is building materials such as pipes or electric cable.

For materials, the stack size defines how many items can be stacked on to a tray or box, etc. Good examples include food, mail and license plates.

Rubbish can also be stacked in to bins or bin bags (see Properties – Rubbish).

To properly use stacks, appropriate sprites must be defined for small, medium and large stacks (in addition to the sprite for a single unit). For more information see Sprites – StackSprite.

Price

How much does the object cost to place/build?

• Optional: Defaults to 0 (free)
  
• Value type: Negative integer (eg. -100 means it costs $100)
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    Price                -50

Properties – SlowDelivery

Should the object be delivered by truck, or just magically appear at the Deliveries area?

• Optional: Defaults to normal delivery
  
• Value type:
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Normal delivery means the item will usually just magically appear in the Deliveries area, unless there's already a truck which has some available space waiting to enter the map in which case it will be delivered by that truck.

Slow delivery means that the item will always be delivered by truck, even if a new truck has to spawn to make that possible. To use slow delivery add the following to your object definition:

    Properties           SlowDelivery

Teleportable

Do workers have to collect the object from the Deliveries/Storage area, or does it just magically teleport to their hands?

• Optional: Defaults to false (workers must collect item from deliveries or storage)
  
• Value type: Boolean (true or false)
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible

Example:

    Teleportable         true

The property is most commonly set to true for items that are very regularly placed (lights, doors, etc) to ensre construction can be completed in a reasonable time frame. This is particularly important for ongoing jobs whch are initially fast when the prison is small, but get exponentially slower as the prison gets bigger – the user will notice the jobs are taking longer and longer to complete. By making an object teleportable, the game can teleport it if the travel distance (ie. time) is prohibitively long.

Placement Attributes

The next batch of properties define the basics of where and how your object can be placed on the map.

AttachToWall

When constructed, should the object position be tweaked to move it closer to adjacent walls?

• Optional: Defaults to false
  
• Value type: Boolean (true or false)
  
• Singleton: Can be used only once per object definition
  
• Lua scripts: Not accessible, although there is a .Walls property that tells you if an object is adjacent to walls

To set the value to true, use:

    AttachToWall         true

Note: Attaching things to walls is notoriously clunky, especially when objects are placed in a corner.

Properties – BuiltOnWall

Should this object be built on walls?

• Optional: Defaults to not needing to be built on walls
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           BuiltOnWall

This causes the object to be only placable on walls. Windows and shop fronts are good examples of this.

BlockedBy

What groups of objects block placement of your object?

• Optional: Defaults to not being blocked by anything
  
• Value type: Bitmask
  
• Multiple: You can define multiple "BlockedBy" per object definition, one for each value required
  
• Lua scripts: Not accessible

Example:

    BlockedBy            Wall
    BlockedBy            StaticObject
    BlockedBy            UtilityStation

Valid values (for both Group and BlockedBy properties) are: Wall, StaticObject, Cable, LargePipe, SmallPipe, UtilityStation.

To add an object to a group, use the Group property, for example:

    Group                UtilityStation

That would then prevent any object that's "BlockedBy UtilityStation" to be placed on your object.

Walls are a special case in that they apply to materials (see Materials.txt – Materials). Simply including the word "Wall" in the material name in that context will cause it to be added to the Walls group. I've not tried to see what will happen if a normal object is added to "Group Wall".

BlockedBy – MustBeOutdoor

The MustBeOutdoor value is unusual in that it's never defined as a Group value. Instead, it only works when used as a BlockedBy value.

• Optional: Defaults to allowing build indoors
  
• Value type: Bitmask
  
• Multiple: You can define multiple "BlockedBy" per object definition, one for each value required
  
• Lua scripts: Not accessible

    BlockedBy       MustBeOutdoor

This will add a requirement that your object cannot be built inside or on building walls; it must be built outside.

Note: For rooms, use the "Requirement Type Indoor" or "Requirement Type Outdoor" properties (see Materials.txt – Rooms for details). For materials, use the IndoorOutdoor property (see Materials.txt – Materials for details).

Properties – CanPlaceOnRoad

Can this object be placed on roads?

• Optional: Defaults to not placeable on roads
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Be careful when using this property as most objects will block road traffic and visitors from using the road (depending on how you define the object of course).

Research

Is research required before the entity becomes available?

• Optional: By default no research is required
  
• Value type: Enum (research name as defined in research.txt)
  
• Singleton: Can use only once per object definition
  
• Lua script: Not accessible

Example:

    Research             Armoury

For more information on research tasks, see Research.txt – Overview.

RenderDepth

What z-index (layer) does the object appear on?

• Optional: Defaults to 0 (materials layer, not recommended for most objects)
  
• Value type: Integer between 0 and 3
  
• Singleton: Can be used only once per object defintion
  
• Lua scripts: Not accessible

Example:

    RenderDepth          2

Valid depths are:

• 0 – Ground layer (underneath everything): Grass, floor tiles, road...
  
• 1 – Buildings and fixtures: Walls, toilets, pressure pads...
  
• 2 – Room objects: Chairs, tables, prisoners...
  
• 3 – Overhead objects: Lights, sprinklers, shower head...

I've seen values of -1 and 4 be used on rare occasions, although it's not clear what effects - if any - that has.

RenderPostOffset

No idea what this property does (spotted on WeightsBench object).

    RenderPostOffset     2

RenderPreOffset

No idea what this property does (spotted on RoadGate object).

    RenderPreOffset      -2

Properties – RoomSpecific

This doesn't actually alter where an object can be placed. Instead it hides the object from the Objects menu until an applicable room is being viewed on the map.

Should the object be hidden on the Objects menu by default?

• Optional: Defaults to always show
  
• Value type: Attribute
  
• Singleton: Can be used only once per object definition
  
• Lua script: Not accessible

Example:

    Properties           RoomSpecific

This will hide your object on the menu. In order to see it the user will have to click the "+" in the bottom right corner of the menu that shows all items.

If you want to have your object automatically appear when the user is viewing a room where it can be used, you'll have to list your object in the room definition. For more information on that, see Materials.txt – Rooms (not written yet).

Properties – Uncloneable

Can the object be cloned using the clone tool?

• Optional: Defaults to cloneable
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           Uncloneable

This is most commonly used on objects that have the "Properties – Material" property (things like food trays, mail, etc – see Materials.txt – Consumables for details), but can be applied to any object.

It seems that Entity (people) objects are automatically given this property.

Processors & Providers

There are a few properties relating to processors (eg. a workshop saw, cooker, etc) and providers (chairs, toilets, etc).

Properties – Processor

Is this object a processor?

• Optional: Defaults to normal object
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible (although you can access Slots, see later)

Example:

    Properties           Processor

A processor converts input materials in to output materials. It needs three slots – this is why most processors have a width of 3.

Note that you'll need to define production rules in a separate text file before it will actually work (I'm still learning how to do this myself and will update when I know more).

NumSlots

How many slots (interfaces to other objects) does this object have?

• Optional-ish: Defaults to 0. If you mark the object as a processor you should have at least 3.
  
• Value type: Integer >= 0
  
• Singelton: Can be used only once per object definition
  
• Lua script: Not accessible, although you can access and use all 8 slots (Slot0 .. Slot7) regardles of this property

Example (a table object):

    NumSlots             4

Used for ProductionRules, Providers, Processors and Vehicles.

Processors: Needs three slots (Input, Workplace, Output).

Vehicles: Defines how many items (entities, materials, etc) can be carried by a vehicle.

Note: The positions of slots are defined as part of the sprite definition. See "Sprites" section at end of this guide for more details.

AutoOrder

Should this object automatically order whatever resource it needs, and if so what should it order?

• Optional: Defaults to not ordering anything
  
• Value type: Object name (usually a material object; for example: Ingredients)
  
• Singleton: Can be used only once per object definition
  
• Lua script: Not accessible

Example:

    AutoOrder           ShopGoods

AutoOrderQuantity

If auto-ordering, how many units of the resource should be ordered?

• Optional-ish: Defaults to 0. If you enable auto-ordering you should probably set it to 1 or more
  
• Value type: Integer >= 0
  
• Singleton: Can be used only once per object definition
  
• Lua script: Not accessible

Example:

    AutoOrderQuantity   30

Properties – Sellable

Note: Not currently compatible with Properties – SlowDelivery.

Is the object sellable (via Exports room)?

• Optional: Defaults to not being sellable
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           Sellable

Items made in the workshop are good examples of sellable objects.

Workers object & Worker

Which entities can work at a processor?

• Optional: Defaults to any applicable worker
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Worker" per object definition, one for each value required
  
• Lua script: Not accessible

Example (from WorkshopSaw object):

    BEGIN Workers
        Worker           Prisoner
    END

Only the WorkshopSaw seems to use this and I'm not sure why.

Workgroup

Which workgroup is the object associated with?

• Optional: Defaults to no workgroup
  
• Value type: String (name of the workgroup)
  
• Singleton: Can be used only once per object definition
  
• Lua script: Not accessible

Example:

    WorkGroup            Library

I'm still trying to wrap my head around what this property actually does. From what I can tell it links Rooms and Objects together from the perspective of reform programme qualifications. So the qualification will enable people to work in the room, and the Workgroup of that room defines which objects (having the same Workgroup) they can use within the room. Or something like that.

Utilities & Electrics

This collection of properties relate to utility stations, electrics and wired connections.

Group – Cable

Defines the object to be an electric cable. Never seen a mod use this property so don't have any more information about it currently. If you try it, please comment to let us know the outcome.

Properties – Electrical

Does the object require electric power?

• Optional: Defaults to not needing electricity
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Too many bugs to list

Example:

    Properties           Electrical

This property doesn't seem to work – even when specified, objects will not require power. I was hoping it would mean that an object required direct link to cables, or at least auto-linked by one of those small electric wires (like lights, etc).

It's possible that if an Electrical object comes in to contact with water, it will electrocute anyone stood in the same water, although I've not tested this.

Properties – ExplodeWhenWet

Should the object explode if it comes in to contact with water?

• Optional: Defaults to not exploding
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           ExplodeWhenWet

Common sources of water include showers, broken toilets, and firemen who can hose a room with water. There are potentially other sources that I don't know about.

Group – UtilityStation

Is this object a UtilityStation (like a Door Control, CCTV Monitor, etc)?

• Optional: Defaults to not being a utility station
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Group" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Group               UtilityStation

I'm not sure what specific effect this has, or how it relates to the "Properties – Utility" property. If you try it and find any new effects, please comment with details.

Properties – Utility

Is this object a Utility (like a power station, capacitor, switch, water pump, etc)?

• Optional: Defaults to not being a utility
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Not accessible

Example:

    Properties           Utility

I'm not sure what specific effect this has, or how it relates to the "Group – UtilityStation" property. If you try it and find any new effects, please comment with details.

Properties – Wired

Should the object allow wired connections (just like CCTV and Logic Circuits)?

• Optional: Defaults to not wired
  
• Value type: Bitmask
  
• Multiple: You can define multiple "Properties" per object definition, one for each value required
  
• Lua script: Too many bugs to list

Example:

    Properties           Wired

Themias' Road Sensors mod is a good example of a wired object.

Water & Plumbing

I've never seen a mod use these properties so please excuse the lack of information in this section. If you use the properties please leave a comment to let us know what the outcome was.

Also, there doesn't appear to be any way to define a water source for pipes (like a custom water pump). Likewise, there is currently no way to indicate that a custom object requires water to operate (like a custom sprinkler, shower or toilet).

Group – LargePipe

Defines the object as a large pipe, which has no range limit (as far as I know).

    Group        LargePipe

Group – SmallPipe

Defines the object as a small pipe, which limits the range of water flow (I'm not sure what the limit is).

    Group        SmallPipe

Sprites

I need some time to think about the best way to document sprites. :/

[murgh]

"RenderPostOffset

No idea what this property does (spotted on WeightsBench object)."

This is also on DogCrate, and seems to be there to make the crate hood appear on top of the dog. Try it youself: change renderdepth of Dog to 3, and the dog will be on top. Adjust the RenderPostOffset on the Crate to 4, and the dog will be inside the crate again.

[Unknown]

Came here only to see sprites. And I was disappointed :/

[murgh]

Hmm it seems to only enable the Dump option on an object, not Dismantle.

[murgh]

Property 'MobileObject' spotted on mail satchel, any idea what this does?

[murgh]

Note for AutoOrder:

The ordered object (shopgoods) has to be defined in materials.txt BFORE the processing object which is ordering that object. If the stuff to order is defined after the processor, an error will show up in debug.txt about invalid enum value (shopgoods) and the whole auto order won't work.

[Mr.Lawrence]

nice!

[DARKNESS]

Nice guide, thank you!