Basic concepts: Map, Floors, Coordinates

Map Grid

In Penal Engineer, the map is divided to tiles (more precisely, to tile stacks). An entity normally occupies one or more adjacent tiles – for the purposes of pathfinding, collision detection and so on.

Floors

Penal Engineer natively supports multi-level maps. Thanks to that, a player can construct buildings of various heights, bridges and tunnels or even dungeons with secret rooms underground.

That's why we previously mentioned tile stacks, not just tiles. Actually, the map grid comprises tile stacks, while every stack comprises one or more numbered tiles matching floors.

Things to remember:

• The map is rectangular.
• The map grid consists of Tile Stacks. Their contents may vary. It's totally possible to have a Stack at (1, 1) with floors at -1, 0, 1 and 2 and a nearby Tile Stack at (1, 2) with floors only at 0 and 1.
• The built-in rendering system relies upon that each Tile Stack always has at least one Tile.
• An "empty" (unoccupied by any object/building) Tile Stack initially has one Tile with index 0 standing for the ground.
• A Tile Stack can have gaps in floors. For example, a Tile Stack of Tiles (floors) indexed -1, 0, 1 and 3 (skipping 2) is absolutely valid. This is called Floors Span.

Floors Span

A player can remove a floor slab between floors, effectively spanning floors. This can be used to place tall entities (occupying more than 1 floor of height) or to build a deep water body (artificial channel/river/pond/lake/swimming pool).

To merge, say, floors 1 and 2 into a doubled-tall floor 1 with its ceiling at level 3, is the same as to remove a Tile indexed 2 from every Tile Stack which the building spans across.

note

Spanning of floors doesn't change the map grid structure. It only removes a floor slab between floors, but keeps the coordinate of the "floorless" floor completely valid. For example, if you remove a tile indexed 2 (effectively merging floors 1 and 2), the coordinate (X, Y, 2) will still be valid, and an entity can be placed there and left hanging in air (if opted-out from the attachment, see the next page).

Roofs

Every building should have a roof. It's just yet another Tile stacked on top of the actual floor.

For example, a building with a basement and of a single floor technically contains 3 floors (Tiles in Tile Stacks): -1 for the basement, 0 as the actual floor, and 1 as the roof.

Coordinates

Point coordinate space

The horizontal plane of the game coordinate space is measured in so-called points. A point is a virtual basic unit which closely related to textures. Indeed, one point normally matches one pixel of a texture used for rendering the entity.

Penal Engineer allows a player to zoom in/out the map. The camera zoom value is a factor between a point and an on-screen pixel. The maximum zoom value in Penal Engineer is 1.0. This is when a player can see the most detailed textures.

info

For zoom 1.0 and when an entity texture dimensions match the entity size (which is the strong recommendation):

1 on-screen pixel = 1 point = 1 texture pixel

Every renderable entity has a component describing its position in the game world. It's a component named Position. It comprises 3 fields: X, Y and Floor.

note

• (X, Y) are always measured in points (even for such tiling entities as wall segments).
• (X, Y) always define the top left corner of an entity.
• The coordinate space grows rightwards and downwards (standard screen coordinate space).
• The map origin (top left corner) might not always start with (0, 0). It's the case when the map has been expanded or shrunk by a player.

Tile coordinate space

Although Penal Engineer internally operates with point coordinates, a player thinks in tiles, because every entity is snapped to tile boundaries, and wall segments are always built in between tiles.

Every cell of the map grid has a fixed size of 128×128 points. Indices of every Tile Stack in the map grid are its coordinates in the tile coordinate space. That said, point coordinates can be converted to tile coordinates with dividing by 128 and rounding, and vice versa.

Fortunately, Penal Engineer provides special converters for calculation in points/tiles for a mod script. They are not simple arithmetic functions; they use sophisticated reactive caching of tile coordinates so that to not recalculate them every time when a script would demand them.

warning

If you're scripting, please refrain from manually recalculating coordinates between these two systems (points/tiles). Instead, please use the engine provided API for that, because it leverages reactive caching which significantly boosts performance.

Technical observation

If you closely browse all components an entity has, you might encounter a component named _TiledPosition. It may or may not present. This is exactly the reactively cached result of a conversion made by Penal Engineer coordinates conversion API. Do NEVER touch this component. Do NEVER directly read from it. Always use the provided API to operate with tiled coordinates.

Map expansion/shrinking outcomes

When a player expands or shrinks the map at top or at left, no coordinates of existing entities get recalculated. Instead, the new Tile Stacks get added (even with negative indices) or the shrunk ones get removed. This will shift the map origin (top left corner of the map) behind or ahead of the initial (0, 0).

Key differences to Prison Architect

• In Prison Architect there is only one coordinate space: tiles. In Penal Engineer, everything is measured in points (close to original textures pixels) internally, but the tile system also exists and is supported.
• In Prison Architect a tile is of 32×32 points/pixels. In Penal Engineer it's 128×128.
• In Prison Architect expansion of the map forces recalculation of all coordinates for all objects (which feels painful even on high-end machines). Not only unnecessarily CPU-heavy, but this could also break some inner logic of custom mod scripts. In Penal Engineer coordinates of concrete points on the map are guaranteed to stay immutable, but the origin of the map is not guaranteed to be (0, 0).
• Shrinking of a map is not possible in Prison Architect, but allowed in Penal Engineer.
• There is no multi-level in Prison Architect at all. Penal Engineer, in opposite, encourages building complex prison architectures with galleys, bridges, tunnels, dungeons.