Entities are the people who appear in your prison – from the prisoners themselves, to guards, staff and special people who come with call-outs or are placed using Lua scripts.

Note: This is an Entity-specifc 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.

This guide does not cover things like gangs, needs, jobs, research etc, all of which involve entities. Those things are defined in seprate files which I'll document separately when time permits.

To give a quick overview, here's an example entity definition from the games' materials.txt:


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


If you want your entity to appear on the staff menu, you'll need to define it's price of at least $1 (see Placement – Price section later in this guide for details). No price = Entity won't appear on the menu.

Two good mods to look at for reference are JumbleBumble's InstaSoldier mod and RubenGass' Instant Prisoner mod.

First, you'll need to indicate that your object is an entity by adding the following line to it's definition in materials.txt:



By default, your entity object will be of an unknown type, but you can change that... There are currently four Entity types to choose from:

• Prisoner – probably best not to mess with this one, as prisoners are handled differently to all other entities
  
• Administrator – eg. lawyer, foreman, etc; requires an Office room
  
• Staff – eg. cooks, janitors, etc.
  
• Guard – eg. prison guard, riot guard, dog handler, etc.

Example:


Remember: Guards are staff too. Unless they are shipped in via a call-out.

Depending on the entity type, your entity will automatically be assigned some equipment. For example all Staff entities will have Staff Keys, Guard entities will have Prison Keys and so on. If desired, you can give your entity an additional item of equipment...

• Optional: You don't need to provide them with any additional equipment
  
• Value type: Enum (equipment object name as defined in materials.txt)
  
• Singleton: Can use only once per object definition
  
• Lua script: Not accessible?

For example, to give an entity a Shotgun you'd add this to your object definition:


To learn more about defining equipment, see Materials.txt – Equipment. (not yet written)

There are several properties that define the physical attributes of your entity...


Modifies the default speed of the entity.

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

Example:


Most prison staff in the game seem to be set to 0.5.


The tougher the entity, the harder they are to kill.

• Optional-ish: Defaults to 1, but you probably want >= 5
  
• Value type: Number >= 0
  
• Singleton: Can use only once per object definition
  
• Lua script: Not accessible

Example (prison guards are generally 15.0):


Most prison staff are 5.0.


Prevents your entity from getting tired.

• Optional: Defaults to getting tired (they will get tired)
  
• Value type: Enum
  
• Multiple: You can define multiple "Group" per definition, one for each value required
  
• Lua script: Not accessible

Example:


Unless you specify this property, your entity will get tired and eventually need rest. To get rest they'll go to a specific room depending on the entity type:

• Staff – Staffroom
  
• Administrator – Staffroom
  
• Guard – Security room

When the entity becomes tired, they'll go to the room to recover. Once fully recovered they'll return to their normal duties.

Some entities are hard-coded to use different resting locations. For example, dogs will rest in a dog crate in the kennels. And, if you mod armed guards to get tired, they will rest in the armoury.

Prisoners needs are handled separately via their "Needs". For more information see the Needs.txt guide. (not yet written)

For unknown entity types, there's no way to define a resting room or alter their tiredness level.


How far does the entity clear the fog of war (in map tiles) around themselves?

• Optional: Defaults to 0
  
• Value type: Integer >= 0
  
• Singleton: Can use only once per object definition
  
• Lua script: Not accessible

Example:


A good example of this in action is the Improved Staff Mod.

Entities that appear in the Staff menu (due to having their entity type defined) can be placed on the map; there's a few properties that configure how that works...


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.


Defines how much the entity costs to hire, and adds them to the Staff menu.

• Optional: Defaults to 0 (free, but won't appear on Staff menu)
  
• Value type: Integer
  
• Singleton: Can only be used once per object definition
  
• Lua script: Not accesible

Example:


In the example above, it would cost $1500 to hire the entity. Note: If you use a positive integer you will earn money when the entity is hired. (Thanks to Trixi for the info on prices!)

Note: I have no idea how the daily salary of an entity is calculated. Maybe the price for entities defines their monthly salary and the daily salary is based on that?


All entities should have a RenderDepth of 2.

• Mandatory: Set it to 2
  
• Data type: Integer
  
• Singleton: Can only be used once per object definition
  
• Lua script: Not accessible

Example:


Note: The only other values that might be feasible are 4 or 5 if you wanted to create a flying entity (like the Aviation mod).


Defines object groups that a new entity can't be placed on.

• Optional-ish: You don't need to specify these, but unless you want entities being placed in walls or other objects, it's best to do so.
  
• Value type: Bitmask (an object group)
  
• Multiple: You can define multiple "BlockedBy" per definition, one for each value required
  
• Lua script: Not accessible

Example (these three apply to pretty much all entities):


Available object groups are: Wall, StaticObject, Cable, LargePipe, SmallPipe, UtilityStation, MustBeOutdoor. As you can probably guess, only three of those are applicable to most entities.

Many of the other properties available in materials.txt can be used when defining an entity object, however their effects are somewhat hit and miss. That being said, we'll list a few of them here that are known to work.


Protagonists' Aviation Mod automatically orders fuel for its helicopter entities.



The Aviation Mod (linked above), Chad's Drink Mod and dsdude123/BigGiantRobots' Computers and More! mod define scripted entities:


Most entities, including those that come with the game, can be scripted. There are quite a few features in the Lua scripting API that enable fairly good control over entities, such as navigating them to a specific location, checking their health and so on.

Trixi's People Controller/Remover mod is another good example, it uses faux entitie objects on the Staff menu to run scripts that remove certain types of entities from your prison.

For more information on scripting, see Object Scripting with Lua.


Most entities are the default width and height of 1x1 map tiles, and for this reason you rarely see these properties defined in entity objects. However, in the Aviation mod (linked above) the helicopters are given custom widths and heights. I have no idea what would happen if you made ground-based entities have non-default width and height; would they get blocked in narrow corridors?

Sprites define how your entity looks on the map, and also what their icons will look like if they appear in the Staff menu.

Not done this section yet, it's going to take quite some time to complete.

Sprite ArmedGuard
SpriteVariants 4