Almost everything that appears on the map is defined by materials.txt. If you want to add a new object, person, vehicle, consumable, tool, weapon, ground texture or just about anything else, this is the place to do it. You can also override definitions of stuff that comes with the game.


Pretty much everything that appears on the map is defined by materials.txt:

• Callout – emergency service call outs
  
• Equipment – contraband, tools and weapons
  
• Material – ground textures, building foundations and walls
  
• Object – there are several flavours of object (all of which can be scripted):
  • Entities – people such as guards, dogs, prisoners, staff, etc.
    
  • Vehicles – trucks, cars, etc.
    
  • Objects & Utilities – stuff you can build in your prison (desks, showers, CCTV, etc)
    
  • Consumables – stuff like food, mail and clothes
• Room – uhm, rooms :)

As it's name suggests, materials.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 materials, you'll first need to create a materials.txt file in the 'data' folder of your mod.

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


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


Once you've made a materials.txt, you can start defining things.

Each type of thing that you can define in materials.txt has it's own set of properties. For example, here's what an Object definition might look like:



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


After "BEGIN" is a word that defines what sort of thing it is. The properties that follow on the following lines (....) until the "END" statement are the properties defining that thing.


Most properties are in the form of a "name value" pairs, 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 "WarningLight", the "ConstructionTime" property to have a value of 4.00000 and the "Toughness" property to have a value of 10.00000.

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.

Some properties, like Name, can only be used once per definition. Others, like "BlockedBy" or "Properties", can be used multiple times to specify multiple values for the same property.

There are some special properties that have their own BEGIN .. END wrapper, for example:


In this example, we're defining a property called "Sprite" that itself has child properties (x, y, etc). It's more obvious if we separate things on to separate lines (both formats will work, it's personal preference as to which you use):

Every definition in materials.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: Name property is available on all items

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

Example of a correclty defined name, in this case for an Object definition:

Examples of incorrectly defined names:

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

If you specify a name that doesn't exist, you'll create a new type of thing 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 WarningLight example above, which is an Object that appears on the Utilities menu, the language strings were defined as follows:


The format of the name locale key depends on what type of thing you're defining:

• ?? – any definition starting with BEGIN Callout
  
• equipment_<name> – any definition starting with BEGIN Equipment
  
• material_<name> – any definition starting with BEGIN Material
  
• object_<name> – any definition starting with BEGIN Object
  
• room_<name> – any definition starting with BEGIN Room

You can also add a description to the menu button tooltips:

• buildtoolbar_popup_obj_<name> – for Objects menu
  
• buildtoolbar_popup_room_<name> – for Rooms menu
  
• buildtoolbar_popup_staff_<name> – for Staff menu
  
• buildtoolbar_popup_uts_<name> – for Utilities menu
  
• todo: find out what keys are used for the materials menu

In addition, you can usually define custom descriptions in tooltips when you hover over your item on the map. To do this you'll have to use a Lua script – see the "Tooltip property" section in Object Scripting with Lua. I've only tested this with "Object" type things, but assume it will work with other items too so long as they can be scripted.

For details on adding additional languages, see the Localisation Guide.

I want to get the detailed guides finished first, then I'll add the quick reference tables.

Links to the currently completed guides are at the top of this guide, I'm hoping to finish all of them within the next few weeks.