Contributing¶
Thanks for your interest. Issues and pull requests are welcome in English or Japanese (日本語でも大丈夫です). This is a personal project maintained in spare time: there is no promise of a reply, a review or a release date.
To only use the tool, Getting started is enough. This page is for changing the code.
1. Setup and tests¶
git clone https://github.com/atinfinity/agentic-sim-world-gen.git
cd agentic-sim-world-gen
uv sync --extra usd --extra mcp --extra dxf --extra ifc --extra photo --extra hf --extra dev
uv run pytest -q # offline tests (about 2 minutes)
uv run pytest -q -m network # optional: calls the real SimReady Central / Poly Haven APIs
CI runs the tests twice: with the extras the README installs (usd, hf, mcp, dev) and with all but taste.
A test that needs another extra skips without it (pytest.importorskip).
Checking a scene in Isaac Sim (check) needs an NVIDIA RTX GPU and Isaac Sim 6.1 on Linux; everything else
(search, layout, USD, previews) runs without a GPU. Pull requests that cannot be tested on Isaac Sim are fine:
say so in the description.
If you change an MCP tool's signature or docstring, regenerate the reference:
uv run python scripts/make_tool_reference.py (a test checks that
tools.md is up to date).
2. Where things are¶
How it works explains the flow with diagrams, using the names in the code. Conventions (coordinate system, USD structure, environment variables) are in CLAUDE.md.
| What | Code |
|---|---|
SceneSpec (the format every input turns into; examples in examples/) |
src/agentic_sim_world_gen/scene/spec.py |
| Floor plans (JSON / DXF / IFC) | src/agentic_sim_world_gen/scene/plan.py, src/agentic_sim_world_gen/plan/ |
| Outdoor sites | src/agentic_sim_world_gen/scene/site.py |
| Floor, walls, lighting | src/agentic_sim_world_gen/scene/looks.py |
| Missing assets | src/agentic_sim_world_gen/missing.py |
| Synthetic data | src/agentic_sim_world_gen/sdg.py, scripts/isaac/sdg.py |
| The Isaac Sim check | scripts/isaac/check_scene.py |
| CLI and MCP tools (the same operations) | src/agentic_sim_world_gen/service.py, src/agentic_sim_world_gen/mcp_server.py |
| Claude's conversation steps | .claude/skills/world-gen/ |
agentic-sim-world-gen check runs scripts/isaac/check_scene.py with Isaac Sim's python. To call it directly:
~/isaacsim/python.sh scripts/isaac/check_scene.py out/study/scene.usda \
--screenshot out/study/check.png --report out/study/check.json [--gif out/study/check.gif]
3. Pull requests¶
- One topic per pull request. Add or update tests under
tests/. - For a change you can see (layout, preview, rendering), attach a screenshot or GIF to the description.
- Never commit asset files (USD, textures, MDL, meshes) of a third party, or any material you may not
redistribute (including non-commercial assets and photos of people). Refer to assets by URL or by a
local:folder instead. - By submitting a pull request you agree that your contribution is licensed under the Apache License 2.0 (see LICENSE). There is no CLA and no sign-off (DCO) requirement.
4. Reporting problems¶
Use the issue templates. Please include the request text, the asset sources (AGENTIC_SIM_WORLD_GEN_SOURCES),
the version and the OS. Do not attach photos that show people, or screenshots of assets you may not
share. Security problems: see SECURITY.md.
5. Project page¶
The project page (https://atinfinity.github.io/agentic-sim-world-gen/) is built with Zensical
and published by .github/workflows/pages.yml on every push to main. There are two sites with the same pages: English
(zensical.en.toml: README.md and the guides in docs/en/) and Japanese under /ja/ (zensical.toml:
README.ja.md and the guides in docs/). scripts/build_site.py puts them together under build/, so edit the
READMEs and docs/. When you change a guide, change both languages. To look at it locally:
uv pip install zensical==0.1.1
python scripts/build_site.py --serve # http://127.0.0.1:8000/agentic-sim-world-gen/
6. GitHub Actions¶
The actions used by .github/workflows/ are pinned to commits in .github/workflows/actions.lock
(workflow lockfile), made by the GitHub CLI extension
gh-actions-lock. Do not edit it by hand: after you add or change a
uses: (or add a workflow), run
gh extension install github/gh-actions-lock # once
gh actions-lock # pins full version tags (@v7 -> @v7.0.1) and updates actions.lock
gh actions-lock --verify # check
and commit the workflows together with actions.lock. The lockfile job of CI runs gh actions-lock --verify
on every pull request, and the repository's Require lockfile policy stops a workflow whose actions are not in the lockfile.
Dependabot (.github/dependabot.yml) opens one pull request a week per ecosystem (the actions and uv.lock); for
an action it updates actions.lock in the same pull request.