Textures & Sprites

Penal Engineer draws a clear boundary between textures and sprites.

Textures

Penal Engineer defines a texture as just a rasterized bitmap image file .png.

You just draw a PNG of necessary size and drop it in your mod folder at any place you wish. Folders hierarchy structure is totally up to you.

Then you'll just point at the relative path of your texture when you'll have to define a sprite.

Sprites

A sprite is basically a reference to a texture accompanied by optional rendering features.

For various renderable entities, Penal Engineer requires you to indeed provide a sprite, not a texture. The rendering system operates with sprites only.

Think about a sprite as about a way how you actually register your texture with Penal Engineer.

The clear separation between sprites and textures allows you to re-use a same .png for different sprites. For example, if you want a wall segment to be rendered at vertical edges in the same way as at horizontal edges just rotated 90°, you don't have to supply 2 .png files. Instead, you can define your wall like that (only sprites part is left for sake of clarity):

<Sprites>
    <Sprite>
        <NamespacedId Value="MyMod/Walls/Brick/body_horizontal" />
        <Texture Path="walls/brick/body_horizontal.png" />
    </Sprite>
    <Sprite>
        <NamespacedId Value="MyMod/Walls/Brick/body_vertical" />
        <Texture Path="walls/brick/body_horizontal.png" />
        <Rotation Value="90" />
    </Sprite>
</Sprites>

<Prefabs>
    <Prefab>
        <WallSprites>
            <HorizontalWallBodySprite NamespacedId="MyMod/Walls/Brick/body_horizontal" />
            <VerticalWallBodySprite NamespacedId="MyMod/Walls/Brick/body_vertical" />
        </WallSprites>
    </Prefab>
</Prefabs>

warning

Pay attention that whenever you define a sprite you must specify a NamespacedId for it. This allows you or any other mod author to consume a sprite by its ID.

note

As paths to texture files are relative to the mod folder, it's not possible to re-use textures from an alien mod in your own sprite definition. However, you can totally use an alien sprite as whole by specifying its registered ID. The alien texture shall follow automatically.

XML doesn't allow you to register your own sprite definition to be just an alias to an alien sprite definition. If you want to use alien mod textures, you stick with that alien mod sprite definitions, not your own. Aliasing can be achieved with scripting, though. But scripting is out of scope of this tutorial.

Scaling

Actually, the engine doesn't bind you to make a texture of exactly the same dimensions as an entity. Penal Engineer is capable to scale up and down textures on rendering.

Example: you supply a bunk of 1×2 tiles. So, while you bunk is actually of 128×256 points, you may supply a texture of 32×64 pixels. The rendering system of Penal Engineer shall scale it up on camera zoom greater than .25.

Penal Engineer also distorts the aspect ratio if necessary to stretch a texture to an envisaged box on the map matching the declared entity size.

Texture Atlas (aka Sprite Sheet)

In many 2D games a technique known as texture atlas is heavily leveraged. It's when all textures are collected and compiled ("baked") in a single bitmap .png. That whole file gets fed into GPU once (game devs name it "binding a texture to GPU"). When an engine has to render a sprite, it just points out coordinates in the atlas without binding a concrete texture to GPU. Unfortunately, a lot of engines force a modder to deal with baking atlases on themselves.

Penal Engineer is different. Forget about tools like Texture Packer, Atlas Creator and other stuff.

info

You don't have to care of baking texture atlases. Just supply standalone .png textures with your mod content. Penal Engineer shall take care of them to bake a texture atlas at load time automatically.

Note that Penal Engineer engine shan't rebuild the atlas on every load. It checks your .png files modification timestamps, and shall rebuild only if something changed. Anyway, the atlas baking is optimized and quite fast (several milliseconds), which is negligible and achieves the same efficiency as consuming prebaked atlases.

Key differences to Prison Architect

• In Prison Architect textures are limited to be exactly of 32×32 pixels per 1 tile with no autoscaling. Penal Engineer makes modders' life much easier in that aspect.
• In Prison Architect modders must bake atlases on themselves, and point concrete coordinates in the atlas for required textures. In Penal Engineer, you simply specify a concrete path name relative to your mod folder. The loader shall do all the rest baking and calculating at runtime with caching results.