flocking 0.1.0__cp39-abi3-win_amd64.whl

flocking/__init__.py

@@ -0,0 +1,22 @@
+"""Rust-owned vehicle simulation with coherent snapshots and queued commands.
+
+Command IDs acknowledge queue admission. State changes become visible at tick
+commit. Stop worlds explicitly (or use a context manager) to join their worker.
+NumPy is optional: install ``flocking[numpy]`` for heightmaps and array snapshots.
+"""
+
+from ._native import (
+    CapacityError, CollisionError, Deadlock, DynamicObstacle, FlockingError,
+    FormationConfig, FormationMemberStatus, FormationStatus, InvalidArgumentError,
+    LifecycleError, NavigationStatus, QueueFullError, RecoveryConfig, RecoveryStatus, SafetyStatus, Snapshot, StateFrame,
+    StoppedError, TimeoutError, UnknownIdError, UnsupportedError, VehicleControl,
+    VehicleProfile, WorkerError, World,
+)
+
+__all__ = [
+    "CapacityError", "CollisionError", "Deadlock", "DynamicObstacle", "FlockingError",
+    "FormationConfig", "FormationMemberStatus", "FormationStatus", "InvalidArgumentError",
+    "LifecycleError", "NavigationStatus", "QueueFullError", "RecoveryConfig", "RecoveryStatus", "SafetyStatus", "Snapshot", "StateFrame",
+    "StoppedError", "TimeoutError", "UnknownIdError", "UnsupportedError", "VehicleControl",
+    "VehicleProfile", "WorkerError", "World",
+]

flocking/_native.pyi

