roblox-headless-renderer

See Roblox files without opening Studio.
Pictures and plain facts about your UI and 3D builds, in seconds, from the command line.

Point rhr at a Roblox file (.rbxm, .rbxmx, .rbxl, .rbxlx), a Rojo project, a UI story or a Creator Store link, and it tells you what's there: a PNG to look at, and JSON that says where everything is, what's clickable, and what looks broken.

It was built for AI agents that make Roblox games and need to check their own work, and it's just as handy when you want a quick look at a file, a free model or a pull request without starting Studio. It runs on Windows, macOS and Linux, including CI and cloud sandboxes: no display, GPU or running Studio needed.

Quick start

uv tool install roblox-headless-renderer     # or: pip install --pre roblox-headless-renderer

Then, on any file of yours:

rhr ui     MyGame.rbxl --out ui.png          # the screen UI, as a PNG
rhr scene  MyGame.rbxl --out world.png       # the 3D world, as a PNG
rhr check  MyGame.rbxl                       # UI mistakes a player would notice

That's it: no setup step. The first run fetches anything missing (see what gets downloaded). Just want to try it once? uvx roblox-headless-renderer ui MyGui.rbxmx --out gui.png runs it without installing anything.

This is the 1.0 release candidate. It's fast and ready to use, and we'd love your feedback before the final 1.0: open an issue, ideally with a small file that shows the problem.

What it can tell you

Anywhere a file goes, you can also pass a Rojo project folder or a Roblox asset id or link. rhr --help and rhr <command> --help list every option.

An example

The repo's examples/shop.rbxmx has one deliberate mistake. rhr check examples/shop.rbxmx finds it:

{
  "check": "text-wider-than-box",
  "detail": "text is 413px wide in a 148px box with TextWrapped off: it spills out",
  "paths": ["ShopGui/Shop/Items/Item5/ItemName"],
  "severity": "warning"
}

For AI agents

rhr is a plain command-line tool: an agent runs it from its shell, and it costs nothing in the agent's context until it's used. Every JSON output is small, carries a schema name, and uses the same paths you pass back in.

Claude Code and Codex: install the skill, and the agent knows when and how to use it.

rhr skill --install .claude/skills      # this project; ~/.claude/skills for all of them

Any other agent: paste this into your project's AGENTS.md.

## Seeing the UI and builds
Use `rhr` (roblox-headless-renderer) to check Roblox UI and 3D work without Studio:
`rhr check <target>` after each edit (exit 1 = error findings; `--baseline before.json`
for only what the edit added), `rhr layout <target> --path <screen>` for rects,
`rhr ui <target> --only <screen> --fit --max-size 800 --out shot.png` to look, and
`rhr check <target> --devices all` before done. The target is the project, a
`*.story.luau`, or the place file when the UI is saved in Studio. `rhr skill` prints
the full guide.

The full agent guide, with which command answers which question and how far to trust each one, is docs/AGENTS.md.

How accurate is it?

• UI layout matches Studio. Positions and sizes are within 2 px of Studio's on every test place.
• Pictures are previews. They're close enough to spot mistakes, not a pixel copy of Roblox. Anything rhr can't draw faithfully, it says so in its output instead of guessing quietly. Here's what's approximated.
• It doesn't run your game. Scripts, physics and animation don't run, so you see files as they're saved. (Effects are the exception: rhr plays common VFX setups itself and shows them at their fullest moment.)

Details

Contributing

Bug reports with a small file attached are the most useful thing you can send. To work on rhr itself:

git clone https://github.com/TabooHarmony/roblox-headless-renderer && cd roblox-headless-renderer
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]" && rhr setup
python -m pytest -m smoke                           # a quick check; drop -m smoke for everything

docs/GOAL.md describes where the project is heading, and docs/interface-1.0.md is the full list of commands, outputs and settings.

License

Apache 2.0. Bundled third-party code and fonts are listed in THIRD_PARTY_NOTICES.md. Not affiliated with or endorsed by Roblox Corporation. Roblox is a trademark of Roblox Corporation.