Skip to content

tilemap

tilemap

Load and draw tile maps made in LDtk (https://ldtk.io).

LDtk saves a project as one JSON file. This reads that file into a small model the engine can draw and query: a project holds its tilesets and levels, a level holds its layers (in bottom-to-top draw order), and a layer holds either placed tiles, an IntGrid (a grid of integers for collision or logic), or entities with their typed fields. AutoLayer tiles are baked into the file by LDtk, so this reads finished tiles and never runs the editor's rules.

parseLdtk turns the JSON text into the model with no GPU, which is what makes it testable headlessly and what lets you bake a level in with staticRead. loadLdtk reads the file and also loads each tileset image, resolved relative to the file, so the example only needs one call. The tileset PNGs are loaded from disk either way, since that is how the engine loads any image.

draw paints a level, intGridAt reads the collision grid to feed collide, and the level, layer and entity-field lookups pull the rest out by name.

This is an opt-in module, imported on its own with import nim2d/tilemap. The core engine does not pull it in.

LdtkLayerKind 

type LdtkLayerKind = enum

The kind of a layer: hand-placed Tiles, rule-painted AutoLayer, an

IntGrid of per-cell integers for collision or logic, or Entities.

Values

  • lkTiles
  • lkAutoLayer
  • lkIntGrid
  • lkEntities
Source: src/nim2d/tilemap.nim:27

LdtkTile 

type LdtkTile = object

One placed tile, positioned in level-local pixels with its

source region already cut from the tileset (flips baked into the texcoords).

Fields

  • x float
  • y float
  • quad Quad
  • alpha float
  • tileId int
Source: src/nim2d/tilemap.nim:35

LdtkEntity 

type LdtkEntity = object

An entity instance: where it sits, how big it is, an optional sprite tile,

and its custom fields reached through the get* accessors.

Fields

  • identifier string
  • gridX int
  • gridY int
  • x float – level-local pixel position
  • y float – level-local pixel position
  • width int
  • height int
  • pivotX float
  • pivotY float
  • hasTile bool
  • tile Quad
  • tilesetUid int
  • tileset Image – the image the tile is cut from, or nil
  • fields Table[string, JsonNode]
Source: src/nim2d/tilemap.nim:44

LdtkLayer 

type LdtkLayer = object

One layer of a level. By its kind it holds placed tiles, an intGrid,

or entities. Tiles are positioned in level-local pixels.

Fields

  • identifier string
  • kind LdtkLayerKind
  • cWid int
  • cHei int
  • gridSize int
  • offsetX float
  • offsetY float
  • opacity float
  • tilesetUid int
  • tileset Image – the tileset image these tiles are drawn from, or nil
  • tiles seq[LdtkTile]
  • intGrid seq[int] – row-major, length cWid*cHei, 0 for empty
  • entities seq[LdtkEntity]
Source: src/nim2d/tilemap.nim:58

LdtkLevel 

type LdtkLevel = ref object

A single level: its position in the world, its size, background color, the

identifiers of its neighbours, and its layers in bottom-to-top draw order.

Fields

  • identifier string
  • iid string
  • worldX int
  • worldY int
  • pxWid int
  • pxHei int
  • bgColor Color
  • neighbours seq[string] – identifiers of adjacent levels
  • layers seq[LdtkLayer] – bottom-to-top, ready to draw in order
  • fields Table[string, JsonNode]
Source: src/nim2d/tilemap.nim:73

LdtkTileset 

type LdtkTileset = object

A tileset definition: the image its tiles are cut from and the cell size.

Fields

  • uid int
  • identifier string
  • relPath string – empty for LDtk's internal tilesets
  • pxWid int
  • pxHei int
  • gridSize int
  • image Image – loaded by loadLdtk, nil after parseLdtk alone
Source: src/nim2d/tilemap.nim:85

LdtkProject 

type LdtkProject = ref object

Fields

  • jsonVersion string
  • tilesets seq[LdtkTileset]
  • levels seq[LdtkLevel]
Source: src/nim2d/tilemap.nim:94

parseLdtk 

proc parseLdtk(jsonText: string): LdtkProject

Parse an LDtk project from its JSON text into the model, without a GPU or any

image loading. Use this to test headlessly or to bake a level in through staticRead; call loadTilesets afterwards to draw it. Raises ValueError on malformed JSON.

Parameters

  • jsonText (string)

Returns

LdtkProject

Source: src/nim2d/tilemap.nim:229

loadTilesets 

proc loadTilesets(project: LdtkProject; nim2d: Nim2d; baseDir: string)

Load each tileset's PNG into an image, resolving its path relative to

baseDir (the folder the .ldtk file lives in). Tilesets with no path, like LDtk's internal icons, are skipped. Then point every layer at its tileset image so draw is self-contained.

Parameters

  • project (LdtkProject)
  • nim2d (Nim2d)
  • baseDir (string)
Source: src/nim2d/tilemap.nim:306

loadLdtk 

proc loadLdtk(nim2d: Nim2d; path: string): LdtkProject

Read an LDtk file, parse it, and load its tileset images from the same

folder. This is the one call an example or game needs. Raises IOError if the file cannot be read.

Parameters

  • nim2d (Nim2d)
  • path (string)

Returns

LdtkProject

Source: src/nim2d/tilemap.nim:327

draw 

proc draw(level: LdtkLevel; nim2d: Nim2d; x = 0.0; y = 0.0; scale = 1.0)

Draw the level with its top-left at (x, y), every pixel scaled by scale.

Layers paint bottom to top. Call loadLdtk (or loadTilesets) first, or the tile layers have no image to draw and are skipped.

Parameters

  • level (LdtkLevel)
  • nim2d (Nim2d)
  • x (auto)
  • y (auto)
  • scale (auto)
Source: src/nim2d/tilemap.nim:341

level 

proc level(project: LdtkProject; identifier: string): LdtkLevel

The level with this identifier, or nil if there is none.

Parameters

  • project (LdtkProject)
  • identifier (string)

Returns

LdtkLevel

Source: src/nim2d/tilemap.nim:358

intGridAt 

proc intGridAt(level: LdtkLevel; layerIdentifier: string; cx, cy: int): int

The IntGrid value at cell (cx, cy) of the named layer, or 0 (empty) when the

layer is missing or the cell is out of range. A game checks this against its own "solid" value and feeds the result to collide.

Parameters

  • level (LdtkLevel)
  • layerIdentifier (string)
  • cx (int)
  • cy (int)

Returns

int

Source: src/nim2d/tilemap.nim:365

layerGridSize 

proc layerGridSize(level: LdtkLevel; layerIdentifier: string): int

The cell size in pixels of the named layer, or 0 if there is no such layer.

Parameters

  • level (LdtkLevel)
  • layerIdentifier (string)

Returns

int

Source: src/nim2d/tilemap.nim:382

entities 

proc entities(level: LdtkLevel; identifier: string): seq[LdtkEntity]

Every entity instance with the given identifier, across the level's entity

layers.

Parameters

  • level (LdtkLevel)
  • identifier (string)

Returns

seq[LdtkEntity]

Source: src/nim2d/tilemap.nim:389

getInt 

proc getInt(e: LdtkEntity; field: string; default = 0): int

An Int field, or default if it is missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)
  • default (auto)

