The Bureaucracy screen lists all research tasks that are available in your prison; these are all defined in research.txt.

Almost all other aspects of the game can be made dependent on research being completed, for example you could block access to a room, refrom program or object until certain research has been completed.


There are two flavours of research: Entity and Ability.

An Ability research is used to unlock other features in the game (objects, rooms, grants, etc).

An Entity research is the same as Ability but is used to semantically indicate that the purpose of the research is to gain access to a new member of staff. The corresponding entity (and what, if any, research it requires to become available) must be defined in materials.txt; for more information see Materials.txt – Entities.


In the various other text files, such as materials.txt, reform_programs.txt, etc., you add a "Research <name>" (where <name> is replaced with the name of your resarch) property to your definitions. Whatever is being defined will now require your research task to be completed before whatever is associated with that definition is enabled.

In terms of scripting, the only script environment that currently interfaces with research is grants.lua (and possibly scenarios too – not checked).

As it's name suggests, research.txt is just a text file. It needs to be in the right location and contain the right information for it to actually do anything...


To add or update research tasks, you'll first need to create a research.txt file in the 'data' folder of your mod.

For example, if your mod is called "Your Mod", the path to research.txt would be something like this:

..../Prison Architect/mods/YourMod/data/research.txt

Note that the filename 'research.txt' is in lowercase; it won't work any other way.


Once you've made a research.txt, you can start defining research tasks. Here's an example of one of the research tasks that comes with the game:



Each research task is wrapped in a BEGIN .. END statement like this:


The various properties of the research task are then defined between those two lines (where the .... is).


Currently, all properties are in the form of a "name value" pair, like this:


The first word is the property name, then there's at least one space, then the value. In the example above we've defined the "Name" property to have a value of "GroundsKeeping", the "Type" property to have a value of "Entity" and the "Requires" property to have a value of "Maintainance".

It doesn't matter how many spaces (if any) appear at the start of the line, or how many spaces are between the property name and it's value (as long as there is at least one space). It's convention to use spaces to indent all the property names and to align all their values.

Every definition in research.txt must have a Name property that defines it's unique ID in the game.

• Mandatory: Must be specified for every definition
  
• Value type: String (should be TitleCase with no spaces)
  
• Singleton: Can appear only once per definition
  
• Lua Scripts: ??

Although it doesn't matter where the name appears in the definition, everyone always puts it as the first item immediately after the "BEGIN Research" line.

Example of a correclty defined name:


Examples of incorrectly defined names:


If you specify a name of a research task that already exists then your definition will replace the existing definition.

If you specify a name that doesn't exist, you'll create a completely new research task with the specified name.


To ensure the name is correctly displayed in the game (eg. on the menu, tooltips, etc) you should define it's translation in ..../YourMod/data/Language/base-language.txt.

In the case of the BaconButty example above, the language strings would be defined as follows:


As you can see there are two items. The first one is used to provide the localisation of the Name property itself. The second one is optional and can be used to add some descriptive text to the tooltip when hovering over the research task (a "\n" in it's value will make the text after it start on a new line).

These attributes define your research task...


Is this an Ability or Entity?

• Mandatory: Must be specified for every definition
  
• Value type: Enum (Ability or Entity)
  
• Singleton: Can be used only once per definition
  
• Lua script: Not accessible

Example:


As mentioned at the start of the guide, an Ability is a general research task. It's like a flag that, once set by completing the research, can be used to enable other features in the game.


The Entity type is the same as an Ability but semantically has the sole purpose of enabling a new member of staff on the Staff menu. The icon on the Staff menu will get an overlay indicating how many of that entity type that is currently hired.

Bug #9758[bugs.introversion.co.uk]: It's not currently possible to define the hiring limit (the game currently hard-codes limits for special entities like Warden and Foreman).

The actual enabling of the entity is handled by the "Research" property of the entity definition; it's up to you whether you want the entity to require some research before it can be hired. For more details see Materials.txt – Entities.


Before starting your research task, does the user have to complete some other research task?

• Optional-ish: Defaults to None, but it will be inconsistent with the game if your research doesn't require completion of some other research first.
  
• Value type: Name of a research task
  
• Singleton: Can be used only once per definition
  
• Lua script: Not accessible

Example:


In the example above, the user would have to research Security before they could research your task.


Who performs the research?

• Mandatory? All other tasks require a member of administration staff so I assume it's mandatory.
  
• Value type: Name of any entity object that has "Properties Administration"
  
• Singleton: Can be used only once per definition
  
• Lua script: Not accessible

Example:


Because the research is performed in an office, and only Administration staff can be assigned to offices, the entity has to have the property "Properties Administration".

You can define your own Administration staff in materials.txt. For more information see Materials.txt – Entities.


How much does this research cost?

• Optional: Defaults to 0 (free)
  
• Value type: Negative integer <= 0 (eg. -1000 would mean $1000)
  
• Singleton: Can be used only once per definition
  
• Lua script: Not accessible

Example:


If you want to provide a reward for completing research, do that via grants.lua.


How long does the research take (in game minutes)?

• Optional: Defaults to 0
  
• Value type: Integer >= 0 (eg. 60 would mean 1 game hour)
  
• Singleton: Can be used only once per definition
  
• Lua script: Not accessible

Example (6 game hours):

These define how the research task appears on the Bureaucracy screen.


What is the fixed position (from top-left corner, in pixels) of the postit note on the Bureaucracy screen?

• Mandatory: Must be specified for every research definition
  
• Value type: Integer >= 0 (pixels)
  
• Singleton: The properties can be used only once per definition
  
• Lua scripting: Not accessible

Example:


Since Alpha 34 there are two additional propterties which define the position when the game is viewed on a smaller display:


The use of hard-coded positions is utterly stupid. A bug has been reported to get it changed, please comment/support it: Bug #9597[bugs.introversion.co.uk].


Should the postit note have an icon on it?

• Optional: Defaults to no icon (and a smaller postit note)
  
• Value type: Sprite name as defined in the spritebank
  
• Singleton: Can be used only one per definition
  
• Lua script: Not accessible

Example:


It's not currently possible to define your own sprite using sprites.png, which makes it very difficult to get your own icon shown on the postit note (while it's possible to update the game's spritebank and associated image files, it's too error prone to be worth it). A bug has been reported to get this fixed, please comment/support it: Bug #9596[bugs.introversion.co.uk].