Skip to main content

Introduction

Penal Engineer (PE) is not just a clone of infamous Prison Architect (developed by Introversion/Paradox) but a totally refurbished, built from scratch, game with the main focus on high extensibility and on making modding enjoyable.

Your expertise​

We expect modders:

  • To have basic computer literacy in working with plain text files (.txt, .xml)
  • To know how to work with bitmap editors (MS Paint, GIMP)
  • Good to know: XML, XSD and how to define a schema (but not required).

Shortly put, nothing exceptional. The PE is crafted with modding capability in heart. No hacks, no quirks, no baking of atlases. We truly hope you'll enjoy modding our game.

Mods vs. plugins​

It's crucial to understand the difference.

  • Mods are packages crafted in the own Penal Engineer structure:
    • an XML file (or several),
    • bunch of textures,
    • bunch of Lua scripts. Mods provide Penal Engineer the content in a declarative, not imperative manner. That said, all turns around the XML file in the package. It's the core of every mod, telling the engine what the mod supplies and where to look for what.
  • Plugins are full-fledged .NET .dll assemblies, relying upon the Penal Engineer API.

Mods are the safest (for a player) way to supply your content. They run sandboxed and don't have access to anything outside their jails (no corruption of the filesystem, no suspicious open ports left after the game exits, etc.). They are also easier to understand and to start authoring straight away.

In rare cases, mods can be not enough. Penal Engineer Plugin API allows a more comprehensive access to the engine internals. However, you should bear in mind that plugins are just unsafe executables running in the same process context as the game itself. There are no guards protecting a player's PC from the plugin code going mad and starting damaging their files. You'll have to gain player's trust to expect them installing your plugin.

tip

Always strive to distribute your content as mods in favor of plugins.

This tutorial covers mods only.

Languages​

The first-class citizen for modding Penal Engineer is declarative syntax of XML. Most basic things (such as new walls, replacing textures of existing ones) can be done via XML.

We are aware that many modders prefer JSON. There are a lot of reasons why it could be better and more convenient for you. However, we considered that JSON has some natural limitations compared to XML (no namespaces, no rich documentation in schemas, no flexibility in splitting across files), which might make your mod not easily maintainable at a long distance. That's why we initially planned to support JSON but later abandoned such plans, and decided to stick you with XML. Even if it shows off its monstrosity in the beginning – trust, it will pay off.

Scripting​

We strive to outline everything that someone's might reasonably want to alter in declarative way (XML). So, you don't have to be a programmer, to install a heavy IDE and to mess around with feeding it with mysterious symbol files just to patch a single texture.

However, it's virtually inevitable you'll want to ship some custom logic with your mod at some time of your development. Lua 5.1 is what you'll use for scripting.

note

No Lua script shall be called automatically just because you put a .lua file into your mod folder.

XML is a must. You should specify when to trigger your Lua script by way of defining the <Script> tag where allowed.

Your tools​

For the time being, we unfortunately don't provide any sophisticated SDK (but we have it on our roadmap).

We recommend you to use JetBrains IntelliJ IDEA for crafting and maintaining your XML-based mod package. No-subscription mode (formerly Community Edition) should suffice with its syntax highlighting and popups with documentation extracted automatically from the schema files.