API Reference

Entry point for a tilemap-editor map JSON. Feeds TileLayerRenderer and PhysicsWorld.from_map. Exposes tile_size, render_scale, parsed and build_tile_map(). Full wiring on the Map Parsing & Rendering page.

Lower-level parsers behind load_map. parse_map_json handles a JSON string;

parse_map_file a path.

Collapses the map's tile layers into { (col, row): tile_id } , the layer the runner iterates and PhysicsWorld owns. use_gids=True keys by global tile id.

Gets one tile texture from the tileset, scaled by render_scale. Handy when you want a tile's art outside the renderer (icons, minimaps).

Read-only data classes for everything a map JSON contains. You usually touch parsed.meta.tile_size and parsed.tilesets; the rest is there when you need to query editor data. ParsedLayer now carries image_path / image_rect for type == "image" (aliases "background", "background_layer"). ParsedObject.animation is ObjectAnimation | None — required frame_count + frame_duration_ms, optional speed, loop, animation_mode, random_phase, frames; bad values raise MapParseError.

Eagerly loaded image layer: image_path, image_rect: (x,y,w,h) | None, surface: Surface | None. Exposed as TilemapData.background_layer (first image layer). get_layers(layer_type="image") lists all.

Returns the effective object animation as AnimData (a normalized dict with frames as surfaces, frame_w/h, frame_duration_ms, loop, animation_mode, and properties). When per-object obj.animation is None, falls back to the matching tileset animation; returns None only when neither the object nor its tileset defines an animation. The render_scale parameter scales both the frame surfaces and their dimensions in the returned dict (default 1.0 leaves at source resolution). Access frames via anim_data["frames"]. Playback (speed, loop, random_start_times hash) is user-side.

Parses editor node data (e.g. particle emitters placed in the map). AreaNode wraps a parsed node with itsrect and properties, scaled by render_scale; see JSON Formats for a real example.

Tiled TMX/TSX converter: bridge maps made in Tiled into the same parsed structures.

MapObject is the body used by polygon solids: it keeps its own shapes instead of relying on Body, which only accepts primitives. Use this one for polygon bodies.

Box. (x, y) anchor is top-left plus offset. Only primitive shapes are accepted on Body.

Disc. (x, y) anchor is the center plus offset.

Vertical capsule: two circles height apart. Full collision against every shape type.

Tile/object polygon. transform(tile_x, tile_y, scale) moves it to world space; is_valid() requires ≥ 3 vertices. one_way=True = platform pass-through from below (honored by the platformer family).

Per-tile-id polygons. has_collision(tile_id), get_world_shapes(tile_id, x, y, scale), and merge(collisions, firstgids) for multi-tileset maps.

One tile's polygons; has_collision().

A sprite's single shape, authored in the editor. Feed it to your sprite at spawn.

Region-based polygon paint. get_region(id), per-region layer/mask.

Loads and caches collision JSON: get_tileset_collision(path), get_character_collision, get_object_collision; clear_collision_cache() to drop it. Also the module-level load_* and parse_*_collision functions.

'platformer' | 'topdown' | 'rpg' presets; see the guide's table. Unknown names raise ValueError.

Preset + attach in one call. The world's tile_size/render_scale are adopted.

Bind or unbind a PhysicsWorld. Attach once; pass None, None for tile args afterwards.

Displacement + wall sliding. No gravity, never reads vx/vy. Fast path tries the full move first.

Displacement + full blocking. No sliding: a diagonal into a corner stops both axes.

Gravity + landing. velocity=(vx, vy) skips gravity. Ledge detection when the sprite was grounded.

Gravity, jump, step-up, one-way platforms, ground snapping.

Slope-aware: walks polygon floor surfaces within max_walk_angle.

Dispatches on self.mode (SLIDE/PLATFORMER/RPG/GROUNDED), handy for one generic call.

World-space queries without moving anything.

Range and consistency checks; called by presets. See the guide's validation section.

collided, final_x, final_y, hit_wall_x, hit_wall_y, hit_ceiling, on_ground, slide_vector.

