tilemap

Tiled JSON and TMX tilemap loading and collision helpers

Files

Dependencies

Installation

kit add gitlab.com/kit-lang/packages/kit-tilemap.git

Usage

import Auth.File.{file-auth, file-read-auth}

import Kit.Tilemap as Tilemap

main = fn(env: Env) =>
  read-auth = file-read-auth (file-auth env.root)
  tileset = {ptr: 0, width: 32, height: 32}

  match Tilemap.load read-auth "examples/basic.tmx" tileset
    | Err e ->
      println "Failed to load map: ${show e}"
    | Ok tilemap ->
      println "${tilemap.width}x${tilemap.height}"
      println "Solid at 1,0: ${to-string (Tilemap.is-solid? tilemap 1 0)}"

main

Tilemap.load supports .tmx, .tmj, and .json map files. Collision uses

layers named Collision or layers with a solid=true property.

This package has no rendering backend. It stores the tileset value you pass in

so your game renderer can draw with its own graphics package.

Development

Running Examples

Run the loader example from the package root:

kit run examples/load.kit --allow-requested

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow:

kit dev

This will:

1. Format and check source files
2. Type check examples and fixtures
3. Run tests with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/tilemap/, making it

available for import as Kit.Tilemap in other projects.

License

This package is released under the MIT License - see LICENSE for

details.

Exported Functions & Types

create

Create an empty tilemap

Config fields: tile-width: Int - Width of each tile in pixels tile-height: Int - Height of each tile in pixels width: Int - Map width in tiles height: Int - Map height in tiles tileset: Texture - The tileset texture

Tilemap.create {
  tile-width: 16,
  tile-height: 16,
  width: 50,
  height: 30,
  tileset: tileset-texture
}

add-layer

Add a layer to the tilemap

create-layer

Create a layer with empty data

create-layer-with-data

Create a layer with initial data

get-tile

Get tile index at position (in tile coordinates)

set-tile

Set tile at position (returns new tilemap)

get-tile-at

Get tile at world position (in pixels)

world-to-tile

Convert world position to tile position

tile-to-world

Convert tile position to world position (top-left corner)

get-layer

Get layer by name

set-layer-visible

Set layer visibility

toggle-layer

Toggle layer visibility

is-solid?

Check if a tile position is solid

is-solid-at?

Check if a world position is solid

rect-collides?

Check if a rectangle collides with any solid tiles Tests every tile the rectangle overlaps, so entities larger than one tile cannot straddle a solid tile undetected

get-colliding-tiles

Get all solid tiles that a rectangle overlaps with

resolve-collision

Resolve collision by pushing entity out of solid tiles Returns adjusted position {x, y}

pixel-width

Get tilemap dimensions in pixels

pixel-height

Get tilemap height in pixels

fill-rect

Fill a rectangular region with a tile

clear-layer

Clear all tiles in a layer

TilemapError

Error type for tilemap loading

Type

load

Load a tilemap from a Tiled JSON file (.tmj or .json)

Parameters:

• path - String - Path to the JSON file
• tileset - Texture - The tileset texture to use (loaded separately)

Returns: Result Tilemap TilemapError

Parameters:

  tileset = Assets.load-texture "tiles.png"
  match Tilemap.load fa "level1.tmj" tileset
    | Ok map -> use map
    | Err e -> print "Failed to load: ${show e}"

Load a Tiled JSON map from a file.

  fa: FileReadAuth supplied by the consuming app
  path: String - Path to the .tmj file
  tileset: Texture - The loaded tileset texture

Note: The tileset texture must be loaded separately using Assets.load-texture.

from-tiled-json

Parse a Tiled JSON string into a tilemap

Parameters:

• json-str - String - JSON content from a Tiled map file
• tileset - Texture - The tileset texture

Returns: Result Tilemap TilemapError

get-tileset-info

Get tileset info from Tiled JSON (helper for loading tileset)

Parameters:

• fa - FileReadAuth supplied by the consuming app
• path - String - Path to the Tiled JSON file

Returns: Result {image: String, tile-width: Int, tile-height: Int} TilemapError

match Tilemap.get-tileset-info fa "level1.tmj"
  | Ok info ->
    tileset = Assets.load-texture info.image
    Tilemap.load fa "level1.tmj" tileset
  | Err e -> print "Error: ${show e}"

load-tmx

Load a tilemap from a Tiled TMX XML file (.tmx)

Parameters:

• path - String - Path to the TMX file
• tileset - Texture - The tileset texture to use (loaded separately)

Returns: Result Tilemap TilemapError

Note: CSV and base64 tile data are supported. Base64 may be uncompressed, zlib-compressed, or gzip-compressed.

tileset = Assets.load-texture "tiles.png"
match Tilemap.load-tmx fa "level1.tmx" tileset
  | Ok map -> use map
  | Err e -> print "Failed to load: ${show e}"

from-tmx-xml

Parse a Tiled TMX XML string into a tilemap

Parameters:

• xml-str - String - XML content from a Tiled TMX file
• tileset - Texture - The tileset texture

Returns: Result Tilemap TilemapError

Note: CSV and base64 tile data are supported.

parse-tmx-objectgroups

Parse object group layers from a TMX XML document string.

Returns a list of {name: String, visible: Bool, objects: List} records. Each object has: id, x, y, width, height, kind, name.

Note: This is a separate utility function. Object groups are not yet integrated into the main tilemap structure.

get-tileset-info-tmx

Get tileset info from a Tiled TMX file.

Parameters:

• path - String - Path to the TMX file

Returns: Result {image: String, tile-width: Int, tile-height: Int, tile-count: Int} TilemapError

Note: For external tilesets, the .tsx file is loaded and parsed automatically.

match Tilemap.get-tileset-info-tmx fa "level1.tmx"
  | Ok info ->
    tileset = Assets.load-texture info.image
    Tilemap.load-tmx fa "level1.tmx" tileset
  | Err e -> print "Error: ${show e}"