tilemap-parser 4.0.0__tar.gz → 5.0.0__tar.gz

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 4.0.0
+Version: 5.0.0
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -704,7 +704,10 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## 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
@@ -713,16 +716,22 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## Quick Start
 
 ```python
-from tilemap_parser import load_map, TileLayerRenderer
+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)
 ```
 
 ```python
 from tilemap_parser import (
     CollisionRunner, CollisionCache,
     ObjectCollisionManager, CircleShape, RectangleShape,
+    ParticleSystem, ParticleSystemConfig
 )
 
 # Tile-based collision
@@ -735,10 +744,29 @@ 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)
 ```
 
 ## Links
 
-- **Docs**: https://tilemap-parser.vercel.app/
+- **Docs**: [https://deepwiki.com/FluffyBrudy/tilemap-parser](https://deepwiki.com/FluffyBrudy/tilemap-parser)
 - **Editor**: https://pypi.org/project/tilemap-editor/
 - **Repository**: https://github.com/FluffyBrudy/tilemap-parser

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/README.md

@@ -5,7 +5,10 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## 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
@@ -14,16 +17,22 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## Quick Start
 
 ```python
-from tilemap_parser import load_map, TileLayerRenderer
+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)
 ```
 
 ```python
 from tilemap_parser import (
     CollisionRunner, CollisionCache,
     ObjectCollisionManager, CircleShape, RectangleShape,
+    ParticleSystem, ParticleSystemConfig
 )
 
 # Tile-based collision
@@ -36,10 +45,29 @@ 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)
 ```
 
 ## Links
 
-- **Docs**: https://tilemap-parser.vercel.app/
+- **Docs**: [https://deepwiki.com/FluffyBrudy/tilemap-parser](https://deepwiki.com/FluffyBrudy/tilemap-parser)
 - **Editor**: https://pypi.org/project/tilemap-editor/
 - **Repository**: https://github.com/FluffyBrudy/tilemap-parser

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "4.0.0"
+version = "5.0.0"
 description = "Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime."
 readme = "README.md"
 requires-python = ">=3.10"

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/src/tilemap_parser/parser/__init__.py

@@ -46,6 +46,7 @@ from .map_parse import (
     parse_map_json,
 )
 from .node_parse import ParsedNode, parse_nodes_dict, parse_nodes_file
+from .tmx_converter import TmxParseError, parse_tmx_file, parse_tsx_file
 from .particle import (
     ALPHA_FADE_MODES,
     EMISSION_SHAPES,
@@ -84,6 +85,7 @@ __all__ = [
     "TilesetAnimation",
     "TileCollisionData",
     "TilesetCollision",
+    "TmxParseError",
     "parse_animation_dict",
     "parse_animation_file",
     "parse_animation_json",
@@ -96,6 +98,8 @@ __all__ = [
     "parse_map_json",
     "parse_nodes_dict",
     "parse_nodes_file",
+    "parse_tmx_file",
+    "parse_tsx_file",
     "parse_object_collision",
     "parse_tileset_collision",
     "ALPHA_FADE_MODES",

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/src/tilemap_parser/parser/map_parse.py

@@ -106,6 +106,10 @@ class ParsedTile:
     ttype: TilesetRef
     variant: int
     properties: Optional[JsonDict] = None
+    flip_h: bool = False
+    flip_v: bool = False
+    flip_d: bool = False
+    rotated_hex120: bool = False
 
 
 @dataclass
@@ -213,7 +217,16 @@ def _parse_tile(tile_data: JsonDict, ctx: str) -> ParsedTile:
     else:
         ttype = _coerce_int(ttype_raw, f"{ctx}.ttype")
     props = _optional_dict(tile_data.get("properties"), f"{ctx}.properties")
-    return ParsedTile(pos=pos, ttype=ttype, variant=variant, properties=props)
+    return ParsedTile(
+        pos=pos,
+        ttype=ttype,
+        variant=variant,
+        properties=props,
+        flip_h=tile_data.get("flip_h", False),
+        flip_v=tile_data.get("flip_v", False),
+        flip_d=tile_data.get("flip_d", False),
+        rotated_hex120=tile_data.get("rotated_hex120", False),
+    )
 
 
 def _parse_tiles(tiles_obj: JsonDict, ctx: str) -> Dict[Point, ParsedTile]:
@@ -484,8 +497,13 @@ def parse_map_file(path: Union[str, Path]) -> ParsedMap:
     p = Path(path)
     if not p.is_file():
         raise MapParseError(f"Not a file: {p}")
-    if p.suffix.lower() != ".json":
-        raise MapParseError(f"Expected .json map file, got {p.suffix!r}")
+    suffix = p.suffix.lower()
+    if suffix == ".tmx":
+        from .tmx_converter import parse_tmx_file
+
+        return parse_tmx_file(p)
+    if suffix != ".json":
+        raise MapParseError(f"Expected .json or .tmx map file, got {suffix!r}")
     try:
         text = p.read_text(encoding="utf-8")
     except OSError as e:

tilemap_parser-5.0.0/src/tilemap_parser/parser/tmx_converter.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+import base64
+import gzip
+import logging
+import struct
+import zlib
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+from xml.etree import ElementTree
+
+from .map_parse import (
+    MapParseError,
+    ParsedLayer,
+    ParsedMap,
+    ParsedMeta,
+    ParsedProjectState,
+    ParsedTile,
+    ParsedTileset,
+)
+
+log = logging.getLogger(__name__)
+
+TILE_FLIP_H = 0x80000000
+TILE_FLIP_V = 0x40000000
+TILE_FLIP_D = 0x20000000
+TILE_FLIP_HEX = 0x10000000
+TILE_FLIP_MASK = 0x0FFFFFFF
+
+FLIP_BIT_NAMES = {
+    TILE_FLIP_H: "H",
+    TILE_FLIP_V: "V",
+    TILE_FLIP_D: "D",
+    TILE_FLIP_HEX: "HEX120",
+}
+FLIP_ALL = TILE_FLIP_H | TILE_FLIP_V | TILE_FLIP_D | TILE_FLIP_HEX
+
+
+class TmxParseError(MapParseError):
+    pass
+
+
+def _coerce_int(value: Any, ctx: str) -> int:
+    try:
+        return int(value)
+    except (ValueError, TypeError) as e:
+        raise TmxParseError(f"{ctx}: expected int, got {value!r}") from e
+
+
+def _coerce_float(value: Any, ctx: str) -> float:
+    try:
+        return float(value)
+    except (ValueError, TypeError) as e:
+        raise TmxParseError(f"{ctx}: expected float, got {value!r}") from e
+
+
+def _require_attr(elem: ElementTree.Element, name: str, ctx: str) -> str:
+    value = elem.get(name)
+    if value is None:
+        raise TmxParseError(f"{ctx}: missing required attribute {name!r}")
+    return value
+
+
+def _decode_flip_flags(
+    gid: int,
+) -> Tuple[int, bool, bool, bool, bool]:
+    flipped = gid & FLIP_ALL
+    stripped = gid & TILE_FLIP_MASK
+    if flipped:
+        bits = "+".join(name for mask, name in FLIP_BIT_NAMES.items() if flipped & mask)
+        log.debug("Tile GID 0x%x has flip flag(s) %s — decoded", gid, bits)
+    return (
+        stripped,
+        bool(gid & TILE_FLIP_H),
+        bool(gid & TILE_FLIP_V),
+        bool(gid & TILE_FLIP_D),
+        bool(gid & TILE_FLIP_HEX),
+    )
+
+
+def _parse_tsx_root(root: ElementTree.Element, source_path: Path) -> dict:
+    if root.tag == "tileset":
+        tileset = root
+    else:
+        tileset = root.find("tileset")
+    if tileset is None:
+        raise TmxParseError(f"TSX {source_path}: missing <tileset> root element")
+    return _build_tsx_data(tileset, source_path)
+
+
+def _build_tsx_data(ts_elem: ElementTree.Element, source_path: Path) -> dict:
+    name = ts_elem.get("name", "")
+    tilewidth = _coerce_int(_require_attr(ts_elem, "tilewidth", name), f"{name}.tilewidth")
+    tileheight = _coerce_int(_require_attr(ts_elem, "tileheight", name), f"{name}.tileheight")
+    tilecount = _coerce_int(ts_elem.get("tilecount", 0), f"{name}.tilecount")
+    columns = _coerce_int(ts_elem.get("columns", 0), f"{name}.columns")
+
+    image_elem = ts_elem.find("image")
+    image_source = ""
+    image_width = 0
+    image_height = 0
+    if image_elem is not None:
+        image_source = image_elem.get("source", "")
+        image_width = _coerce_int(image_elem.get("width", 0), f"{name}.image.width")
+        image_height = _coerce_int(image_elem.get("height", 0), f"{name}.image.height")
+
+    data: dict = {
+        "name": name,
+        "tilewidth": tilewidth,
+        "tileheight": tileheight,
+        "tilecount": tilecount,
+        "columns": columns,
+        "image": image_source,
+        "imagewidth": image_width,
+        "imageheight": image_height,
+    }
+
+    props = _parse_properties(ts_elem)
+    if props:
+        data["properties"] = props
+
+    tile_properties: Dict[str, Dict[str, Any]] = {}
+    for tile_elem in ts_elem.findall("tile"):
+        tid = _coerce_int(_require_attr(tile_elem, "id", f"{name}.tile"), f"{name}.tile.id")
+        tile_props = _parse_properties(tile_elem)
+        if tile_props:
+            tile_properties[str(tid)] = tile_props
+    if tile_properties:
+        data["tile_properties"] = tile_properties
+
+    return data
+
+
+def _coerce_property_value(value: str, prop_type: str) -> Any:
+    if prop_type == "int":
+        return int(value)
+    elif prop_type == "float":
+        return float(value)
+    elif prop_type == "bool":
+        return value.lower() in ("true", "1")
+    elif prop_type == "color":
+        return value
+    return value
+
+
+def _parse_properties(elem: ElementTree.Element) -> Dict[str, Any]:
+    props: Dict[str, Any] = {}
+    props_elem = elem.find("properties")
+    if props_elem is None:
+        return props
+    for prop in props_elem.findall("property"):
+        prop_name = prop.get("name", "")
+        prop_type = prop.get("type", "string")
+        raw_value = prop.get("value")
+        if raw_value is None:
+            raw_value = (prop.text or "").strip()
+        props[prop_name] = _coerce_property_value(raw_value, prop_type)
+    return props
+
+
+def _build_embedded_tileset_properties(data: dict) -> Dict[str, Any]:
+    props: Dict[str, Any] = {}
+    if "properties" in data:
+        props["properties"] = data["properties"]
+    return props
+
+
+def _build_embedded_tile_properties(data: dict) -> Dict[str, Dict[str, Any]]:
+    return data.get("tile_properties", {})
+
+
+def _tileset_data_to_parsed(data: dict) -> ParsedTileset:
+    image_path = data.get("image", "")
+    ts_type = "tile"
+    props = _build_embedded_tileset_properties(data)
+    tile_props = _build_embedded_tile_properties(data)
+    return ParsedTileset(
+        path=image_path,
+        type=ts_type,
+        properties=props,
+        tile_properties=tile_props,
+        animation=None,
+    )
+
+
+def parse_tsx_file(path: Union[str, Path]) -> dict:
+    p = Path(path)
+    if not p.is_file():
+        raise TmxParseError(f"TSX file not found: {p}")
+    try:
+        tree = ElementTree.parse(p)
+    except ElementTree.ParseError as e:
+        raise TmxParseError(f"Invalid TSX XML in {p}: {e}") from e
+    return _parse_tsx_root(tree.getroot(), p)
+
+
+def _resolve_image_path(
+    raw_path: str, map_dir: Path, tsx_dir: Optional[Path] = None
+) -> str:
+    if not raw_path:
+        return ""
+    p = Path(raw_path)
+    if p.is_absolute():
+        return raw_path
+    if tsx_dir:
+        candidate = tsx_dir / p
+        if candidate.exists():
+            return str(candidate)
+    candidate = map_dir / p
+    if candidate.exists():
+        return str(candidate)
+    return raw_path
+
+
+def _decode_csv(text: str) -> List[int]:
+    gids: List[int] = []
+    for line in text.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        for token in line.split(","):
+            token = token.strip()
+            if not token:
+                continue
+            base = 16 if token.lower().startswith("0x") else 10
+            gids.append(int(token, base))
+    return gids
+
+
+def _decode_base64(text: str, compression: Optional[str]) -> List[int]:
+    try:
+        raw = base64.b64decode(text.strip())
+        if compression == "zlib":
+            raw = zlib.decompress(raw)
+        elif compression == "gzip":
+            raw = gzip.decompress(raw)
+        elif compression:
+            raise TmxParseError(
+                f"Unsupported tile data compression: {compression!r}"
+            )
+    except (ValueError, OSError, zlib.error) as e:
+        raise TmxParseError(f"Failed to decode tile data: {e}") from e
+
+    if len(raw) % 4 != 0:
+        raise TmxParseError(
+            f"Tile data payload has {len(raw)} bytes, expected multiple of 4"
+        )
+    count = len(raw) // 4
+    return list(struct.unpack(f"<{count}I", raw))
+
+
+def _parse_tile_layer(
+    layer_elem: ElementTree.Element,
+    tilesets: List[Tuple[int, ParsedTileset]],
+    ctx: str,
+) -> ParsedLayer:
+    name = layer_elem.get("name", "Unnamed")
+    width = _coerce_int(_require_attr(layer_elem, "width", ctx), f"{ctx}.width")
+    height = _coerce_int(_require_attr(layer_elem, "height", ctx), f"{ctx}.height")
+    visible = layer_elem.get("visible", "1") != "0"
+    opacity = _coerce_float(layer_elem.get("opacity", 1.0), f"{ctx}.opacity")
+
+    layer = ParsedLayer(
+        id=0,
+        name=name,
+        layer_type="tile",
+        visible=visible,
+        locked=False,
+        opacity=opacity,
+        z_index=0,
+    )
+
+    layer.properties = _parse_properties(layer_elem)
+
+    data_elem = layer_elem.find("data")
+    if data_elem is None:
+        return layer
+
+    encoding = data_elem.get("encoding", "xml")
+    compression = data_elem.get("compression")
+    text = data_elem.text or ""
+
+    if encoding == "csv":
+        gids = _decode_csv(text)
+    elif encoding == "base64":
+        gids = _decode_base64(text, compression)
+    else:
+        if encoding != "xml":
+            log.warning("%s: unsupported encoding %r, treating as xml", ctx, encoding)
+        gids = _decode_xml_tiles(data_elem, ctx)
+
+    expected = width * height
+    if len(gids) != expected:
+        raise TmxParseError(
+            f"{ctx}: expected {expected} tile GIDs, got {len(gids)}"
+        )
+
+    for idx, raw_gid in enumerate(gids):
+        if raw_gid == 0:
+            continue
+        tx = idx % width
+        ty = idx // width
+        stripped_gid, flip_h, flip_v, flip_d, flip_hex = _decode_flip_flags(raw_gid)
+        ttype, variant = _map_gid(stripped_gid, tilesets, f"{ctx}.tile[{ty},{tx}]")
+        if ttype is not None:
+            pos = (tx, ty)
+            layer.tiles[pos] = ParsedTile(
+                pos=pos,
+                ttype=ttype,
+                variant=variant,
+                flip_h=flip_h,
+                flip_v=flip_v,
+                flip_d=flip_d,
+                rotated_hex120=flip_hex,
+            )
+
+    return layer
+
+
+def _decode_xml_tiles(data_elem: ElementTree.Element, ctx: str) -> List[int]:
+    gids: List[int] = []
+    for tile_elem in data_elem.findall("tile"):
+        gid_str = tile_elem.get("gid", "0")
+        gids.append(int(gid_str))
+    return gids
+
+
+def _map_gid(
+    gid: int,
+    tilesets: List[Tuple[int, ParsedTileset]],
+    ctx: str,
+) -> Tuple[Optional[Union[int, str]], int]:
+    for i, (firstgid, ts) in enumerate(tilesets):
+        tilecount = int(getattr(ts, "_tilecount", 0))
+        if ts.animation is not None:
+            tilecount = max(tilecount, ts.animation.frame_count)
+        if tilecount > 0:
+            if firstgid <= gid < firstgid + tilecount:
+                return i, gid - firstgid
+        else:
+            next_firstgid = tilesets[i + 1][0] if i + 1 < len(tilesets) else float("inf")
+            if firstgid <= gid < next_firstgid:
+                return i, gid - firstgid
+    log.debug("%s: GID %d does not fall into any known tileset range", ctx, gid)
+    return None, 0
+
+
+def _parse_tmx_root(root: ElementTree.Element, map_dir: Path) -> ParsedMap:
+    map_elem = root
+
+    tilewidth = _coerce_int(
+        _require_attr(map_elem, "tilewidth", "<map>"), "<map>.tilewidth"
+    )
+    tileheight = _coerce_int(
+        _require_attr(map_elem, "tileheight", "<map>"), "<map>.tileheight"
+    )
+    map_width = _coerce_int(
+        _require_attr(map_elem, "width", "<map>"), "<map>.width"
+    )
+    map_height = _coerce_int(
+        _require_attr(map_elem, "height", "<map>"), "<map>.height"
+    )
+
+    meta = ParsedMeta(
+        tile_size=(tilewidth, tileheight),
+        map_size=(map_width, map_height),
+        initial_map_size=(map_width, map_height),
+        zoom_level=1.0,
+        scroll=(0, 0),
+        version="1.1",
+        render_scale=1.0,
+    )
+
+    parsed_tilesets: List[ParsedTileset] = []
+    tileset_ranges: List[Tuple[int, ParsedTileset]] = []
+
+    for ts_elem in map_elem.findall("tileset"):
+        firstgid = _coerce_int(
+            _require_attr(ts_elem, "firstgid", "<tileset>"), "<tileset>.firstgid"
+        )
+        source = ts_elem.get("source", "")
+        if source:
+            tsx_path = (map_dir / source).resolve()
+            if not tsx_path.is_file():
+                log.warning("Referenced TSX not found: %s", tsx_path)
+                ts = ParsedTileset(path="", type="tile")
+                ts_data: dict = {"tilecount": 0}
+            else:
+                ts_data = parse_tsx_file(tsx_path)
+                ts_data["image"] = _resolve_image_path(
+                    ts_data.get("image", ""), map_dir, tsx_path.parent
+                )
+                ts = _tileset_data_to_parsed(ts_data)
+        else:
+            ts_data = _build_tsx_data(ts_elem, map_dir)
+            ts_data["image"] = _resolve_image_path(
+                ts_data.get("image", ""), map_dir, None
+            )
+            ts = _tileset_data_to_parsed(ts_data)
+
+        tilecount = ts_data.get("tilecount", 0)
+        if tilecount == 0 and ts_data.get("imagewidth") and ts_data.get("tilewidth"):
+            cols = ts_data["imagewidth"] // ts_data["tilewidth"]
+            rows = ts_data["imageheight"] // ts_data["tileheight"]
+            tilecount = cols * rows
+        if tilecount:
+            ts._tilecount = tilecount
+        parsed_tilesets.append(ts)
+        tileset_ranges.append((firstgid, parsed_tilesets[-1]))
+        if tilecount == 0:
+            log.warning(
+                "Tileset %r (firstgid=%d) has tilecount=0, GID lookup may be imprecise",
+                ts_data.get("name", ""),
+                firstgid,
+            )
+
+    layers: List[ParsedLayer] = []
+    for i, layer_elem in enumerate(map_elem.findall("layer")):
+        layer = _parse_tile_layer(
+            layer_elem, tileset_ranges, f"layer[{i}]"
+        )
+        layer.id = i
+        layer.z_index = i
+        layers.append(layer)
+
+    project_state = ParsedProjectState(rules=[], groups=[], automap_rules=None)
+
+    return ParsedMap(
+        meta=meta,
+        layers=layers,
+        tilesets=parsed_tilesets,
+        project_state=project_state,
+        raw={},
+    )
+
+
+def parse_tmx_file(path: Union[str, Path]) -> ParsedMap:
+    p = Path(path)
+    if not p.is_file():
+        raise TmxParseError(f"TMX file not found: {p}")
+    if p.suffix.lower() not in (".tmx", ".xml"):
+        raise TmxParseError(f"Expected .tmx file, got {p.suffix!r}")
+    try:
+        tree = ElementTree.parse(p)
+    except ElementTree.ParseError as e:
+        raise TmxParseError(f"Invalid TMX XML in {p}: {e}") from e
+    return _parse_tmx_root(tree.getroot(), p.parent)

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/src/tilemap_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 4.0.0
+Version: 5.0.0
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -704,7 +704,10 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## 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
@@ -713,16 +716,22 @@ Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and co
 ## Quick Start
 
 ```python
-from tilemap_parser import load_map, TileLayerRenderer
+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)
 ```
 
 ```python
 from tilemap_parser import (
     CollisionRunner, CollisionCache,
     ObjectCollisionManager, CircleShape, RectangleShape,
+    ParticleSystem, ParticleSystemConfig
 )
 
 # Tile-based collision
@@ -735,10 +744,29 @@ 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)
 ```
 
 ## Links
 
-- **Docs**: https://tilemap-parser.vercel.app/
+- **Docs**: [https://deepwiki.com/FluffyBrudy/tilemap-parser](https://deepwiki.com/FluffyBrudy/tilemap-parser)
 - **Editor**: https://pypi.org/project/tilemap-editor/
 - **Repository**: https://github.com/FluffyBrudy/tilemap-parser

{tilemap_parser-4.0.0 → tilemap_parser-5.0.0}/src/tilemap_parser.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/tilemap_parser/parser/collision_loader.py
 src/tilemap_parser/parser/map_parse.py
 src/tilemap_parser/parser/node_parse.py
 src/tilemap_parser/parser/particle.py
+src/tilemap_parser/parser/tmx_converter.py
 src/tilemap_parser/runtime/__init__.py
 src/tilemap_parser/runtime/animation_player.py
 src/tilemap_parser/runtime/area_node.py
@@ -38,4 +39,5 @@ tests/test_object_collision.py
 tests/test_object_surfaces.py
 tests/test_particle_emitter.py
 tests/test_render_scale.py
-tests/test_tile_collision.py
+tests/test_tile_collision.py
+tests/test_tmx_converter.py

tilemap_parser-5.0.0/tests/test_tmx_converter.py

@@ -0,0 +1,442 @@
+from pathlib import Path
+
+import pytest
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def _resolve(name: str) -> Path:
+    p = FIXTURES / name
+    assert p.is_file(), f"Fixture not found: {p}"
+    return p
+
+
+class TestParseTsx:
+    def test_basic_tsx(self):
+        from tilemap_parser.parser.tmx_converter import parse_tsx_file
+
+        data = parse_tsx_file(_resolve("test_tileset.tsx"))
+        assert data["name"] == "test_tileset"
+        assert data["tilewidth"] == 32
+        assert data["tileheight"] == 32
+        assert data["tilecount"] == 4
+        assert data["columns"] == 2
+        assert data["image"] == "tileset.png"
+        assert "properties" not in data
+        assert "tile_properties" in data
+        tile0 = data["tile_properties"]["0"]
+        assert tile0["grass"] is True
+        tile1 = data["tile_properties"]["1"]
+        assert tile1["hp"] == 10
+
+    def test_tsx_file_not_found(self):
+        from tilemap_parser.parser.tmx_converter import TmxParseError, parse_tsx_file
+
+        with pytest.raises(TmxParseError, match="not found"):
+            parse_tsx_file("/nonexistent/nope.tsx")
+
+    def test_tsx_invalid_xml(self, tmp_path):
+        from tilemap_parser.parser.tmx_converter import TmxParseError, parse_tsx_file
+
+        bad = tmp_path / "bad.tsx"
+        bad.write_text("not xml")
+        with pytest.raises(TmxParseError, match="Invalid TSX"):
+            parse_tsx_file(bad)
+
+
+class TestParseTmxCsv:
+    def test_load_via_parse_map_file(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_csv.tmx"))
+
+        assert parsed.meta.tile_size == (32, 32)
+        assert parsed.meta.map_size == (3, 3)
+
+        assert len(parsed.tilesets) == 1
+        assert parsed.tilesets[0].path.endswith("tileset.png")
+
+        assert len(parsed.layers) == 1
+        layer = parsed.layers[0]
+        assert layer.name == "Tile Layer 1"
+        assert layer.layer_type == "tile"
+        assert layer.visible is True
+        assert layer.opacity == 1.0
+
+        assert len(layer.tiles) == 4  # only GIDs 1-4 valid (tilecount=4)
+
+        assert (0, 0) in layer.tiles
+        assert layer.tiles[(0, 0)].ttype == 0
+        assert layer.tiles[(0, 0)].variant == 0
+        assert layer.tiles[(1, 0)].variant == 1
+        assert layer.tiles[(2, 0)].variant == 2
+        assert layer.tiles[(0, 1)].variant == 3
+
+        assert (2, 2) not in layer.tiles  # GID 0 → empty
+
+    def test_embedded_tileset(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_embedded_tileset.tmx"))
+
+        assert len(parsed.tilesets) == 1
+        ts = parsed.tilesets[0]
+        assert ts.path.endswith("builtin.png")
+        assert ts.type == "tile"
+        assert ts._tilecount == 4
+
+        layer = parsed.layers[0]
+        assert len(layer.tiles) == 4
+        assert layer.tiles[(0, 0)].ttype == 0
+        assert layer.tiles[(0, 0)].variant == 0
+        assert layer.tiles[(1, 1)].variant == 3
+
+    def test_empty_map(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_empty.tmx"))
+
+        assert parsed.meta.map_size == (10, 10)
+        assert len(parsed.tilesets) == 0
+        assert len(parsed.layers) == 1
+        assert len(parsed.layers[0].tiles) == 0
+
+
+class TestParseTmxBase64:
+    def test_base64_zlib(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_base64.tmx"))
+
+        assert len(parsed.layers) == 1
+        layer = parsed.layers[0]
+        assert len(layer.tiles) == 4
+
+        assert layer.tiles[(0, 0)].ttype == 0
+        assert layer.tiles[(0, 0)].variant == 0
+        assert layer.tiles[(1, 0)].variant == 1
+        assert (2, 2) not in layer.tiles  # GID 0 → empty
+
+    def test_base64_raw_uncompressed(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_base64_raw.tmx"))
+
+        assert len(parsed.layers) == 1
+        layer = parsed.layers[0]
+        assert len(layer.tiles) == 4
+        assert layer.tiles[(0, 0)].variant == 0
+        assert layer.tiles[(2, 0)].variant == 2
+        assert (1, 1) not in layer.tiles  # GID 5 is out of range
+
+
+class TestFlipFlags:
+    def test_flip_flags_preserved_on_parsed_tile(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_flip.tmx"))
+
+        layer = parsed.layers[0]
+        assert len(layer.tiles) == 2
+
+        tile_with_flag = layer.tiles[(0, 0)]
+        assert tile_with_flag.variant == 0
+        assert tile_with_flag.flip_h is True
+        assert tile_with_flag.flip_v is False
+        assert tile_with_flag.flip_d is False
+        assert tile_with_flag.rotated_hex120 is False
+
+        tile_no_flag = layer.tiles[(1, 0)]
+        assert tile_no_flag.variant == 0
+        assert tile_no_flag.flip_h is False
+        assert tile_no_flag.flip_v is False
+        assert tile_no_flag.flip_d is False
+        assert tile_no_flag.rotated_hex120 is False
+
+    def test_strip_flip_bits(self):
+        from tilemap_parser.parser.tmx_converter import (
+            TILE_FLIP_H,
+            TILE_FLIP_V,
+            TILE_FLIP_D,
+            TILE_FLIP_HEX,
+            TILE_FLIP_MASK,
+            _decode_flip_flags,
+        )
+
+        assert _decode_flip_flags(1) == (1, False, False, False, False)
+        assert _decode_flip_flags(TILE_FLIP_H | 5) == (5, True, False, False, False)
+        assert _decode_flip_flags(TILE_FLIP_V | 3) == (3, False, True, False, False)
+        assert _decode_flip_flags(TILE_FLIP_D | 7) == (7, False, False, True, False)
+        assert _decode_flip_flags(TILE_FLIP_HEX | 11) == (11, False, False, False, True)
+        assert _decode_flip_flags(TILE_FLIP_H | TILE_FLIP_V | 42) == (42, True, True, False, False)
+        assert _decode_flip_flags(TILE_FLIP_H | TILE_FLIP_V | TILE_FLIP_D | 99) == (99, True, True, True, False)
+        assert _decode_flip_flags(0) == (0, False, False, False, False)
+
+
+class TestDecodeHelpers:
+    def test_decode_csv(self):
+        from tilemap_parser.parser.tmx_converter import _decode_csv
+
+        result = _decode_csv("1,2,3\n4,5,6\n")
+        assert result == [1, 2, 3, 4, 5, 6]
+
+    def test_decode_csv_empty(self):
+        from tilemap_parser.parser.tmx_converter import _decode_csv
+
+        assert _decode_csv("") == []
+
+    def test_decode_base64_zlib(self):
+        import base64
+        import struct
+        import zlib
+
+        from tilemap_parser.parser.tmx_converter import _decode_base64
+
+        data = struct.pack("<4I", 10, 20, 30, 40)
+        b64 = base64.b64encode(zlib.compress(data)).decode()
+        result = _decode_base64(b64, "zlib")
+        assert result == [10, 20, 30, 40]
+
+    def test_decode_base64_uncompressed(self):
+        import base64
+        import struct
+
+        from tilemap_parser.parser.tmx_converter import _decode_base64
+
+        data = struct.pack("<3I", 7, 8, 9)
+        b64 = base64.b64encode(data).decode()
+        result = _decode_base64(b64, None)
+        assert result == [7, 8, 9]
+
+    def test_decode_base64_unsupported_compression(self):
+        from tilemap_parser.parser.tmx_converter import TmxParseError, _decode_base64
+
+        with pytest.raises(TmxParseError, match="Unsupported"):
+            _decode_base64("AAAA", "lzma")
+
+
+class TestProjectState:
+    def test_project_state_empty(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        parsed = parse_map_file(_resolve("test_map_csv.tmx"))
+
+        assert len(parsed.project_state.rules) == 0
+        assert len(parsed.project_state.groups) == 0
+        assert parsed.project_state.automap_rules is None
+
+
+class TestXmlEncoding:
+    def test_xml_tile_encoding(self, tmp_path):
+        from tilemap_parser.parser.tmx_converter import parse_tmx_file
+
+        tmx = tmp_path / "xml_encoded.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="2" height="2" tilewidth="16" tileheight="16" infinite="0">
+ <tileset firstgid="1" name="a" tilewidth="16" tileheight="16" tilecount="4" columns="2">
+  <image source="a.png" width="32" height="32"/>
+ </tileset>
+ <layer id="1" name="Tile Layer 1" width="2" height="2">
+  <data>
+   <tile gid="1"/>
+   <tile gid="2"/>
+   <tile gid="3"/>
+   <tile gid="4"/>
+  </data>
+ </layer>
+</map>""")
+        parsed = parse_tmx_file(tmx)
+        assert len(parsed.layers[0].tiles) == 4
+        assert parsed.layers[0].tiles[(0, 0)].variant == 0
+        assert parsed.layers[0].tiles[(1, 1)].variant == 3
+
+    def test_xml_with_empty_tiles(self, tmp_path):
+        from tilemap_parser.parser.tmx_converter import parse_tmx_file
+
+        tmx = tmp_path / "xml_empty.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="2" height="2" tilewidth="16" tileheight="16" infinite="0">
+ <tileset firstgid="1" name="a" tilewidth="16" tileheight="16" tilecount="4" columns="2">
+  <image source="a.png" width="32" height="32"/>
+ </tileset>
+ <layer id="1" name="Empty" width="2" height="2">
+  <data>
+   <tile gid="0"/>
+   <tile gid="0"/>
+   <tile gid="0"/>
+   <tile gid="1"/>
+  </data>
+ </layer>
+</map>""")
+        parsed = parse_tmx_file(tmx)
+        assert len(parsed.layers[0].tiles) == 1
+        assert (1, 1) in parsed.layers[0].tiles
+
+
+class TestLayerProperties:
+    def test_layer_visibility_and_opacity(self, tmp_path):
+        from tilemap_parser.parser.tmx_converter import parse_tmx_file
+
+        tmx = tmp_path / "props.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="1" height="1" tilewidth="16" tileheight="16" infinite="0">
+ <layer id="1" name="Hidden" width="1" height="1" visible="0" opacity="0.5">
+  <data encoding="csv">0</data>
+ </layer>
+</map>""")
+        parsed = parse_tmx_file(tmx)
+        layer = parsed.layers[0]
+        assert layer.visible is False
+        assert layer.opacity == 0.5
+        assert layer.name == "Hidden"
+
+
+class TestMultipleLayers:
+    def test_two_layers(self, tmp_path):
+        from tilemap_parser.parser.tmx_converter import parse_tmx_file
+
+        tmx = tmp_path / "two_layers.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="2" height="2" tilewidth="16" tileheight="16" infinite="0">
+ <tileset firstgid="1" name="a" tilewidth="16" tileheight="16" tilecount="4" columns="2">
+  <image source="a.png" width="32" height="32"/>
+ </tileset>
+ <layer id="1" name="Ground" width="2" height="2">
+  <data encoding="csv">1,1,1,1</data>
+ </layer>
+ <layer id="2" name="Overlay" width="2" height="2">
+  <data encoding="csv">0,2,0,0</data>
+ </layer>
+</map>""")
+        parsed = parse_tmx_file(tmx)
+        assert len(parsed.layers) == 2
+        assert parsed.layers[0].name == "Ground"
+        assert parsed.layers[0].z_index == 0
+        assert len(parsed.layers[0].tiles) == 4
+        assert parsed.layers[1].name == "Overlay"
+        assert parsed.layers[1].z_index == 1
+        assert len(parsed.layers[1].tiles) == 1
+
+
+class TestRuntimeIntegration:
+    def test_tmx_loads_via_tilemap_data(self, tmp_path):
+        import pygame
+
+        from tilemap_parser.runtime.map_loader import TilemapData
+
+        data_dir = tmp_path / "data"
+        data_dir.mkdir()
+        assets_dir = tmp_path / "assets"
+        assets_dir.mkdir()
+
+        png = assets_dir / "tileset.png"
+        surf = pygame.Surface((64, 64))
+        surf.fill((255, 0, 255))
+        pygame.image.save(surf, str(png))
+
+        tmx = data_dir / "test.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="2" height="2" tilewidth="32" tileheight="32" infinite="0">
+ <tileset firstgid="1" name="test" tilewidth="32" tileheight="32" tilecount="4" columns="2">
+  <image source="../assets/tileset.png" width="64" height="64"/>
+ </tileset>
+ <layer id="1" name="Ground" width="2" height="2">
+  <data encoding="csv">1,2,3,4</data>
+ </layer>
+</map>""")
+
+        td = TilemapData.load(tmx, skip_missing_images=False)
+        assert len(td.warnings) == 0
+        assert len(td.surfaces) == 1
+        assert td.surfaces[0] is not None
+        assert len(td.parsed.layers) == 1
+        layer_data = td.get_layer("Ground")
+        assert layer_data is not None
+        assert len(layer_data.tiles) == 4
+
+    def test_tmx_missing_tileset_warns(self, tmp_path):
+        import pygame
+
+        from tilemap_parser.runtime.map_loader import TilemapData
+
+        tmx = tmp_path / "missing.tmx"
+        tmx.write_text("""<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.10" orientation="orthogonal" renderorder="right-down" width="2" height="2" tilewidth="32" tileheight="32" infinite="0">
+ <tileset firstgid="1" source="nonexistent.tsx"/>
+ <layer id="1" name="Ground" width="2" height="2">
+  <data encoding="csv">0,0,0,0</data>
+ </layer>
+</map>""")
+
+        td = TilemapData.load(tmx, extra_search_base=tmp_path)
+        assert len(td.warnings) >= 1
+
+    def test_real_sewers_map_from_tiled_examples(self):
+        import pygame
+
+        from tilemap_parser.runtime.map_loader import TilemapData
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        tmx_path = _resolve("sewers.tmx")
+        png_path = _resolve("sewer_tileset.png")
+        assert png_path.is_file()
+
+        parsed = parse_map_file(tmx_path)
+
+        assert parsed.meta.tile_size == (24, 24)
+        assert parsed.meta.map_size == (50, 50)
+
+        assert len(parsed.tilesets) == 1
+        ts = parsed.tilesets[0]
+        assert ts.path.endswith("sewer_tileset.png")
+        assert ts.type == "tile"
+
+        assert len(parsed.layers) == 2
+        bottom = parsed.layers[0]
+        top = parsed.layers[1]
+
+        assert bottom.name == "Bottom"
+        assert bottom.layer_type == "tile"
+        assert bottom.opacity == 1.0
+        assert len(bottom.tiles) > 0
+
+        assert top.name == "Top"
+        assert top.layer_type == "tile"
+        assert top.opacity == 0.49
+        assert len(top.tiles) > 0
+
+        all_ttypes = {t.ttype for t in bottom.tiles.values()}
+        assert all_ttypes == {0}
+
+        all_variants = {t.variant for t in bottom.tiles.values()}
+        max_variant = max(all_variants)
+        min_variant = min(all_variants)
+        assert min_variant >= 0
+        assert max_variant < 72  # 8 cols * 9 rows
+
+        td = TilemapData.load(tmx_path, skip_missing_images=False)
+        assert len(td.warnings) == 0
+        assert len(td.surfaces) == 1
+        assert td.surfaces[0] is not None
+        assert td.surfaces[0].get_size() == (192, 217)
+
+        assert len(td.parsed.layers) == 2
+
+        assert td.get_layer("Bottom") is not None
+        assert td.get_layer("Top") is not None
+
+
+class TestErrorCases:
+    def test_nonexistent_file(self):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        with pytest.raises(Exception, match="Not a file"):
+            parse_map_file("/nonexistent/map.tmx")
+
+    def test_wrong_extension_raises_error(self, tmp_path):
+        from tilemap_parser.parser.map_parse import parse_map_file
+
+        f = tmp_path / "test.py"
+        f.write_text("not a map")
+        with pytest.raises(Exception, match=r"\.json.*\.tmx"):
+            parse_map_file(f)