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 concerned Tile Stack which the building spans across.

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

Every concerned entity has a component describing its position in the game world. It's a component named Position. It comprises 3 coordinates: X, Y and Floor, and 2 derived values: TileX and TileY.

• (X, Y) always defines the top-left corner of an entity.
• X and Y are in the point coordinate space (see below), NOT in tiles.
• TileX and TileY are indeed in the tile coordinate space.
• Points coordinates are the first-class citizen (except for walls).
• Tile coordinates are secondary (except for walls) and derived from points coordinates.
• Tile coordinates are reactive (except walls). Whenever a point coordinate changes, the relevant tile coordinate doesn't get immediately recalculated but only invalidated. It would only be recalculated on next read access (e.g. by the pathfinding system).

Point coordinate space

The maximum zoom value in Penal Engineer is exactly 1.0. This is when a player can see the most detailed sprites/textures. At this zoom scale, every texture is being rendered as was drawn, without scaling (given they were drawn meeting the requirements to sizes).

• The point coordinates match real screen pixels at this 1.0 zoom scale.
• The point coordinate space initially (if the map hasn't been expanded at top or at left) starts from (0, 0) which is the map's top-left corner.
• The point coordinate space goes rightward by X and downward by Y.
• The point coordinate space is used by the rendering systems and by most logic systems (collision detection etc.)

Tile coordinate space

Every cell of the map grid has a fixed size of 128x128 points (and, running ahead, 128x128 is a standard size of a floor tile). Indices of every Tile Stack in the map grid are effectively its coordinates in the tile coordinate space.

• The initial (if the map hasn't been expanded at top or at left) top-left Tile Stack has tile coordinates (0, 0).
• The coordinates grow rightward by X and downward by Y.
• Point Coordinates can be converted to Tile Coordinates with dividing by 128 and rounding, and vice versa.
• The tile coordinate space is used by the pathfinding system.

Map expansion & negative coordinates

When a player expands the map at top or at left, no coordinates of existing entities get recalculated. Instead, the new Tile Stacks get added with negative indices, and every entity spawned there will also get negative point coordinates.

Key differences to Prison Architect

• In Prison Architect there is only one coordinate space: tiles. In Penal Engineer, there are two: points and tiles; they are used by different systems for different purposes.
• In Prison Architect a tile is of 32x32 pixels. In Penal Engineer it's 128x128.
• In Prison Architect expansion of the map forces recalculation of all coordinates for all objects. This could break some inner logic of custom mod scripts. In Penal Engineer coordinates of concrete points on the map are guaranteed to stay immutable.
• There is no multi-level in Prison Architect at all.