helix scene

CLI version 0.1.27-helix3.551. Run helix scene --help for the text your installed build prints.

`helix scene`

Bring a captured world into the scene sources a HELIX world streams

helix scene <command>

`helix scene hlod`

Select static scene features and bake simplified cell geometry with transferred PBR materials

helix scene hlod <command>

Bake higher-quality regional geometry and appearance above the retained complete coarse tier

helix scene hlod bake-refinements [options] <scenes...>

Argument	Required	Description
`scenes...`	yes	sealed complete HLOD scenes in one bundle

Option	Description
`--distance <metres>`	refinement loading range (default 896)
`--fade <ms>`	coarse/refinement transition (default 350)
`--error <metres>`	geometric error (default 0.5)
`--ratio <fraction>`	target triangle ratio (default 0.01)
`--voxel-size <metres>`	exterior voxel size (default 0.5)
`--texels-per-metre <density>`	regional texture density (default 4)
`--min-tile <pixels>`	minimum prototype tile (default 64)
`--max-tile <pixels>`	maximum prototype tile (default 256)
`--atlas <pixels>`	regional atlas edge limit: 256, 512, 1024 or 2048 (default 1024)
`--compression <format>`	ktx2 or png (default "ktx2")
`--force`	ignore cached prototypes

`helix scene hlod tag`

helix scene hlod tag [options] <scene>

Argument	Required	Description
`scene`	yes	sealed local Scene v2 file to update

Option	Description
`--nodes <ids...>`	scene node IDs; parent policies are inherited by descendants (required)
`--mode <mode>`	include, exclude or inherit (default "include")
`--layer <id>`	HLOD layer ID
`--distance <metres>`	fine-to-proxy switch distance (default 128)
`--max-distance <metres>`	maximum proxy residency distance (default 2048)
`--fade <ms>`	replacement fade duration (default 350)
`--ratio <fraction>`	target triangle ratio (default 0.2)
`--error <metres>`	maximum simplification error (default 0.1)
`--atlas <pixels>`	128, 256, 512 or 1024 (default 512)

`helix scene hlod inspect`

helix scene hlod inspect <scene>

Argument	Required	Description
`scene`	yes	sealed local Scene v2 file

`helix scene hlod bake`

helix scene hlod bake [options] <scene>

Argument	Required	Description
`scene`	yes	sealed local Scene v2 file to update after every cluster succeeds

Option	Description
`--compression <format>`	ktx2 (GPU compressed) or png (default "ktx2")
`--force`	ignore cached bakes

`helix scene hlod bake-complete`

helix scene hlod bake-complete [options] <scenes...>

Argument	Required	Description
`scenes...`	yes	sealed scene files in one bundle; all selected sources receive coarse coverage

Option	Description
`--cell-size <metres>`	independent coarse cell size (default 512)
`--voxel-size <metres>`	exterior approximation voxel size (default 2)
`--texels-per-metre <density>`	shared appearance density (default 1)
`--min-tile <pixels>`	minimum prototype tile: 32, 64, 128, 256, 512 or 1024 (default 64)
`--max-tile <pixels>`	maximum prototype tile: 32, 64, 128, 256, 512 or 1024 (default 256)
`--allocation <rule>`	tile size rule: extent (default; largest dimension x density) or area (sqrt of exterior wall area, one density solved to a texel budget) (default "extent")
`--atlas-budget <texels>`	area rule: total texels of all tiles (default: what the extent rule would spend on the same prototypes)
`--compression <format>`	ktx2 (GPU compressed) or png (default "ktx2")
`--force`	ignore cached prototype bakes

Check a Scene v2 package against the shared Scene validator and, with --perf, the open-world performance rules (docs/scene-perf.md). Also counts placements whose base stands more than 0.3 m above or below the terrain: refused above 0.5% of them, a warning below. Exits 0 on pass, 1 when refused, 2 when it cannot be judged.

helix scene validate [options] <path>

Argument	Required	Description
`path`	yes	a Scene package folder (holding scene.helix-scene.json) or a .helix-scene.json file

Option	Description
`--perf`	also evaluate the 14 performance rules (P01 to P14) against the package bytes
`--scene <file>`	the Scene document inside the folder (default scene.helix-scene.json)
`--tier <tiers>`	desktop, mobile or desktop,mobile: the tier(s) the document is built for (default "desktop")
`--profile <id>`	the Scene profile to evaluate (default world)
`--json`	print the helix.scene-perf-report/1 JSON instead of text
`--out <file>`	write the helix.scene-perf-report/1 JSON to this file

`helix scene split`

Split a monolithic environment (one big GLB, or a Scene v2 document with an eager shell) into a small eager spawn core plus distance-streamed cells on a fixed, content-addressed grid, and write a validated Scene v2 package