@@ -0,0 +1,340 @@
+"""Public native API. Coordinates are meters, angles radians, times seconds."""
+from collections.abc import Iterable, Sequence
+from types import TracebackType
+from typing import Any, Literal, Optional, TypedDict, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+class FlockingError(RuntimeError): ...
+class LifecycleError(FlockingError): ...
+class QueueFullError(FlockingError): ...
+class StoppedError(FlockingError): ...
+class WorkerError(FlockingError): ...
+class UnknownIdError(FlockingError): ...
+class InvalidArgumentError(FlockingError): ...
+class CapacityError(FlockingError): ...
+class CollisionError(FlockingError): ...
+class UnsupportedError(FlockingError): ...
+class TimeoutError(FlockingError): ...
+
+class VehicleProfile:
+    def __init__(self, *, wheelbase: float = 2.7, length: float = 4.5,
+        width: float = 1.8, max_steering_angle: float = 0.6,
+        max_forward_speed: float = 20.0, max_reverse_speed: float = 5.0,
+        max_acceleration: float = 3.0, max_braking: float = 8.0,
+        max_slope_radians: float = 1.5707963267948966) -> None: ...
+    @property
+    def wheelbase(self) -> float: ...
+    @property
+    def length(self) -> float: ...
+    @property
+    def width(self) -> float: ...
+    @property
+    def max_steering_angle(self) -> float: ...
+    @property
+    def max_forward_speed(self) -> float: ...
+    @property
+    def max_reverse_speed(self) -> float: ...
+    @property
+    def max_acceleration(self) -> float: ...
+    @property
+    def max_braking(self) -> float: ...
+    @property
+    def max_slope_radians(self) -> float: ...
+
+class VehicleControl:
+    def __init__(self, throttle: float = 0.0, brake: float = 0.0,
+        steering: float = 0.0, reverse: bool = False) -> None: ...
+    @property
+    def throttle(self) -> float: ...
+    @property
+    def brake(self) -> float: ...
+    @property
+    def steering(self) -> float: ...
+    @property
+    def reverse(self) -> bool: ...
+
+class FormationConfig:
+    def __init__(self, kind: str = "convoy", *, spacing: float = 3.0,
+        max_speed: float = 8.0, target_weight: float = 1.0,
+        separation_weight: float = 1.5, alignment_weight: float = 0.25,
+        cohesion_weight: float = 0.1, neighbor_radius: float = 25.0,
+        separation_radius: float = 8.0, arrival_radius: float = 1.0,
+        reassignment_interval: int = 30, reassignment_hysteresis: float = 2.0,
+        bottleneck_lookahead: float = 12.0, widening_ticks: int = 30,
+        overtaking: bool = False, narrowing: bool = True, max_members: int = 256,
+        max_neighbors: int = 64, work_per_tick: int = 65536) -> None: ...
+    @property
+    def kind(self) -> str: ...
+    @property
+    def spacing(self) -> float: ...
+    @property
+    def max_speed(self) -> float: ...
+    @property
+    def target_weight(self) -> float: ...
+    @property
+    def separation_weight(self) -> float: ...
+    @property
+    def alignment_weight(self) -> float: ...
+    @property
+    def cohesion_weight(self) -> float: ...
+    @property
+    def neighbor_radius(self) -> float: ...
+    @property
+    def separation_radius(self) -> float: ...
+    @property
+    def arrival_radius(self) -> float: ...
+    @property
+    def reassignment_interval(self) -> int: ...
+    @property
+    def reassignment_hysteresis(self) -> float: ...
+    @property
+    def bottleneck_lookahead(self) -> float: ...
+    @property
+    def widening_ticks(self) -> int: ...
+    @property
+    def overtaking(self) -> bool: ...
+    @property
+    def narrowing(self) -> bool: ...
+    @property
+    def max_members(self) -> int: ...
+    @property
+    def max_neighbors(self) -> int: ...
+    @property
+    def work_per_tick(self) -> int: ...
+
+class FormationMemberStatus:
+    @property
+    def vehicle_id(self) -> int: ...
+    @property
+    def slot(self) -> int: ...
+    @property
+    def target(self) -> tuple[float, float]: ...
+    @property
+    def state(self) -> str: ...
+
+class FormationStatus:
+    @property
+    def id(self) -> int: ...
+    @property
+    def leader_id(self) -> int: ...
+    @property
+    def kind(self) -> str: ...
+    @property
+    def narrowed(self) -> bool: ...
+    @property
+    def resource_limited(self) -> bool: ...
+    @property
+    def work_used(self) -> int: ...
+    @property
+    def members(self) -> list[FormationMemberStatus]: ...
+
+class SafetyStatus:
+    @property
+    def vehicle_id(self) -> int: ...
+    @property
+    def state(self) -> str: ...
+    @property
+    def blocked_by(self) -> list[str]: ...
+    @property
+    def blocked_ticks(self) -> int: ...
+
+class DynamicObstacle:
+    @property
+    def id(self) -> int: ...
+    @property
+    def bounds(self) -> tuple[float, float, float, float]: ...
+    @property
+    def velocity(self) -> tuple[float, float]: ...
+    @property
+    def stopped(self) -> bool: ...
+
+class Deadlock:
+    @property
+    def vehicle_ids(self) -> list[int]: ...
+    @property
+    def dynamic_obstacle_ids(self) -> list[int]: ...
+    @property
+    def blocked_ticks(self) -> int: ...
+
+class NavigationStatus:
+    @property
+    def vehicle_id(self) -> int: ...
+    @property
+    def request_id(self) -> Optional[int]: ...
+    @property
+    def goal(self) -> Optional[tuple[float, float, Optional[float]]]: ...
+    @property
+    def state(self) -> str: ...
+    @property
+    def failure(self) -> Optional[str]: ...
+    @property
+    def route_id(self) -> Optional[int]: ...
+    @property
+    def progress(self) -> float: ...
+    @property
+    def attempt(self) -> int: ...
+    @property
+    def work_units(self) -> int: ...
+    @property
+    def guard_deferred(self) -> bool: ...
+    @property
+    def deferred_ticks(self) -> int: ...
+    @property
+    def cache_hits(self) -> int: ...
+
+class SnapshotArrays(TypedDict):
+    tick: int
+    version: int
+    ids: NDArray[np.uint64]
+    states: NDArray[np.float32]
+    corners: NDArray[np.float32]
+
+class RecoveryConfig:
+    def __init__(self, *, enabled: bool = False, blocked_ticks: int = 60,
+        reverse_ticks: int = 120, cooldown_ticks: int = 60, max_distance: float = 6.0,
+        reverse_speed: float = 2.0, max_attempts: int = 3, max_active: int = 16,
+        work_per_tick: int = 65536) -> None: ...
+    @property
+    def enabled(self) -> bool: ...
+    @property
+    def blocked_ticks(self) -> int: ...
+    @property
+    def reverse_ticks(self) -> int: ...
+    @property
+    def cooldown_ticks(self) -> int: ...
+    @property
+    def max_distance(self) -> float: ...
+    @property
+    def reverse_speed(self) -> float: ...
+    @property
+    def max_attempts(self) -> int: ...
+    @property
+    def max_active(self) -> int: ...
+    @property
+    def work_per_tick(self) -> int: ...
+
+class RecoveryStatus:
+    @property
+    def vehicle_id(self) -> int: ...
+    @property
+    def state(self) -> str: ...
+    @property
+    def attempt(self) -> int: ...
+    @property
+    def started_tick(self) -> int: ...
+    @property
+    def distance(self) -> float: ...
+
+class Snapshot:
+    @property
+    def tick(self) -> int: ...
+    @property
+    def version(self) -> int: ...
+    @property
+    def terrain_revision(self) -> int: ...
+    @property
+    def simulated_seconds(self) -> float: ...
+    @property
+    def vehicles(self) -> list[tuple[int, float, float, float]]: ...
+    @property
+    def formations(self) -> list[FormationStatus]: ...
+    @property
+    def recovery(self) -> list[RecoveryStatus]: ...
+    @property
+    def safety(self) -> list[SafetyStatus]: ...
+    @property
+    def dynamic_obstacles(self) -> list[DynamicObstacle]: ...
+    @property
+    def deadlocks(self) -> list[Deadlock]: ...
+    @property
+    def navigation(self) -> list[NavigationStatus]: ...
+    def to_bytes(self) -> bytes: ...
+    def numpy(self) -> SnapshotArrays:
+        """Immutable owned arrays: ids[N], states[N,8], corners[N,4,2]."""
+        ...
+
+class StateFrame:
+    @staticmethod
+    def from_bytes(data: bytes) -> StateFrame: ...
+    @property
+    def tick(self) -> int: ...
+    @property
+    def version(self) -> int: ...
+    @property
+    def simulated_seconds(self) -> float: ...
+    @property
+    def vehicles(self) -> list[tuple[int, float, float, float]]: ...
+    @property
+    def dynamic_obstacles(self) -> list[DynamicObstacle]: ...
+    def numpy(self) -> SnapshotArrays: ...
+    def to_bytes(self) -> bytes: ...
+
+Profile = Union[VehicleProfile, Literal["default"], None]
+GoalRow = Union[tuple[int, float, float], tuple[int, float, float, Optional[float]]]
+
+class World:
+    def __init__(self, width: int = 10000, height: int = 10000,
+        tick_hz: int = 30, queue_capacity: int = 1024, *, threads: Optional[int] = None,
+        parallel_threshold: int = 128,
+        max_slope_radians: float = 0.7853981633974483, terrain_cost_weight: float = 0.0) -> None: ...
+    @staticmethod
+    def from_heightmap(heights: ArrayLike, meters_per_cell: float = 1.0,
+        tick_hz: int = 30, queue_capacity: int = 1024, *, threads: Optional[int] = None,
+        parallel_threshold: int = 128,
+        max_slope_radians: float = 0.7853981633974483, terrain_cost_weight: float = 0.0, minimum_height: Optional[float] = None) -> World: ...
+    def update_heightmap(self, x: int, y: int, heights: ArrayLike) -> int:
+        """Admit a bounded absolute sample patch; snapshot.terrain_revision confirms commit."""
+        ...
+    def set_static_obstacles(self, obstacles: Iterable[tuple[int, float, float, float, float]]) -> int:
+        """Replace at most 128 (id,min_x,min_y,max_x,max_y) footprints; snapshot.terrain_revision confirms commit."""
+        ...
+    def __enter__(self) -> World: ...
+    def __exit__(self, exc_type: Optional[type[BaseException]],
+        exc_value: Optional[BaseException], traceback: Optional[TracebackType]) -> bool: ...
+    @property
+    def lifecycle(self) -> str: ...
+    @property
+    def threads(self) -> int: ...
+    @property
+    def tick_hz(self) -> int: ...
+    @property
+    def max_slope_radians(self) -> float: ...
+    @property
+    def terrain_cost_weight(self) -> float: ...
+    def metrics(self) -> dict[str, Any]: ...
+    def queue_metrics(self) -> dict[str, Any]: ...
+    def start(self) -> None: ...
+    def pause(self) -> None: ...
+    def resume(self) -> None: ...
+    def stop(self) -> None: ...
+    def step_once(self) -> None: ...
+    def snapshot(self) -> Snapshot: ...
+    def wait_for_tick(self, minimum_tick: int, timeout: float = 1.0) -> Snapshot: ...
+    def spawn_vehicle(self, x: float, y: float, heading: float = 0.0,
+        profile: Profile = None, *, control: Optional[VehicleControl] = None) -> int:
+        """Admit spawn and optional initial control together; control uses a second queue slot."""
+        ...
+    def spawn_vehicles(self, poses: Union[Iterable[tuple[float, float, float]], NDArray[Any]],
+        profile: Profile = None) -> list[int]: ...
+    def set_vehicle_control(self, id: int, control: VehicleControl) -> None: ...
+    def set_vehicle_controls(self, controls: Iterable[tuple[int, VehicleControl]]) -> None: ...
+    def go_to(self, id: int, x: float, y: float) -> None: ...
+    def request_go_to(self, id: int, x: float, y: float, heading: Optional[float] = None) -> int: ...
+    def request_go_to_many(self, goals: Iterable[GoalRow]) -> list[int]: ...
+    def cancel_navigation(self, id: int) -> None: ...
+    def despawn_vehicle(self, id: int) -> None: ...
+    def despawn_vehicles(self, ids: Iterable[int]) -> None: ...
+    def set_vehicle_priority(self, id: int, priority: int) -> None: ...
+    def configure_recovery(self, config: RecoveryConfig) -> None: ...
+    def create_formation(self, leader_id: int, follower_ids: Sequence[int],
+        config: Optional[FormationConfig] = None) -> int: ...
+    def configure_formation(self, id: int, config: FormationConfig) -> None: ...
+    def set_formation_members(self, id: int, follower_ids: Sequence[int]) -> None: ...
+    def disband_formation(self, id: int) -> None: ...
+    def spawn_dynamic_obstacle(self, min_x: float, min_y: float, max_x: float,
+        max_y: float, velocity_x: float = 0.0, velocity_y: float = 0.0) -> int: ...
+    def set_dynamic_obstacle_velocity(self, id: int, velocity_x: float,
+        velocity_y: float) -> None: ...
+    def despawn_dynamic_obstacle(self, id: int) -> None: ...