Returns

int

Source: src/nim2d/tilemap.nim:399

getFloat 

proc getFloat(e: LdtkEntity; field: string; default = 0.0): float

A Float field, or default if it is missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)
  • default (auto)

Returns

float

Source: src/nim2d/tilemap.nim:404

getBool 

proc getBool(e: LdtkEntity; field: string; default = false): bool

A Bool field, or default if it is missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)
  • default (auto)

Returns

bool

Source: src/nim2d/tilemap.nim:409

getStr 

proc getStr(e: LdtkEntity; field: string; default = ""): string

A String, Multilines, FilePath or enum field as text, or default if it is

missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)
  • default (auto)

Returns

string

Source: src/nim2d/tilemap.nim:414

getColor 

proc getColor(e: LdtkEntity; field: string; default = (255'u8, 255'u8, 255'u8, 255'u8)): Color

A Color field, or default if it is missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)
  • default (auto)

Returns

Color

Source: src/nim2d/tilemap.nim:420

getPoint 

proc getPoint(e: LdtkEntity; field: string): tuple[cx, cy: int]

A Point field as grid coordinates, or (0, 0) if it is missing or unset.

Parameters

  • e (LdtkEntity)
  • field (string)

Returns

tuple[cx, cy: int]

Source: src/nim2d/tilemap.nim:430

getPoints 

proc getPoints(e: LdtkEntity; field: string): seq[tuple[cx, cy: int]]

An Array<Point> field as grid coordinates in order, empty when the field

is missing or unset. Handy for a patrol path or a marked-out region.

Parameters

  • e (LdtkEntity)
  • field (string)

Returns

seq[tuple[cx, cy: int]]

Source: src/nim2d/tilemap.nim:438
Generated with mkdocstrings-nim