helix scene split [options] <input>

Argument	Required	Description
`input`	yes	a .glb, a Scene v2 .helix-scene.json, or a folder holding one

Option	Description
`-o, --output <dir>`	new or empty output directory (required)
`--cell-size <metres>`	grid cell edge; the grid is anchored at the world origin so cell bytes depend only on their cell (default 16)
`--core-radius <metres>`	spawn core radius; default is half the stream radius
`--spawn <x,y,z>`	spawn point; default is the document spawn, or a probed standing point for a GLB
`--stream-radius <metres>`	declared stream radius; default keeps the document value, or 2.5 cells
`--encoding <mode>`	chunk geometry encoding: meshopt or none (default "meshopt")
`--textures <mode>`	ktx2 (default): each distinct texture is encoded once to a shared KTX2 file the chunks reference; keep: textures stay as authored, embedded in every chunk that uses them (default "ktx2")
`--texture-cache <dir>`	remember encoded textures here (keyed by content) so repeat splits skip the encoder
`--title <title>`	Scene title
`--scene-id <id>`	Scene id for a GLB input
`--profile <id>`	profile to split when the document has several
`--dry-run`	plan, build and report without writing files
`--json`	machine-readable report

`helix scene retexture`

Shrink the textures of a split Scene bundle without moving a cell: merge textures that decode to the same picture, re-encode UASTC data and normal maps with RDO (each only above a PSNR floor), rewrite the image uris in the affected GLBs, reseal and validate the document. Nodes, stream groups, bounds, spawn and budgets are copied through untouched.

helix scene retexture [options] <input>

Argument	Required	Description
`input`	yes	a folder holding scene.helix-scene.json and the files its resources name (what `helix scene split` writes)

Option	Description
`-o, --output <dir>`	new or empty output directory (required)
`--merge-psnr <dB>`	merge two textures when their decoded PSNR is at least this (default 44)
`--merge-max-delta <levels>`	and no texel differs by more than this, 0-255 (default 24)
`--uastc-rdo <scalars>`	comma-separated UASTC RDO quality scalars to try for data and normal maps, highest first (higher is smaller and lossier); "off" turns RDO off (default 2,1)
`--reencode-psnr <dB>`	floor for an RDO re-encode against the decoded original (default 40)
`--dry-run`	measure and report without writing files
`--json`	machine-readable report

`helix scene create`

Assemble a whole Scene from a source: a city-source folder becomes a sealed, perf-gated open-world Scene v2 package (docs/scene-create.md)

helix scene create <command>

`helix scene create city`

Terrain from the DEM, procedural buildings with the far layer always resident, vegetation, Vault props and the engine city materials, in one deterministic package

helix scene create city [options]

Option	Description
`--source <dir>`	a helix.city-source/1 folder (city-source.json) (required)
`--out <dir>`	the Scene package folder to write (scene.helix-scene.json, pin.json, bundle files) (required)
`--plan <file>`	a helix.scene-plan/1 recipe; flags override it for this run and the result is written to <out>/scene-plan.json
`--work <dir>`	work folder for the intermediate terrain, placements and buildings (default <out>.work)
`--id <id>`	the Scene id (default scene.<city source id>)
`--title <title>`	the Scene title
`--tier <tiers>`	desktop, mobile or desktop,mobile: the tier(s) the package is gated for
`--budget <mib>`	desktop memory budget (MiB)
`--mobile-budget <mib>`	mobile memory budget (MiB)
`--stream-radius <m>`	distance groups load inside this radius (metres)
`--spawn <x,z>`	spawn near this plan point instead of the densest street
`--cell <m>`	building cell size (256 or 512)
`--far-cell <m>`	far-layer cluster size (a multiple of --cell)
`--terrain-mps <m>`	terrain metres per sample: 1, 2 or 4 (default 2)
`--margin <m>`	terrain margin: low-detail ground this far beyond the city bounds, from the DEM (default 4096; 0 for none)
`--margin-cache <dir>`	where the margin DEM is kept and read (default <source>/terrain/margin)
`--no-vegetation`	leave the trees out
`--no-props`	leave the Vault props out
`--no-roads`	leave the roads out (the street surface is then only painted on the terrain)
`--offline`	do not reach the network (the Vault is not searched)
`--skip-perf`	do not run the perf gate (publish always does)
`--json`	print the result as JSON

`helix scene import`

Convert a captured bundle into a terrain source folder, its ocean field and a scene-elements document

helix scene import <command>

`helix scene import restyle-buildings`

Restyle the captured Granit buildings (KTX2 near models in colourways, per-building colour on the far tiers) into an overlay data folder

helix scene import restyle-buildings [options] <dataFolder>

Argument	Required	Description
`dataFolder`	yes	the shared granit-data/public folder (read only)

