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.

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


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


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


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


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:


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


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.


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.

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:


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


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


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:


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


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:


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


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:


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


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:


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


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:


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.


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:

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


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:


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


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:


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.


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:


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

These properties define object cost and delivery method.


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:


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.


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:



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:



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:


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.

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


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:


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


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:


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


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:


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:


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


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

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


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


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:


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


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:


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.


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



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



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:


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


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:


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.

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


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:


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


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


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.


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:



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:



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:


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


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


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


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:


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.

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


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.


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:


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.


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:


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.


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:


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.


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:


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.


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:


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

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


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



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

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