Skip to main content

Basic concepts: Identifiers

Before we jump into details of XML definitions, you should learn something about identifiers.

Overview​

In Penal Engineer everything referrable has an ID. It's represented as a string, but internally has two parts:

  • Namespace
  • Scoped ID

When being represented as a string, it takes the form: Namespace/ScopedID, i.e. the namespace followed by slash / then the scoped ID.

When you need to point out an ID, you are free to choose any form, explicit or stringified:

<NamespacedId>
    <Namespace>MainContent</Namespace>
    <Id>Bench</Id>
</NamespacedId>

or

<NamespacedId Value="MainContent/Bench" />

Namespaces​

Every namespace your mod uses to supply a new stuff (entity, sprite) must be registered (claimed) by your mod. This is only required to supply stuff with such identifiers, not to consume (refer to) stuff supplied by other mods.

The best practice to choose a namespace is to take the same name as your mod bear for all your supplied entities. This facilitates debugging significantly. No one prevents you to introduce "inner namespaces" inside your scoped IDs (slashes are allowed tokens for <Id>).

info

Your mod always implicitly claims at least one namespace, exactly matching the mod identifier itself. Therefore, if you limit yourself to supply only entities/sprites with the namespace matching your mod identifier, you don't have to make any specific declaration in your mod metadata to make things work.

You can claim as many namespaces as you wish. If you need to claim a namespace other than your mod identifier, please refer to Structure of your mod.

warning

Penal Engineer enforces non-clashing namespaces strictly. If your mod supplies an entity with a namespaced identifier where the namespace has not been claimed by your mod, your mod shall be rejected to load.

If your mod claims a namespace which is already claimed by another mod, your mod shall also be rejected to load.

Scoped ID​

There is no strict requirement on a scoped ID. It can be any string, with spaces, Unicode emojis and so on. The only requirement on a scoped ID is that it must not be empty, and must be unique within its namespace.

It may contain slashes, effectively allowing you to organize nested levels of namespacing.

warning

Penal Engineer prevents two things of a same kind to get same IDs, even if they are defined identically.