Option	Description
`--out <dir>`	overlay folder to write: buildings/ plus restyle/ (point GRANIT_DATA at it) (required)
`--stage <stage>`	prototypes, clusters or all (default all) (default "all")
`--shard <i/n>`	prototypes stage only: this process takes every n-th prototype starting at i, e.g. 0/4
`--limit <n>`	prototypes stage only: stop after n prototypes (a trial)
`--only <text...>`	prototypes stage only: only prototypes whose source uri contains one of these
`--json`	machine-readable report

`helix scene import mesh-buildings`

Real CS2 prefab meshes for a city: prototype GLBs, building part Scenes and the World root that mounts them

helix scene import mesh-buildings <command>

`helix scene import mesh-buildings prototypes`

Build prototype GLBs (colourways, KTX2) and bake sources for every prefab a city-source places

helix scene import mesh-buildings prototypes [options] <citySource>

Argument	Required	Description
`citySource`	yes	a helix.city-source/1 folder whose buildings carry mesh pointers

Option	Description
`--bundle <dir>`	the folder holding meshes-v2/ and materials-v2/ (what `city import cs2` reads) (required)
`--out <dir>`	data root to write buildings/ into (required)
`--shard <i/n>`	this process takes every n-th prefab starting at i; run shards as separate processes, then `merge`
`--max-triangles <n>`	simplify a prototype above this many triangles (default 20000)
`--albedo-edge <px>`	longest edge of a colour map (default 1024)
`--data-edge <px>`	longest edge of a normal or ORM map (default 512)
`--max-variants <n>`	colourways per prefab (default 4)
`--max-side <m>`	cut a prefab wider than this into tile models (default 640; a streamed cell is limited to 1,024 m)

`helix scene import mesh-buildings merge`

Join the shard indices of a sharded prototypes run into buildings/prototypes.json

helix scene import mesh-buildings merge <data>

Argument	Required	Description
`data`	yes	the data root the shards wrote into

`helix scene import mesh-buildings parts`

Write part.<n>.scene.json: one node per building, distance stream groups, nodes tagged for complete HLOD

helix scene import mesh-buildings parts [options] <citySource>

Argument	Required	Description
`citySource`	yes	the helix.city-source/1 folder

Option	Description
`--data <dir>`	the data root holding buildings/prototypes.json (part documents are written beside buildings/) (required)
`--id <sceneId>`	part scene id prefix (default scene.city.buildings)
`--title <title>`	part title
`--group-cap <MiB>`	declared memory cap of one near group (default 48)
`--group-draws <n>`	a near group draws at most this many calls (default unlimited; the phone tier uses 24 so four resident groups and the HLOD stay under P06's 150)
`--hlod-cell <m>`	HLOD bake cell size in metres (default 512); larger cells mean fewer cluster draws
`--max-parts <n>`	at most this many parts (default 8, the engine mount limit)
`--json`	machine-readable report

`helix scene import mesh-buildings compose`

Mount the baked parts into a landscape package: <out>/<name>/ is the root, one <sha256>/ folder per part beside it

helix scene import mesh-buildings compose [options]

Option	Description
`--land <dir>`	the landscape package (`helix scene create city` output) (required)
`--data <dir>`	the data root holding part.<n>.scene.json, buildings/ and hlod-complete/ (after bake-complete) (required)
`--out <dir>`	folder to write the root and the parts into (emptied first) (required)
`--name <name>`	root folder name (default world) (default "world")
`--tier <tier>`	desktop or mobile (default desktop) (default "desktop")
`--id <sceneId>`	root scene id (default: the landscape's)
`--title <title>`	root title

`helix scene import cs2`

Convert a Cities: Skylines II source-v2 bundle: its landscape at 4 m per sample, sea level on zero, water bodies cut open

helix scene import cs2 [options] <bundleRoot>

Argument	Required	Description
`bundleRoot`	yes	the bundle folder holding terrain/ and water/

Option	Description
`--out <dir>`	folder to write terrain/, ocean.rgba, ocean.json and scene-elements.json into (required)
`--metres-per-sample <n>`	metres per sample of the authoring grid: 0.5, 1, 2, 4 or 8 (default 4)
`--preset <id-or-path>`	built-in preset id or preset JSON file; omitted, the converter's own CS2 city preset
`--only <part>`	terrain, roads or trees; omitted, terrain and roads plus trees when --trees is supplied
`--trees <catalog>`	prepared vegetation catalog: replace all captured tree positions with pine/fir; exclude bushes
`--tree-road-clearance`	exclude tree roots above/below road and bridge surfaces; retain trees on plots
`--inspect`	report what the conversion would write, and write nothing
`--json`	machine-readable report
`--force`	overwrite an existing terrain source folder