Metadata-Version: 2.4
Name: robot-jungol
Version: 0.1.0
Summary: Grid-based robot programming environment and judge helpers for Jungol-style Python problems.
Author-email: Jeongmin Byun <me@seorii.page>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hancomac/robot-jungol
Project-URL: Repository, https://github.com/hancomac/robot-jungol
Project-URL: Issues, https://github.com/hancomac/robot-jungol/issues
Keywords: jungol,robot,judge,education,grid-world
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# robot-jungol

`robot-jungol` is a small Python package for Jungol-style robot programming problems. It provides a grid-world robot API, Pillow-based rendering, action logs, and helpers that judge runners can use to capture and replay submitted robot actions.

The distribution name is `robot-jungol`. The primary import package is `jungol_robot`, and the package also keeps Jungol-compatible top-level modules such as `robot` and `robot_judge`.

![Robot world screenshot](readme_assets/screenshot.png)

## Installation

Install from GitHub:

```sh
python -m pip install git+https://github.com/hancomac/robot-jungol.git
```

For local development:

```sh
python -m pip install -e ".[dev]"
```

## Quick Start

The top-level `robot` module is the compatibility entry point used by existing judge environments:

```python
from robot import Beeper, Robot, Wall, World

world = World(width=5, height=5, walls=[Wall((1, 0), (2, 0))])
world.add_piece(Beeper(position=(2, 2)))

robot = Robot(position=(0, 0), direction="R", beepers=1)
world.add_piece(robot)

robot.set_trace("red")
robot.move()
robot.turn_left()
robot.drop_beeper()
```

You can also import the package API directly:

```python
from jungol_robot import Robot, World
```

## Judge Helpers

`robot_judge` runs a submitted Python file, captures logged robot actions, and emits a machine-readable line prefixed with `__ROBOTLOG__`.

```python
from robot_judge import extract_actions_from_output, run_robot_judge, simulate_robot

run_robot_judge(path="User.py")

actions = extract_actions_from_output(output_text)
final_x, final_y, final_direction = simulate_robot(actions)
```

If a saved world should be loaded when `World()` is created, pass `world_file` or `world_path` to `run_robot_judge`. This sets the `ROBOT_WORLD_SAVE` environment variable for the duration of the run.

## Image Output

Interactive robot actions can emit image payloads for judge UIs. Set `IMG_OUT_DIR` to a writable directory to produce `images.jsonl` and per-frame JSON files.

Supported environment variables:

- `IMG_OUT_DIR`: output directory for image JSON payloads
- `IMG_MAX_WIDTH`: maximum emitted image width, default `1280`
- `IMG_MAX_HEIGHT`: maximum emitted image height, default `720`
- `IMG_WEBP_QUALITY`: WebP output quality, default `85`

## Development

Run the test suite with the standard library test runner:

```sh
python -m unittest discover -s tests
```

Build source and wheel distributions:

```sh
python -m build
```

## License

MIT. Portions are derived from the `urobot` project.
