Quick Start

The smallest thing that loads a map, moves a sprite against tiles, and draws. Top-down slide movement: swap the runner preset and the sprite contract for a platformer (see Physics & Bodies).

quickstart.pyPYTHON

import pygame
from tilemap_parser import (
    Camera, CollisionCache, CollisionRunner, RectangleShape,
    TileLayerRenderer, load_map,
)

pygame.init()
screen = pygame.display.set_mode((800, 600))

# 1. load the map and its tile collision data
game_data = load_map("data/map.json")
renderer  = TileLayerRenderer(game_data)
tileset   = CollisionCache().get_tileset_collision("data/collision/terrain.collision.json")
tile_map  = game_data.build_tile_map()

# 2. a player: any object with x, y, collision_shape
class Player:
    def __init__(self, x, y):
        self.x = float(x)
        self.y = float(y)
        self.collision_shape = RectangleShape(width=16, height=16)

player = Player(96, 96)
camera = Camera(800, 600, mode="centered")
camera.follow(player)

# 3. collision runner (top-down => slide mode, no gravity)
runner = CollisionRunner.from_game_type("topdown", tile_size=game_data.tile_size)

clock = pygame.time.Clock()
running = True
while running:
    dt = clock.tick(60) / 1000.0
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    keys = pygame.key.get_pressed()
    dx = (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 160.0 * dt
    dy = (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 160.0 * dt

    runner.move(player, tileset, tile_map, delta_x=dx, delta_y=dy)
    camera.update(dt)

    screen.fill((35, 35, 45))
    renderer.render(screen, camera.offset)
    pygame.display.flip()

pygame.quit()

WHAT JUST HAPPENED

load_map parses the tilemap-editor JSON into a TilemapData. The renderer draws it;build_tile_map() turns the tile layers into a { (col, row): tile_id } dict the runner iterates.
CollisionCache.get_tileset_collision loads the per-tile polygons. Tiles with no entry are walkable.
CollisionRunner.from_game_type("topdown") = slide mode, gravity off. Each frame you hand it a displacement (velocity × dt) and it slides the sprite along walls.
camera.update(dt) then renderer.render(screen, camera.offset): the camera offsets the world, the renderer culls to the viewport.

WANT GRAVITY INSTEAD?

Give the player vx, vy, on_ground, build a PhysicsWorld from the map, attach the runner once, and call runner.move_platformer(player, None, None, dt, input_x=..., jump_pressed=...). That path, and the crate-pushing it enables, is the whole Physics & Bodies guide.