Add environment layers to mjModel, MJCF and the spec API

[teerthsharma]

First of two steps toward #3452, which measures what MuJoCo's five global environment constants cost and proposes replacing them with fields. This step adds the data and the authoring surface; #3461 adds the reader.

Relates to #3452. Depends on #3458 for sanitizer builds.

Summary

mjOption carries one gravity vector, one wind vector, one density and one viscosity, and those four values hold at every point of the model. This adds an ordered stack of horizontal medium slabs so they can vary with height along +z.

mjModel gains nlayer and the arrays layer_height, layer_gravity, layer_density, layer_viscosity, layer_wind. mjSpec gains mjsLayer with mjs_addLayer, mjs_getLayer and mjs_deleteLayers. <option> accepts any number of <layer> children, each inheriting unspecified attributes from the global medium, and the compiler rejects heights that are not strictly ascending.

Layers are unnamed global option data rather than model elements: no mjtObj type, no name, no id, hence no mjsElement, and the stack is cleared at once rather than deleted element by element. The compiler holds them in a deque so pointers returned by mjs_addLayer survive later adds.

Nothing reads the new fields yet. A model with no <layer> element compiles to nlayer == 0 and is unchanged. The consumer is a follow-up: the sampler and its use in the fluid models.

There is no change to mjOption, to any existing physics path, or to the meaning of any existing attribute.

Cost at nlayer == 0

Step time, 13 models, Linux x86-64, gcc 15.2.0, SCHED_FIFO on a pinned core, best of 28 timed batches per arm, arm order alternated. main measured against a second build of itself is the control.

	geometric mean	range
this branch / main	0.9999	[0.9600, 1.0332]
main / main (control)	0.9981	[0.9825, 1.0187]

Four of thirteen ratios fall below 1.0, which this change cannot cause, so the residual spread is measurement noise. Each arm loaded its own libmujoco proven three ways, including reading /proc/self/maps at run time; the two library hashes differ.

qpos+qvel checksums after 2000 steps are bit-identical on all 13 models between main and this branch, so the nlayer == 0 path is the legacy path rather than an approximation of it.

Memory, 11 shipped models: mj_sizeModel grows by exactly +8 bytes on every one, the mjtSize nlayer counter, and nbuffer is byte-identical. The five arrays allocate nothing when unused. On the largest model in the corpus that is 1.9e-5 %.

Validation

check	result
CTest, Linux, gcc 15.2.0, Release	1977/1977, 0 failed
new test/xml/xml_layer_test.cc	4/4
XMLWriterLocaleTest.IgnoresLocale	skipped, as on main

main at f9a00bd5 reports 1973 on this host; 1973 + 4 new = 1977.

The four new tests cover an XML round trip of three layers including attribute inheritance from the global medium, rejection of unsorted and of duplicate heights, nlayer == 0 for a model with no <layer>, and a spec-API round trip exercising mjs_addLayer pointer stability across a later add, mjs_getLayer bounds, and mjs_deleteLayers compiling back to nlayer == 0.

src/xml/generated/mjcf.xsd is regenerated from mjcf.schema; without it doc_test fails.

Limits

Sanitizers were not run against this branch. An ASan or UBSan build of MuJoCo does not currently compile under GCC 15.2.0 or clang 21.1.8 because of two constructs in include/mujoco/mjsan.h, which #3458 fixes; with that fix applied locally the follow-up branch's tests pass clean under ASan, UBSan and LeakSanitizer. This branch adds no runtime code path, so there is nothing new for a sanitizer to reach until the consumer lands.

layer_height is sized nlayer with the final entry unused rather than nlayer-1, because every MJMODEL_POINTERS row count expands to a literal member name. The header says so and the compiler writes all nlayer values so the writer round-trips.

The benchmark host was under sustained competing load throughout, which is why every arm ran pinned at real-time priority and why the base-versus-base control is load bearing rather than decorative. Run spreads of 0.3–5.4% mean this setup resolves regressions to roughly 2% and no finer.

MJX and the Warp backend are not extended; both are unaffected at nlayer == 0.