Skip to content

Feature(launch): let --assets-path add assets roots to the core one - #47

Open
cmoron wants to merge 1 commit into
naval-group:mainfrom
cmoron-lab:feature/composable-assets-path
Open

Feature(launch): let --assets-path add assets roots to the core one#47
cmoron wants to merge 1 commit into
naval-group:mainfrom
cmoron-lab:feature/composable-assets-path

Conversation

@cmoron

@cmoron cmoron commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Closes #46.

What

--assets-path now adds an assets root instead of replacing the core one, so a
project that consumes LOTUSim can keep its own worlds and models in its own
repository and still run them through lotusim run:

lotusim --assets-path /my/scenario/assets run my_scenario.world

The core catalogue stays available — the sailboat from assets/models and the buoy
from the scenario resolve in the same world.

Details

  • The core root is always searched first; --assets-path appends after it.
  • The option accepts a colon-separated list (--assets-path "$A:$B") and is
    repeatable (--assets-path $A --assets-path $B). Both forms are equivalent — the
    colon form mirrors the GZ_SIM_RESOURCE_PATH this feeds.
  • Worlds are resolved from whichever root holds them.
  • A missing world now names every root searched, instead of being handed to gz and
    failing there with a less obvious message.
  • Shell completion follows the same roots, so worlds outside the core are offered.

Behaviour change, stated plainly

A single --assets-path used to replace the core root; it now adds to it.

We looked for callers before changing this: the option appears nowhere in this
repository, its CI, its documentation, the wiki, or LOTUSim-generic-scenario — only
in the completion script's option list. The replacing semantics were also the direct
cause of the limitation in #46. If you would rather keep them untouched, we are happy
to move the additive behaviour behind a separate flag.

There is no longer a way to exclude the core root. Nobody asked for that isolation and
an extra search entry is harmless, so we did not invent a flag for it.

Verification

launch/tests/test_assets_path.sh is self-contained: it builds two throwaway assets
roots under mktemp -d, touches nothing in the workspace, and needs only a built
LOTUSim environment.

bash launch/tests/test_assets_path.sh
===== 9 passed / 0 failed =====

It covers the unchanged default, the additive single option, both multi-root forms and
their equivalence, world resolution from the owning root, the error message, and
completion. The decisive case is an A/B on gz itself: a world in root B that includes
model://alpha from root A loads with both roots and fails with
Unable to find uri[model://alpha] without root A — so the test would notice if the
composition silently stopped working.

Note for anyone reproducing it: the check needs --debug, because at the default
-v0 gz reports nothing and the A/B would prove nothing.

Run against ghcr.io/naval-group/lotusim (Jazzy / Harmonic, noble).

Not included

The wiki lives in its own repository, so the --assets-path entry in Getting-Started
is not part of this PR. Happy to send that separately if useful.


Assisted-by: Claude Opus 5 (claude-opus-5) via Claude Code.

A consumer project could not use `lotusim run` with a world of its own that
also includes a model from the core catalogue: --assets-path replaced the
assets root instead of adding to it, so one had to choose between the two.

The core root is now always searched first and --assets-path appends to it,
so a scenario keeps its assets in its own repository and still runs through
the supported entry point. The option takes a colon-separated list, like the
GZ_SIM_RESOURCE_PATH it feeds, and stays repeatable; both forms append. A
missing world now names every root searched instead of failing later in gz.
Shell completion follows the same roots, so worlds living outside the core
are offered too.

This changes what a single --assets-path does: it used to replace the core
root, it now adds to it. Nothing in the repository, the CI, the docs or
LOTUSim-generic-scenario passes the option today, and the previous behaviour
was what made out-of-tree scenarios impossible in the first place.

Covered by launch/tests/test_assets_path.sh.

Refs naval-group#46

Assisted-by: Claude Opus 5 (claude-opus-5) via Claude Code
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Cyril Moron <cyril.moron@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

launch/lotusim: a scenario cannot compose its own assets with the core's (--assets-path replaces the root, GZ_SIM_RESOURCE_PATH overwritten)

1 participant