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.

Installation

Install from GitHub:

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

For local development:

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

Quick Start

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

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:

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__.

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:

python -m unittest discover -s tests

Build source and wheel distributions:

python -m build

License

MIT. Portions are derived from the urobot project.