tilemap-parser 5.0.2__tar.gz → 5.0.3__tar.gz

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 5.0.2
+Version: 5.0.3
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -699,106 +699,50 @@ Dynamic: license-file
 
 # tilemap-parser
 
-Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
+Standalone parser/loader for [tilemap-editor](https://pypi.org/project/tilemap-editor/) JSON maps, sprite animations, and a collision detection runtime.
 
-## Features
+## Install
 
-- **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
+```bash
+pip install tilemap-parser
+```
 
-## Quick Start
+## Quick start
 
 ```python
-from tilemap_parser import load_map, TileLayerRenderer, Camera
+from tilemap_parser import load_map, TileLayerRenderer, Camera, ParticleField, FOG_PROFILE
 
-# 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
-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,
+# Persistent fog: fill once, wrap forever — no particle churn
+mist = ParticleField(
+    area=(0, 0, 800, 600),
+    profile=FOG_PROFILE,   # plain data — copy and tweak for your own moods
+    color=(200, 50, 80),
+    global_alpha=0.5,
 )
-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](docs/physics-world.md) and `examples/physics-crate/main.py`.
-
-```python
-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)
-```
+## Features
 
-Pushable crates are just kinematic bodies moved with an explicit velocity (gravity is skipped when `velocity=` is given):
+- **Map parsing** — tilemaps, layers, objects, and autotile data from JSON
+- **Collision** — tile-based (`CollisionRunner`) and object-to-object (`ObjectCollisionManager`) with rect, circle, capsule, and polygon shapes
+- **Physics** — `PhysicsWorld` with static/kinematic `Body` solids and one-way platforms
+- **Particles** — wrapped continuous fields (`ParticleField`, `FOG_PROFILE`), burst emitters, alpha fades, and batch rendering (`SpriteBatchRenderer`)
+- **Pathfinding** — A* `Pathfinder` over eroded `NavGrid`s
+- **Animation** — frame-based `AnimationPlayer`, plus a `Camera` with centered/deadzone follow
+- **Rendering** — chunked `TileLayerRenderer` and `LayerRenderStats`
 
-```python
-# 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
-```
+## Requirements
 
-`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).
+- Python 3.10+
+- `pygame-ce>=2.5` (installed automatically)
 
-## Docs
+## Links
 
