🧩 TileMap

This component is designed exclusively for tilemaps exported from PyxelEdit.

The TileMap component provides tile-based rendering for a GameObject. It is designed exclusively to work with JSON tilemaps generated by PyxelEdit, which define the grid size, tile dimensions, and layers of tiles.

The component loads a tileset texture, crops the appropriate tiles based on the JSON map, and renders them as layers using efficient vertex arrays. The tilemap is always centered on the GameObject’s transform position (instead of its top-left corner), making it easy to align in the scene.

Behaviour

The TileMap component is responsible for taking a PyxelEdit-exported tilemap and turning it into something the engine can efficiently render. When the JSON is loaded, the component reads the map dimensions, the size of each tile, and the list of layers. For every layer, it builds an optimized sf::VertexArray of quads where each quad corresponds to one tile on the map.

Tiles are mapped into the tileset PNG by index. The tileset is assumed to be a fixed grid of equally sized tiles, ordered left-to-right and top-to-bottom. Tile index 0 is valid and corresponds to the first tile in the tileset, while index -1 represents an empty tile (no rendering).

The system also handles common PyxelEdit features such as horizontal flips and 90° rotations. To prevent visual artifacts, a small anti-bleeding offset is applied to texture coordinates.

Unlike a raw SFML sprite, the TileMap is always positioned so that its center coincides with the GameObject’s transform position. This means the tilemap grows outward from its center, making alignment with other GameObjects more intuitive. Additional adjustments can be made with the offset parameter, and the tilemap respects the owning GameObject’s scale and rotation.

Finally, the component calculates and updates its cardinals, which are the four corner points of its bounding rectangle in world space. These cardinals are later combined by the Scene system with other components’ cardinals (such as sprites or text renderers) to determine the final render bounds of the GameObject. This allows the engine to quickly decide whether an object should be rendered or skipped if it falls outside the camera’s visible area.

⚠️ Important notes:

Only JSON maps exported from PyxelEdit are supported. Tile index -1 means empty; tile index 0 is valid. The map is always centered at the transform position, not drawn from the top-left corner. Transform scaling and rotation are applied to the whole map.

Fields

• Vector2 scale: Additional scale factor applied to the tilemap (added to the GameObject’s transform scale).

• Vector2 offset: Positional adjustment applied after transform position, useful for fine-tuning placement.

• Vector2 tileSize: Size of each tile (in pixels), parsed from the JSON.

• int tilesWide: Number of tiles horizontally in the map.

• int tilesHigh: Number of tiles vertically in the map.

• int tilesPerRow: Number of columns in the tileset PNG (default = 8).

• Dictionary<String, Vector2Ptr> cardinals: The four corner points of the tilemap’s bounding box:

  • top-left

  • top-right

  • bottom-left

  • bottom-right

Constructors

Default Constructor

TileMap()

Creates a new TileMap component with empty layers.

Methods

Load

bool Load(String tilemap, String tileset, int tilesPerRow = 8)

Loads a PyxelEdit JSON tilemap and a tileset PNG.

• tilemap: JSON filename inside ./Assets/.

• tileset: PNG filename inside ./Assets/.

• tilesPerRow: Number of columns in the tileset image (default 8).

Returns true if successful.

GetCardinals

Dictionary<String, Vector2Ptr> GetCardinals()

Returns the current bounding box of the rendered tilemap as a dictionary of four points.

Example Usage

TileMapPtr map = std::make_shared<TileMap>();

// Load PyxelEdit JSON and tileset
map->Load("maps/level1.json", "tilesets/terrain.png", 8);

// Apply scaling and offset
map->scale = Vector2(1.0f, 1.0f);
map->offset = Vector2(0.0f, 0.0f);

// Attach to GameObject
gameObject->AddComponent(map);

This will render the full PyxelEdit map, centered at the GameObject’s transform, and update its cardinal points for scene culling.