Enum: SLIDE, PLATFORMER, RPG, GROUNDED (moves via move_grounded; reachable through the raw CollisionRunner(tile_size, mode=...) constructor, not through the from_game_type presets).

The space. A tile_map without tileset_collision raises ValueError.

Build from a loaded map; adopts the map's grid geometry.

Body management. Duplicate add_body is a no-op; removing an absent body raises ValueError.

First overlapping body in insertion order, self excluded, layers honored. Bodies are always solid both ways.

body in world, len(world).

A solid. Primitive shapes only (TypeError otherwise); mode in ('static', 'kinematic'): scripted velocity, no engine dynamics. top_y_at(world_x) and as_polygon() back the resolver's ground sampling and slide normals.

The duck-type contracts the runner and world accept. ICollidable: x, y, collision_shape. ICollidableObject adds collision_layer/mask. ICollidableSprite adds vx, vy, on_ground for the physics modes. Anything with these attributes works; no subclassing required.

Draws the visible tile layers, chunk-culled (32×32 tiles per chunk). render(target, camera_xy=(0,0), viewport_size=None, *, extra_objects=None, current_time_ms=None) → LayerRenderStats. warm_cache() pre-bakes tile variants (then frees the source data). Respects layer z_index, y_sort and tileset animations.

Raw {layer_id: TileLayer} view of the layers the renderer draws — for debug readouts and custom layer iteration.

drawn_tiles, skipped_tiles, visible_layers: your per-frame culling report.

'centered' keeps the target centered; 'deadzone' only moves when the target exits a box. follow(target) (needs x, y, collision_shape), update(dt), offset, shake(duration, intensity), lerp_speed, bounds.

Loads an animation JSON + spritesheet into one object. render_scale scales the spritesheet and its atlas grid (tile_size, grid_offset) so frames render at a different resolution; values must be finite and > 0, and scales that produce zero-sized or non-fitting cells raise ValueError. get_image(variant_id), get_content_bounds(clip_name).

Frame clock: update(dt_ms), get_current_image(), reset(), finished, frame_index. Honors per-frame durations and loop.

Parsed animation data. AnimationParseError for bad files.

High-level continuous field helper. Builds wrapped fields internally, so users tune density, strength (global_alpha), color, motion and quality instead of particle internals. Layer tuning comes from a FieldProfile — plain data, e.g. the shipped FOG_PROFILE, which you can copy and tweak for your own moods. Profiles are immutable; FOG_PROFILE.with_alpha(factor, name=None) returns a scaled copy without touching the source. blend passes a pygame blend flag (e.g. pygame.BLEND_RGBA_ADD for additive particles, pygame.BLEND_PREMULTIPLIED for premultiplied tints); for scene glow, alpha-blend the field into a black RGB buffer and blit that with pygame.BLEND_RGB_ADD. Every parameter, its valid values and its meaning: the Particles parameter reference.

Low-level particle config and advanced escape hatch. Full wiring on the Particles page.

The runtime: emitters spawn, fade, and batch-draw. Node-based emitters come from the map's node data (see JSON Formats). clear_texture_caches() frees loaded textures.

Parse configs from JSON and the accepted value sets.

NavGrid builds the walkable grid from a tile layer; Pathfinder computes a path; PathFollower moves an entity along it. Full wiring on the Pathfinding page and in examples/rpg-pathfinding/main.py.

True if the tile at (tx, ty) carries a one-way polygon. The pathfinding answer to "can I stand on it" — one-way tiles are walkable, solid tiles are walls.

Layer filter → AABB broadphase → narrowphase (deepest pair wins). Handles multi-shape objects.

The mutual-agreement layer rule: (a_mask & b_layer) and (b_mask & a_layer).

Box math. get_shape_bounds backs the runner's tile queries.

Standalone narrowphase tests, when you want collision without the runner.

resolve(), slide_velocity(), involves(), other(): the object-collision lane's results.

All subclass ValueError. Parse failures give you the offending data plus the reason. The runner raises plain ValueError for config violations and invalid game_type.