tilemap-parser

Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.

Features

Map parsing: Load and query tilemaps, layers, objects, and autotile data from JSON
Chunked tile rendering: Efficient visibility culling and chunk-based rendering with TileLayerRenderer
Camera system: Centered/deadzone follow, lerp smoothing, screen-shake, and bounds clamping with Camera
Animation: Frame-based sprite animation with AnimationPlayer
Particle system: Configurable particle emitters with shapes, color transitions, alpha fades, gravity, and batch rendering with ParticleSystem + SpriteBatchRenderer
Collision (tile-based): Polygon collision detection for tilemaps with slide, platformer, and RPG movement modes via CollisionRunner
Collision (object-to-object): Spatial-grid mixed-shape collision detection (rect, circle, capsule, polygon) with layer filtering via ObjectCollisionManager
Capsule support: Full capsule collision against all shape types
Hit helpers: CollisionHit.resolve(), involves(), other() for ergonomic separation

Quick Start

from tilemap_parser import load_map, TileLayerRenderer, Camera

# Load map and set up renderer
game_data = load_map("path/to/map.json")
renderer = TileLayerRenderer(game_data)

# Set up camera
camera = Camera(800, 600, mode="centered")
camera.follow(player)

from tilemap_parser import (
    CollisionRunner, CollisionCache,
    ObjectCollisionManager, CircleShape, RectangleShape,
    ParticleSystem, ParticleSystemConfig
)

# Tile-based collision
cache = CollisionCache()
tileset = cache.get_tileset_collision("data/collision/tileset.collision.json")
runner = CollisionRunner.from_game_type("topdown", tile_size=(32, 32))

# Object-to-object collision
manager = ObjectCollisionManager()
manager.add_object(player)
for hit in manager.check_all_collisions():
    hit.resolve()  # separate both objects

# Particle system
particle_config = ParticleSystemConfig(
    particle_shape="circle",
    spawn_rate=10.0,
    max_particles=100,
    lifetime_min=0.5,
    lifetime_max=2.0,
    speed_min=50,
    speed_max=100,
    direction=270,
    spread=45,
    start_color_r=255, start_color_g=200, start_color_b=100, start_color_a=255,
    end_color_r=255, end_color_g=100, end_color_b=50, end_color_a=0,
    alpha_fade="fade_out",
    gravity_x=0,
    gravity_y=50,
)
particles = ParticleSystem(particle_config)

Physics bodies

A PhysicsWorld is a single space holding the tile layer plus solid Body objects (static walls, kinematic crates). Attach a CollisionRunner to the world once and every move method resolves tiles and bodies through it — no per-call tile arguments.

Full contract — object↔world↔move_*↔tiles↔rendering: see docs/physics-world.md and examples/physics-crate/main.py.

from tilemap_parser import (
    Body, PhysicsWorld, CollisionRunner, RectangleShape,
    TilemapData, TilesetCollision, CollisionCache,
)

cache = CollisionCache()
tileset = cache.get_tileset_collision("data/collision/tileset.collision.json")
world = PhysicsWorld.from_map(game_data, tileset)   # adopts tile_size / render_scale

crate = Body(RectangleShape(width=16, height=16), x=320, y=480, mode="kinematic")
world.add_body(crate)

runner = CollisionRunner.from_world(world)          # or runner.attach(world)

Pushable crates are just kinematic bodies moved with an explicit velocity (gravity is skipped when velocity= is given):

# player pressed against the crate -> hand the player's vx over
crate.vx = player.vx
result = runner.move_grounded(crate, None, None, dt, velocity=(crate.vx, 0))
if result.hit_wall_x:
    crate.vx = 0  # crate stopped against a tile wall or another body

Body accepts primitive shapes only (RectangleShape, CircleShape, CapsuleShape); use MapObject for polygon solids. Collision pairs honor both sides' collision_layer / collision_mask, and bodies are landing surfaces for platformer step-up (small crates are climbed, tall ones block like walls).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tilemap_parser-5.0.1.tar.gz (154.5 kB view details)

Uploaded Aug 5, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tilemap_parser-5.0.1-py3-none-any.whl (109.9 kB view details)

Uploaded Aug 5, 2026 Python 3

File details

Details for the file tilemap_parser-5.0.1.tar.gz.

File metadata

Download URL: tilemap_parser-5.0.1.tar.gz
Upload date: Aug 5, 2026
Size: 154.5 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for tilemap_parser-5.0.1.tar.gz
Algorithm	Hash digest
SHA256	`a02f0ff3d7949173dd97c1e1d7a730ee463a3ce73de9c0d7eb567492aa2ca143`
MD5	`ce81d770ae37ac2a49a489504aa0332b`
BLAKE2b-256	`dec83fac7e056943c8f5029f9263bd3c4ceeb91d24cec90461549703bb959e1e`

See more details on using hashes here.

File details

Details for the file tilemap_parser-5.0.1-py3-none-any.whl.

File metadata

Download URL: tilemap_parser-5.0.1-py3-none-any.whl
Upload date: Aug 5, 2026
Size: 109.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for tilemap_parser-5.0.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a7a80056fe4a4f1d5e09d37d4bd012d8d0b1fa59b277aed0f722b16e24719f07`
MD5	`f9d6097c5b6495eb8c1d6786f5b66995`
BLAKE2b-256	`a93800586cf619168200fd48dfcb136991740162c484e0727ec1ff04d84569c6`