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 andexamples/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).
Docs
Full documentation: https://tilemap-parser.vercel.app/
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tilemap_parser-5.0.2.tar.gz.
File metadata
- Download URL: tilemap_parser-5.0.2.tar.gz
- Upload date:
- Size: 154.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
39e593143cfbf01b843a3bb4092151dfdccf09965b797ff1db0dbebb747993f7
|
|
| MD5 |
44fbc798fed1a9d3443cc52066007bb8
|
|
| BLAKE2b-256 |
87f7d8f51a000f7ed0dfb0538e3b3412da96d43d41348ea94d9895bf307a3a44
|
File details
Details for the file tilemap_parser-5.0.2-py3-none-any.whl.
File metadata
- Download URL: tilemap_parser-5.0.2-py3-none-any.whl
- Upload date:
- Size: 109.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4dd89a15d8bf0571db678c75c143bd7c33c7e377007a1fa4caf2398da0e954b0
|
|
| MD5 |
f47df5d64b29af0b31059cd9fc3b685d
|
|
| BLAKE2b-256 |
655317d7ce6d4bf5e469dca3729f3221311cb863d16800d71069714d95cb65ae
|