flocking-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: flocking
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Games/Entertainment :: Simulation
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.26 ; extra == 'numpy'
+Provides-Extra: numpy
+License-File: LICENSE-MIT
+License-File: LICENSE-APACHE
+Summary: Multithreaded off-road vehicle navigation, collision safety and formations in Rust, driven from Python
+Keywords: simulation,navigation,pathfinding,flocking,formations,vehicles,game-server
+Home-Page: https://github.com/benahedron/flocking
+Author: Flocking contributors
+License-Expression: MIT OR Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/benahedron/flocking/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/benahedron/flocking/blob/main/docs/python-api.md
+Project-URL: Homepage, https://github.com/benahedron/flocking
+Project-URL: Issues, https://github.com/benahedron/flocking/issues
+
+# Flocking
+
+Flocking moves large numbers of vehicles across open terrain for game servers
+and simulations. A multithreaded Rust core handles off-road route planning,
+vehicle dynamics, collision safety and formations (convoys, rows, wedges and
+flocks). Python drives it through a small queued-command API.
+
+```bash
+pip install flocking            # or: pip install "flocking[numpy]"
+```
+
+```python
+import time
+import flocking
+
+with flocking.World(width=500, height=500) as world:   # flat 500 m map
+    world.start()                                       # Rust worker ticks at 30 Hz
+    car = world.spawn_vehicle(x=50.0, y=50.0)
+    world.go_to(car, x=120.0, y=90.0)                   # queued; planned off-road
+
+    while True:
+        snap = world.snapshot()                         # coherent, non-blocking
+        status = next((s for s in snap.navigation if s.vehicle_id == car), None)
+        if status and status.state in ("Arrived", "Failed"):
+            break
+        time.sleep(0.1)
+
+    vid, x, y, heading = snap.vehicles[0]
+    print(f"tick {snap.tick}: vehicle {vid} {status.state} at ({x:.1f}, {y:.1f})")
+```
+
+The simulation runs on its own thread. Commands enter a bounded queue and take
+effect at the next tick, and every `snapshot()` is a consistent, tick-stamped
+view of the world. Python callbacks are never invoked from the simulation, and
+blocking calls release the GIL.
+
+## Heightmaps and bulk control
+
+```python
+import numpy as np
+import flocking
+
+xs = np.linspace(0, 6 * np.pi, 1001, dtype=np.float32)
+heights = 20 + 8 * np.sin(xs)[None, :] * np.cos(xs)[:, None]   # 1 km, [y, x]
+
+with flocking.World.from_heightmap(heights, meters_per_cell=1.0) as world:
+    world.pause()                                    # deterministic manual stepping
+    ids = world.spawn_vehicles([(100.0, 100.0 + 8 * i, 0.0) for i in range(10)])
+    world.request_go_to_many([(i, 600.0, 140.0 + 8 * n) for n, i in enumerate(ids)])
+    for _ in range(900):                             # 30 simulated seconds
+        world.step_once()
+    arrays = world.snapshot().numpy()
+    print(arrays["ids"], arrays["states"][:, :2])
+```
+
+Terrain can be edited at runtime with `update_heightmap()` and
+`set_static_obstacles()`. Each committed revision is an immutable snapshot.
+
+## Features
+
+- Worlds up to 10 km × 10 km at 1 m resolution, chunked terrain with slope queries
+- Kinematic bicycle dynamics with footprints, reversing and slope-aware climbing
+- Hierarchical A*, Hybrid A* and Reeds–Shepp route planning with caching
+- Swept collision safety, emergency stops, priorities, deadlock detection and recovery
+- Convoy, row, wedge and flock formations with slot reassignment and bottleneck narrowing
+- Fixed-step worker lifecycle, bulk commands, deterministic replay, NumPy snapshots
+
+Wheels are abi3 (CPython 3.9+) for Linux, macOS and Windows. NumPy is optional
+and is needed only for heightmap arrays and `snapshot.numpy()`.
+
+## Links
+
+- [Source and 3D debug viewer](https://github.com/benahedron/flocking)
+- [Python API reference](https://github.com/benahedron/flocking/blob/main/docs/python-api.md)
+- [Example scripts](https://github.com/benahedron/flocking/blob/main/docs/examples.md)
+- [Changelog](https://github.com/benahedron/flocking/blob/main/CHANGELOG.md)
+
+Licensed under MIT or Apache-2.0, at your option.
+

flocking-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+flocking/__init__.py,sha256=lgC5uI0uM66cz9PQP_rJVdK2P59DnGXc4VbNkIbfRz8,1245
+flocking/_native.pyd,sha256=d6UkVCCXuBnBW7Xl0mplQC7ZJ9N1mXr8oJn1iaWsLG8,1656832
+flocking/_native.pyi,sha256=PPx0yI04lmFZ8bRuc9-LJ3-5n8I8Kcn-Rj0kc6ic_Ac,12541
+flocking/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flocking-0.1.0.dist-info/METADATA,sha256=CdUtO3DeAFc4aPI1p9-JWEt25oBaCE-yW_hBeR1308c,4745
+flocking-0.1.0.dist-info/WHEEL,sha256=xw8F9xBWUOgm5ym2S9tihj_bLJOb723bjhA0kdANo2I,95
+flocking-0.1.0.dist-info/licenses/LICENSE-APACHE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+flocking-0.1.0.dist-info/licenses/LICENSE-MIT,sha256=jk_Ux4ZorHf_chJsGq_8RmKwfGfyF7h3BRvfQc-iVPs,1099
+flocking-0.1.0.dist-info/sboms/flocking-python.cyclonedx.json,sha256=Rr1zgsUxVrEgJz0O2t0ahUE5SnkYhA7ryF-REyhALFk,30299
+flocking-0.1.0.dist-info/RECORD,,

flocking-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.16.0)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64