-Full documentation: [https://tilemap-parser.vercel.app/](https://tilemap-parser.vercel.app/)
+- **Documentation**: https://tilemap-parser.vercel.app/
+- **Repository**: https://github.com/FluffyBrudy/tilemap-parser

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/README.md

@@ -100,6 +100,9 @@ if result.hit_wall_x:
 
 `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
+## Links
 
-Full documentation: [https://tilemap-parser.vercel.app/](https://tilemap-parser.vercel.app/)
+- **Docs**: [https://tilemap-parser.vercel.app/](https://tilemap-parser.vercel.app/)
+- **Docs (deepwiki)**: [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-5.0.3/pypi-readme.md

@@ -0,0 +1,49 @@
+# tilemap-parser
+
+Standalone parser/loader for [tilemap-editor](https://pypi.org/project/tilemap-editor/) JSON maps, sprite animations, and a collision detection runtime.
+
+## Install
+
+```bash
+pip install tilemap-parser
+```
+
+## Quick start
+
+```python
+from tilemap_parser import load_map, TileLayerRenderer, Camera, ParticleField, FOG_PROFILE
+
+game_data = load_map("path/to/map.json")
+renderer = TileLayerRenderer(game_data)
+
+camera = Camera(800, 600, mode="centered")
+camera.follow(player)
+
+# Persistent fog: fill once, wrap forever — no particle churn
+mist = ParticleField(
+    area=(0, 0, 800, 600),
+    profile=FOG_PROFILE,   # plain data — copy and tweak for your own moods
+    color=(200, 50, 80),
+    global_alpha=0.5,
+)
+```
+
+## Features
+
+- **Map parsing** — tilemaps, layers, objects, and autotile data from JSON
+- **Collision** — tile-based (`CollisionRunner`) and object-to-object (`ObjectCollisionManager`) with rect, circle, capsule, and polygon shapes
+- **Physics** — `PhysicsWorld` with static/kinematic `Body` solids and one-way platforms
+- **Particles** — wrapped continuous fields (`ParticleField`, `FOG_PROFILE`), burst emitters, alpha fades, and batch rendering (`SpriteBatchRenderer`)
+- **Pathfinding** — A* `Pathfinder` over eroded `NavGrid`s
+- **Animation** — frame-based `AnimationPlayer`, plus a `Camera` with centered/deadzone follow
+- **Rendering** — chunked `TileLayerRenderer` and `LayerRenderStats`
+
+## Requirements
+
+- Python 3.10+
+- `pygame-ce>=2.5` (installed automatically)
+
+## Links
+
+- **Documentation**: https://tilemap-parser.vercel.app/
+- **Repository**: https://github.com/FluffyBrudy/tilemap-parser

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "5.0.2"
+version = "5.0.3"
 description = "Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime."
-readme = "README.md"
+readme = "pypi-readme.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
 authors = [{ name = "tilemap parser contributors" }]

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/src/tilemap_parser/__init__.py

@@ -46,8 +46,13 @@ __all__ = [
     "TileLayerRenderer",
     "TilesetCollision",
     "TilemapData",
+    "FOG_PROFILE",
+    "FieldLayerSpec",
+    "FieldProfile",
     "Particle",
     "ParticleEmitter",
+    "ParticleField",
+    "ParticleFieldLayer",
     "ParticleRenderer",
     "ParticleSystem",
     "ParticleSystemConfig",

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/src/tilemap_parser/parser/__init__.py

@@ -51,6 +51,10 @@ from .particle import (
     ALPHA_FADE_MODES,
     EMISSION_SHAPES,
     PARTICLE_SHAPES,
+    AlphaFadeMode,
+    EmissionShape,
+    FieldQuality,
+    ParticleShape,
     ParticleSystemConfig,
     parse_particle_dict,
     parse_particle_file,
@@ -105,6 +109,10 @@ __all__ = [
     "ALPHA_FADE_MODES",
     "EMISSION_SHAPES",
     "PARTICLE_SHAPES",
+    "AlphaFadeMode",
+    "EmissionShape",
+    "FieldQuality",
+    "ParticleShape",
     "ParticleSystemConfig",
     "parse_particle_dict",
     "parse_particle_file",

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/src/tilemap_parser/parser/particle.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import json
+import math
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union, cast, get_args
 
 from .map_parse import (
     JsonDict,
@@ -18,16 +19,21 @@ from .map_parse import (
 )
 
 
+EmissionShape = Literal["point", "rect", "circle", "line"]
+ParticleShape = Literal["circle", "square", "diamond", "star", "sparkle", "smoke", "heart", "line", "fog"]
+AlphaFadeMode = Literal["none", "fade_out", "fade_in", "fade_both"]
+FieldQuality = Literal["low", "medium", "high"]
+
 EMISSION_SHAPES = ["point", "rect", "circle", "line"]
-PARTICLE_SHAPES = ["circle", "square", "diamond", "star", "sparkle", "smoke", "heart", "line"]
-ALPHA_FADE_MODES = ["none", "fade_out", "fade_in", "fade_both"]
+PARTICLE_SHAPES = list(get_args(ParticleShape))
+ALPHA_FADE_MODES = list(get_args(AlphaFadeMode))
 
 
 @dataclass
 class ParticleSystemConfig:
     name: str
-    emission_shape: str = "point"
-    particle_shape: str = "circle"
+    emission_shape: EmissionShape = "point"
+    particle_shape: ParticleShape = "circle"
     particle_size_min: int = 2
     particle_size_max: int = 6
     spawn_rate: int = 20
@@ -51,7 +57,9 @@ class ParticleSystemConfig:
     start_scale: float = 1.0
     end_scale: float = 0.3
     rotation_speed: float = 0.0
-    alpha_fade: str = "fade_out"
+    alpha_fade: AlphaFadeMode = "fade_out"
+    fade_peak_alpha: Optional[int] = None
+    wrap: bool = False
 
     def apply_render_scale(self, scale: float) -> None:
         """Scale dimensionful fields by *scale* (typically ``render_scale``).
@@ -70,8 +78,45 @@ class ParticleSystemConfig:
         self.gravity_x *= scale
         self.gravity_y *= scale
 
+    def fill_area(self, w: float, h: float) -> float:
+        """Effective fill area of the emission shape over a ``w x h`` rect.
+
+        Rect and line fill their whole band; circle fills only the
+        inscribed disc (``pi * (min(w, h) / 2) ** 2``), so density math
+        stays honest for non-rect shapes.  ``point`` has no area and
+        raises.
+        """
+        if self.emission_shape == "circle":
+            radius = min(w, h) / 2
+            return math.pi * radius * radius
+        if self.emission_shape == "point":
+            raise ValueError(
+                "emission_shape 'point' has no fill area; use rect/circle/line "
+                "or a wider emission rect"
+            )
+        return w * h
+
+    def count_for_coverage(self, coverage: float, w: float, h: float) -> int:
+        """Particles needed so sheets cover ``coverage`` of the ``w x h`` area.
+
+        ``coverage`` is dimensionless (0.5 = half the area).  Count is
+        ``coverage * fill_area / mean_particle_area``, where the particle
+        area uses the shape's fill factor (circle sheets are roughly
+        ``pi/4`` of their bounding square; everything else uses the full
+        square).  Not capped by ``max_particles`` — cap it yourself or use
+        ``ParticleSystem.emit_field``, which does.
+        """
+        if coverage <= 0:
+            raise ValueError(f"coverage must be > 0, got {coverage}")
+        mean_size = (self.particle_size_min + self.particle_size_max) / 2
+        if mean_size <= 0:
+            return 0
+        fill = math.pi / 4 if self.particle_shape == "circle" else 1.0
+        area = self.fill_area(w, h)
+        return max(0, round(coverage * area / (mean_size * mean_size * fill)))
+
     def to_dict(self) -> JsonDict:
-        return {
+        d = {
             "emission_shape": self.emission_shape,
             "particle_shape": self.particle_shape,
             "particle_size_min": self.particle_size_min,
@@ -98,7 +143,11 @@ class ParticleSystemConfig:
             "end_scale": self.end_scale,
             "rotation_speed": self.rotation_speed,
             "alpha_fade": self.alpha_fade,
+            "wrap": self.wrap,
         }
+        if self.fade_peak_alpha is not None:
+            d["fade_peak_alpha"] = self.fade_peak_alpha
+        return d
 
     @classmethod
     def from_dict(cls, d: JsonDict, name: str = "") -> "ParticleSystemConfig":
@@ -106,18 +155,18 @@ class ParticleSystemConfig:
             return d.get(key, default)
 
         cfg = cls(name=name)
-        cfg.emission_shape = str(g("emission_shape", "point"))
+        cfg.emission_shape = cast(EmissionShape, str(g("emission_shape", "point")))
         if cfg.emission_shape not in EMISSION_SHAPES:
             cfg.emission_shape = "point"
-        cfg.particle_shape = str(g("particle_shape", "circle"))
+        cfg.particle_shape = cast(ParticleShape, str(g("particle_shape", "circle")))
         if cfg.particle_shape not in PARTICLE_SHAPES:
             cfg.particle_shape = "circle"
-        cfg.alpha_fade = str(g("alpha_fade", "fade_out"))
+        cfg.alpha_fade = cast(AlphaFadeMode, str(g("alpha_fade", "fade_out")))
         if cfg.alpha_fade not in ALPHA_FADE_MODES:
             cfg.alpha_fade = "fade_out"
         cfg.particle_size_min = max(1, int(g("particle_size_min", 2)))
         cfg.particle_size_max = max(cfg.particle_size_min, int(g("particle_size_max", 6)))
-        cfg.spawn_rate = max(1, int(g("spawn_rate", 20)))
+        cfg.spawn_rate = max(0, int(g("spawn_rate", 20)))
         cfg.max_particles = max(1, int(g("max_particles", 100)))
         cfg.lifetime_min = max(0.1, float(g("lifetime_min", 0.5)))
         cfg.lifetime_max = max(cfg.lifetime_min, float(g("lifetime_max", 2.0)))
@@ -138,6 +187,12 @@ class ParticleSystemConfig:
         cfg.start_scale = max(0.1, float(g("start_scale", 1.0)))
         cfg.end_scale = max(0.1, float(g("end_scale", 0.3)))
         cfg.rotation_speed = float(g("rotation_speed", 0))
+        cfg.wrap = bool(g("wrap", False))
+        raw_peak = d.get("fade_peak_alpha")
+        if raw_peak is None:
+            cfg.fade_peak_alpha = None
+        else:
+            cfg.fade_peak_alpha = max(0, min(255, int(raw_peak)))
         return cfg
 
 

{tilemap_parser-5.0.2 → tilemap_parser-5.0.3}/src/tilemap_parser/runtime/__init__.py

@@ -26,9 +26,14 @@ from .renderer import LayerRenderStats, TileLayerRenderer
 from .area_node import AreaNode
 from . import navigation
 from .particles import (
+    FOG_PROFILE,
+    FieldLayerSpec,
+    FieldProfile,
     Particle,
     ParticleEmitter,
     ParticleEmitterNode,
+    ParticleField,
+    ParticleFieldLayer,
     ParticleRenderer,
     ParticleSystem,
     SpriteBatchRenderer,
@@ -64,9 +69,14 @@ __all__ = [
     "load_map_objects",
     "load_object_collision",
     "load_tileset_collision",
+    "FOG_PROFILE",
+    "FieldLayerSpec",
+    "FieldProfile",
     "Particle",
     "ParticleEmitter",
     "ParticleEmitterNode",
+    "ParticleField",
+    "ParticleFieldLayer",
     "ParticleRenderer",
     "ParticleSystem",
     "PhysicsWorld",