Metadata-Version: 2.4
Name: playarea
Version: 0.1.0
Summary: Cross-platform robot simulator GUI (native C++/OpenGL), shipped as a self-contained binary, with a pure-Python client library.
Project-URL: Homepage, https://github.com/hassanumari/playarea
Project-URL: Source, https://github.com/hassanumari/playarea
Author-email: Hassan Umari <h.omari91@gmail.com>
License: MIT
Keywords: gui,imgui,opengl,robot,simulator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Games/Entertainment :: Simulation
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# playarea

A cross-platform robot-simulator GUI (native C++ / OpenGL / ImGui), packaged as
a self-contained, `pip`-installable binary. No compiler, no toolchain, no
runtime dependencies to install — the wheel for your platform ships the
prebuilt executable and all of its assets.

## Install

```bash
pipx install playarea       # recommended: isolated, on your PATH
uv tool install playarea    # same idea, via uv
pip install playarea        # into the current environment
```

Then launch it:

```bash
playarea                    # or: python -m playarea
playarea --tcp_port 9000    # all of the app's CLI flags are forwarded
```

## Platforms

Prebuilt wheels are published for:

| OS      | Architecture | Wheel platform tag        |
| ------- | ------------ | ------------------------- |
| Linux   | x86_64       | `manylinux_2_35_x86_64`   |
| macOS   | Apple silicon| `macosx_11_0_arm64`       |
| macOS   | Intel        | `macosx_11_0_x86_64`      |
| Windows | x86_64       | `win_amd64`               |

On Linux the app needs the usual system OpenGL/X11 runtime libraries present
(they ship with any desktop environment).

## Client library

The same package ships a pure-Python (standard-library-only) client for driving
a running simulator over its TCP/UDP [network interface](https://github.com/hassanumari/playarea#network-interface)
and reading back sensor telemetry:

```python
from playarea import Robot

with Robot(host="localhost", port=9000) as robot:
    robot.set_speed(v=0.3, w=0.6)     # linear m/s, angular rad/s

    robot.subscribe_odom()
    print(robot.odom)                 # latest Odometry(x, y, theta, v, w, seq, t)

    robot.subscribe_scan()
    print(robot.scan.points())        # finite laser returns as (x, y)

    robot.subscribe_camera()
    robot.camera.save_ppm("pov.ppm")  # latest head-camera frame
```

Feedback channels are opt-in and independent — subscribe only to what you need.
Each runs on its own background UDP socket, so `robot.odom` / `robot.scan` /
`robot.camera` always return the latest value without blocking. The client has
no third-party dependencies; importing it does not require the native binary.

## How it works

`playarea` is a tiny Python launcher. Installing it drops a `playarea` command
on your `PATH`; running it execs the bundled native binary
(`playarea/_bin/playarea`) with your arguments forwarded, and the binary loads
its `assets/` from right beside itself.
