oriverse-engine 0.1.4 → 0.1.6

package/dist/weave_documentation.txt

@@ -1,23 +1,25 @@
 
 >>>>>>>>>>>>
 Weave World Description Language Documentation
- Version:29Jul26-23:56-13158
+ Version:19Aug26-09:37-59549
 >>>>>>>>>>>>
 
 <weave_language>
 - Weave is used to code on Oriverse (syntax similar to Swift for logic, plus scene declarations at top level).
 - A Weave file has two kinds of top-level content:
-  - scene declarations: `object`, `saved`, `physics`, `crowd`, `display`, `region` — describe what exists in the world.
+  - scene declarations: `object`, `saved`, `physics`, `crowd`, `display`, `region`, and lights `pointLight`/`spotLight`/`areaLight` — describe what exists in the world.
   - class code: `#class <Name> ... #end` blocks of logic; each block compiles to bytecode attached to a game object.
-- Compiler directives (top-level only): #class, #shader (body is WGSL), #texture (CPU-baked procedural PBR texture; auto-creates `material <Name>` usable as `material = "<Name>"`; defaults to triplanar/repeat/opaque, supports `mapping = uv;`, `wrap = clamp;`, `render_mode = cutout;`, and scalar `out.alpha`; see <texture_dsl_usage>; body authoring in the texture_dsl skill), #mesh (local CPU-baked procedural static mesh model `mesh.<Name>`; see <mesh_dsl_usage>; body authoring in the mesh_dsl skill), #tree (procedural tree species `tree.<Name>`; see <tree_dsl_usage>), #forest (scattered-tree region `forest.<Name>`; see <forest_dsl_usage>), #particles (local particle effect JSON asset `effect.<Name>`; `particleTextureName` takes `"flipbook.<word>"` for a shared-library animated atlas, `"texture.<Texture>.color"` for a local #texture, or `"image.<User>.<Name>"` for a known ori image asset; see particle_vfx skill), #adjuster (user-tunable look knobs; see <adjuster_usage>), #rules (see <world_rules>), #end, #set <Name> = <Number> (TileSize, Realistic), #doc_version <N> (authoring doc version; see <updating_old_worlds>).
+- Compiler directives (top-level only): #class, #shader (custom WGSL on the engine lit material — lighting/shadows/IBL stay engine-owned; `@vertex { }` mutates ctx.world_pos for wind/sway, fragment writes out.base_color/world_normal/orm; bind via `material M { shader = "S" }`; live knobs via SetMaterialParameterNumber; body authoring in the shader_dsl skill), #texture (CPU-baked procedural PBR texture; auto-creates `material <Name>` usable as `material = "<Name>"`; defaults to triplanar/repeat/opaque, supports `mapping = uv;`, `wrap = clamp;`, `render_mode = cutout;`, and scalar `out.alpha`; see <texture_dsl_usage>; body authoring in the texture_dsl skill), #mesh (local CPU-baked procedural static mesh model `mesh.<Name>`; see <mesh_dsl_usage>; body authoring in the mesh_dsl skill), #tree (procedural tree species `tree.<Name>`; see <tree_dsl_usage>), #forest (scattered-tree region `forest.<Name>`; see <forest_dsl_usage>), #scatter (scattered-model region `scatter.<Name>`, display-only, no collision; see <scatter_dsl_usage>), #particles (local particle effect JSON asset `effect.<Name>`; `particleTextureName` takes `"flipbook.<word>"` for a shared-library animated atlas, `"texture.<Texture>.color"` for a local #texture, or `"image.<User>.<Name>"` for a known ori image asset; see particle_vfx skill), #sound (local CPU-baked procedural sound asset `sound.<name>`; see <sound_dsl_usage>), #adjuster (user-tunable look knobs; see <adjuster_usage>), #rules (see <world_rules>), #end, #set <Name> = <Number> (TileSize, Realistic; texture policy, display-only: `#set TextureMaxResolution 1024` caps every market texture this world downloads to <=1024px [picks the market's smaller tier], `#set TextureFullResolutionAssets "model.a.x, model.b.y"` always loads listed assets at full resolution, `#set TextureFullResolutionUpgrade 1` enables the desktop post-load full-res texture re-fetch [default off: the world keeps its load-time texture tier — project-load assets land quarter-res; wasm/mobile never run the upgrade]), #doc_version <N> (authoring doc version; see <updating_old_worlds>).
 - Scene numeric fields support constant arithmetic: `+`, `-`, `*`, `/`, unary sign, parentheses.
 - One statement per line; separate statements on the same line with `;`. An empty list literal `[]` needs a List-typed context, e.g. `var H: List<Number> = []`.
 - Numbers are deterministic 48.16 fixed-point; tiny fractions lose precision — track small quantities in a smaller unit (e.g. hundredths of a cm as integers).
 - No recursion: direct or mutual func call cycles are a compile error; rewrite as loops (a List can serve as an explicit stack).
 - Scene object declarations can set position, rotation, size, height, model; model is an Oriverse URL like `ori.username.modelname`; attach a class with `:` (e.g. `object Foo : MyClass { ... }`).
 - Default mesh-backed `object`/`physics`/`crowd`/`display`: `position=(x,y,0)` means bottom-center pivot on ground Z=0. Effects/lights/regions/terrain/groups/canvases use center placement.
-- For axis-aligned cube walls/floors/platforms, prefer `bounds_min=(x1,y1,z1)` + `bounds_max=(x2,y2,z2)` over `position`+`size`; it names exact world-space box corners and avoids center/half-size mistakes. Example: `object NorthWall { model="cube" bounds_min=(-1500,1100,0) bounds_max=(1500,1180,280) }`. Do not combine with position/rotation/size/height/tile fields.
-- Grass on boxes: `object`/`display` clauses with model = "cube" accept grass = true (blades on the top face; display-only, no collision; global SetGrass* look knobs apply). Optional: grass_border = round|noise (edge falloff, default full face), grass_border_noise_scale = 220 (cm, noise feature size). Yaw rotation only - tilted boxes grow nothing.
+- Dynamic lights: `pointLight Lamp { position=(x,y,z) radius=600 intensity=5 color=#ffd9a0 }`; `spotLight` shines along local +X (aim with rotation), `areaLight` emits from its `size` rectangle. `radius` = falloff range in cm; `size` does NOT change a point/spot light (editor gizmo only); `cast_shadow = true` on point/spot only. Nest in `saved` templates to spawn lights from code; for lamps built into a model prefer the mesh `emitter(...)` socket.
+- For axis-aligned cube walls/floors/platforms, prefer `bounds_min=(x1,y1,z1)` + `bounds_max=(x2,y2,z2)` over `position`+`size`; it names exact world-space box corners and avoids center/half-size mistakes. Example: `object NorthWall { model="cube" bounds_min=(-1500,1100,0) bounds_max=(1500,1180,280) }`. Cube boxes only (`model="cube"`; `region_cube` for regions) — other models must use position+size. Do not combine with position/rotation/size/height/tile fields.
+- Object size clamps per axis at load: 500m static-collidable, 100m movable-physics, 1km with collision off — tile bigger floors/walls from 500m pieces.
+- Grass on objects: static mesh `object`/`display` clauses accept grass = true (blades on upward faces; steep faces stay bare; display-only, no collision; global SetGrass* look knobs apply; skinned models grow nothing). On model = "cube" blades cover the top face (yaw rotation only) and grass_border = round|noise (edge falloff, default full face) + grass_border_noise_scale = 220 (cm, noise feature size) shape the edge.
 - Prefer `height = ...` for imported/custom models to preserve proportions; use `ScaleToHeight(...)` at runtime; use `size = ...` only when intentionally stretching X/Y/Z.
 - "world description" = the serialized text of a world (scene + classes); saved from the editor and pasted back to reload. AI builds these; users paste them in.
 - `#class player` is auto-attached to every PlayerObject. Do not declare the player in scene. Declaring it REPLACES the built-in default player: call SetDefaultPlayerControlsEnabled(true) in its OnSpawned to keep built-in WASD move + jump, or code a movement loop — with neither, players cannot move (see <camera>).
@@ -34,7 +36,7 @@ Weave World Description Language Documentation
 - Name aliases by TYPE: `alias.<type>.<name>` with <type> in {model, effect, image, sound}, e.g. `model.goblin`, `effect.explosion`, `image.gold_icon`, `sound.hit`. A typed alias must resolve to a matching asset type.
 - You usually do NOT know real ori urls. Prefer typed alias placeholders and let the system/human bind real assets later:
   - All four types may be referenced UNDECLARED or declared bare (`alias sound.hit`, no `=` target); they resolve from the generated libraries below, show a safe placeholder until generation lands (cube / default explosion / placeholder sprite / placeholder clip), and a human can rebind them.
-  - MODEL aliases resolve from a generated-mesh library: a bare declaration `alias model.tree` (no `=` target, auto-added for undeclared refs too) binds a matching generated mesh by name at load; on a miss it shows a cube while a mesh is generated in the background (available on a later load). Name model aliases with plain singular nouns (`model.tree`, `model.market_stall`, not `model.trees`/`model.bigTreeA`) so library matching works. Want a specific existing mesh to start from or adapt -> the `mesh_library_search` tool returns library `#mesh` source to inline.
+  - MODEL aliases resolve from a generated-mesh library: a bare declaration `alias model.tree` (no `=` target, auto-added for undeclared refs too) binds a matching generated mesh by name at load; on a miss it shows a placeholder (cube; the player a mannequin stand-in) while a mesh is generated in the background, swapping in live when it lands. Name model aliases with plain singular nouns (`model.tree`, `model.market_stall`, not `model.trees`/`model.bigTreeA`) so library matching works. Want a specific existing mesh to start from or adapt -> the `mesh_library_search` tool returns library `#mesh` source to inline. A bound word's source is already in the world text (`#mesh gen_<word>` + its `material`/`#texture` clauses) — recolor/restyle by editing those directly. Character-noun words mint as rigged humanoids that auto-play idle/walk/run; the alias status marks minted words `rigged humanoid`.
   - IMAGE aliases resolve the same way from a generated-UI-image library: bare `alias image.gold_icon` binds a generated icon by name at load; on a miss it shows a placeholder sprite while an icon is generated in the background. Prefer bare image aliases for UI icons; name them by subject (`image.gold_icon`, `image.energy_icon`).
   - SOUND aliases resolve the same way from a generated-sound library: bare `alias sound.coin_pickup` binds a generated clip by name at load; on a miss it plays a placeholder clip while a sound is generated in the background. Name sound aliases by the event they accompany (`sound.coin_pickup`, `sound.sword_hit`, `sound.door_creak`) so generation prompts come out right.
   - ANIMATION: referencing an undefined `Ori.anim.canon.<verb>` appends the canonical-clip library's `#clip <verb> on canon` block at load (plain action verbs: `anim.canon.cheer`, `anim.canon.stomp`); it plays on any rigged humanoid via engine retarget. On a library miss the character keeps its current animation; the verb is queued for house minting and binds on a later load. A world-authored `#clip <verb> on canon` always wins.
@@ -46,58 +48,62 @@ Weave World Description Language Documentation
 </asset_aliases>
 
 <asset_word_library>
-- Established approved library words per alias namespace, plus `flipbook.<word>` particle textures. PREFER an existing word when one matches the need — it binds instantly with no generation wait or spend. Other words still work: misses show a placeholder and auto-generate in the background (flipbook words are minted deliberately via the flipbook_gen tool instead). Model words are not baked here — query them live with the `mesh_library_search` tool.
-image: (none approved yet)
-sound: (none approved yet)
-effect: (none approved yet)
-flipbook: blue_flame bubble_float dust_puff electric_spark ember_glow explosion_burst gray_smoke heart_pulse leaf_flutter magic_sparkle orange_flame poison_cloud snowflake_spin star_twinkle water_splash white_smoke
+- Established library words per alias namespace, plus `flipbook.<word>` particle textures. PREFER an existing word when one matches the need — it binds instantly with no generation wait or spend. Other words still work: misses show a placeholder and auto-generate in the background (flipbook words are minted deliberately via the flipbook_gen tool instead).
+model: abandoned_car alchemist alien_bug alien_hive alley_monster amphora anchor aqua_penguin assembler athlete aunt auntie axe ball banana banana_peel bandage bandit barn barracks barrel barrel_2 base_core baseball_bat battle_car bed bee beehive belt bench bench_2 berry_bush billboard blacksmith boar boat boat_parts bomb bone book boomerang boulder boulder_2 box bread_slice bread_slice_2 brick bridge buddhist_temple bush bush_2 bush_a butter cabbage camp_tent camp_tent_2 campfire canvas_tent cargo_truck carrot cart carved_owl_statue cash_bundle cat cat_blacksmith cat_cart_keeper cat_chef cat_engineer cat_factory_worker cat_merchant cat_rickshaw chair chair_2 checkpoint cheese cheese_2 chest chicken chicken_coop chime_lantern chunk_floor circular_saw clay_buddy cleric cloud clue_item clue_item_2 coin command_center cottage cousin cow crate crate_2 crop crop_plot crossbow crystal crystal_cluster crystal_shard cup customer customer_2 cutting_board cutting_board_2 cyclops dog dragon drill druid dual_blades durian elegant_woman ember_fox enemy_spawn energy_drink evidence_item exp_gem fan farmhouse farmhouse_floor fence finish_arch fish fish_2 fishing_rod flag flag_2 flamethrower flashlight flat_rock_slab flower food_crate forager_hut foundation fountain fox fridge fridge_2 frog frying_pan frying_pan_2 fuel_pump furniture_bookshelf furniture_table furniture_table_2 furniture_wardrobe gargoyle gate ghoul ghoul_2 gilded_hourglass glimmer_crate goblin godfather golden_beak_shaman golden_coin grandma grandpa grape grape_2 grass_rock grass_rock_cliff great_sword green_maple_tree greenhouse grocery_box ground_item guard guard_tower hammer hamster harpy hay_bale hay_bale_2 heal_pickup held_item horned_beast horse hospital_assistant house hungry_mouse hunter_bow hunting_hammer hut ice_shard idle_character invoker_mage iron_node item_crate jam_jar kid killer knife knight ladder lamp lamp_2 lane lantern lantern_2 light_pole log_pile log_pile_2 lumber_camp machine_gun mage magnet market_stall mecha_chameleon medic medicine_crate miner minotaur moss_boar mushroom nephew niece night_watchman ninja_runner npc nurse oak_tree officer owl paddle palm_tree patient pearl_bush pebble person pickaxe pickup_orb pig pine_tree pistol plate plate_2 player_char police_car pond poop projectile pumpkin rabbit rabbit_runner ragdoll_fighter rain_mill rain_totem ranger requiem_gun resident revolver rifle road_sign robot_grunt robot_runner rock rocket rocket_launcher rocksample rope rope_bundle runic_obelisk sandbag sea_mine sedan sentinel_drone shark shield shipping_container shop_counter shop_floor shopkeeper shotgun shuriken signpost signpost_2 signpost_3 skull slime small_rock smg smoke_bomb snail sniper_rifle soil_tile soldier spider sports_car squid stair star star_core statue stepmother stilt_house stone_pile stonecutter_lodge storehouse storm_hearth storm_shrine surgeon survivor sword table tank_hull tent timber_bundle toaster toaster_2 tool_chest torch torch_2 tower training_dummy training_dummy_2 travel_pack tree tribal_cat_elder tribal_cat_villager trophy trunk turret uncle villager volleyball wagon wall warehouse watchtower water_barrel water_well watercan watering_can weapon_rack weapon_rack_2 weapon_shop_sign well wheat wheelbarrow white_tribal_cat_player wizard_staff wood_fence wood_fence_2 wooden_stool worker_robot zebrite_totem zombie
+image: airtank_icon alien_bug angled_player_banner axe_icon bandage_icon bean_icon bean_seeds_icon berries_icon book_icon boss_skull bread_icon bullet_icon cabbage_icon campfire_icon carrot_icon cheese_icon clock_icon coin_icon crop_icon crossed_swords crossed_swords_2 crosshair cute_paw_cursor dash_icon deck_icon deck_icon_2 energy_icon fish_icon fishing_rod_icon flamethrower_icon flint_icon fluffy_sheep_party_portrait forest_ancient_tree_spirit_wide_splash forest_ent gold_coin_icon gold_icon gold_icon_2 hand_icon health_icon health_icon_2 hoe_icon horse_party_portrait hunger_icon inverse_trapezoid_top_bar iron_ore_icon knight_helmet loading_splash log_icon machine_gun_icon mackerel_icon monster_head moon_icon orange_cat_party_portrait panel_frame parsnip_icon parsnip_seeds_icon pickaxe_icon poison_icon potato_icon potato_seeds_icon purple_hive_mind_insect_warrior_wide_splash qa_probe_gem radish_icon revolver_icon rifle_icon robot_face robot_vending_mech_champion_wide_splash rocket_launcher_icon round_table_knight_wide_splash ruby_gem_icon salvage_icon sanity_icon sardine_icon scythe_icon seed_bag_icon seed_icon shotgun_icon skill_dagger_icon skill_fireaura_icon skill_hammer_icon skill_shield_icon skill_stealth_icon snapper_icon snowflake_spin squid_icon steak_icon stone_icon sun_icon tft_alien_portrait_black tft_boss_skull_black tft_clock_black tft_crossed_swords_black tft_forest_portrait_black tft_monster_head_black tft_robot_portrait_black tft_yokai_portrait_black torch_icon tuna_icon twigs_icon undead_death_knight_wide_splash undead_skull water_drop_icon watering_can_icon white_chicken_party_portrait wood_icon yokai_mask yokai_samurai_oni_wide_splash
+sound: ambient_horror apartment_ambience arena_warning baby_raptor_step banana_boomerang baton_hit baton_swing bear_shotgun bite blast body_thump body_thump_2 boost boost_burst bow_hit branch_snap brass_gong cannon_blast cannon_fire car_horn card_draw card_play cash_pickup cash_pickup_2 character_select checkpoint chomp coin_pickup coin_pickup_2 corn_burst countdown countdown_beep countdown_tick crab_blaster crab_hit crab_skill crash crash_burst critical_impact critical_impact_2 croc_machinegun crow_call crowd_cheer crystal_pickup dash_burst dodge dodge_dust dodge_dust_2 dog_bark dog_pistol door_close door_open door_open_2 door_unlock dual_hit earthquake_rumble earthquake_rumble_2 electric_burst electric_shock eliminated energy_empty engine_acceleration engine_idle exit_unlock explosion finish finish_chime fish_caught fishing_cast fishing_reel flamethrower_burst food_complete food_complete_2 front_weapon_activation game_check game_end game_start gameplay_music gameplay_music_2 glimmer_bell gold_pickup golf_cup golf_swing grenade_launcher gunshot hammer_hit hammer_hit_2 heartbeat hit hook_impact hook_impact_2 hook_throw hook_throw_2 item_pickup item_pickup_2 laser_shot laser_shot_2 lasgun_shot level_up level_up_2 level_up_3 level_up_4 level_up_5 line_clear machine_gun machine_gun_reload machine_gun_shot magic_blast medkit_pickup medkit_use menu_music metal_hit metal_hit_2 mine missile_launch mole_sniper monster_attack monster_attack_2 monster_roar monster_roar_2 owl_hoot pickup piece_capture piece_lock piece_move pistol_reload pistol_shot place player_hit player_hurt player_hurt_2 police_siren punch rain_ambience raptor_step ready_up rear_ability_activation repair resource_pickup respawn revive rifle_reload rifle_shot rifle_shot_2 ring_out ringout robot_beam robot_blast robot_charge robot_laser rock_riff rocket_shot rot_loop royal_capture score_boost shield shield_block ship_destroyed shotgun_shot signal_ping siren slab_turn slap slap_hit stone_rotate survivor_step sword_clang sword_clang_2 sword_hit sword_hit_2 tire_skid toast_pop toy_pop trex_step turn_alert ui_click ui_click_2 ui_click_3 ui_click_4 ui_click_5 vehicle_damaged vehicle_destroyed victory victory_fanfare victory_fanfare_2 victory_sting victory_sting_2 vortex_hum wall_deploy wall_pickup warning_siren water_splash wave_crash weapon_switch whistle wind_gust wind_gust_2 wolf_howl wood_impact zebrite_chime zombie_attack zombie_growl zombie_roar
+effect: acid_splash arrow_hit bite_splash blood_hit blood_splash boost_burst cannon_blast capture_burst cartoon_impact cash_sparkle cash_sparkle_2 coin_sparkle collapse_dust crash_burst critical_smoke damage_smoke damage_sparks damage_sparks_2 damage_sparks_3 dash_trail dash_trail_2 dismember dodge_dust dust_puff dust_puff_2 dust_puff_3 electric_burst eliminated_burst explosion explosion_burst finish_confetti fire_burst fireball fireball_burst gold_rush golf_cup golf_hit grenade_blast hammer_impact heal_glow healing_glow hit_burst hook_hit hook_hit_2 impact_flash_critical impact_flash_small impact_shockwave impact_shockwave_2 impact_shockwave_3 impact_sparks ink_cloud item_glow magic_blast magic_sparkle magic_vortex metal_hit meteor_fire mine_burst muzzle_flash objective_pickup player_hit poison_cloud rage_burst rainbow_burst rainbow_burst_2 rapid_slash respawn_burst revive_burst revive_glow rickshaw_burn ringout_explosion rocket_explosion rot_pulse rune_pickup shield_burst shield_pop slap_hit slash_burst slash_burst_2 slash_burst_3 smoke_puff smoke_puff_2 sonar_pulse sparkle_burst sparkle_burst_2 sparkle_burst_3 sparkler speed_burst stun_stars stun_stars_2 stun_stars_3 sword_slash tank_burning tank_explosion terrain_blast top_collision_impact water_burst water_splash wind_leaves
+flipbook: blood_mist blue_flame bubble_float dust_puff electric_spark ember_glow explosion_burst gray_smoke heart_pulse hot_spark_burst leaf_flutter magic_sparkle muzzle_flash_star orange_flame poison_cloud smoke_puff snowflake_spin star_twinkle tracer_streak water_splash white_smoke
 </asset_word_library>
 
 <texture_dsl_usage>
 - For new worlds using primitive meshes, use texture dsl to paint them.
 - `#texture Name ... #end` auto-creates triplanar `material Name`. Use it as `material = "Name"` in scene objects, `Material.Name` in Weave code, `terrain.SetTerrainMaterial(Material.Name)`, `terrain.SetTerrainLayers(...)`, `batch.SetBatchMaterial(Material.Name)`, or as a local `#mesh` slot name (`material: "Name"` / `paint(..., material: "Name")`).
-- Flat color shorthand: `#texture Wood color=#8B5A2B` creates a non-emissive triplanar `material Wood`; useful for low-poly color-blocking and quick placeholders. Optional `roughness=0..1` and `metallic=0..1` (e.g. `#texture Asphalt color=#1E2024 roughness=0.95`) — without a high roughness, dark ground colors read pale from sky reflection.
-- Derived material (color variant, no extra texture bake): `material WoodRed { base = "Wood" tint = "#8a2b1e" }` copies shader/textures/params from the base material and multiplies its color by tint (quoted hex). `base` may also name a built-in tintable detail family - WoodDetail, StoneDetail, MetalDetail, FabricDetail, LeatherDetail, PlasterDetail (near-white; tint sets the color) - or a built-in authored surface: StylizedBricks, OldTilesWhite, StylizedGrass, PolishedConcrete. Prefer this over writing a `#texture` body when only the color differs.
-- Use #texture directly on primitives, terrain, batches, and local `#mesh` slots. For #mesh material precedence: object/batch override > explicit submesh override > authored local mesh slot material > intrinsic GLB PBR. Imported GLB material names are not auto-bound to world materials. For large terrain/floors, set `tile_m = 2.0;`..`4.0;` so repeats are not too tiny.
+- Masonry patterns (pattern.brick/tile) under the default triplanar mapping project world-space joints; on carved/round geometry (columns, moldings, statues) use a coursing-free variant or `mapping = uv;`.
+- Flat color shorthand: `#texture TeamRed color=#B03A2E` creates a non-emissive triplanar `material TeamRed` — for stylized color-blocking and quick placeholders; surfaces meant to read as real should use the built-in library (next clause). Optional `roughness=0..1` and `metallic=0..1` (e.g. `#texture RubberFloor color=#1E2024 roughness=0.95`) — without a high roughness, dark ground colors read pale from sky reflection.
+- Built-in material library — real textured PBR with zero declarations: `material = "Wood"` on any object/batch/terrain (and `Material.Wood` in code) just works; the engine copies the one-line library clause into the world on save, and a world-declared material of the same name always wins. Library: Wood, WoodDark, Plank, Bark, Stone, Rock, Brick, Dirt, Sand, Metal, MetalDark, Gold, Fabric, Cloth, Rope, Straw, Leather, Foliage, Leaf, Grass, Snow, Ceramic, Bone, Glass, GlassTransparent, Water, Default; authored surfaces StylizedBricks, OldTilesWhite, StylizedGrass, PolishedConcrete, Asphalt. Default to these for anything meant to read as a real surface.
+- Derived material (color variant, no extra texture bake): `material WoodRed { base = "Wood" tint = "#8a2b1e" }` copies shader/textures/params from the base material and multiplies its color by tint (quoted hex). `base` may name any built-in above or a tintable near-white detail family (WoodDetail, StoneDetail, MetalDetail, FabricDetail, LeatherDetail, PlasterDetail). Prefer this over writing a `#texture` body when only the color differs.
+  Material clauses also accept `emission = N` (self-lit glow in the material's tinted color; linear: 1 soft, 4 lamp, 16+ neon bloom) and `roughness = 0..1` / `metallic = 0..1` (uniform overrides of the baked surface response) — e.g. `material CyanGlow { base = "MetalDetail" tint = "#19D9FF" emission = 5 }`.
+- Use #texture directly on primitives, terrain, batches, and local `#mesh` slots. For #mesh material precedence: object/batch override > explicit submesh override > authored local mesh slot material > intrinsic GLB PBR. Imported GLB material names are not auto-bound to world materials. `tile_m` = meters per pattern repeat (default 1.0, prop scale): RAISE to `2.0;`..`4.0;` for large terrain/floors so repeats are not too tiny; LOWER to `0.3;`..`0.5;` for small props/panels so the pattern does not print larger than the object. Material clauses accept it too (`material X { base = "Fabric" tileM = 0.4 }`).
 - Authoring or editing a `#texture` BODY (anything beyond the color=/base= one-liners above): read the `texture_dsl` skill first — statement syntax, builtins (noise/pattern/sdf/filter families), recipes, worked examples. Do not guess builtin names or signatures from memory.
 - Terrain layer sets: assign scalar `out.height` on every layer of the set (or none) — higher-height texels win at SetTerrainLayers blend borders (rock pushing through grass).
 - `#terrain_splat Name ... #end` + `terrain.SetTerrainSplat("Name")`: same expression language with terrain inputs `height` (world m), `slope01` (0 flat..1 vertical), `convex` (-1..1), `ao` (0..1), `moist` (0..1), `user` (0..1, fed by `terrain.SetTerrainSplatMask(mask, sx, sy)`, else 0); `out.color` RGB = SetTerrainLayers Steep/High/Low weights (base = leftover). Baked per-terrain; replaces the slope/height auto-bands for hand-authored placement (e.g. `out.color = vec3(smoothstep(0.4, 0.6, slope01), smoothstep(18, 24, height), sat(moist * 2 - convex));`).
 - Optional scalar `out.grass` in `#terrain_splat` = grass spawn density 0..1 (0 = bare; spawn saturates around 0.4, so mid values still read as full cover) - keeps grass off beaches/cliffs/dry zones from the same rules that place the textures, and thins the auto ground tint with it. Unassigned = full density; an explicit SetTerrainGrassWeightmap overrides it.
 - Colormap mode: `out.albedo` (vec3, mutually exclusive with `out.color`) makes the bake the FINAL surface color instead of layer weights - full per-pixel control (satellite-style coloring, stylized palettes, drainage streaks from `user`). The base SetTerrainMaterial still supplies normal/ORM detail; SetTerrainLayers weights, band blending, macro tint and the auto grass ground tint are all bypassed. Set `size = 2048;` (up to 4096) for crisp color; `out.grass` still works alongside.
-- `#road_network Name ... #end`: a road GRAPH the engine meshes into junction-merged road tiles at load (carriageway, miter-blended intersections, curbs, sidewalks, center dashes, crosswalks). Body statements end with `;`: `cell = 32000;` (tile grid cm, optional), `class = width_cm, sidewalk_cm, curb_w_cm, curb_h_cm, "CarriagewayMat", "CurbMat", "SidewalkMat", "MarkingMat";` (repeatable; edges index classes in order; empty marking name = no markings), `nodes = x, y, x, y, ...;` (cm, repeatable/appends), `edges = nodeA, nodeB, classIndex, ...;` (triplets, repeatable). Pair it with ONE object `object Roads_o { model = "roadnet.<Name>" position = (0, 0, 0) }` — the loader expands it into per-tile objects automatically (thin walkable slabs). Prefer this over hand-built per-segment road boxes: junctions come out clean and one graph edit reflows everything.
-- `#terrain_bytes "terrain.url" ... #end`: embedded uploaded-terrain heightfield payload (base64 of zlib-compressed terrain bytes) satisfying `terrain X { model = "terrain.url" }` with zero network fetches, so the world is self-contained (headless validation included). Blocks are machine-generated (desktop `embed_terrain` CLI), not hand-authored. Prefer procedural terrain (`SpawnTerrainFromHeights` + `TerrainHeights*`) for new worlds.
-- Avoid SetEmissionColor/SetEmissionIntensity/SetAssetSubmeshEmissionIntensity for normal world materials for now; they can make generated scenes too bright. Prefer non-emissive #texture/material colors, and use only tiny low-intensity glow accents when explicitly requested.
+- `#road_network Name ... #end`: a road GRAPH the engine meshes into junction-merged road tiles at load (carriageway, miter-blended intersections, curbs, sidewalks, center dashes, crosswalks). Body statements end with `;`: `cell = 32000;` (tile grid cm, optional), `class = width_cm, sidewalk_cm, curb_w_cm, curb_h_cm, "CarriagewayMat", "CurbMat", "SidewalkMat", "MarkingMat";` (repeatable; edges index classes in order; empty marking name = no markings), `nodes = x, y, x, y, ...;` (cm, repeatable/appends), `edges = nodeA, nodeB, classIndex, ...;` (triplets, repeatable), `curve = a, b, c1x, c1y[, c2x, c2y];` (optional per a→b edge: quadratic/cubic bezier control points in cm; omit = straight; junctions meet curves at their end tangents; too-tight curvature for the class width is a load error). The block spawns the network itself: tiled road meshes plus walkable per-edge slabs (no companion object needed); optional `position = x, y, z;` offsets the whole network. Editor edits fold back into this block on save — re-read it before patching. Prefer this over hand-built per-segment road boxes: junctions come out clean and one graph edit reflows everything.
+- `#terrain_bytes "terrain.url" ... #end`: embedded uploaded-terrain heightfield payload (base64 of zlib-compressed terrain bytes) satisfying `terrain X { model = "terrain.url" }` with zero network fetches, so the world is self-contained offline. Blocks are machine-generated (desktop `embed_terrain` CLI), not hand-authored - and never required to submit: validation resolves uploaded `terrain.` assets itself. Prefer procedural terrain (`SpawnTerrainFromHeights` + `TerrainHeights*`) for new worlds.
+- Emission is linear (1 soft self-lit, 4 lamp, 16+ neon bloom): put it on small accents - lamps, signs, runes, windows; large emissive surfaces wash out the scene, keep those <= 1.
 </texture_dsl_usage>
 
 <adjuster_usage>
-- `#adjuster ... #end` (top-level): declares hand-tunable global look knobs shown in the editor's adjuster panel (top-right sliders icon; auto-opens after load). Values apply on load; slider edits fold back into this block on save.
+- `#adjuster ... #end` (top-level): declares hand-tunable global look knobs. Values apply on load; slider edits fold back into this block on save. Sliders: grass/ground knobs in the Terrain inspector (click the terrain), SetWater* in Find > Water, the rest in the Adjust panel (top-right sliders icon; links to both inspectors).
 - Body lines: `section "Title"` groups knobs after it; `knob <SimCallName> = <value> [range a..b]`; value is a number, or `#rrggbb` for color knobs; `range` overrides the slider range of number knobs. `//` comments ok.
 - Only whitelisted global sim calls (below) are valid knob names; each at most once. Texture params and ranged #mesh params expose per-texture/per-mesh panel knobs on their own; no #adjuster entry for those.
-- Add an #adjuster block whenever the look is a matter of taste the user may want to hand-tune (grass, sun, sky, post color grading).
+- Add an #adjuster block whenever the look is a matter of taste the user may want to hand-tune (grass, ground, water, wind, tree LOD).
+- Lighting/sky/grade knobs (sun color/intensity, skybox tint/saturation/exposure, SSAO, vignette, scene contrast/saturation/exposure) are USER-owned: never write or retune them, as knobs or calls; lighting/mood requests -> Adjust panel.
 - SetWater* knobs set the INITIAL ocean state: they replay after load-time code, so a `knob SetWaterEnabled = 0` line keeps water off across reloads (the editor's Find > Water delete writes it). Code that changes water after load (OnSpawned, timers, events) still wins at runtime.
-- Knobs: SetGrassRootColor (color), SetGrassTipColor (color), SetGrassBrightnessVariationPercent (0..300), SetGrassSizeVariationPercent (0..300), SetGrassHeightMinCm (0..300), SetGrassHeightMaxCm (0..300), SetGrassWavePeriodCm (100..3000), SetGrassWindStrengthCm (0..50), SetGrassWindSpeedPercent (0..300), SetGrassBladeWidthPercent (50..200), SetGrassSpacingCm (0..100), SetTerrainErosionDetailPercent (0..300), SetSunColor (color), SetSunIntensity (0..20), SetSkyboxTint (color), SetSkyboxSaturation (0..3), SetSkyboxExposure (0..3), SetSsaoIntensity (0..3), SetTerrainNormalStrengthPercent (0..300), SetContrast (0..4), SetSaturation (0..4), SetExposure (0..3), SetWaterEnabled (0..1), SetWaterSeaLevelCm (-2000..10000), SetWaterAmplitudeCm (0..500), SetWaterWavelengthCm (100..20000), SetWaterSteepness (0..1), SetWaterDirectionDeg (0..360), SetWaterSpeedPercent (0..400), SetWaterShallowColor (color), SetWaterDeepColor (color), SetWaterColorMixRangeCm (1..2000), SetWaterTransparency (0..1), SetWaterReflectionStrength (0..2), SetWaterReflectionDistortion (0..2)
+- Knobs: SetGrassRootColor (color), SetGrassTipColor (color), SetGrassBrightnessVariationPercent (0..300), SetGrassSizeVariationPercent (0..300), SetGrassHeightMinCm (0..300), SetGrassHeightMaxCm (0..300), SetGrassWavePeriodCm (100..3000), SetGrassWindStrengthCm (0..50), SetGrassWindSpeedPercent (0..300), SetGrassBladeWidthPercent (50..200), SetGrassSpacingCm (0..100), SetGrassTerrainActiveDistanceM (0..500), SetGrassCullDistanceM (0..500), SetGrassFadeDistancePercent (0..100), SetGrassFarThinningPower (0..8), SetTerrainErosionDetailPercent (0..300), SetSunColor (color), SetSunIntensity (0..20), SetSunRotation (0..360), SetSunTilt (0..90), SetSkyLightIntensity (0..8), SetSkyLightColor (color), SetSkyLightSaturation (0..3), SetSkyboxTint (color), SetSkyboxSaturation (0..3), SetSkyboxExposure (0..3), SetSkyboxHaze (0..8), SetSkyboxContrast (0..3), SetSkyboxGroundColor (color), SetSkyboxColor (color), SetSkyboxCloudCoverage (0..1), SetSkyboxStarIntensity (0..3), SetShadowBlurRadius (0..20), SetShadowOpacity (0..1), SetShadowLift (0..3), SetShadowLiftThreshold (0.02..0.3), SetShadowDistance (0..500), SetFogColor (color), SetFogStartDistance (0..2000), SetFogEndDistance (0..2000), SetFogSkyboxAffect (0..100), SetHeightFogEnabled (0..1), SetHeightFogTop (0..200), SetHeightFogBottom (-100..200), SetHeightFogSoftness (0..1), SetSsaoIntensity (0..1), SetSsaoDistance (0..10), SetBloomThreshold (0..3), SetBloomIntensity (0..2), SetTerrainNormalStrengthPercent (0..300), SetContrast (0..4), SetSaturation (0..4), SetExposure (-3..3), SetVignetteStrength (0..1), SetVignetteRadius (0..1), SetVignetteSoftness (0..1), SetVignetteColor (color), SetWaterEnabled (0..1), SetWaterSeaLevelCm (-2000..10000), SetWaterAmplitudeCm (0..500), SetWaterWavelengthCm (100..20000), SetWaterSteepness (0..1), SetWaterDirectionDeg (0..360), SetWaterSpeedPercent (0..400), SetWaterShallowColor (color), SetWaterDeepColor (color), SetWaterColorMixRangeCm (1..2000), SetWaterTransparency (0..1), SetWaterReflectionStrength (0..2), SetWaterReflectionDistortion (0..2), SetWindDirectionDeg (0..360), SetWindStrength (0..1), SetWindGustiness (0..1), SetTreeLodSwitchDistanceM (0..300), SetTreeMeshDistanceM (0..1000), SetTreeCullDistanceM (0..3000), SetTreeFadeDistancePercent (5..80), SetTreeFarLeafDensityPercent (10..300)
 Example:
 #adjuster
 section "Grass"
 knob SetGrassTipColor = #8fbf4a
-knob SetGrassHeightMaxCm = 45
-knob SetSunIntensity = 4.5 range 2..8
+knob SetGrassHeightMaxCm = 45 range 0..120
 #end
 </adjuster_usage>
 
 <particles_json_usage>
 - `#particles Name ... #end` defines local effect asset `effect.Name`; `#particles effect.Name` also works, but prefer short `Name`. Body is a JSON array; each object is one emitter component.
 - Every local component needs a top-level `"particleTextureName"`: `"flipbook.<word>"` for an animated sprite-sheet atlas from the shared flipbook library (best for fire/smoke/magic; lowercase subject words like `flipbook.orange_flame`; misses render a glow placeholder until the word is minted), `"texture.TextureName.color"` with a matching `#texture TextureName`, or `"image.<User>.<Name>"` referencing a real ori image asset you actually know (never invent one). Use `texture.*.color` (`baked.*` addresses material-slot maps, not particle textures; `.normal`/`.orm` are not particle flipbooks).
-- Spawn with scene `effect Spark { effect = "effect.Name" }` or Weave effect APIs.
-- Sizing: declare `"boundingBoxSize": [x, y, z]` (meters, Z-up; per-component, max wins) as the effect's authored real-world footprint, and author emitters (`radius`, `sizeSequence`, speeds) at that real scale. The object's `size` (cm, like any object) then scales the effect by `size / boundingBoxSize` — e.g. a campfire authored with `boundingBoxSize [1, 1, 1.5]` placed with `size = 100` renders at its authored 1m footprint. Without `boundingBoxSize` the base is a legacy 10cm box, so `size = 100` blows the effect up 10x — always declare it. Size effects with `size`, not `scale`.
+- Spawn with scene `effect Spark { effect = "effect.Name" }` - or, for prop-attached fire/smoke, prefer a `particles("<word>", at: ...)` socket inside the `#mesh` (see <mesh_dsl_usage>). From code pass the ASSET as a static import: `SpawnEffectWithAutoDestroy(Ori.effect.Name, pos)` (returns the spawned object — `.SetSizeUniform(n)` to size it), or `Ori.alias.effect.<word>` for aliases. A `Scene.<object>` reference is not an effect asset (W2C0405).
+- Sizing: declare `"boundingBoxSize": [x, y, z]` (meters, Z-up; per-component, max wins) as the effect's authored real-world footprint, and author emitters (`radius`, `sizeSequence`, speeds) at that real scale. The object's `size` (cm, like any object) then scales the effect by `size / boundingBoxSize` — e.g. a campfire authored with `boundingBoxSize [1, 1, 1.5]` placed with `size = 100` renders at its authored 1m footprint. Without `boundingBoxSize` the base is a legacy 10cm box, so `size = 100` blows the effect up 10x — always declare it. Size effects with `size`, not `scale`. Author emitters freely around your origin; when the content is not origin-centered, add `"boundingBoxCenter": [x, y, z]` (meters; where the box CENTER sits relative to that origin; default [0,0,0]) so the box covers the content — e.g. a ground flame rising 0..1.5m declares [0, 0, 0.75]. Placement matches meshes: the object's `position` rests the declared box's bottom on the point (`transform_pivot = center` centers it); code spawns (`SpawnEffect*`) put the box CENTER at the given position.
 - JSON values: scalars are numbers, vecs are `[x,y]`/`[x,y,z]`, curves are up to 8 `[[life01, value], ...]`; `colorSequence` uses `[[life01, [r,g,b]], ...]`. Prefer numeric `0/1` for booleans.
-- CPU/import keys: `_particleName_` ignored label; `particleCount` live-particle capacity override, not spawn count; `emitterPosition`/`emitterRotation` component-local offset/XYZ degrees; `boundingBoxSize` authored footprint in meters (see sizing bullet above).
+- CPU/import keys: `_particleName_` ignored label; `particleCount` live-particle capacity override, not spawn count; `emitterPosition`/`emitterRotation` component-local offset/XYZ degrees; `boundingBoxSize`/`boundingBoxCenter` authored footprint + box placement in meters (see sizing bullet above).
 - Flipbook keys: `framesX`, `framesY`, `totalFrames`, `flipbookAnimationSpeed`, `flipbookStartRandom`. For `flipbook.<word>` refs these auto-fill from the library at load; set them only to override.
-- Spawn keys: `spawnStartDelay`, `spawnRate` per sec, `isLooping`, `duration` seconds (`0` means no shader stop; use finite duration for one-shots), `burstParticleCount`, `burstInterval`.
-- Shape keys: `emitterShapeType` = `"sphere"|"box"|"cylinder"|"disc"` or `0..3`; `shapeStyle` = `"volume"|"surface"`; `shapeInOut` = `"in"|"out"|"both"` (omitted defaults inward); `radius`, `cylinderHeight`, `boxSize`, `shapePartial`, `lifeTimeRange`, `speedRange`, `spreadAngle` `[yaw,pitch]` degrees, `lockedToEmitter`. Box surface emits from +Z face; cylinder height is local X; disc uses `cylinderHeight` as thickness.
-- Visual/motion keys: `sizeConstant` or `sizeSequence`; `opacityConstant` or `opacitySequence`; `colorConstant` or `colorSequence`; `accelerationVector` authored Z-up; `drag` seconds to halve velocity; `rotationRange`, `rotationSpeedRange`; `orientation` 0 facing camera / 1 world-up / 2 velocity-parallel / 3 velocity-perpendicular; `additiveBlend`, `isHidden`, `softParticleFadeDisabled`, `softParticleFadeDistance`, `squashConstant` or `squashSequence` (positive stretches up, negative sideways).
+- Spawn keys: `spawnStartDelay`, `spawnRate` per sec, `isLooping`, `duration` seconds (`0` means no shader stop; use finite duration for one-shots), `burstParticleCount` (fires at t=0, then every `burstInterval` seconds while emitting; `burstInterval` unset = the t=0 burst only).
+- Shape keys: `emitterShapeType` = `"sphere"|"box"|"cylinder"|"disc"` or `0..3`; `shapeStyle` = `"volume"|"surface"`; `shapeInOut` = `"in"|"out"|"both"` (omitted defaults inward); `radius`, `cylinderHeight`, `boxSize`, `shapePartial`, `lifeTimeRange`, `speedRange`, `spreadAngle` `[yaw,pitch]` degrees, `lockedToEmitter` (`0` default = particles keep world position once spawned - trails stay behind a moving emitter; `1` = particles ride it, e.g. torch flame). Box surface emits from +Z face; cylinder height is local X; disc uses `cylinderHeight` as thickness. Emission direction: each shape emits along its own radial direction; `shapeInOut` omitted = INWARD, `"out"` flips outward, `"both"` = 50/50. `spreadAngle [yaw, pitch]` then jitters that direction by uniform +/-yaw degrees about the emitter's local Y axis and +/-pitch degrees about its X axis (fixed local axes, not a cone around the direction).
+- Visual/motion keys: `sizeConstant` or `sizeSequence`; `opacityConstant` or `opacitySequence`; `colorConstant` or `colorSequence`; `accelerationVector` authored Z-up; `drag` seconds to halve velocity; `rotationRange`, `rotationSpeedRange`; `orientation` 0 facing camera / 1 world-up / 2 velocity-parallel / 3 velocity-perpendicular; `additiveBlend`, `isHidden`, `softParticleFadeDisabled`, `softParticleFadeDistance`, `squashConstant` or `squashSequence` (positive stretches up, negative sideways); `lit` 1 = sun+sky shading (smoke/dust/debris read as lit volumes; leave 0 for emissive fire/glow).
 - Resolution key: components render at full (native) resolution by default (crisp edges, no distance shimmer). Set `"renderResolution": "half"` on soft/volumetric high-overdraw components (smoke, fog, glow) — cuts GPU fill cost on weak GPUs; avoid on hard-edged/crisp content (`"full"` is accepted as an explicit no-op).
-- Ribbon/trail components (boost trails, sword arcs, tracers, dash streaks): `"type": "ribbon"` renders one connected camera-facing strip through the emitter's recent world path instead of billboards; layer with billboard components in the same effect (ideal boost = ribbon streak + sparse additive orbs). Keys: `trailSeconds` (point max age = trail length, default 0.5), `pointsPerSecond` (path sampling rate, default 30), `ribbonUv` = `"stretch"` (default) | `"repeat_per_meter"` (tiles by real distance), `ribbonPoints` (ring cap; defaults to fit trailSeconds*pointsPerSecond, max 256); `sizeConstant`/`sizeSequence` = strip WIDTH in meters over point age; texture/flipbook, color/opacity, `additiveBlend`, `renderResolution`, `boundingBoxSize`, `emitterPosition`/`emitterRotation`, soft-fade keys keep their exact meaning. Emission/shape/motion keys (`spawnRate`, `lifeTimeRange`, `emitterShapeType`, `speedRange`, `spreadAngle`, `drag`, `orientation`, `duration`, ...) are load ERRORS on a ribbon component. Ribbon effects are always continuous; the strip exists only while the emitter MOVES (attach to a moving object; `preview_effect` sweeps the emitter for you). Object `size` scales strip width — trail length is temporal (`trailSeconds` x actual speed).
+- Ribbon/trail components (boost trails, sword arcs, tracers, dash streaks): `"type": "ribbon"` renders one connected camera-facing strip through the emitter's recent world path instead of billboards; layer with billboard components in the same effect (ideal boost = ribbon streak + sparse additive orbs). Keys: `trailSeconds` (point max age = trail length, default 0.5), `pointsPerSecond` (path sampling rate, default 30), `ribbonUv` = `"stretch"` (default) | `"repeat_per_meter"` (tiles by real distance), `ribbonPoints` (ring cap; defaults to fit trailSeconds*pointsPerSecond, max 256); `sizeConstant`/`sizeSequence` = strip WIDTH in meters over point age; texture/flipbook, color/opacity, `additiveBlend`, `renderResolution`, `boundingBoxSize`, `emitterPosition`/`emitterRotation`, soft-fade keys keep their exact meaning. Emission/shape/motion keys (`spawnRate`, `lifeTimeRange`, `emitterShapeType`, `speedRange`, `spreadAngle`, `drag`, `orientation`, `duration`, ...) are load ERRORS on a ribbon component. Ribbon effects are always continuous; the strip exists only while the emitter MOVES (attach to a moving object; `preview_effect` sweeps the emitter for you). Object `size` scales strip width — trail length is temporal (`trailSeconds` x actual speed). A trail that looks unchanged after resizing its object wants `trailSeconds`/`sizeSequence` edits, not more `size`.
 - Mesh components (debris, coins, leaves, shards, casings): `"type": "mesh"` renders lit opaque 3D instances of a real mesh instead of sprites; layer with billboard/ribbon components in one effect (rock burst = mesh chunks + dust billboards + one flash). `"particleMeshName"`: a local `"mesh.Name"` or a bare-alias `"alias.model.<noun>"` (library-bound or background-generated; placeholder cube until it lands) — or an array of up to 4, picked per particle (identical chunks read fake). Meshes keep their own materials and receive scene lighting: `colorConstant`/`colorSequence` tints (omit = untinted), `opacityConstant`/`opacitySequence` dither-fades, `sizeConstant`/`sizeSequence` = largest mesh dimension in meters. `"meshAlign"`: `"tumble"` (default; `"tumbleSpeedRange": [min,max]` deg/s random-axis, default [90, 360]) | `"velocity"` (mesh +Z along travel: arrows, shards) | `"world"` (authored orientation). Emission/shape/motion keys keep their exact billboard meaning. Texture/flipbook keys, `orientation`, `rotationRange`/`rotationSpeedRange`, `squash*`, `additiveBlend`, `softParticleFade*`, `renderResolution` are load ERRORS on a mesh component. `"castShadow": 1` enables shadow casting (default off; a fading particle stops casting, like skinned deaths). `"groundBounce": 0..1` bounces world-space particles off terrain/static ground with that restitution and lets them settle until life ends (visual bounce, not physics; `lockedToEmitter` particles skip it). HDR `colorConstant`/`colorSequence` excess over 1.0 becomes emissive glow. Each particle is a real lit draw — keep `spawnRate * lifeTime` under ~100 and meshes low-poly.
 - Runtime-managed fields are not useful in JSON: `time`, `delta_time`, `world_matrix`, `world_matrix_inv`, `emitter_time`, `emitter_id`, `system_scale`, `instance_tint`, `instantClearOnRemove`, padding fields. Unknown keys only log warnings.
 Example:
@@ -123,32 +129,48 @@ effect ChimneySmoke {
 }
 </particles_json_usage>
 
+<sound_dsl_usage>
+- `#sound Name ... #end` bakes a local procedural sound asset `sound.name` at load (name lowercased; reference case-insensitive, no creator segment). Play like any sound url: `PlaySound(Ori.sound.name, 1.0)`.
+- Body: `duration = <sec>` (max 8, default 1), `let x = <expr>` chains, final `out = <expr>`. Combine with `+ - * /` and parens; scalar constants broadcast, shorter signals zero-pad.
+- Ops: `osc(sin/saw/square/tri, freq, phase)` (freq may be a signal for sweeps/FM), `noise(white/pink, seed)`, `biquad(lp/hp/bp, input, cutoff, q)` (cutoff may be a signal), `env_adsr(attack, decay, sustain, release)`, `env_exp(start, end, time)` (freq or amp ramps), `mix(a, b, t)`, `layer(a, b, ...)`, `delay(input, time, feedback, mix)`, `pitch(input, ratio)`, `normalize(input, peak)`, `limit(input, ceiling)`.
+- Edits rebake on reload. Keep one-shots short; looping ambience via PlaySoundLooped works on any baked sound.
+- Music/BGM: this synth is SFX-grade (8s cap, no instruments) and cannot produce music — say so up front and use a marketplace/uploaded sound url with PlaySoundLooped instead of iterating synth attempts.
+#sound laser
+duration = 0.35
+let sweep = osc(saw, freq = env_exp(1800, 250))
+out = normalize(biquad(lp, sweep, cutoff = 2200, q = 1.2) * env_adsr(0.005, 0.1, 0.0, 0.08), 0.9)
+#end
+</sound_dsl_usage>
+
 <mesh_dsl_usage>
-- `#mesh <Name> ... #end` defines a local CPU-baked procedural static mesh; reference it as `model = "mesh.Name"` in scene declarations or `Ori.model.mesh.Name` in Weave code (SpawnObject, CreateInstanceBatch). Authoring units are simulation centimeters, Z-up; baked meshes are bottom-center anchored at object origin and their deterministic cm AABB supplies box-collider bounds.
+- `#mesh <Name> ... #end` defines a local CPU-baked procedural static mesh; reference it as `model = "mesh.Name"` in scene declarations or `Ori.model.mesh.Name` in Weave code (SpawnObject, CreateStaticInstanceBatch). Authoring units are simulation centimeters, Z-up; baked meshes are bottom-center anchored at object origin and their deterministic cm AABB supplies box-collider bounds.
+- `#mesh <Name> destructible: masonry|wood|rock|concrete` bakes a hidden debris chunk set for the model; `obj.ShatterAndDestroy()` then bursts the object into tumbling chunks that bounce, settle, and fade (display-only, no sim collision; without the tag it acts as plain Destroy()). Preview with the preview_destruction tool; destructible mesh names cap at 46 chars.
 - For standard props (tree, crate, market_stall, ...), PREFER a bare `alias model.<noun>` (see <asset_aliases>): it binds a matching generated mesh from the library at load, or background-generates one.
 - Authoring or editing a `#mesh` body: read the `mesh_dsl` skill first — full language + builtin reference and the preview workflow. Do not guess builtin names or signatures from memory; unknown, duplicate, or wrong-type arguments fail loudly.
+- Lights on meshes: an `emitter("Bulb", at:, color:, intensity:, kind: "point"|"spot", ...)` line in the mesh body bakes a light socket; every placed instance shines from it (lamps, signs, projectors) - no separate light object needed. Syntax in the `mesh_dsl` skill; per-object toggle `Object.SetEmitterLightsEnabled(false)`.
+- Effects on meshes: `particles("<effect word>", at: (x,y,z)[, axis:, scale:])` in the mesh body embeds a particle effect the way `emitter()` embeds a light - mesh-local, riding every instance/rotation/saved object. The word must be a quoted literal and resolves like `effect.<word>` (local `#particles` block name, case-sensitive, or lowercase library word). Rest-pose like emitter(); prefer loops (fire, smoke, drips). For prop-attached fire/smoke prefer this over hand-placed effect objects.
 - Material slots: `material: "Name"` on generators or `paint(g, material: "Name")`. A slot name resolves to world `material.Name` when it exists (pair slots with `#texture Name` for low-poly color-blocking). Precedence: object/batch material override > explicit submesh override > authored local slot material > intrinsic GLB PBR.
-- Canonical slot names auto-fill from the built-in material library when the world doesn't declare them (library meshes only use these): Wood, WoodDark, Plank, Bark, Stone, Rock, Brick, Dirt, Sand, Metal, MetalDark, Gold, Fabric, Cloth, Rope, Straw, Leather, Foliage, Leaf, Grass, Snow, Ceramic, Bone, Glass, GlassTransparent, Water, Default. Recolor one via a derived material, e.g. `material Wood { base = "WoodDetail" tint = "#8a2b1e" }` (see <texture_dsl_usage>).
+- Canonical slot names auto-fill from the built-in material library when the world doesn't declare them (library meshes only use these; name list in <texture_dsl_usage>). Recolor one for every library mesh by declaring it, e.g. `material Wood { base = "WoodDetail" tint = "#8a2b1e" }`.
 - GlassTransparent is the real translucent glass (fresnel reflection + grime; casts no shadow) - only for panes with real geometry behind them (balustrades, canopies, display cases), NOT hollow building window walls (blend reveals the empty shell; use `interior_window_pbr`, next clause). Derive tints in one line - `material PoolGlass { base = "GlassTransparent" tint = "#3A7E8C" }` - and override `opacity = 0..1` (transmission) / `glassRoughness = 0..1` (reflection blur) only to tune.
-- Hollow building window walls (where GlassTransparent would expose the empty shell): `material TowerWin { base = "InteriorRooms" shader = "interior_window_pbr" tint = "#D8CFC0" glassTint = "#3A4E4A" }` - opaque fake-parallax rooms, night-lit cells automatic. `tint` = mullions; `roomW/roomH/roomDepth/bayW` m override 4.41/3.3/4.0/1.47.
+- Hollow building window walls (where GlassTransparent would expose the empty shell): `material TowerWin { base = "InteriorRooms" shader = "interior_window_pbr" tint = "#D8CFC0" glassTint = "#3A4E4A" }` - opaque fake-parallax rooms, night-lit cells automatic. Base picks the interior per building: `"InteriorRooms"` homes, `"InteriorOffice"` workplaces. Homes get side drapes by default (`drapeSides` = per-side width 0..0.35, 0 disables; offices default 0). `tint` = mullions; `roomW/roomH/roomDepth/bayW` m override 4.41/3.3/4.0/1.47 - repeat PITCHES of the fake-room grid (set to the real floor/bay pitch), not opening sizes; `roomOffsetX/roomOffsetZ` m shift the grid datum (default 0).
 </mesh_dsl_usage>
 
 <tree_dsl_usage>
 - `#tree Name ... #end` (top-level): procedural tree species `tree.Name` for scene objects (`model = "tree.Name"`). Deterministic: trunk + branches become the sim collider; the renderer adds detail, leaf cards, LODs, impostors, and wind sway automatically.
-- Body is integer-only `key: value` lines (all optional; defaults are a curated broadleaf oak, so `seed:` alone gives a good tree). Keys: seed, levels (1-4), children (1-16), rings (whorl only: 0-40 branch rings along the trunk, decoupled from segments; 0 = one per segment - reference firs want ~15-20; members auto-stagger vertically), fill (whorl only: 0-16 short branches between rings - dense conifers), segments (2-8), collider_levels (dense conifers should author 1 - collide with the trunk, not hundreds of branchlets), trunk_height (cm), trunk_radius (cm), length_pct, radius_pct, angle_deg (child pitch from the parent axis; >90 emits below horizontal - with up_bias_pct the branch swoops down then up, the fir/spruce shelf), angle_jitter_deg, up_bias_pct, curve_jitter_pct, trunk_lean_deg (whole-trunk tilt, default 2; the trunk-shape low band), trunk_sweep_pct (one C- or S-arc over the trunk height, default 10; the mid band), trunk_noise_pct (trunk wobble amplitude; 0 = dead-straight leader with curve_jitter_pct branches) + trunk_noise_scale_pct (its wavelength as % of trunk height, 8-100, default 35; small = ragged bark-beat, large = slow bends - the high band), trunk_gnarl_pct (0-100; display-only radial lobe noise on the thick lower trunk - buttress/character silhouette for hero close-ups; collider stays smooth), leaves (frond stations per end branch), leaf_size (cm; mean size of one leaf-cluster card - each card is a baked spray of many leaves, not a single leaf; default 150), leaf_base (cm; no leaf cards below this height - bare forks/scaffolds; leaf_base_fade cm band above it ramps density to full, default 120), leaf_shell_pct (0-100; blend toward smooth per-pixel crown-shell shading - 0 = flat per-card facing, 100 = crown shades as a smooth rounded volume; default 100), leaf_clump_pct (0-100; shifts that shell reference from the whole-crown center toward each level-1 branch clump's own center, so big canopies shade as separate puffy lobes instead of one ball; default 40), leaf_detail_pct (0-300; leafy normal-detail sparkle bumped from the frond texture itself; 0 = smooth shell only; default 200), leaf_ao_pct (0-200; canopy AO strength darkening cards near the trunk column and canopy bottom; 0 = off; default 40), leaf_curl_pct (0-300; how strongly leaf cards bow out of their plane for varied, non-flat silhouettes; 0 = flat cards; default 150), leaf_far_shade_pct (0-150; far-billboard brightness; billboards lose cast shadows so <100 darkens them to match the near tree; default 60), droop_pct (tips sag), length_taper_pct (shorter branches higher up; ~70 = conifer cone), root_flare_pct (wider trunk base).
+- Body is integer-only `key: value` lines (all optional; defaults are a curated broadleaf oak, so `seed:` alone gives a good tree). Keys: seed, levels (1-4), children (1-16), rings (whorl only: 0-40 branch rings along the trunk, decoupled from segments; 0 = one per segment - reference firs want ~15-20; members auto-stagger vertically), fill (whorl only: 0-16 short branches between rings - dense conifers), segments (2-8), collider_levels (dense conifers should author 1 - collide with the trunk, not hundreds of branchlets), trunk_height (cm), trunk_radius (cm), length_pct, radius_pct, angle_deg (child pitch from the parent axis; >90 emits below horizontal - with up_bias_pct the branch swoops down then up, the fir/spruce shelf), angle_jitter_deg, up_bias_pct, curve_jitter_pct, trunk_lean_deg (whole-trunk tilt, default 2; the trunk-shape low band), trunk_sweep_pct (one C- or S-arc over the trunk height, default 10; the mid band), trunk_noise_pct (trunk wobble amplitude; 0 = dead-straight leader with curve_jitter_pct branches) + trunk_noise_scale_pct (its wavelength as % of trunk height, 8-100, default 35; small = ragged bark-beat, large = slow bends - the high band), trunk_gnarl_pct (0-100; display-only radial lobe noise on the thick lower trunk - buttress/character silhouette for hero close-ups; collider stays smooth), leaves (frond stations per end branch), leaf_size (cm; mean size of one leaf-cluster card - each card is a baked spray of many leaves, not a single leaf; default 150), leaf_base (cm; no leaf cards below this height - bare forks/scaffolds; leaf_base_fade cm band above it ramps density to full, default 120), leaf_shell_pct (0-100; blend toward smooth per-pixel crown-shell shading - 0 = flat per-card facing, 100 = crown shades as a smooth rounded volume; default 100), leaf_clump_pct (0-100; shifts that shell reference from the whole-crown center toward each level-1 branch clump's own center, so big canopies shade as separate puffy lobes instead of one ball; default 40), leaf_detail_pct (0-300; leafy normal-detail sparkle bumped from the frond texture itself; 0 = smooth shell only; default 200), leaf_ao_pct (0-200; canopy AO strength darkening cards near the trunk column and canopy bottom; 0 = off; default 40), leaf_curl_pct (0-300; how strongly leaf cards bow out of their plane for varied, non-flat silhouettes; 0 = flat cards; default 150), leaf_far_shade_pct (0-150; far-billboard brightness; billboards lose cast shadows so <100 darkens them to match the near tree; default 60), droop_pct (tips sag), length_taper_pct (shorter branches higher up; ~70 = conifer cone), root_flare_pct (wider trunk base), wind_pct (0-300; sway response to the global wind - trunk, branches and leaf cards; 0 = rigid, default 100).
 - Word keys: `mode: spiral|whorl|colonize` (whorl = rings of branches off a straight central leader - the pine/fir/spruce mode; colonize = space-colonization crown grown to fill a shape), `crown_shape: round|cone|vase` (colonize only), `leaf_mode: broadleaf|needle|weeping|mat|frond` (foliage style; weeping = hanging strand curtain, pair with high droop_pct for willows; frond = one whole-branch ribbon card per branch replacing the branch wood - THE fir/spruce mode, pair with mode: whorl and angle_deg ~95-115; mat = scattered flat shelf mats, a lighter conifer fill).
 - Colonize-only integer keys: points (crown attraction point count; auto-scales with crown size up to 1024, override for extra fine/coarse branching), leader (0-100: how far up the crown the central trunk persists before dissolving into forks - 0 = open broadleaf habit, oaks/beeches fork early; ~50-70 = beech/maple with a trunk partway into the crown; 100 = excurrent conifer/poplar spire), crown_width (cm, 0 = auto), crown_base (crown bottom height cm, 0 = auto; whorl mode also honors it as the lowest branch ring - ground-sweeping firs author ~150), crown_follow_pct (0-100, default 75: how much the crown envelope rides a leaning/swept trunk's top - 100 = crown centered on the bole, 0 = crown stays over the root and limbs reach back, the "leaning toward a clearing" habit).
 - Colonize authored crown shapes: `crown_sphere: x, y, z, r` / `crown_ellipsoid: x, y, z, rx, ry, rz` / `crown_dome: x, y, z_cut, rx, ry, rise` lines (cm, up to 8) grow branches to fill the union of those volumes, overriding crown_shape/crown_width/crown_base. A dome is the upper half of an ellipsoid with a flat cut at z_cut (umbrella/mushroom caps). Keep volumes near/above the trunk; disconnected lobes get bridged by a reaching branch. Colonize branches stay inside their envelope, so droop_pct barely bends them - weeping/cascading silhouettes (willows) need mode: spiral with high droop_pct instead.
 - Authored trunk path (any mode): `trunk_point: x, y, z` lines (cm, up to 8, z strictly ascending) draw the trunk's xy course as a smooth spline through the knots, replacing trunk_lean_deg/trunk_sweep_pct (trunk_noise still layers on top). Above the top knot the offset holds, so put the top knot at trunk_height (or crown_base) for a fully drawn bole; pair with crown volumes + crown_follow_pct 100 for a hero leaning tree. Note: trees in a #forest keep a straight vertical collision capsule - keep heavy lean/sweep/trunk_point species out of forests or accept coarse trunk collision there.
-- Optional `#texture TreeLeaf_<Name> ... #end` (with `mapping = uv;`, `render_mode = cutout;` + `out.alpha`) replaces the auto-generated leaf frond card. `mapping = uv;` is required - cards are UV quads; the triplanar default renders them invisible. Author the card as a spray of MANY leaves via `sdf.pinnate` (thin leaflets for needle/frond conifers) or `pattern.foliage`, never one big leaf. Cluster cards consume only color+alpha; authored `out.normal`/`out.orm` matter only for `leaf_mode: frond` ribbon cards.
-- Optional `#texture TreeBark ... #end` (or `material TreeBark { ... }`) replaces the built-in bark material shared by all tree species.
-- Global wind: `SetWind(DirectionDeg, Strength01, Gustiness01)`.
+- Leaf card: `leaf: <TextureName>` body key (or naming the texture `TreeLeaf_<Name>`) replaces the auto-generated frond card; the texture needs `mapping = uv;`, `render_mode = cutout;` + `out.alpha`. `mapping = uv;` is required - cards are UV quads; the triplanar default renders them invisible (unknown or non-uv `leaf:` refs = load error). Author the card as a spray of MANY leaves via `sdf.pinnate` (thin leaflets for needle/frond conifers) or `pattern.foliage`, never one big leaf, with the stem at the bottom edge (v=0) - the card's base sits on the branch. Cluster cards consume only color+alpha; authored `out.normal`/`out.orm` matter only for `leaf_mode: frond` ribbon cards.
+- Bark: `bark: <TextureOrMaterialName>` body key per species (unknown name = load error); bare `TreeBark` (#texture or material) is the shared default for species without one (else built-in bark). Cheap per-species tint: `material PineBark { base = "TreeBark" tint = "#5a4630" }` + `bark: PineBark`.
+- Global wind: `SetWind(DirectionDeg, Strength01, Gustiness01)`; per-species response: `wind_pct`.
 - Authored integer keys expose editor adjuster-panel sliders (live rebake; the sim collider updates on save) - author the look-defining ones. When the look matters, iterate with the `preview_tree` tool before submitting.
 Species recipes: see <example_tree_species> in <world_description_examples>.
 </tree_dsl_usage>
 
 <forest_dsl_usage>
-- `#forest Name ... #end` (top-level): scatters a `#tree` species over an object's box region (`model = "forest.Name"`; set the object's `size` (cm) to shape the region, default 20x20x10 m). Each tree stands on the terrain surface under its XY; where that surface lies outside the region's z-span the tree is skipped, so the z-span doubles as an elevation band (e.g. bottom above the waterline = no beach/underwater trees, top below the peaks = a tree line). An XY with no terrain under it is skipped too when the world has terrain (a region overhanging the terrain edge grows no drowned/floating trees); only fully terrain-less worlds anchor on the box bottom (flat-ground worlds just work; deliberate floating platforms use on_terrain: 0). Placements stay stable when the region is resized/moved. THE way to put woods on terrain - one region object, no spawn loops.
+- `#forest Name ... #end` (top-level): scatters a `#tree` species over an object's box region (`model = "forest.Name"`; set the object's `size` (cm) to shape the region, default 20x20x10 m; the region object is bottom-anchored like any object - z-span = [position.z, position.z + size.z]). Each tree stands on the terrain surface under its XY; where that surface lies outside the region's z-span the tree is skipped, so the z-span doubles as an elevation band (e.g. bottom above the waterline = no beach/underwater trees, top below the peaks = a tree line). An XY with no terrain under it is skipped too when the world has terrain (a region overhanging the terrain edge grows no drowned/floating trees); only fully terrain-less worlds anchor on the box bottom (flat-ground worlds just work; deliberate floating platforms use on_terrain: 0). Placements stay stable when the region is resized/moved. THE way to put woods on terrain - one region object, no spawn loops.
 - Body is `key: value` lines. `species: <TreeName>` (required, a `#tree` in this world); optional integers: seed, spacing (cm cell size, >= 100, default 700), density_pct (0-100 chance per cell), scale_min_pct / scale_max_pct (per-tree size range, default 85-125), on_terrain (default 1; 0 = always stand on the box bottom, e.g. floating platform forests).
 - Terrain filters (the precise control; the z-span is the coarse bracket): height_min_cm / height_max_cm keep trees inside a world-z band at their terrain anchor (waterline, tree line); slope_max_pct (0-100 on the #terrain_splat slope01 scale: 50 = 45deg, 35 ~ 30deg) skips steeper ground (no cliff trees). Filters gate terrain-anchored trees only and require on_terrain: 1. Prefer one big region + filters over hand-fitted boxes.
 - Collision is per trunk only (a vertical capsule from the species' trunk), never the region box - players walk between trees and brush through leaves.
@@ -163,6 +185,21 @@ Example:
 object Woods1 { model = "forest.PineWoods" position = (0, 0, 500) size = (12000, 8000, 1000) }
 </forest_dsl_usage>
 
+<scatter_dsl_usage>
+- `#scatter Name ... #end` (top-level): scatters ANY model over an object's box region (`model = "scatter.Name"`), exactly like `#forest` placement-wise (same region object, terrain anchoring, z-span band, filters) but display-only: NO collision, plus per-instance color variation. Use for rocks, bushes, props, debris; use `#forest` when trees should collide.
+- Body: `model: <url>` (required; `mesh.<Name>`, `Ori.model.*`, or a market model url) + the `#forest` keys minus `species`; optional integers hue_jitter_deg (0-180), sat_jitter_pct / val_jitter_pct (0-100) tint each instance (multiplies the region object's color; a tint on textured models, not true hue rotation).
+Example:
+#scatter Boulders
+  model: "mesh.Rock"
+  spacing: 900
+  density_pct: 40
+  scale_min_pct: 60
+  scale_max_pct: 160
+  hue_jitter_deg: 12
+#end
+object RockField { model = "scatter.Boulders" position = (0, 0, 500) size = (12000, 8000, 1000) }
+</scatter_dsl_usage>
+
 <room_building>
 - For simple rectangular rooms, prefer `BuildRoom(Center, RoomSize, Thickness, Height, GateSide, GateWidth)` instead of hand-placing wall boxes. It creates clean aligned walls and avoids crooked wall edges/gaps.
 - `Center` is the room center position. `RoomSize` is the INNER clear size in cm. Walls sit just outside that footprint, with bottoms at `Center.Z` and height `Height`.
@@ -196,13 +233,22 @@ event OnSpawned {
 - `TileGridCreate(TilesX, TilesY, DefaultWalkable)` returns an opaque compact List. `TileGridCreate(TilesX, TilesY, DefaultWalkable, EdgeBlockingEnabled)` enables optional edge-wall storage when the Bool is true. Do not call generic mutating List functions (`Add`, `Set`, `Resize`, `Clear`, `Pop`, etc.) on it; use TileGrid helpers. Padded grid capacity is capped at 1,048,576 tiles.
 - Edge-blocking grids can use `TileGridSetEdgeBlocked(Grid, X1, Y1, X2, Y2, Blocked)` for cardinal-adjacent tile pairs. Compact grids reject SetEdgeBlocked; `TileGridIsEdgeBlocked(...)` returns false for valid compact-grid edges. Edge-enabled diagonal pathfinding does not cross blocked cardinal edges, and a diagonal step requires all four cardinal edges around the crossed 2x2 tile corner to be clear.
 - `BuildTileBlockedGridFromTag(OriginTile, TilesX, TilesY, BlockerTag)` creates a walkable grid and blocks tiles whose world-center point overlaps an object with the tag. Build/rebuild grids when blockers change, not every frame.
-- `TileGridSetWalkableFromStaticColliders(Grid, OriginTile, ZMin, ZMax)` re-rasterizes an existing non-layered grid from the static world colliders: every tile resets, and a tile blocks when any static collider's world AABB overlaps its rect within the [ZMin, ZMax] cm band (rotated colliders use their conservative AABB; colliders covering the whole grid footprint - floors, world bounds - are ignored). Keep ZMin above the walk surface (e.g. 20) so partial floor slabs don't block their tiles. Call once after building/editing static geometry - walls and crates then block FindPath without hand-authored SetWalkable loops; re-call after edits.
-- `TileGridFindPath4/8(Grid, StartX, StartY, GoalX, GoalY)` returns a reversed path List: Goal ... Start. Empty means blocked start/goal, out of bounds, or no path. Compact TileGridFindPath8 preserves corner cutting through unwalkable side tiles; edge-enabled grids still require crossed cardinal edges to be clear.
+- `TileGridSetWalkableFromStaticColliders(Grid, OriginTile, ZMin, ZMax)` re-rasterizes an existing grid from the static colliders: every tile resets, and a tile blocks when any static collider's world AABB overlaps its rect within the [ZMin, ZMax] cm band (rotated colliders use their conservative AABB; colliders covering the whole grid footprint - floors, world bounds - are ignored). Static world objects, static PhysicsObjects, and tilemap solid cells all block; keep ZMin above the walk surface AND above any solid ground tilemap's top (e.g. 20) so floor slabs don't block their tiles. Layered grids rasterize per layer ([ZMin, ZMax] relative to each layer plane). It RESETS every tile - call it BEFORE the FromTerrain pair; for runtime placements stamp instead of re-rastering.
+- `TileGridSetWalkableFromTerrain(Grid, OriginTile, MaxSlope01)` marks tiles UNWALKABLE where the topmost terrain at the tile center is steeper than MaxSlope01 (slope01 = g/(1+g); 0.5 = 45deg; walkers wedge above ~0.5, so 0.4-0.45 is a safe unit ceiling) or absent. Subtractive only - never re-opens tiles.
+- `TileGridSetEdgesFromTerrain(Grid, OriginTile, MaxStepCm)` (edge-blocking grids) blocks the edge between cardinal neighbors whose terrain height difference exceeds MaxStepCm: cliffs become impassable EDGES while rim tiles stay standable; graded ramps (small per-tile rise) stay open. Tile centers sample mid-cell, so a hard TierCm cliff reads as two TierCm/2 steps - MaxStepCm = TierCm/3 separates cliff jumps from ramp rise; size ramps >= 2 tiles of run per tier step so their slope stays below the ~45deg walk limit.
+- Cliff-map load order (manager OnSpawned): collider raster -> FromTerrain -> EdgesFromTerrain -> BakeCrowdObstacles -> IsReachable asserts. Then placements only stamp.
+- `TileGridStampRect(Grid, X1, Y1, X2, Y2, Blocked)` / `TileGridStampObject(Grid, OriginTile, Obj, Blocked)` stamp footprints incrementally (rect corners clamp to the grid; spawn: true, despawn: false re-opens the stamped rect - overlapping footprints must re-stamp their survivors) - cheaper than re-rastering after each placement.
+- `TileGridIsReachable(Grid, X1, Y1, X2, Y2)` (layered: 7-arg form) = "does an 8-dir path exist" without building one - assert connectivity (spawn points, ramps) in a manager OnSpawned with `RaiseWorldError` so broken maps fail at load, not mid-game; also check before wall placements that could seal a region.
+- `TileGridBakeCrowdObstacles(Grid, OriginTile)` bakes avoidance line obstacles from the grid's blocked edges and unwalkable borders so crowd units are never pushed off cliffs or into tilemap walls avoidance cannot see. It is a snapshot: re-bake after runtime walkability edits (opened gates, razed bridges); placed buildings already repel via their own colliders, no re-bake needed.
+- One grid, many movers (RTS): build the grid ONCE on a manager scene object (`var Grid: List<Number>` field; `TileGridCreate` + `TileGridSetWalkableFromStaticColliders` in its OnSpawned) and let every unit reach it through a scene cast - `TileGridFindPath8((Scene.Manager as HQ).Grid, ...)`. Cross-class field access works for List fields; never rebuild the grid per unit.
+- `TileGridFindPath4/8(Grid, StartX, StartY, GoalX, GoalY[, GoalToleranceTiles])` returns a reversed path List: Goal ... Start. Empty means blocked start/goal, out of bounds, or no path (a TRUE verdict - the search budget covers the whole grid, so a no-path query floods the goal's component; on big maps gate mass orders with one TileGridIsReachable, share flow fields, and cache no-path results). GoalToleranceTiles (0-16) accepts the cheapest walkable tile within that ring of the goal - set it when ordering onto colliders (buildings, resource nodes); empty then means the ring itself is unreachable. Compact TileGridFindPath8 preserves corner cutting through unwalkable side tiles; edge-enabled grids still require crossed cardinal edges to be clear.
 - `TileGridHasLineOfSight(Grid, StartX, StartY, GoalX, GoalY)` (layered: 7-arg form, same Z only) returns true when the straight tile-center corridor is fully walkable (crossed edges clear on edge grids; exact corner crossings also need both side tiles). Chasing a moving target: LOS true -> `MoveTowardContinuous` at the live position, false -> FindPath + follow.
 - `TileGridSmoothPath(Grid, Path)` returns a new reversed path with waypoints dropped wherever the straight corridor between the survivors is clear (string pulling; never smooths across a layer change). Walkers zigzagging tile centers -> smooth once after FindPath, before following.
-- To follow a path, call `MoveAlongTilePathContinuous(Path, Grid, OriginTile, Speed)` each frame: one call steps the mover, pops reached waypoints, and returns true once the path is consumed (false for an already-empty path). Prefer it over manual MoveToward + Pop loops; it is one sim call per mover per frame.
+- To follow a path, call `MoveAlongTilePathContinuous(Path, Grid, OriginTile, Speed[, ArriveWithinCm[, OrientTurnRate]])` each frame: one call steps the mover, pops reached waypoints, and returns true once the path is consumed (false for an already-empty path). ArriveWithinCm (default 1) completes the FINAL waypoint within that distance - set it when the goal can be occupied (resource node, building) so contact does not stall arrival. OrientTurnRate faces the mover along its travel (deg/s; 0 = instant) - RTS vehicles read wrong without it. Prefer it over manual MoveToward + Pop loops; it is one sim call per mover per frame.
+- Mover frozen after an early order switch: a half-consumed path re-followed later pushes at a stale waypoint - Clear() the path list whenever you leave a follow before it returns true.
 - For CROWDS (Weave2, hundreds+ of movers): `obj.StartTilePathFollow(Path, Grid, OriginTile, Speed)` registers the mover with the native segment follower (same movement semantics, zero per-mover calls while walking; returns false for an empty path). Start CONSUMES the path list (it is empty afterwards - the follower owns a copy); sim-visible mover positions update at waypoint granularity while walking. One manager then drains `TilePathFollowTakeArrivals()` once per frame (returns finished movers as `List<Object>`) to run arrival logic. `obj.StopTilePathFollow()` cancels; `obj.IsTilePathFollowDone()` polls instead of draining (an arrival stays set until taken/stopped/restarted). Starting again replaces the previous follow.
-- Layered grids (bridges/multi-floor): `TileGridCreate3D(TilesX, TilesY, Layers, DefaultWalkable)`; each layer is an independent walkable plane at OriginTile.z + Z. `TileGridSetWalkable/IsWalkable(Grid, X, Y, Z, ...)`, `TileGridSetLinkUp(Grid, X, Y, Z, Linked)` marks a stair cell connecting Z and Z+1 (both ends must also be walkable), `TileGridFindPath4/8(Grid, StartX, StartY, StartZ, GoalX, GoalY, GoalZ)`. On layered grids MoveAlongTilePathContinuous drives Z too (object bottom rests on the layer plane). No edge blocking on layered grids.
+- For MANY movers sharing ONE destination set (group move / rally / harvest points): `TileGridFlowFieldBuild(Grid, GoalTiles)` bakes per-tile direction toward the nearest goal into a reusable opaque List (GoalTiles = flat X,Y,Z coordinate triples; unwalkable goal tiles are skipped; every goal blocked -> all-unreachable field). `obj.StartTileFlowFollow(Field, Grid, OriginTile, Speed)` walks it with the same native follower - the lists stay CALLER-OWNED, one field serves any number of movers; returns false when the mover's tile is off-grid or unreachable in the field. Fields are build-once snapshots: after `TileGridSetWalkable` edits affected movers HALT and surface in `TilePathFollowTakeBlocked()` (drains like TakeArrivals) - rebuild the field and restart them. TakeArrivals/Stop/IsDone work as for path follows.
+- Layered grids (bridges/multi-floor): `TileGridCreate3D(TilesX, TilesY, Layers, DefaultWalkable)`; each layer is an independent walkable plane at OriginTile.z + Z. `TileGridSetWalkable/TileGridIsWalkable(Grid, X, Y, Z, ...)`, `TileGridSetLinkUp(Grid, X, Y, Z, Linked)` marks a stair cell connecting Z and Z+1 (both ends must also be walkable), `TileGridFindPath4/8(Grid, StartX, StartY, StartZ, GoalX, GoalY, GoalZ)`. On layered grids MoveAlongTilePathContinuous drives Z too (object bottom rests on the layer plane). No edge blocking on layered grids.
 </tile_pathfinding>
 
 <exported_params_v1>
@@ -218,7 +264,7 @@ event OnSpawned {
 - `@exportRange(...)` implies export
 - `@exportColor` implies export
 - local `var`, `let`, and other types are not supported in v1
-- exported params appear in the editor AI chat tune drawer when exactly one object with those vars is selected
+- exported params appear in the editor AI Feed tune drawer when exactly one object with those vars is selected
 - for live tuning in the editor, apply exported values inside `event OnTuneChanged { ... }`
 - common pattern: initialize once in `OnPreSpawn`/`OnSpawned`, then mirror the same property updates in `OnTuneChanged`
 - user keeps nudging one number per message (offset/size/speed/color) -> declare it `@exportRange`, ask them to drag the slider, then bake the settled value back into the source instead of resubmitting per nudge
@@ -234,6 +280,17 @@ event OnTuneChanged {
 #end
 </exported_params_v1>
 
+<persistent_state_v1>
+- `@persist var Name = ...` (class-scope top-level var): value survives save/load and world reload
+- supported types: Number, Bool, Text, Vector, Position (others are a compile error)
+- scene objects rehydrate by object name; a standalone `@persistSpawned` line inside a class also recreates its runtime-spawned instances (saved template + position/rotation/size + tagged vars); crowd instances and multi-object templates are not recreated
+- class edits migrate loudly: removed/retyped tagged vars are dropped and reported; new tagged vars start at their defaults
+- a destroyed scene object reappears on load; persist a `@persist var Opened` style flag and react in OnSpawned
+- saving is automatic per project; there is nothing to call
+- PersistClear() wipes the project's saved state (pair with RestartGame() for a New Game button)
+- prefer @persist over PersistGet/SetNumber for object state; the KV remains for per-player counters
+</persistent_state_v1>
+
 <multiplayer_guidance>
 - Core model: multiplayer is deterministic lockstep with client prediction/rollback, NOT object replication.
   - All weave code, scene objects, and sim state run identically on every client/server (same world + inputs => same result; verifiable on-chain).
@@ -257,16 +314,22 @@ event OnTuneChanged {
 - Validation/simulate auto-joins a second mock player a few frames in when these per-player APIs are referenced, so per-player join/visibility/index logic is actually exercised.
 - Players/teams:
   - SetPlayerOwnerIndex/GetPlayerOwnerIndex, SetRenderVisibleOnlyToPlayerIndex/SetRenderVisibleToAllPlayers, SetTeam/GetTeam
+  - Scene field: `object X { team = 0 }` assigns the spawn team (same values as SetTeam; omit for teamless).
+  - Fog of war: SetFogOfWarEnabled(true) (needs terrain) then SetSightRadius on teamed objects - per-team grid; shroud, explored-memory, enemy-object hiding, and pick-through are built in (no per-object SetRenderVisible needed).
   - Iterate via GetAllPlayers()/GetAllPlayersWithTag(..) (existing players only, no None entries).
+  - A player who leaves stays in GetAllPlayers() for ~90s (reconnect window) before OnDestroy: gate rosters/win checks on p.IsConnected(), not Exists(), and react to the drop in `event OnPlayerLeft` / to a grace resume in `event OnPlayerReconnected` (both fire on that player's object). Bots are always connected.
+  - p.GetPlayerName() = the user's display name (not unique - key logic by player object/index, not name). The engine draws it above visible remote players (SetPlayerNamesVisible(false) hides that); obj.SetHoverText(text) puts a persistent label above any other body (hero units, NPCs).
   - Never assume a fixed player count or index order (players join/leave).
 - Determinism caveats:
   - Time is sim-time and pause-aware: TimeSecs/TimeTicks freeze on pause and may reset on world reset, so capture your own baseline (StartTime=TimeSecs()); RawTimeSecs/RawTimeTicks is unfrozen raw time.
-  - RandomNumber/RandomPosition* are deterministic (seeded per tick + calling object + call index, so repeated or cross-object same-tick calls draw fresh values); inside player input events (key/mouse/action) all Random* calls are seeded by that input edge instead, so the predicted result matches the final one. RandomChancePercent outside input events returns false during client prediction, so there use it only for delay-tolerant side effects (e.g. drops), not moment-to-moment combat.
+  - RandomNumber/RandomPosition* are deterministic (seeded per tick + calling object + call index, so repeated or cross-object same-tick calls draw fresh values); inside player input events (key/mouse/action) all Random* calls are seeded by that input edge instead, so the predicted result matches the final one. RandomChancePercent outside input events returns false during client prediction, so there use it only for delay-tolerant side effects (e.g. drops), not moment-to-moment combat. A fresh load always starts at the same tick, so the FIRST draws repeat across sessions (identical opening deck/magazine every load) — mix a per-session value (e.g. TimeTicks() at game start) into anything that must differ between sessions.
   - Don't rely on cross-object event ordering (OnSpawned order across objects is unspecified).
-- Lobby/session APIs:
-  - AdvertiseLobbySession()/ListLobbySessions()/JoinLobbySession are relay lobby discovery for menus; identity is automatic - sessions match only peers running this project with identical content (same saved version). LobbySessionStage(i) says which stage each session is on.
-  - They do NOT create gameplay replication endpoints or change sim authority; once joined, the same shared deterministic simulation model applies.
-  - Lobby UI lists real joined players via GetAllPlayers(); never simulate joins with a local counter/button.
+- Session APIs (for CUSTOM in-game browsers only - the engine ships a built-in session browser + share/visibility panel for every project; most games need no session code):
+  - AdvertiseSession()/StopAdvertisingSession() toggle whether this session is listed in the project's public session list (same switch the host's engine panel sets; last write wins; play-mode entries auto-list - a game that wants private sessions calls StopAdvertisingSession()). Unlisted sessions stay joinable via share link.
+  - ListSessions()/JoinSession are relay session discovery; identity is automatic - listings match peers running this project with identical content (same saved version). SessionStage(i)/SessionPlayerCount(i) describe each listed session.
+  - OpenSessionBrowser() opens the built-in browser from a game menu.
+  - These do NOT create replication endpoints or change sim authority; once joined, the same shared deterministic sim applies.
+  - Session UI lists real joined players via GetAllPlayers(); never simulate joins with a local counter/button.
 - AI players (bots): var bot = SpawnAIPlayer("Rival") spawns a real PlayerObject: '#class player' code + OnSpawned run for it, it appears in GetAllPlayers(), has physics/animations, but no user/camera/UI. The Name arg becomes the bot's object name and its GetPlayerName().
   - Drive it from script: bot.SetAIMoveVector(dir) (held stick, persists until changed) and bot.PressAIAction(Action.Jump) (tap; Down next frame, auto-release after). The bot's own ...ByThisPlayer input reads and Action events then behave as if a user pressed them.
   - bot.IsAIPlayer() distinguishes bots; bot.DespawnAIPlayer() (or bot.Destroy()) removes them. Keyboard/mouse reads (IsKeyPressedByThisPlayer, GetMouseTarget*) return false/none for bots.
@@ -404,14 +467,18 @@ event OnSpawned {
 
 <object_types>
 - WorldObject: Game's objects, start off with static/CanCollide physics
+  - Scene `position = (x, y, z)` places the object's PIVOT; primitives and library meshes pivot at their base, so z is the bottom (like position_tiles). Effect objects render their authored local origin at `position`.
 - PlayerObject: Object representing player
 - RegionObject: Used in weave for detecting object overlap etc. cannot be seen in play-mode, cannot collide, or click
 - PhysicsObject: like WorldObject, but starts as dynamic/CanCollide physics
 - CrowdObject: Useful as creatures/walkable-NPCs. like WorldObject, but starts with crowd collision avoidance
-  - it automatically avoids objects with CanCollide; no extra setup call is needed
+  - it steers around other crowd agents and obstacles it approaches at an angle; a blocker dead-ahead STOPS it (avoidance is anti-collision, not pathfinding) - route around structures with tile pathfinding
+  - RTS units: route with `MoveAlongTilePathContinuous` on a `crowd` receiver - the path sets the preferred velocity and avoidance shapes it every frame (global path + local separation). The zero-call `StartTilePathFollow` is waypoint-granular, so avoidance cannot shape it mid-segment - use it for overlap-tolerant swarms instead. Terrain cliffs and tilemap walls are invisible to avoidance until `TileGridBakeCrowdObstacles` bakes them from the nav grid.
   - Avoidance scope: XY-plane only; Z/height is ignored.
+  - Gravity is ON at spawn; crowd bodies stand on static geometry, terrain, and tilemaps (not on dynamic objects). ClimbingCrowdObject remains the climb/stack-capable crowd.
   - For grid-based or fixed-lane games (e.g., Tower Defense), avoid using CrowdObject, as its built-in avoidance can cause objects to move off their intended path.
   - Prefer it over plain WorldObject for free-roaming monster swarms in top-down games.
+  - Bone/pose simcalls (SetBoneRotation family, SetUpperBodyAnimationWeight, SetRenderOffset) reject crowd instances - use a regular object for featured NPCs needing bone-level control.
 - ClimbingCrowdObject: like CrowdObject, but simulated by the deterministic "climbing crowd" step (lean crowd bodies)
   - Prefer it over plain WorldObject for player-chasing enemies in flat first-/third-person worlds.
   - Always seeks the nearest player in XY each tick; players are never pushed (climbers always yield)
@@ -419,13 +486,15 @@ event OnSpawned {
   - Terrain + static primitive obstacles; supports elevator-like climbing
   - Can climb/stack on other climbers; large swarms may pile into a single moving blob
 - DisplayObject: like WorldObject but visual-only — no collision, no interaction events (Touched, ClickThisObject, etc. will never fire), doesn’t respond to forces
+  - When a display shell forms a player-reachable structure (building, wall), add a static collision core or invisible collider proxy behind it — display-only geometry is walked through.
 - EffectObject: visual effects
-- PointLightObject: point light
-- DiffuseOnlyLightObject: diffuse-only local light with flat core fade shell
-- SpotLightObject: spot light
-- AreaLightObject: area light
-- DirectionalLightObject: the world sun (editor-placed); control it with the SetSun* simcalls, not the generic light setters
+- pointLight: local point light. `pointLight L { position = (0, 0, 150) radius = 500 intensity = 4 color = (1, 0.85, 0.6) }` - radius cm (default 100 = dim 1m pool); optional cast_shadow = true, light_diffuse_scale/light_specular_scale. For a bulb on a mesh prop, prefer an emitter(...) socket in the #mesh (see <mesh_dsl_usage>)
+- spotLight: cone along the object's +X facing (aim with rotation); pointLight keys plus cos_inner/cos_outer = cosine of the half-angle, not degrees (defaults 24deg/30deg)
+- diffuseOnlyLight: diffuse-only, flat core with fade_width (cm) fade shell; pointLight keys minus cast_shadow/light_specular_scale
+- areaLight: area light; pointLight keys minus cast_shadow
+- directionalLight: the world sun (editor-placed); control it with the SetSun* simcalls, not the generic light setters
 - PositionMarkerObject: position marker object useful as things like waypoints (easily manipulated by human visually in editor)
+- DecalObject: projected surface overlay re-writing color/normal/roughness on the geometry inside its oriented box (bullet holes, stains, scorch marks). Spawn at runtime with SpawnDecal(Material, Position, RotationEuler, Size); scene keyword `decal Name { material = "M" ... }`. Globals: SetAllDecalsEnabled, SetDecalCullingDistanceM, SetAssetSubmeshReceiveDecal
 </object_types>
 
 <variable_types>
@@ -437,9 +506,11 @@ event OnSpawned {
 - Vector — (X,Y,Z) direction/offset; also used for RGB triples.
 - Position — world point (X,Y,Z). Alias of Vector; implicit cast both ways.
 - List<T> — homogeneous typed list; T is Number | Bool | Text | Object | Vector | Position | Timer | a class name (e.g. 'var Waypoints: List<Position>', 'var Minions: List<Monster>'). In List.* signatures below, T is the element type.
-  - Class-scope 'var X: List<T>' needs no initializer; lists start empty.
+  - 'var X: List<T>' needs no initializer (class scope or local); lists start empty.
   - Bare 'var X: List' infers T from usage; annotate List<T> explicitly when inference reports conflicting evidence.
-  - No List<List<T>> and no non-empty literals ([1,2,3]): start empty then Add, or Resize(n, default).
+  - No List<List<T>>. Non-empty literals ([1,2,3]) are const-only: runtime lists start empty then Add, or Resize(n, default).
+  - Class-scope 'const Ids = [10, 20, 30]' (Number/Bool/Text/Vector elements, type inferred) bakes a read-only table into the program: Get/Count/Contains/for-each work, writes are runtime errors. Const tables have zero per-frame snapshot/hash cost — item/monster/config databases belong here, not in runtime lists filled row-by-row at startup.
+- Map<Number, T> — keyed store (T: Number | Bool | Text | Object): Set(K, V), Get(K) (missing key is a runtime error), GetOr(K, Default), Has(K), Remove(K)->Bool, Count(), IsEmpty(), Clear(). Keys compare exactly (no fractional truncation) — use integer keys. Replaces hand-rolled bucket/chain index lists for id -> row lookups (entity id -> row, structure id -> data).
   - Contains/IndexOf: List<Number|Bool|Vector|Position> and object lists only (not List<Text>/List<Timer>).
   - Sort()/SortDescending(): in-place numeric sort, List<Number> only.
   - List<struct>.SortByField("FieldName")/SortByFieldDescending: in-place sort of a record list by one of its Number fields (field name is a compile-checked string literal). Ties keep original order.
@@ -453,17 +524,19 @@ event OnSpawned {
     }
   - Fields: Number | Bool | Vector | Position | Object (plain or class-typed, e.g. 'var M: Monster' — member calls through class-typed fields are validated statically). Max 16 slots; Vector/Position count as 3, Object counts as 1. No Text/Timer/nested-struct fields yet. Object fields default to None (zeroed class-scope structs and Resize-grown list elements included).
   - Construct positionally with one arg per field: 'var S = Stat(100, Vector(1,0,0))'. Read/write fields ('S.Health += 1', 'S.Speed.X = 2') on locals, Self vars, and list elements ('Table.Get(i).Health = 5' writes back); copies are by value ('var C = S' snapshots), so fields on a function's returned struct need a var first.
-  - Class-scope 'var Stats: Stat' starts zeroed (no struct initializers there; fill in OnSpawned). Structs work as function params/returns.
+  - 'var Stats: Stat' without an initializer starts zeroed in any scope, Object fields None (no struct literals at class scope; fill in OnSpawned). Structs work as function params/returns.
   - List<struct> is supported ('var Table: List<Stat>') with Add/Get/Set/RemoveAt/Swap/Shuffle/Resize(count)/Count/IsEmpty/Clear + for-each; not Contains/IndexOf/Pop/Last/GetRandomElement or Resize with fill.
   - Lists cap at ~1M elements: an every-frame Add with no Clear/dedupe (e.g. selections, hit logs) reaches the cap in minutes of play and stops the world with CapacityExceeded - clear or bound accumulating lists.
   - No struct operators ('==' included) — compare fields; no scene-clause overrides.
 
 Rules:
 - The literal None is valid **only** for Object (e.g., 'var o:Object = None').
+- An annotated 'var' may omit its initializer in any scope and starts at the type default: 0 / false / "" / zero vector / None / done Timer / empty List / zeroed struct. Untyped locals still need '= value'.
+- 'const Name = <value>' (class scope or local) folds at compile time with zero snapshot cost; values that never change (tuning numbers, names, data tables) belong in const, not var.
 </variable_types>
 
 <tags>
-- Tag is like enum, and can be made up by user without any declaration (Tag.None reserved for empty tag).
+- Tag is like enum, and can be made up by user without any declaration. `Tag.None` is not writable in code; a Tag param always filters to that tag — there is no empty-tag value, so for an unfiltered query use the overload without a Tag param.
 - Use any made-up name (e.g. Tag.Monster) across classes; the same name resolves to the same tag everywhere.
 - Assign a tag directly in world description: object MySpawn { tag = Tag.Spawn }
 - AddTag/RemoveTag add and clear one tag; ClearTag() wipes all tags. Tag membership can be toggled at runtime (e.g. flag/unflag Tag.Burning) and HasTag/GetAllObjectsWithTag update immediately.
@@ -491,11 +564,13 @@ object test : MeleeEnemy { size = (70,70,100), override MaxHP = 100 }
 <world_description_information>
 - 1 world unit = 1 cm (centimeter)
 - Basic cube is 100x100x100 cm, sphere 100 cm diameter
-- Basic models: cube, sphere, cylinder, capsule, cone (apex +Z), wedge (slope rises toward +X)
+- Basic models: cube, sphere, cylinder, capsule (long axis +Z), cone (apex +Z), wedge (slope rises toward +X)
 - Object position is the BOTTOM center: the object rests its base at position.z (top = position.z + size.z). A ground slab with its top at z=0 is position = (0, 0, -H) size = (X, Y, H).
 - Object size is clamped per axis: 50,000 cm for solid objects, 100,000 cm display-only (10,000 cm dynamic). Meshes scale to object size, so oversized objects render SQUASHED — tile large ground/water/road geometry into pieces under the cap.
 - cone/wedge collide as boxes. Walkable ramp = rotated thin cube, e.g. size = (630, 300, 20) rotation = (0, -18, 0) rises toward +X
-- Marketplace/#mesh models also collide as their AABB box: a boat deck, bridge, or house interior is NOT walkable/enterable by default. Declare `collision = mesh` on the object clause (object Boat { model = "..." collision = mesh }) to collide against the model's actual geometry. Skinned/animated models keep the box.
+- Marketplace/#mesh models also collide as their AABB box: a boat deck, bridge, or house interior is NOT walkable/enterable by default, and interior furniture's box juts far past its real shape, blocking walkways. Declare `collision = mesh` on the object clause (object Boat { model = "..." collision = mesh }) to collide against the model's actual geometry — the right choice for enterable structures AND for furniture players move around. Skinned/animated models keep the box.
+- `collision = off` spawns the object with no collider: nothing blocks on it and Touched/Click never fire (detect pickups by distance) — for movers/markers that must not block. Purely decorative geometry is cheaper as a `display` clause.
+- Colliders are also the hit/UI anchor: Touched/Click/raycasts test the collider box, and hover bars/labels draw on the object they were set on. Size colliders to the visible model and set bars on the visible object, not a hidden collider proxy (symptoms: shots that visually touch but miss; bars floating beside the model).
 - Player is 40 cm diameter and 180 cm height, to fit inside a 100x100 cm sized tile with gap
 - Default player spawn: Origin() (0,0,0).
 - Calling an Object function without a caller implies 'Self.'
@@ -535,6 +610,7 @@ Applies to all physics types: Dynamic, Static, and Kinematic.
     - Dynamic objects have gravity on by default 
     - Dynamic bodies have no feel knobs (no bounciness/friction/mass calls): use them for incidental 3D physics - debris, tumbling props, knockback - where the exact trajectory doesn't matter. Don't use them for 2D-style games.
     - For gameplay-tuned motion (sport balls, vehicles, designed arcs: basketball, tennis, racing), keep the object kinematic and integrate your own velocity var per frame (V.Z = V.Z - g*DeltaSecs(); MoveWithVelocityContinuously(V); reflect/steer V on contact - see #class Ball in <example_breakout>). Works because plain kinematic objects have gravity OFF; a gravity-affected character discards scripted Z (see <movement_rules>). Hand-rolled constants stay user-tweakable (@exportRange).
+    - Designed arcs that must land on an exact point at an exact time (serves, passes, lobs, throws): ArcToTarget/ArcToTargetWithPeak build the arc once (gravity captured with it), ArcFlightSeconds gives the contact time, SetPosition(ArcPositionAt(arc, t)) drives the object each frame - closed form, so no drift and no velocity kink between rally phases. Feed the remaining time to MoveToArriveIn and PlayAnimationHittingContactIn so mover and clip land on the same instant. Do not hand-author per-phase LerpVector segments.
     - if you move Static object with MoveTo etc., it becomes Kinematic (behaves like Kinematic platform)
     </defaults>
 
@@ -560,7 +636,7 @@ Applies to all physics types: Dynamic, Static, and Kinematic.
     <defaults>
     - PlayerObject defaults to kinematic with gravity
     - `collision = mesh` objects keep mesh collision while static or moved as a kinematic platform (players ride them); giving one gravity or PreventOverlap drops it back to box collision.
-    - SetCharacterPreventOverlap give kinematic object fake physics avoiding CanCollide objects (turning PreventOverlap off for player with gravity will make it fall through ground)
+    - SetCharacterPreventOverlap(true) gives a kinematic object fake-physics separation from CanCollide objects and supplies a gravity character's ground support: off on a player with gravity = falls through the floor
     - SetCharacterOverlapIgnoreTag(Tag, IsOn) makes this character's overlap resolution skip objects with that tag (selective ghosting, e.g. walk through Tag.Enemy while charging) without touching ground collision; Touched/regions still fire. Prefer it over toggling SetCharacterPreventOverlap or SetCanCollide for pass-through-some-objects behavior.
     </defaults>
 
@@ -576,8 +652,11 @@ Applies to all physics types: Dynamic, Static, and Kinematic.
         - MoveTowardContinuousFacing
         - MoveTowardContinuousHorizontal
         - MoveTowardContinuousHorizontalFacing
+        - MoveToArriveIn (speed = remaining distance / remaining seconds; pair with ArcFlightSeconds)
+        - MoveToArriveInFacing
         </kinematic_functions>
-    - On gravity-affected characters (the PlayerObject default; EnableCharacterGravity(true) objects) the Z component of these calls is silently DISCARDED - gravity/jump owns vertical velocity, only X/Y apply, and the mover never lifts. Flying/hovering: SetCharacterGravity(false) (players: SetPlayerModeHover); jumps: Jump(). Gravity-off and bodyless objects honor full 3D velocity.
+    - These continuous movers drive ONE frame of velocity then stop: call them every frame (a brain loop that Waits 0.2s between calls crawls at ~1/12 speed).
+    - On gravity-affected characters (the PlayerObject default; EnableCharacterGravity(true) objects) the Z component of these calls is silently DISCARDED - gravity/jump owns vertical velocity, only X/Y apply, and the mover never lifts. Flying/hovering: EnableCharacterGravity(false) (players: SetPlayerModeHover); jumps: Jump(). Gravity-off and bodyless objects honor full 3D velocity.
     - Gravity characters auto-step rises up to 45cm (capped at 1/4 body height for small NPCs); taller needs a ramp or Jump()
     - To move somewhere over N seconds, use an explicit per-frame loop instead of a fire-and-forget helper:
         <example_of_move_over_time>
@@ -641,19 +720,20 @@ Applies to all physics types: Dynamic, Static, and Kinematic.
       if T >= 1 { O.SetPosition(Target) break }
       O.SetPosition(LerpVector(Start, Target, EaseInOut(T)))
   }
-- SetPosition/SetCenterPosition/SetRotation are continuous "moved" setters: they keep velocity, contacts, and render interpolation, so they are the right per-frame drivers for tweens, movers, and platforms (bodiless, static, or kinematic objects). On force-affected dynamic bodies they fight physics integration (warned in the log) - use SetPhysicsVelocity/AddImpulse there, or SetAffectedByForce(false) first.
+- SetPosition/SetCenterPosition/SetRotation are continuous "moved" setters: they keep velocity, contacts, and render interpolation, so they are the right per-frame drivers for tweens, movers, and platforms (bodiless or kinematic objects; a colliding STATIC re-carves its collider on every set - drive it with Move* movers instead, which auto-convert it to kinematic). On force-affected dynamic bodies they fight physics integration (warned in the log) - use SetPhysicsVelocity/AddImpulse there, or SetAffectedByForce(false) first.
 - TeleportTo is a discontinuity: it zeroes velocity and snaps interpolation. Use it for instant far moves, not per-frame motion.
 - EaseOutBack overshoots ~10% past the target near the end (snappy UI pops); EaseOutBounce settles with bounces. Both still end at exactly T=1 -> 1.
 </easing>
 
 <world_markers>
 - World-anchored HUD markers (lock-on reticles, waypoints, offscreen-target indicators, icon nameplates) are screen-space UI driven by projection. Do NOT build them from thin world cubes or hand-aimed meshes.
-- Recipe: a canvas image element + WorldToScreenPosition (call on a PlayerObject; returns base UI viewport coords 1600x900, or Vector(-1,-1,0) when behind/unprojectable) + SetCenterPosition per frame:
+- Recipe: a canvas image element + WorldToScreenPosition (call on a PlayerObject; returns base UI viewport coords 1600x900, or Vector(-1,-1,0) when behind/unprojectable) + SetCenterPosition per frame. Call Marker.SetUiPivot(1, 1) ONCE first: without it, SetPosition/SetCenterPosition both place the element's TOP-LEFT at the point, so a 320x220 marker lands half its size off. The marker must be a direct child of a plain frame/canvas — inside a vStack/hStack/grid the parent's layout wins and the position is ignored.
+  Marker.SetUiPivot(1, 1)   // once, e.g. OnSpawned
   var sp = WorldToScreenPosition(Target.GetCenterPosition())
-  if sp.X >= 0 { Marker.SetVisible(true) Marker.SetCenterPosition(sp) } else { Marker.SetVisible(false) }
+  if sp.X >= 0 { Marker.SetVisible(true); Marker.SetCenterPosition(sp) } else { Marker.SetVisible(false) }
 - Per-player markers (each player sees their own lock-on): put the marker on a SpawnCanvas HUD owned via SetPlayerOwnerIndex and run the loop in '#class player' (see <multiplayer_guidance>).
 - Offscreen indicator: when the sentinel fires or sp leaves 0..1600 / 0..900, clamp to the screen edge yourself (direction from screen center 800,450 toward sp).
-- Before hand-rolling: SetHoverBar (bars/pills above objects, custom material supported), SetSaidText, and SpawnFloatingText already cover the common above-object UI.
+- Before hand-rolling: SetHoverBar (bars/pills above objects, custom material supported), Say/SayTo (speech bubbles above the speaker), and SpawnFloatingText already cover the common above-object UI.
 </world_markers>
 
 <movement_laws>
@@ -661,10 +741,11 @@ Movement Laws (single-frame vs over-time)
 - Exactly one continuous translate per object per frame (and one continuous rotation). Calls whose names end with Continuous/Continuously are single-frame. If multiple are issued in one frame, last call wins (later calls overwrite earlier ones). Compose motion into one call.
 - See <time> for over-time/continuous rules.
 - TeleportTo* is absolute this frame. If a TeleportTo* and any continuous move happen in the same frame, teleport cancels motion and sets the final transform.
-- SnapToGround only when setting up an initial position; TeleportTo only when instantly moving far away (it zeroes velocity and snaps interpolation). For authored per-frame motion (tweens/movers) use SetPosition, which keeps velocity and interpolation; see <easing>.
+- SnapToGround only when setting up an initial position; TeleportTo only when instantly moving far away (it zeroes velocity and snaps interpolation). For authored per-frame motion (tweens/movers) on bodiless/kinematic objects use SetPosition, which keeps velocity and interpolation; see <easing>.
+- Arrival at an OBJECT: colliders stop the mover before centers meet, so DistanceTo(target) may never drop below both half-extents (reads as a freeze while Move* keeps firing). Gate on SurfaceGapTo(Target) <= margin instead.
 - Timing & readback: see <frame_and_scheduling_model> for tick order and GetPosition/GetRotation semantics.
 
-- Clarification: SnapToGround raycasts downward (-Z) from the object's bottom-center and snaps to the first WorldObject hit (ignores PhysicsObject/PlayerObject/CrowdObject etc.). It overrides any Z offset you set earlier in the same frame. For stacking on tiles/objects, compute Z = baseZ + baseSizeZ/2 + itemSizeZ/2 instead of using SnapToGround.
+- Clarification: SnapToGround raycasts downward (-Z) from the object's bottom-center and snaps to the first WorldObject hit (ignores PhysicsObject/PlayerObject/CrowdObject etc.). It overrides any Z offset you set earlier in the same frame. For stacking on tiles/objects, compute Z = baseZ + baseSizeZ/2 + itemSizeZ/2 instead of using SnapToGround. Flat/plane items (rugs, road markings, decals): add ~1cm more — face-on-face at the same height shimmers (z-fights), worse at long view distances.
 </movement_laws>
 
 <inputs>
@@ -672,7 +753,7 @@ Movement Laws (single-frame vs over-time)
 - Builtin action constants: Action.Primary, Action.Secondary, Action.Interact, Action.Jump.
 - Custom actions (Weave2 worlds): declare a top-level scene clause `action dash { label="Dash" key=Key.LeftShift icon="image.<owner>.<name>" }` (all properties optional; icon is a QUOTED image url). The name then works everywhere builtins do: Action.dash, IsActionPressedByThisPlayer(Action.dash), event ActionDownByThisPlayer[dash]. Prefer custom actions over raw IsKeyPressed for gameplay verbs: they get a mobile touch button (label text) automatically when the world handles their events, and `key=` gives the desktop binding. Up to 27 per world; a key already bound (or used by another action) is a load error. Undeclared action names are a compile error.
 - PlayerObject.IsActionPressedByThisPlayer(Action.Primary) .. must be in player class; checks this player's held action.
-- PlayerObject.GetMoveVectorWorld() / GetMoveVectorCamera() .. this player's normalized move vector; diagonals clamp to length 1, thumbstick magnitudes below 1 are preserved.
+- PlayerObject.GetMoveVectorWorld() / GetMoveVectorCamera() .. this player's normalized move vector; diagonals clamp to length 1, thumbstick magnitudes below 1 are preserved. World = raw input on fixed world axes (W = +Y), camera-independent; Camera = rotated by the player's orbit yaw, which per-frame camera overrides FREEZE - under SetCamera*ThisFrame, derive steering from your authored camera yaw instead.
 - event ActionDownByThisPlayer[Primary] / ActionUpByThisPlayer[Primary] .. must be in player class; options are the builtins plus declared action names.
 - Current builtin bindings: Left mouse -> Primary, Right mouse -> Secondary, E -> Interact, Space -> Jump.
 - Current movement bindings: WASD and mobile thumbstick feed the shared move vector.
@@ -691,6 +772,7 @@ Movement Laws (single-frame vs over-time)
 - Binding P in a Keyboard event overrides the built-in P sim-pause in game mode (editor P still pauses)
 - Delivery: ALL Weave input events (keyboard, mouse, action) fire in GAME mode only - editor mode delivers none of them (use IsKeyPressedByThisPlayerInEditor for editor tooling). Global KeyboardDown[..] reaches only live objects of the handler's class and skips objects currently selected in the editor (selection survives pressing Play) - put input handlers in `#class player`, where ByThisPlayer/Action events always land.
 - AI bots (SpawnAIPlayer) have NO keyboard at all and mobile sends only WASD + touch buttons: actions are the only input verb that works for every participant. Bare IsKeyPressed / KeyboardDown[..] are any-player and always false for bots/mobile.
+- Hold-to-drain abilities (turbo/sprint): do not gate on `IsKeyPressedByThisPlayer(..) and Fuel > 0` — with passive regen that re-triggers every frame at empty and strobes FX/sound. Keep an Armed flag: disarm when fuel hits 0; re-arm only in KeyboardDownByThisPlayer (or the action's press event) after release + cooldown.
 - Object.GetMouseTargetPosition (caller must be a PlayerObject) returns a far point along the mouse ray when nothing is hit; use GetMouseTargetObject to test what was hit
 - Mobile/touch: pinch in/out maps to mouse scroll (event OnMouseScroll)
 </inputs>
@@ -717,34 +799,34 @@ Movement Laws (single-frame vs over-time)
 <colors>
 - colors are Vector rgb 0..1, e.g. SetColor(Vector(1, 0.5, 0)); ColorHex(Hex:Text) parses hex text like #FF8000
 - Default daylight leans slightly cool (sky ambient), most visibly in shadows - that is the intended look; author materials in their intended base colors rather than counter-tinting them for it.
-- Scene grade (SetContrast/SetSaturation/SetExposure/SetSkyboxHue) shifts every color in the scene at once - a fit for an explicitly requested mood, in small steps, rather than for correcting one object's color.
+- Scene lighting/grade is user-tuned in the Adjust panel (see <adjuster_usage>): to fix one object's color, recolor that object/material - never with scene-wide grade.
 </colors>
 
 <time>
-- Wait(1) .. Wait 1 sec
+- Wait(1) .. Wait 1 sec (event bodies only; not inside custom functions)
 - forever { ... } runs its scope once per frame (implicit WaitNextFrame() between iterations)
   - doesn't need WaitNextFrame() to work
   - use Wait(seconds) inside forever if you want slower than once-per-frame
 - while { ... } is same-frame (no implicit yield). Use only for bounded work that must finish this frame. For per-frame logic/conditions, prefer forever + if.
-- func in outer scope cannot use function that activate over time like Wait, WaitNextFrame
-  - Clarification: "Continuous" functions (names ending in Continuous/Continuously) are single-frame and must be called every frame you want the effect. They ARE allowed inside funcs.
-  - Clarification: "Over-time" functions (multi-frame, e.g. Wait, WaitNextFrame) run across multiple frames. These are NOT allowed inside funcs; use them in events instead.
+- A same-frame loop stuck on movement/physics/time (e.g. while GetPosition().DistanceTo(t) > r { MoveTowardContinuous.. }) trips the SameFrameLoopBudgetExceeded guard - use forever + if, or Wait in the loop.
+- Over-time calls (Wait, WaitNextFrame) work only in event bodies, never inside funcs. Continuous* calls are single-frame (call every frame you want the effect) and are fine inside funcs.
 </time>
 
 <camera>
 - default camera is third person with mouse-look (like fortnite).. mouse target will just be crosshair target
-- SetIsMouseLookOn(true) is the default mouse look like counter-strike and fortnite (SetCameraToFirstPerson also turns it on): the cursor is hidden and pinned to screen center, so players CANNOT click UI buttons — call SetIsMouseLookOn(false) while a menu/shop/end screen is open, restore true on close (touch players can still tap)
-- Camera always follows PlayerObject every frame unless overridden by SetCameraThisFrame()/SetCameraLookAtThisFrame()/SetChaseCameraThisFrame() (each is a one-frame override; call every frame to keep it).
+- SetIsMouseLookOn(true) is the default mouse look like counter-strike and fortnite (SetCameraToFirstPerson also turns it on): the cursor is hidden and pinned to screen center, so players CANNOT click UI buttons — call SetCursorUiMode(true) while a menu/shop/end screen is open (releases look AND shows the cursor), SetCursorUiMode(false) on close (touch players can still tap). Spectator + per-frame camera overrides (SetCameraLookAtThisFrame) keep the cursor pinned+hidden while the script owns the camera angles: commander-camera/RTS worlds call SetCursorUiMode(true) once at player spawn
+- Camera always follows PlayerObject every frame unless overridden by SetCameraThisFrame()/SetCameraLookAtThisFrame()/SetChaseCameraThisFrame() (each is a one-frame override; call every frame to keep it) — or parked with SetCameraFixed(Position, LookAt), the persistent one-call variant. While a per-frame override or fixed camera is active the mouse no longer steers the camera. The camera always views the caller's own PlayerObject; no simcall views through another player's object.
+- SetCameraFixed(Position, LookAt) parks the camera (security cam / lobby / cinematic shot): persists across frames AND save/reload, camera collision is off while fixed, mouse-look is ignored; any camera-mode switch (SetCameraToThirdPerson(...) etc.) releases it — SetIsMouseLookOn/SetCursorUiMode do NOT. Prefer it over a per-frame SetCameraLookAtThisFrame loop for static shots.
 - Default camera yaw/rotation is 0 degrees.
 - At camera yaw 0: camera forward is +X, camera up is +Z, and camera left is +Y.
 - Camera yaw is right-hand (same as object yaw): `SetCameraRotation(0)` faces +X, `SetCameraRotation(90)` faces +Y, `SetCameraRotation(-90)` faces -Y.
 - Objects also face +X at rotation 0, with +Y their LEFT side (right-hand system): a character's right-side parts sit at negative y.
-- Angles in this API are degrees. For trig on degree angles use `SinDegree()`/`CosDegree()`/`TanDegree()` (and `Atan2Degree()` returns degrees); `Sin()`/`Cos()`/`Tan()`/`Atan2()` are radians.
+- Angles in this API are degrees. Trig is Number methods on the angle: `Angle.SinDegree()`/`CosDegree()`/`TanDegree()`, `Y.Atan2Degree(X)` (degrees); `.Sin()`/`.Cos()`/`.Tan()`/`.Atan2(X)` are radians. There are no global trig functions.
 - SetCameraToTopDown() defaults to 70-degree tilt down, 900 units zoom, facing +Y.
-- Camera-mode switch signatures: `SetCameraToTopDown()`, `SetCameraToFirstPerson()`, `SetCameraToSideView()` take no args; only `SetCameraToThirdPerson(IsMouseLookOn)` takes one Bool. Collision is always restored on switch.
+- Camera-mode switch signatures: `SetCameraToTopDown()`, `SetCameraToFirstPerson()`, `SetCameraToSideView()` take no args; only `SetCameraToThirdPerson(IsMouseLookOn)` takes one Bool. Switches restore collision+gravity, except an active SetPlayerModeHover/Spectator survives (SetPlayerModeGrounded exits it).
 - 2D-style games (top-down or side-view camera) are still 3D worlds: keep a ground/background object so the camera never shows bare skybox, and for side-view keep gameplay on a constant Y plane. A compact ~500x500 cm play area suits board/arcade layouts (chess, brick-breaker).
 - Third-person body faces its MOVEMENT direction, not the camera; GetCrosshairDirection() is camera-only. So a gun/item aimed via crosshair won't match the body when looking around while standing still. Fix: SetOrientingWithCameraYaw(true) makes the body track the camera yaw.
-- SetCameraZoom .. 0 will make it first person, 900 will make it third-person with camera 900 units away from character
+- SetCameraZoom .. 0 will make it first person, 900 will make it third-person with camera 900 units away from character (zoom alone never enables mouse steering; use SetCameraToFirstPerson() for playable first person)
 - Third-person default framing: zoom 525 with pivot offset (0, -39, 87) = over-the-shoulder, body slightly left of screen center; override via SetCameraZoom()/SetCameraPivotOffset()
 - player movement must come from the player class: either SetDefaultPlayerControlsEnabled(true) in OnSpawned (attaches the built-in default controls, equivalent to the class below) or a coded movement loop — with neither, the player and thus the camera cannot move in play-mode. SetDefaultPlayerControlsEnabled(false) detaches them again (cutscene/stun freeze).
 - built-in default player controls (also the template for custom movement):
@@ -784,9 +866,6 @@ event OnSpawned {
 - player object always stand upright (lock rotation axis to z)
 </camera>
 
-<built_in_functions>
-- example: ObjectA.LookAt(ObjectB.GetPosition())
-</built_in_functions>
 <built_in_function_list>
 PrintNumber(Number: Number)
 Print(Text: Text)
@@ -800,8 +879,8 @@ SetAutoGameLogOn()
 PlayerPrint(PlayerIndex: Number, Text: Text)
 SetSunIntensity(Intensity: Number) // Default: 4
 SetSunSpecularScale(Scale: Number) // Default: 1
-SetSunRotation(Rotation: Number) // Default: 10
-SetSunTilt(Tilt: Number) // Default: 46
+SetSunRotation(Rotation: Number) // Default: 10. Azimuth, degrees from +X toward +Y; shadows fall toward Rotation+180
+SetSunTilt(Tilt: Number) // Default: 46. Elevation above the horizon, degrees (90 = overhead)
 SetSkybox(Skybox: Object)
 SetSkyboxHorizonTilt(AngleDegrees: Number) // Default: 0
 SetSkyboxRotation(RotationDegrees: Number) // Default: 0
@@ -831,11 +910,10 @@ SetShadowDepthBiasConstant(Units: Number) // Default: 1
 SetShadowDepthBiasSlopeScale(Scale: Number) // Default: 2.5
 SetShadowOpacity(Opacity01: Number) // Default: 1
 SetStaticLodTransitions(Lod1Size: Number, Lod2Size: Number, Lod3Size: Number) // Default: 0.18, 0.07, 0.025
-SetStaticLodShadowTransitions(Lod1Size: Number, Lod2Size: Number, Lod3Size: Number) // Default: 0.35, 0.18, 0.08
-SetStaticLodShadowSkipTexels(Cascade2SkipTexels: Number, Cascade3SkipTexels: Number, Lod0ExceptionTexels: Number) // Default: 24, 64, 768
-SetContrast(Contrast: Number) // Contrast multiplier around mid-gray. Default: 1 = neutral; 0 = flat gray, 2 = double
+SetStaticLodShadowTransitions(Lod1Size: Number, Lod2Size: Number, Lod3Size: Number) // Same screen-size units as SetStaticLodTransitions, but for meshes drawn into the sun-shadow maps (defaults higher: shadows tolerate earlier LOD). Lower toward the view values if a large caster's shadow silhouette looks low-poly or pops. Default: 0.35, 0.18, 0.08
+SetContrast(Contrast: Number) // Power curve around mid-gray, pre-tonemap: shadows compress, never crush to black. Default: 1 = neutral; 0 = flat gray, 2 = strong
 SetSaturation(Saturation: Number) // Saturation multiplier. Default: 1 = neutral; 0 = grayscale, 2 = vivid
-SetExposure(Exposure: Number) // Default: 0
+SetExposure(Exposure: Number) // EV stops, pre-tonemap: +1 = twice as bright, -1 = half. Default: 0
 SetShadowLift(Amount: Number) // Default: 2; 0 = off
 SetShadowLiftThreshold(Threshold: Number) // Default: 0.06
 SetSmaaEdgesThreshold(Threshold01: Number) // Default: 0.01
@@ -852,12 +930,12 @@ SetAllLocalShadowsEnabled(Enabled: Bool)
 SetAllDecalsEnabled(Enabled: Bool)
 SetGravity(Gravity: Number)
 SetTerminalVelocityZ(MaxFallSpeed: Number)
-SetFogStartDistance(StartDistance: Number) // Default: 10. The skybox is fogged only via SetFogSkyboxAffect or height fog; underwater, automatic murk overrides all fog settings
-SetFogEndDistance(EndDistance: Number) // Default: 600
+SetFogStartDistance(StartDistance: Number) // Default: 10. Meters (not cm). The skybox is fogged only via SetFogSkyboxAffect or height fog; underwater, automatic murk overrides all fog settings
+SetFogEndDistance(EndDistance: Number) // Default: 600. Meters
 SetHeightFogEnabled(Enabled: Bool)
-SetHeightFogTop(Top: Number) // Default: 30
-SetHeightFogBottom(Bottom: Number) // Default: 0
-SetHeightFogSoftness(Softness: Number) // Default: 0.25
+SetHeightFogTop(Top: Number) // Default: 50. Meters
+SetHeightFogBottom(Bottom: Number) // Default: 0. Meters
+SetHeightFogSoftness(Softness: Number) // Default: 1
 SetGpuCullingDistance(DistanceMeters: Number) // Default: 0 (distance culling off)
 SetFrustumCulling(Enabled: Bool)
 SetFrustumCullingMargin(MarginMeters: Number) // Default: 0
@@ -867,12 +945,17 @@ SetGrassTerrainActiveDistanceM(DistanceMeters: Number) // Default: 140
 SetGrassCullDistanceM(DistanceMeters: Number) // Default: 140
 SetGrassFadeDistancePercent(FadeBandPercent: Number) // Default: 50
 SetGrassFarThinningPower(Power: Number) // Default: 3
+SetTreeLodSwitchDistanceM(DistanceMeters: Number) // Leaf cards -> whole-tree impostor switch distance, desktop meters (mobile auto-scales down). Default: 0 = auto (140 / 90)
+SetTreeMeshDistanceM(DistanceMeters: Number) // Real branch-mesh max draw distance, desktop meters; impostors only beyond. Default: 0 = auto (400 / 260)
+SetTreeCullDistanceM(DistanceMeters: Number) // Trees vanish entirely past this, desktop meters (the outermost bound - it caps the mesh + leaf-switch ranges under it). Default: 0 = auto (800 / 300)
+SetTreeFadeDistancePercent(FadeBandPercent: Number) // Card->impostor crossfade band as % of the switch distance, clamped 5..80. Default: 36
+SetTreeFarLeafDensityPercent(DensityPercent: Number) // Leaf-card density kept across the fade band, clamped 10..300; <100 thins earlier (cheaper), >100 denser. Default: 100
 SetAssetSubmeshHue(ModelAsset: Object, SubmeshIndex: Number, HueDegrees: Number)
 SetAssetSubmeshSaturation(ModelAsset: Object, SubmeshIndex: Number, Saturation: Number) // Chroma multiplier: 1 = neutral, 0 = grayscale
 SetAssetSubmeshBrightness(ModelAsset: Object, SubmeshIndex: Number, Brightness: Number) // Gain: 1 = neutral
 SetAssetSubmeshContrast(ModelAsset: Object, SubmeshIndex: Number, Contrast: Number) // Multiplier around mid-gray: 1 = neutral, 0 = flat gray. Use only when the user asks for it specifically; Tint/Brightness/Saturation cover normal fitting
 SetAssetSubmeshTint(ModelAsset: Object, SubmeshIndex: Number, TintRGB: Vector)
-SetAssetSubmeshEmissionIntensity(ModelAsset: Object, SubmeshIndex: Number, Intensity: Number)
+SetAssetSubmeshEmissionIntensity(ModelAsset: Object, SubmeshIndex: Number, Intensity: Number) // Linear glow multiplier for this submesh; composes with object emission
 SetAssetSubmeshMinRoughness(ModelAsset: Object, SubmeshIndex: Number, MinRoughness: Number)
 SetAssetSubmeshRoughnessSmoothStepRemap(ModelAsset: Object, SubmeshIndex: Number, Enabled: Bool)
 SetAssetSubmeshNormalStrength(ModelAsset: Object, SubmeshIndex: Number, Strength: Number)
@@ -1005,8 +1088,8 @@ Object.GetRotation() -> Vector
 Object.GetScale() -> Vector
 Object.GetSize() -> Vector
 Object.GetSizeY() -> Number
-Object.GetSizeX() -> Number
-Object.GetHeight() -> Number
+Object.GetSizeX() -> Number // Footprint X size in cm (Y: GetSizeY). Vertical size is GetHeight - there is no GetSizeZ
+Object.GetHeight() -> Number // Vertical (Z) size in cm
 Object.GetHalfHeight() -> Number
 Object.GetHeightInTiles() -> Number
 Object.GetHalfHeightInTiles() -> Number
@@ -1024,7 +1107,7 @@ Object.MoveTowardContinuousHorizontal(Position: Position, Speed: Number)
 Object.MoveTowardContinuousHorizontalFacing(Position: Position, Speed: Number) // Facing means object's forward (local +X) is aligned to world-space Direction
 Object.MoveInDirectionContinuously(Direction: Vector, Speed: Number)
 Object.MoveInDirectionContinuouslyFacing(Direction: Vector, Speed: Number) // Facing means object's forward (local +X) is aligned to world-space Direction. On players with SetOrientingWithCameraYaw(true) the facing part is ignored (camera yaw owns the body).
-Object.MoveWithVelocityContinuously(Velocity: Vector) // On gravity-affected characters (the PlayerObject default) the Z component is silently DISCARDED - gravity/jump owns vertical velocity; only X/Y apply. For flying/hovering turn gravity off first (SetCharacterGravity(false); players: SetPlayerModeHover); for jumps use Jump(). Gravity-off and bodyless objects honor full 3D
+Object.MoveWithVelocityContinuously(Velocity: Vector) // On gravity-affected characters (the PlayerObject default) the Z component is silently DISCARDED - gravity/jump owns vertical velocity; only X/Y apply. For flying/hovering turn gravity off first (EnableCharacterGravity(false); players: SetPlayerModeHover); for jumps use Jump(). Gravity-off and bodyless objects honor full 3D
 Object.MoveWithVelocityContinuouslyFacing(Velocity: Vector)
 Object.RotateLeftInstantly(Degree: Number)
 Object.RotateRightInstantly(Degree: Number)
@@ -1047,12 +1130,12 @@ Object.GetPlayerInputDirectionCamera(ForwardKey: Number, BackwardKey: Number, Le
 Object.GetMoveVectorWorld() -> Vector
 Object.GetMoveVectorCamera() -> Vector
 IsKeyPressed(Key: Number) -> Bool
-Object.GetMousePositionDelayed() -> Vector // Player only. Sim cursor, 1600x900 base space; delayed a few frames behind the OS cursor. Clicks/hover/aim/drag/tooltips have dedicated calls (Click events, IsMouseOnUi, GetMouseTarget*, SetUiDraggable, SetUiFollowsCursor)
+Object.GetMousePositionDelayed() -> Vector // Player only. Sim cursor, 1600x900 base space (same space as UI rects; can run negative/past-base in the letterbox bands of non-16:9 windows); delayed a few frames behind the OS cursor, so a read cached across frames is NOT a click/drag anchor - under load it lags the press; anchor on Event.MouseDownPosition/Event.MousePosition. Clicks/hover/aim/drag/tooltips have dedicated calls (Click events, IsMouseOnUi, GetMouseTarget*, SetUiDraggable, SetUiFollowsCursor)
 Object.GetMouseDirection() -> Vector
-Object.IsMouseOnUi() -> Bool // returns true if this UI element is hovered. Shared canvas: any player. Owned canvas: owner only.
+Object.IsMouseOnUi() -> Bool // True if the cursor's click target (topmost interactable or block_input element) is this element or inside it; screenCanvas receiver: over ANY of that canvas's clickable/blocking elements (empty canvas space stays false) - the usual whole-HUD gate. Gate raw click/action handlers with it. Plain labels/images never match (give them block_input=true or a class). Shared canvas: any player. Owned canvas: owner only.
 Object.GetMouseTargetObject() -> Object
 Object.GetMouseTargetPosition() -> Position
-Object.GetMouseTargetPositionOnPlaneZ(PlaneZ: Number) -> Position
+Object.GetMouseTargetPositionOnPlaneZ(PlaneZ: Number) -> Position // Player only. Cursor-ray hit on plane z=PlaneZ; Invalid position when the ray misses (cursor at/above horizon) - gate with .IsValid()
 Object.GetMouseTargetNormal() -> Vector
 Object.GetMouseTargetObjectWithTag(Tag: Number) -> Object
 Object.GetMouseTargetPositionWithTag(Tag: Number) -> Position
@@ -1062,7 +1145,7 @@ Object.GetMouseTargetPlayer() -> Object
 Object.GetMouseTargetPlayerWithTag(Tag: Number) -> Object
 Object.GetCrosshairDirection() -> Vector
 Object.GetCrosshairTargetObject() -> Object
-Object.GetCrosshairTargetPosition() -> Position // On miss, returns a point 20000 units along the crosshair ray. For gunfire: bullet Dir = (this - GetWeaponAnchorWorldPos("muzzle")).GetNormal().
+Object.GetCrosshairTargetPosition() -> Position // On miss, returns a point 1000 units along the crosshair ray. For gunfire: bullet Dir = (this - GetWeaponAnchorWorldPos("muzzle")).GetNormal().
 Object.GetCrosshairTargetNormal() -> Vector
 Object.GetCrosshairTargetObjectWithTag(Tag: Number) -> Object
 Object.GetCrosshairTargetPositionWithTag(Tag: Number) -> Position
@@ -1144,7 +1227,7 @@ Object.AddTag(Tag: Number)
 Object.HasTag(Tag: Number) -> Bool
 Object.ClearTag()
 Object.GetColor() -> Vector
-Object.IsEditorMode() -> Bool
+Object.IsEditorMode() -> Bool // Per-player state; player receiver (runtime error on non-players). From non-player classes call it on a player, e.g. GetAllPlayers().Get(0).IsEditorMode()
 Object.IsMouseLookOn() -> Bool
 Object.IsMouseVisible() -> Bool
 Object.IsCrosshairVisible() -> Bool
@@ -1233,14 +1316,14 @@ TileGridFindPath8(Grid: List, StartX: Number, StartY: Number, GoalX: Number, Goa
 TileGridPathTile(Grid: List, TileId: Number, OriginTile: Vector) -> Vector
 TileGridPathWorld(Grid: List, TileId: Number, OriginTile: Vector) -> Position
 Object.GetTile() -> Position
-Object.GetMouseTargetTileOnZeroZ() -> Vector
+Object.GetMouseTargetTileOnZeroZ() -> Position // Player only. Tile index (hit/TileSizeXY floored) of the cursor ray on z=0; Invalid on miss - gate with .IsValid()
 Object.WorldToScreenPosition(Position: Position) -> Vector // Base UI viewport coords (1600x900). Returns Vector(-1,-1,0) if behind/unprojectable.
 Object.LocalOffsetToWorld(OffsetLocal: Position) -> Position // Origin: GetPosition()
 Object.LocalDirectionToWorld(DirLocal: Vector) -> Vector
-Object.EquipWeapon(WeaponModel: Object) // attach a weapon model to this object's hand (render) + enable weapon anchors (sim)
+Object.EquipWeapon(WeaponModel: Object) // attach a weapon model to this object's hand (render) + enable weapon anchors (sim). Use for ALL player-held items - never a per-frame position-follow loop: scripts read sim aim, which trails the instantly-rendered camera, so the item swings ~100ms late on every turn. Aim/strafe games: add SetOrientingWithCameraYaw(true). Models with no grip data are held at a bbox guess (mid-body grips): give #mesh weapons socket("grip"); fix library/store models with SetModelAnchor
 Object.UnequipWeapon() // remove the held weapon
 Object.GetHeldWeapon() -> Object // held weapon model, or InvalidId when unarmed
-Object.GetWeaponAnchorWorldPos(AnchorName: Text) -> Position // AnchorName can be any model anchor; returns held-weapon anchor position in world space
+Object.GetWeaponAnchorWorldPos(AnchorName: Text) -> Position // AnchorName can be any model anchor; returns held-weapon anchor position in world space. Market-model anchors register only once the model has downloaded (OnSpawned can be too early); SetModelAnchor anchors are available immediately
 Object.LookAtTileHorizontal(TileX: Number, TileY: Number)
 Object.LookAtTileHorizontal(TileX: Number, TileY: Number, TileZ: Number)
 Object.LookAtTileHorizontal(TileXYZ: Vector)
@@ -1258,10 +1341,11 @@ SpawnAtTile(SavedObject: Object, TileXYZ: Vector) -> Object
 Object.TeleportToTile(TileX: Number, TileY: Number)
 Object.TeleportToTile(TileX: Number, TileY: Number, TileZ: Number)
 Object.TeleportToTile(TileXYZ: Vector)
-Object.SetRotation(Rotation: Vector) // Rotates about GetPosition() (bottom-center pivot for mesh objects). To spin about the middle: SetRotation(R) then SetCenterPosition(C) with C the fixed world center
-Object.SetRotation(X: Number, Y: Number, Z: Number) // Rotates about GetPosition() (bottom-center pivot for mesh objects). To spin about the middle: SetRotation(R) then SetCenterPosition(C) with C the fixed world center
+Object.SetRotation(Rotation: Vector) // Rotates about GetPosition() (bottom-center pivot for mesh objects). To spin about the middle: SetRotation(R) then SetCenterPosition(C) with C the fixed world center; any other hinge point: SetRotationWithPivot
+Object.SetRotation(X: Number, Y: Number, Z: Number) // Rotates about GetPosition() (bottom-center pivot for mesh objects). To spin about the middle: SetRotation(R) then SetCenterPosition(C) with C the fixed world center; any other hinge point: SetRotationWithPivot
 Object.SetGroupRotationWithPivot(Pivot: AnyBasicType, Rotation: Vector)
 Object.LookAtGroupWithPivot(Pivot: AnyBasicType, Target: AnyBasicType)
+Object.SetRotationWithPivot(Pivot: Position, Rotation: Vector) // Part swings around its middle instead of its mount (wing root, tail base, door edge) -> rigid-rotate about world-space Pivot: sets Rotation and moves GetPosition accordingly. Rejects gravity/force receivers. Group receivers: SetGroupRotationWithPivot
 Object.SetScale(Scale: Vector) // raw multiplier of the model's authored size; prefer SetSize (world-unit footprint) for world objects AND effects (effects: size scales vs their boundingBoxSize)
 Object.SetScale(X: Number, Y: Number, Z: Number) // raw multiplier of the model's authored size; prefer SetSize (world-unit footprint) for world objects AND effects (effects: size scales vs their boundingBoxSize)
 Object.SetSize(Size: Vector) // Resizes around the object's CENTER: a grounded object sinks by half the growth (re-ground after, or use ScaleToHeight which stays base-anchored). Per-axis values stretch imported models - prefer uniform scaling for marketplace meshes
@@ -1271,11 +1355,12 @@ Object.SetSizeTilesUniform(Size: Number)
 Object.SetSizeTiles(Size: Vector)
 Object.SetSizeTiles(X: Number, Y: Number, Z: Number)
 Position.IsCloseXY(Other: Position) -> Bool
+Position.IsValid() -> Bool // False for Invalid positions (the GetMouseTarget* miss sentinel); position-writing calls (SetPosition/TeleportTo/Spawn*) error on Invalid
 Object.ScaleToHeight(Height: Number) // Uniform scale anchored at the base/bottom (feet stay planted) - the safe resize for characters and imported models. SetSize* grows around the CENTER: a grounded object sinks by half the growth
 Object.SnapToGround() // Snap bottom-center downward to first collider; ignores prior Z offsets
 Object.SnapToGroundWithTag(Tag: Number)
 Object.SnapToGroundIgnoreTag(Tag: Number)
-Object.SetColor(RGB: Vector)
+Object.SetColor(RGB: Vector) // Tint that MULTIPLIES the material's existing colors (white = unchanged, black = black); it does not replace the albedo
 Object.SetColor(R: Number, G: Number, B: Number)
 Object.SetOpacity(Opacity01: Number)
 Object.SetDebugMetallic(Metallic01: Number)
@@ -1288,19 +1373,21 @@ Object.SetWaterDeepColor(RGB: Vector) // Deep-water tint.
 Object.SetWaterDeepColor(R: Number, G: Number, B: Number)
 Object.SetWaterColorMixRange(ShallowCm: Number, DeepCm: Number) // Depth range for shallow-to-deep tint.
 Object.SetWaterTransparency(Alpha: Number) // Water alpha/refraction blend.
-Object.SetEmissionColor(RGB: Vector)
-Object.SetEmissionColor(R: Number, G: Number, B: Number)
-Object.SetEmissionIntensity(Intensity: Number)
+Object.SetEmissionColor(RGB: Vector) // Glow tint; unset/near-black = glows in the object's own color
+Object.SetEmissionColor(R: Number, G: Number, B: Number) // Glow tint; unset/near-black = glows in the object's own color
+Object.SetEmissionIntensity(Intensity: Number) // Linear glow: 0 off, 1 soft self-lit, 4 lamp, 16+ neon bloom
 Object.SetLightIntensity(Intensity: Number)
-Object.SetLightFadeWidth(FadeWidth: Number)
+Object.SetLightFadeWidth(FadeWidthCm: Number) // diffuseOnlyLight only (edge fade band; default 30, clamped to the light radius)
 Object.SetLightCastShadow(Enabled: Bool)
 Object.SetLightDiffuseScale(Scale: Number)
 Object.SetLightSpecularScale(Scale: Number)
-Object.GetLightFadeWidth() -> Number
+Object.GetLightFadeWidth() -> Number // diffuseOnlyLight only
 Object.GetLightDiffuseScale() -> Number
 Object.GetLightSpecularScale() -> Number
+Object.SetLightRadius(RadiusCm: Number)
+Object.GetLightRadius() -> Number
 Object.SetTeam(TeamId: Number)
-Object.GetTeam() -> Number // Unset team = 32767 (no SetTeam yet; players spawn teamless). Compare against team ids you assigned; never assume 0/1.
+Object.GetTeam() -> Number // Unset team = 32767 (no SetTeam or scene `team =` yet; players spawn teamless). Compare against team ids you assigned; never assume 0/1.
 Object.SetPlayerOwnerIndex(PlayerIndex: Number)
 Object.GetPlayerOwnerIndex() -> Number
 Object.GetPlayerName() -> Text
@@ -1321,8 +1408,10 @@ Object.SpawnFloatingText(Text: Text)
 Object.SpawnFloatingText(Text: Text, Color: Vector)
 Object.SetHoverHPBar(HP: Number, MaxHP: Number)
 Object.SetHoverSPBar(SP: Number, MaxSP: Number)
-Object.SetHoverBar(BarIndex: Number, Value: Number, MaxValue: Number, Color: Vector, BackgroundColor: Vector, OffsetX: Number, OffsetY: Number, Width: Number, Height: Number)
-Object.ClearHoverBars()
+Object.SetHoverBar(BarIndex: Number, Value: Number, MaxValue: Number, Color: Vector, BackgroundColor: Vector, OffsetX: Number, OffsetY: Number, Width: Number, Height: Number) // Floating stat bar above the caller at BarIndex 0..=29 (30/31 are the built-in SP/HP bars — use SetHoverSPBar/SetHoverHPBar). MaxValue <= 0 hides the bar. Overlapping bars on one object auto-separate toward their intended side; offsets need not be pixel-exact
+Object.ClearHoverBars() // Remove all of the caller's hover bars; SetHoverText("") clears the label. Objects reused without Destroy (repositioned indicators, manual pools) keep their previous life's bars and label - clear on repurpose
+Object.SetHoverText(Text: Text) // Persistent label above the object (unit names, vendor tags); empty Text removes it
+SetPlayerNamesVisible(IsVisible: Bool) // Default: visible. Hide the engine's username labels when drawing custom nameplates
 DrawLine(Start: Position, End: Position, Color: Vector, Thickness: Number)
 DrawSphere(Position: Position, Radius: Number, Color: Vector)
 DrawSphere(Position: Position, Radius: Number)
@@ -1331,16 +1420,24 @@ DrawDot(Position: Position)
 SpawnEffect(Effect: Object, Position: Position) -> Object
 SpawnEffectWithAutoDestroy(Effect: Object, Position: Position) -> Object
 SpawnEffectForDuration(Effect: Object, Position: Position, Duration: Number) -> Object
+SpawnDecal(Material: Object, Position: Position, RotationEuler: Vector, Size: Vector) -> Object // Projects onto geometry inside its oriented box along local -Z (down at rotation 0); Size z = projection depth cm. Bullet holes/stains/scorch marks. No engine pool: keep spawned decals in a List and Destroy the oldest past a few hundred
+SetScreenShader(Material: Object) // Fullscreen screen effect (film grain, color grade, distortion, damage flash): a #shader material applied after tonemap/AA; fragment reads ctx.color/ctx.depth. None clears. Animate via SetMaterialParameterNumber; see shader_dsl skill
+SetVolumetricLightIntensity(Percent: Number) // Sun shafts / god rays (raymarched vs the sun's shadows). Default: 0 (off); ~40 = subtle atmosphere, 100+ = dramatic alley/doorway shafts. Reads best with a low sun + occluding geometry
+SetVolumetricLightDensity(Percent: Number) // Haze thickness the shafts scatter in, percent of baseline. Default: 100; lower = crisper thinner shafts, higher = foggier
+Object.EnableLocalWeaponView(Offset: Position, RotationDegrees: Vector, Scale: Number, FovDegrees: Number) // EnableLocalWeaponView + own weapon FOV: FovDegrees 0 = follow camera; ~50-70 = classic FPS viewmodel that ignores ADS zoom and never clips walls
+SetSoundVolume(Sound: Object, Volume: Number) // Live per-asset volume (1 = as authored): retunes every instance already playing, loops included, and every later play; the per-play PlaySound volume multiplies on top. 0 mutes but keeps loops running - StopSound to end them
+FadeOutSound(Sound: Object, Seconds: Number) // Ramps this sound's playing instances to silence over Seconds, then stops them; queued plays drop immediately, plays started after the call are unaffected. Music/ambience handoffs - StopSound cuts instantly
 PlaySound(Sound: Object, Volume: Number) // Global (every client, full volume): UI/music. Positional per-player attenuation: PlaySoundAtPosition; stop an asset's instances: StopSound
 PlaySound(Sound: Object, Volume: Number, Pitch: Number)
 PlaySoundLooped(Sound: Object, Volume: Number) // Loops until StopSound(sound)/StopAllSounds; for BGM/engine hum (PlaySound stays one-shot)
+PlaySoundForPlayer(Player: Object, Sound: Object, Volume: Number) // Plays only on that player's client (global mix, no position): personal announcements/feedback the other players must not hear. Runtime error if Player is not a live player
 SetSoundAssetPriority(Sound: Object, Priority: Number)
 SetSoundAssetCooldown(Sound: Object, CooldownSeconds: Number)
 SetMaxSimultaneousSoundEffect(Max: Number)
-GetRayHitPosition(Position: Position, Direction: Vector, Tag: Number) -> Position // Tag filters hits (no max-distance param). On miss, returns Position + Direction * 1000000.
-GetRayHitObject(Position: Position, Direction: Vector, Tag: Number) -> Object
-GetRayHitStaticPosition(Position: Position, Direction: Vector, Tag: Number) -> Position // Tag filters hits (no max-distance param). On miss, returns Position + Direction * 1000000.
-GetRayHitStaticObject(Position: Position, Direction: Vector, Tag: Number) -> Object
+GetRayHitPosition(Position: Position, Direction: Vector, Tag: Number) -> Position // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. No max-distance param (range-gate on GetRayHitDistance); on miss returns Position + Direction * 1000000.
+GetRayHitObject(Position: Position, Direction: Vector, Tag: Number) -> Object // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. Returns null Object on miss (check .Exists()).
+GetRayHitStaticPosition(Position: Position, Direction: Vector, Tag: Number) -> Position // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. No max-distance param (range-gate on GetRayHitDistance); on miss returns Position + Direction * 1000000.
+GetRayHitStaticObject(Position: Position, Direction: Vector, Tag: Number) -> Object // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. Returns null Object on miss (check .Exists()).
 Object.SetCameraThisFrame(Position: Position, YawDegrees: Number, PitchDegrees: Number)
 Object.SetCameraLookAtThisFrame(Position: Position, LookAt: Position)
 Object.SetChaseCameraThisFrame(TargetPosition: Position, ForwardDirection: Vector, BackDistance: Number, Height: Number, LookAtHeight: Number) // Places camera at TargetPosition - normalize(ForwardDirection.xy)*BackDistance + Z*Height, looking at TargetPosition + Z*LookAtHeight
@@ -1363,18 +1460,7 @@ PersistGetNumber(Player: Object, Key: Text) -> Number
 PersistSetNumber(Player: Object, Key: Text, Value: Number)
 PersistAddNumber(Player: Object, Key: Text, Delta: Number)
 RefreshStaticBaseline() // Call once at the end of heavy static-scene init; non-moving objects then skip per-frame display CPU (a later manipulation opts that object out).
-RestartGame()
-AdvertiseLobbySession() // Advertise this relay as a joinable lobby session for the running project; not a gameplay replication/server-authority API.
-StopAdvertisingLobbySession() // Stop advertising this relay lobby session.
-ListLobbySessions() // Request discoverable lobby sessions of the running project (identity automatic, exact content version). Results update LobbySession* getters and fire OnLobbySessionListUpdated; state 2 with 0 sessions = nobody hosts this exact version.
-JoinLobbySession(RelayPubkey: Text) // Join a discovered relay lobby session by LobbySessionRelayPubkey; deterministic shared sim still applies after joining.
-LobbySessionCount() -> Number // Number of discovered relay lobby sessions from the latest ListLobbySessions result.
-LobbySessionRelayPubkey(Index: Number) -> Text // Relay pubkey for a discovered lobby session; pass to JoinLobbySession.
-LobbySessionConnectId(Index: Number) -> Text // Debug/connect id for a discovered relay lobby session; usually not needed for gameplay code.
-LobbySessionDisplayName(Index: Number) -> Text // Human display name for a discovered relay lobby session.
-LobbySessionRefreshState() -> Number // Latest list state: 0 idle, 1 pending, 2 ok, 3 error (read LobbySessionErrorText).
-LobbySessionStage(Index: Number) -> Text // #stage name a discovered session is currently on (empty for stageless projects); show or filter it in the session browser.
-LobbySessionErrorText() -> Text // Reason for state 3 (empty otherwise), e.g. relay unreachable or no loaded world.
+RestartGame() // Reloads the WHOLE project (fresh load flow; discards the user's unsaved manual editor edits). Hard New Game only - pair with PersistClear(). Round/match resets: reset positions/scores in code instead.
 AnyBasicType.NearestPlayerNonSpectator() -> Object
 SetSsrRoughnessFade(StartRoughness: Number, EndRoughness: Number) // Default: 0.68, 0.7
 SetSsrRayFade(NearFadePower: Number, FarFadePower: Number) // Default: 0.08, 0.8
@@ -1383,16 +1469,15 @@ SetSkyboxContrast(Contrast: Number) // Contrast multiplier. Default: 1 = neutral
 Hash2(X: Number, Y: Number, Seed: Number) -> Number // Deterministic [0,1): constant within each integer X/Y cell (see <procedural_generation>)
 ValueNoise2(X: Number, Y: Number, Seed: Number) -> Number // Deterministic smooth noise [0,1), X/Y in cell units
 Fbm2(X: Number, Y: Number, Octaves: Number, Seed: Number) -> Number // Deterministic fractal noise [0,1), Octaves 1..8
-SpawnTerrainFromHeights(Heights: List, SamplesX: Number, SamplesY: Number, CellSize: Number, Position: Position) -> Object // Heights: row-major List of Numbers (cm, relative to Position.Z), len = SamplesX*SamplesY (2..513 each)
-SpawnTerrainFromHeights(Name: Text, Heights: List, SamplesX: Number, SamplesY: Number, CellSize: Number, Position: Position) -> Object // Same + registers terrain asset under Name (error if name taken)
+SpawnTerrainFromHeights(Heights: List, SamplesX: Number, SamplesY: Number, CellSize: Number, Position: Position) -> Object // Heights: row-major List of Numbers (cm, relative to Position.Z), len = SamplesX*SamplesY (2..513 each). Terrain XY is CENTERED on Position
+SpawnTerrainFromHeights(Name: Text, Heights: List, SamplesX: Number, SamplesY: Number, CellSize: Number, Position: Position) -> Object // Same + registers terrain asset under Name (error if name taken or starting with 'terrain.' - reserved for uploaded assets)
 Object.SetTerrainMaterial(MaterialAsset: Object) // Terrain objects only; Material.X (#shader or #texture auto-material, triplanar works), None clears
 Object.SetTerrainLayers(Steep: Object, High: Object, Low: Object) // Terrain only; blends extra #texture materials over the base by slope/height: Steep on cliffs, High above HighStartZ, Low below LowStartZ. None skips a layer. Set base via SetTerrainMaterial
 Object.SetTerrainLayerParams(SlopeStartDeg: Number, SlopeEndDeg: Number, HighStartZ: Number, HighEndZ: Number, LowStartZ: Number, LowEndZ: Number) // Terrain only; tunes SetTerrainLayers blending. Slope in degrees (start..end ramp), heights in world Z cm. 0,0 for a pair = auto (slope 32..50, High top ~25%, Low bottom ~15% of height range)
-CreateInstanceBatch(Model: Object, Origin: Position) -> Object // Display-only mass scatter batch (see <procedural_generation>); Model: Ori.model.* (basics like Ori.model.cone work) or Ori.alias.model.* - mesh models ONLY (effects/images/spawned Objects are rejected at runtime). Max 128 batches per world
 Object.AddInstance(Offset: Vector, RotationEuler: Vector, Size: Vector, ColorRGB: Vector) // Batch only. Offset cm from batch origin (within +-30000), RotationEuler deg, Size cm, ColorRGB 0..1
 Object.ClearInstances() // Batch only; removes all instances
 Object.GetInstanceCount() -> Number // Batch only
-Object.SetBatchOrigin(Origin: Position) // Batch only; moves whole batch (offsets stay relative)
+Object.SetBatchOrigin(Origin: Position) // Batch only; moves whole batch (offsets stay relative). Counts as a batch edit (full re-upload) - not a per-frame motion lane
 Object.SetBatchCastShadow(Enabled: Bool) // Batch only; default true
 Object.SetBatchMaterial(Material: Object) // Batch only; Material.X (#shader/#texture auto-material) replaces all submesh materials of every instance, None reverts to the model's own
 Object.ShowSelectionRing(Player: Object, Radius: Number, Color: Vector) // RTS selected-unit ground circle on caller; visible only to Player; persists until Hide.
@@ -1401,7 +1486,7 @@ Object.ShowOutlineHighlight(Player: Object, ThicknessPixels: Number, Color: Vect
 Object.HideOutlineHighlight(Player: Object) // Removes this player's outline on caller (no-op if absent)
 Object.EnableLocalSelectionBox(BorderColor: Vector, FillColor: Vector, FillOpacity: Number, BorderWidthPixels: Number, MinDragPixels: Number) // PlayerObject only. Enables a visual-only local drag box for this player; gameplay selection should use Event.MouseDownPosition/Event.MousePosition
 Object.DisableLocalSelectionBox() // PlayerObject only. Disables the visual-only local drag box
-Object.EnableLocalWeaponView(Offset: Position, RotationDegrees: Vector, Scale: Number) // PlayerObject only. Renders this player's equipped weapon as a local first-person camera-attached visual for the owning client (active only in first-person camera). Offset is camera-local cm (+X right, +Y up, +Z forward); RotationDegrees (0,0,0) = barrel forward; e.g. (Position(15, -25, 32), Vector(2, 4, 0), 1.0) for an FPS-style close lower-right framing (a close-in gun keeps the auto-arms shoulder area off-screen). Visual-only; gameplay still uses EquipWeapon/GetHeldWeapon.
+Object.EnableLocalWeaponView(Offset: Position, RotationDegrees: Vector, Scale: Number) // PlayerObject only. Renders this player's equipped weapon as a local first-person camera-attached visual for the owning client (active only in first-person camera). Offset is camera-local cm (+X right, +Y up, +Z forward); RotationDegrees is a first-person camera tilt, (0,0,0) = barrel forward (third person seats the weapon on the hand frame + grip anchor, not on this value); e.g. (Position(15, -25, 32), Vector(2, 4, 0), 1.0) for an FPS-style close lower-right framing (a close-in gun keeps the auto-arms shoulder area off-screen). Visual-only; gameplay still uses EquipWeapon/GetHeldWeapon.
 Object.DisableLocalWeaponView() // PlayerObject only. Disables the local first-person weapon visual
 Object.GetWeaponAnchorWorldDir(AnchorName: Text) -> Vector // Anchor local +X (forward) transformed to world space
 Object.GetWeaponAnchorWorldUp(AnchorName: Text) -> Vector // Anchor local +Z transformed to world space
@@ -1411,7 +1496,7 @@ TileGridCreate(TilesX: Number, TilesY: Number, DefaultWalkable: Bool, EdgeBlocki
 TileGridSetEdgeBlocked(Grid: List, X1: Number, Y1: Number, X2: Number, Y2: Number, Blocked: Bool)
 TileGridIsEdgeBlocked(Grid: List, X1: Number, Y1: Number, X2: Number, Y2: Number) -> Bool
 Object.GetCenterPosition() -> Position
-Object.SetCenterPosition(Position: Position) // Center-anchored twin of SetPosition (same continuous moved semantics)
+Object.SetCenterPosition(Position: Position) // Center-anchored twin of SetPosition (same continuous moved semantics). The center resolves against the object's CURRENT rotation, so rotate first, then place (reversed order drifts rotated parts by half a box). On UI/canvas elements both calls place the element's TOP-LEFT (pivot 0,0); call SetUiPivot(1,1) once to center — GetCenterPosition mirrors the same convention
 Object.SetUiFollowsCursor(IsOn: Bool, OffsetX: Number, OffsetY: Number) // UI element on an owned screen canvas. Engine pins element+children at the owner's cursor + offset every frame, clamped on-screen, drawn latency-free. For tooltips/drag images, not clickable elements
 Object.SetRenderVisibleOnlyToPlayerIndex(PlayerIndex: Number) // World object render/pick visibility only for this player index; also sets owner metadata
 Object.SetRenderVisibleToAllPlayers() // Clears private render/pick visibility; does not clear owner metadata
@@ -1421,14 +1506,17 @@ Object.StopUpperBodyAnimation() // Base clip retakes the upper bones instantly;
 Object.SetCursorImage(ImageAsset: Object)
 Object.SetCursorImage(ImageAsset: Object, HotspotX: Number, HotspotY: Number, Opacity: Number)
 Object.SetWeaponAimCalibration(IsOn: Bool) // Default true: while OrientingWithCameraYaw, the upper body twists so the muzzle (in the weapon-hold pose) aligns with the camera/crosshair ray (aim offset); locomotion bob passes through. Turn off for reloads/cinematic poses where the gun shouldn't track the crosshair.
+Object.SetCursorAim(IsOn: Bool) // Cursor-aim games (top-down/twin-stick): the player's rendered body yaw tracks their live cursor between sim frames, hiding input latency on their own screen; the sim rotation your per-frame LookAt sets stays authoritative. Muzzle/body trails a fast-moving mouse -> turn this on.
+Object.SetCameraFixed(Position: Position, LookAt: Position) // Parks the camera at Position looking at LookAt until a camera-mode switch releases it: persistent across frames AND save/reload, camera collision off while fixed. Security cams, lobby shots, cinematics - no per-frame loop needed.
 SpawnAIPlayer(Name: Text) -> Object // Spawns a bot: a real PlayerObject ('#class player' code, physics, animations) driven by script instead of a user
 Object.IsAIPlayer() -> Bool // True only for players spawned via SpawnAIPlayer()
+Object.IsConnected() -> Bool
 Object.SetAIMoveVector(Direction: Vector) // Bot move input, like a held stick (persists until changed; xy, auto-clamped to length 1). Takes effect next frame
 Object.PressAIAction(Action: Number) // Bot action tap (Action.Jump etc). Down fires next frame, auto-releases the frame after
 Object.DespawnAIPlayer() // Removes a bot (errors on real players). Plain Destroy() also works on bots
 Object.SetTerrainGrass(Model: Object, Material: Object) // Terrain only; Model: Ori.model.* or Ori.model.mesh.* (#mesh blade), None = built-in grass (tuft cards; see SetTerrainGrassStyle); Material: Material.X (#texture auto-material) or None = built-in atlas (usually enough; colors come from the grass knobs). On tuft cards the material's texture replaces the built-in card atlas (2x2 variant cells, uv+clamp+cutout; greyscale luminance = root->tip gradient, color still comes from the grass color knobs). Per-terrain (each terrain can have its own grass style)
 Object.SetTerrainGrassWeightmap(Material: Object) // Terrain only; Material: #texture auto-material; R channel of its color = grass density 0..1 across the terrain; None clears (full density). Overrides #terrain_splat out.grass; prefer out.grass when density should follow the terrain (height/slope), since a #texture cannot see it
-Object.SetWeaponConfig(WeaponModel: Object, IdleAnim: Object, ReloadAnim: Object, FireAnim: Object, ForegripAnchor: Text, GripAnchor: Text, MuzzleAnchor: Text, FireInterval: Number, ReloadDuration: Number) // Register per-weapon-model TPS config. IdleAnim auto-plays as upper-body loop on EquipWeapon (if no upper animation is active); anims accept InvalidId = off. Anchor names may be "" = built-in defaults (foregrip/grip). FireInterval/ReloadDuration are seconds, readable via GetWeaponFireInterval/GetWeaponReloadDuration for script fire loops.
+Object.SetWeaponConfig(WeaponModel: Object, IdleAnim: Object, ReloadAnim: Object, FireAnim: Object, ForegripAnchor: Text, GripAnchor: Text, MuzzleAnchor: Text, FireInterval: Number, ReloadDuration: Number) // Register per-weapon-model held-weapon config. IdleAnim auto-plays as upper-body loop on EquipWeapon (if no upper animation is active); anims accept InvalidId = off. Anchor names may be "" = built-in defaults (foregrip/grip). GripAnchor seats third-person AND the viewmodel; no foregrip anchor on the model = support hand dropped = one-handed hold. FireInterval/ReloadDuration are seconds, readable via GetWeaponFireInterval/GetWeaponReloadDuration for script fire loops.
 Object.GetWeaponFireInterval(WeaponModel: Object) -> Number // Seconds between shots from the weapon model's SetWeaponConfig (0 when unset)
 Object.GetWeaponReloadDuration(WeaponModel: Object) -> Number // Reload seconds from the weapon model's SetWeaponConfig (0 when unset)
 Object.SetEmitting(IsOn: Bool) // EffectObject only. false: stop spawning new particles (existing ones finish while still following the emitter); true: resume. Emitter stays alive.
@@ -1437,7 +1525,7 @@ Object.DestroyImmediate() // EffectObject only. Destroys the emitter and hard-cl
 Object.ShowSelectionRing(Player: Object, Radius: Number, Color: Vector, ZOffset: Number) // As 3-arg; ZOffset cm shifts ring vertically from feet (negative grounds a flying unit's ring)
 SetSkyboxCloudCoverage(Coverage: Number) // Procedural sky only (no SetSkybox asset). Default: 0.1; 0 = clear sky, 1 = overcast
 SetSkyboxHaze(Haze: Number) // Procedural sky only. Default: 0.5; 0.3 = crisp alpine air, 2-3 = hazy horizon
-SetSkyboxStarIntensity(Intensity: Number) // Night star overlay brightness. Default: 1; 0 = no stars
+SetSkyboxStarIntensity(Intensity: Number) // Night star overlay brightness; visible only with the sun near/below the horizon or SetSkyboxIsNight(true). Default: 1; 0 = no stars
 SetSkyboxCloudDetail(Detail: Number) // Procedural sky only. Cloud fractal detail. Default: 1; 0 = soft blobs, 2 = max wispy detail
 SetSkyboxCloudScale(Scale: Number) // Procedural sky only. Cloud pattern size. Default: 1; 0.5 = big clouds, 2 = many small clouds
 SetSkyboxGroundColor(Color: Vector) // Procedural sky only. Ground-bounce light color lighting surfaces from below. Default: (0.34, 0.44, 0.32) dim green; brightness follows the sky
@@ -1452,7 +1540,7 @@ Object.SetTerrainSplat(SplatRules: Text) // Terrain only; SplatRules: #terrain_s
 SetWaterPlanarReflection(Strength: Number, Distortion: Number) // Mirror reflection of the scene on the GLOBAL water surface (SetWaterEnabled) only; placed water meshes always use skybox reflections. Strength 0 disables, Distortion scales wave wobble. Defaults: 0.7, 0.3
 Object.SetHoverHPBarMaterial(Material: Object) // Custom look for caller's hover HP bar; Material.X (#shader or #texture auto-material), None reverts to default. #shader gets ctx.fraction/ctx.background_color and draws the whole bar as one quad (textures don't squash). Persists across SetHoverHPBar updates; ClearHoverBars removes it
 Object.SetHoverSPBarMaterial(Material: Object) // Same as SetHoverHPBarMaterial for the hover SP bar
-Object.SetHoverBarMaterial(BarIndex: Number, Material: Object) // Custom look for caller's SetHoverBar bar at BarIndex (0..28); Material.X or None reverts to default. See SetHoverHPBarMaterial for the #shader contract
+Object.SetHoverBarMaterial(BarIndex: Number, Material: Object) // Custom look for caller's SetHoverBar bar at BarIndex (0..=29); Material.X or None reverts to default. See SetHoverHPBarMaterial for the #shader contract
 SetDefaultHoverBarMaterial(Material: Object) // World default material for all hover bars (HP/SP/custom) without a per-object material; None reverts to built-in look
 StopSound(Sound: Object) // Stops all currently playing and queued instances of this sound asset (e.g. cut off a long music one-shot)
 StopAllSounds() // Stops every currently playing and queued sound
@@ -1534,12 +1622,14 @@ Object.GetTerrainHeightAt(X: Number, Y: Number) -> Number
 Text.Word(Index: Number) -> Text
 Text.WordCount() -> Number
 Text.ToNumber() -> Number
+Text.Length() -> Number // Character count (chars, not bytes - Thai etc. count per character).
+Text.Substring(Start: Number, Count: Number) -> Text // Chars [Start, Start+Count), 0-based, clamped to the text; negative Start or Count <= 0 -> empty Text.
 SetOcclusionCulling(Enabled: Bool) // Default: false (experimental Hi-Z occlusion culling)
 TerrainHeightsErosionFilter(Heights: List, SamplesX: Number, SamplesY: Number, CellCm: Number, ScaleCells: Number, Octaves: Number, StrengthCm: Number, Seed: Number, Mask: List, RidgeMapOut: List) // Stateless erosion filter (Phacelle gullies, no droplet sim): slope-aligned V-gullies + dendritic ridges; altitude fade keeps peaks sharp and valley floors intact. ScaleCells=largest gully size, StrengthCm=max carve/raise, Octaves 1..8, Mask=0..1 weights ([]=all), RidgeMapOut (pass [] List, auto-sized) 0..1: 0=crease 1=ridge (splat/tree/drainage rules). The go-to eroded-mountain look. Heavy: cost ~ sx*sy*Octaves (513 grid + 5 octaves = noticeable load time; prefer <=257 grids or <=4 octaves when loads must stay snappy)
 SetTerrainErosionDetailPercent(Percent: Number) // Global display-only knob: scales the GPU sub-cell erosion-gully detail on all terrain surfaces, and the displayed gully depth of #terrain recipe terrains (100 = default, clamped 0..300, 0 = smooth). Visual only — collision/heights unchanged; grass follows the displayed surface automatically
 TerrainHeightsOriErosion(Heights: List, SamplesX: Number, SamplesY: Number, CellCm: Number, BaseScaleCells: Number, ErosionScaleCells: Number, Octaves: Number, StrengthCm: Number, SlopeStrength: Number, BranchStrength: Number, Seed: Number, Mask: List, ErosionMapOut: List) // OriErosion directional erosion (the #terrain recipe engine as a bulk op; docs/ori_erosion_spec.md): cos-wave gullies steered by the base slope with per-octave branch feedback. BaseScaleCells = base-noise feature size (for slope direction recovery), ErosionScaleCells = first-octave gully size, SlopeStrength ~3, BranchStrength ~0.5, StrengthCm = carve depth. Mask scales accumulation ([] = full); note masked zones sink ~0.5*StrengthCm (water datum). ErosionMapOut (pass [] List, auto-sized) = hx*0.5+0.5 for splat user-plane coloring
 SetTerrainDisplayExtension(RadiusM: Number) // Display-only: renders procedural terrain BEYOND the sim grid out to RadiusM (0 = off), no collision. The generator params come from the world's #terrain block (required; errors without one) — build the sim grid with TerrainHeightsFromTerrain from the same block and the extension continues it seamlessly. Pair with SetCameraFarDistanceM to actually see it
-SetCameraFarDistanceM(Meters: Number) // Display-only camera far plane in meters; 0 = engine default 1000, else clamped 1000..8000. Distant terrain needs SetFogEndDistance raised too; shadows/light clustering keep near-field tuning (distant geometry is unshadowed)
+SetCameraFarDistanceM(Meters: Number) // Display-only camera far plane in meters; 0 = engine default 1000, else clamped 1000..8000. Distant terrain needs SetFogEndDistance raised too; light clustering keeps near-field tuning; static geometry keeps sun shadows to ~2km (cached far layer; desktop)
 Object.SpawnDamageNumber(Amount: Number) // Damage number above caller: pop-arc motion, world-scaled, size grows with Amount; rounds to integer. Call from WasAttacked with Event.Damage. For custom look use the 5-arg SpawnFloatingText overload
 Object.SpawnFloatingText(Text: Text, Color: Vector, SizeScale: Number, Motion: Number, Anchor: Number) // Styled overload: SizeScale multiplies text size; Motion 0=RiseFade 1=PopArc 2=Sticky 3=BounceLand; Anchor 0=constant screen size 1=scales with camera distance
 SetDefaultFloatingTextFont(Font: Object) // World default font for SpawnFloatingText/SpawnDamageNumber (e.g. Ori.font.google.Lobster); None reverts to built-in
@@ -1551,15 +1641,15 @@ Object.SetTerrainGrassSpawnMaterial(Material: Object) // Terrain only; Material:
 Object.SetTerrainSurfaces(SurfacesName: Text) // Terrain only; SurfacesName: #terrain_surfaces block name (up to 8 tiled PBR surfaces packed into texture arrays; lines `surface = <albedo>, <normal>, <tiling_m>[, <orm>[, <grass01>]]` - optional orm alpha carries height for crisp height-blended transitions; optional grass01 = grass density factor on that surface (default 1 for the first surface, 0 for the rest, so grass skips rock/snow); pair with SetTerrainSurfaceWeightsMaterial for per-texel weights). "" clears
 Object.SetTerrainSurfaceWeightsMaterial(Material: Object) // Terrain only; Material: material with a #shader - a CUSTOM surface-weights COMPUTE shader writing 8 blend weights per terrain texel (recipe terrains; covers the display extension via the surface clipmap). None clears
 GetWaterHeightAt(X: Number, Y: Number) -> Number // Deterministic ocean surface height (cm) at world XY this frame - the wave swell all clients agree on (visual-only fine detail excluded). Use for floating/buoyancy. Returns sea level when the ocean is off or flat
-GetWaterNormalAt(X: Number, Y: Number) -> Vector // Deterministic ocean surface unit normal (Z-up) at world XY this frame - pair with GetWaterHeightAt to tilt floating objects (e.g. LookAlong(GetWaterNormalAt(P.X, P.Y)) style alignment). Returns (0,0,1) when the ocean is off or flat
-Object.SetMakesWaterWake(Enabled: Bool) // Opt this object into churning the global ocean: wake ripples + foam while moving through the surface band, and a splash on crossing the surface. Visual only. Tag boats/swimmers/thrown objects; players splash automatically without it. Default: off
+GetWaterNormalAt(X: Number, Y: Number) -> Vector // Deterministic ocean surface unit normal (Z-up) at world XY this frame - pair with GetWaterHeightAt to tilt floating objects (e.g. AlignRotationWith(GetWaterNormalAt(P.X, P.Y)) style alignment). Returns (0,0,1) when the ocean is off or flat
+Object.SetMakesWaterWake(Enabled: Bool) // Opt this object into churning the global ocean: wake ripples + foam while moving through the surface band, and a splash on crossing the surface. Visual only. Tag boats/swimmers/thrown objects; players splash automatically without it. Wake width scales with the hull's horizontal size (floor ~0.6 m); rings spread outward like real water. Default: off
 Object.GetCrosshairRayOrigin() -> Position // Camera eye point the crosshair ray starts from (= this player's camera position; pair with GetCrosshairDirection for the camera pose). Use this (not GetPosition().ShiftUp(N), which sits below the eye and lands low) as the origin for hand-rolled crosshair rays/markers.
 SetWaterSplashEffect(Effect: Object) // Replace the built-in ocean surface-crossing splash particle effect world-wide (all wake/splash objects and players). Pass an Effect asset (e.g. Ori.alias.effect.big_splash). Visual only; the built-in droplet burst is used until this is called
 Object.SetCharacterOverlapIgnoreTag(Tag: Number, IsOn: Bool) // This character's overlap resolution skips objects carrying Tag (walk through them; ground/other collision unaffected, Touched/regions still fire). Call with IsOn=false to restore. Per-tag, stacks
 Object.SetDefaultPlayerControlsEnabled(IsOn: Bool) // Weave2 only, player receiver. true: attach the built-in default player controls (WASD camera-relative move + jump) alongside this class — the one-liner for '#class player' hooks that don't code their own movement. false: detach them (freeze for cutscenes; classless-world players can be frozen from any class). Idempotent
 Object.AttachTo(Parent: Object) // Rigidly ride Parent from the CURRENT relative pose (re-baked from Parent's post-physics transform every tick; overrides this object's own moves). Child must be collision-free: display/effect/light/marker objects, or SetCanCollide(false) first. Chains allowed (arm -> gun); cycles error. Replaces per-frame SetPosition follow loops. Order-sensitive in OnSpawned (parent may not be placed yet) - prefer the 3-arg overload there
 Object.AttachTo(Parent: Object, LocalPosition: Position, LocalRotation: Vector) // Explicit-mount overload: LocalPosition (absolute cm) and LocalRotation (euler degrees) in Parent's local frame; safe in OnSpawned. The frame runs CENTER-to-CENTER (not the bottom-center pivot GetPosition/#mesh use): seat a child by adding half ITS height to the offset. Offsets don't rescale when Parent's size changes - re-attach after growth
-Object.AttachToAnchor(Parent: Object, AnchorName: Text) // AttachTo at a named model anchor of Parent's mesh (e.g. "muzzle", "grip"); errors when the anchor doesn't exist (anchors resolve after asset import). The anchor's axis is its local +Z but object/effect forward is local +X - directional effects on an anchor need a LocalRotation (usually RotY +-90). Anchor offsets don't follow Parent scale. A `bone:`-bound socket anchor makes the child visually ride that bone's animation (sim pose stays rest)
+Object.AttachToAnchor(Parent: Object, AnchorName: Text) // AttachTo at a named model anchor of Parent's mesh (e.g. "muzzle", "grip"); errors when the anchor doesn't exist (anchors resolve after asset import). The anchor's axis is its local +Z but object/effect forward is local +X - directional effects on an anchor need a LocalRotation (usually RotY +-90). The mount point follows the parent's scale at attach time (where the socket visually sits); captured offsets don't re-follow LATER parent rescales. A `bone:`-bound socket anchor makes the child visually ride that bone's animation (sim pose stays rest)
 Object.Detach() // Remove this object's attachment; it keeps its current world transform
 Object.GetAttachParent() -> Object // Attachment parent, or None-like non-existing Object when not attached (check with Exists())
 EaseIn(T: Number) -> Number
@@ -1579,11 +1669,11 @@ Vector.RotateByEuler(Yaw: Number, Pitch: Number, Roll: Number) -> Vector // Rota
 Vector.ToYawPitch() -> Vector // Treat this vector as a direction: returns Vector(yaw, pitch, 0) in degrees. Yaw 0 = +X (counter-clockwise toward +Y), pitch positive = up. Zero-length input gives (0, 0, 0)
 YawPitchToDirection(Yaw: Number, Pitch: Number) -> Vector // Unit direction from aim angles in degrees (inverse of ToYawPitch): yaw 0 = +X, pitch positive = up
 SetDefaultFont(Font: Object) // World default font for all UI text/buttons that don't set one (e.g. Ori.font.google.Fredoka); None reverts to the engine default (Nunito)
-SetModelAnchor(Model: Object, AnchorName: Text, LocalPosition: Position, LocalRotationEulerDegrees: Vector) // Weapon sits wrong in the hand / anchor misplaced -> define or replace any named anchor ("grip", "muzzle", custom): model-root local, cm Z-up, rotation maps anchor axes (+X = forward) into model axes; wins over the asset's own anchors, call before or after EquipWeapon
+SetModelAnchor(Model: Object, AnchorName: Text, LocalPosition: Position, LocalRotationEulerDegrees: Vector) // Weapon sits wrong in the hand / anchor misplaced -> define or replace any named anchor ("grip", "muzzle", custom): model-root local, cm Z-up, rotation maps anchor axes (+X = forward) into model axes; wins over the asset's own anchors, call before or after EquipWeapon; a grip anchor seats BOTH the third-person hold and the EnableLocalWeaponView viewmodel
 SwitchStage(Name: Text) // `#stage` projects only: switch to another stage of this project (multiplayer-safe; all stages ship in the project source, so Name may be dynamic). Use LoadWorldTransferPush before switching to carry values across.
-Object.SetRenderOffset(OffsetCm: Vector, RotationEulerDegrees: Vector, Scale: Number) // Visual-only offset on top of the sim transform (bob/lean/sway); colliders/AI/queries unaffected. OffsetCm shifts in WORLD space (not rotated into the object's local frame); rotation composes after the object's own, Scale multiplies visuals. Call per-frame for procedural animation; ClearRenderOffset resets
+Object.SetRenderOffset(OffsetCm: Vector, RotationEulerDegrees: Vector, Scale: Number) // World/display/player objects only (crowds/instance batches reject). Visual-only offset on top of the sim transform (bob/lean/sway); colliders/AI/queries unaffected. OffsetCm shifts in WORLD space (not rotated into the object's local frame); rotation composes after the object's own and pivots at the object CENTER (SetRotation pivots at origin = ref-box bottom-center). Call per-frame for procedural animation; ClearRenderOffset resets
 Object.ClearRenderOffset() // Remove this object's visual render offset
-Object.RaycastObject(Origin: Position, Direction: Vector, MaxDistance: Number) -> Object // Nearest object the ray hits within MaxDistance (this object excluded), or a None-like Object on miss (check Exists()). Hits anything solid incl. untagged walls/floor/terrain - the go-to for projectile impact and line-of-sight tests. Direction need not be normalized
+Object.RaycastObject(Origin: Position, Direction: Vector, MaxDistance: Number) -> Object // Nearest object the ray hits within MaxDistance (this object excluded), or a None-like Object on miss (check Exists()). Hits anything solid incl. untagged walls/floor/terrain - the go-to for projectile impact and line-of-sight tests. Direction need not be normalized; fast projectiles: raycast the segment travelled this frame (origin = previous position, MaxDistance = the step) - positional overlap checks skip thin targets between frames
 Object.RaycastObjectWithTag(Origin: Position, Direction: Vector, MaxDistance: Number, Tag: Number) -> Object // RaycastObject limited to objects carrying Tag
 Object.RaycastObjectIgnoreTag(Origin: Position, Direction: Vector, MaxDistance: Number, IgnoreTag: Number) -> Object // RaycastObject that skips objects carrying IgnoreTag (e.g. ignore pickups/projectiles)
 Object.RaycastPosition(Origin: Position, Direction: Vector, MaxDistance: Number) -> Position // Impact point of RaycastObject's ray; on miss returns Origin + Direction.GetNormal() * MaxDistance
@@ -1595,11 +1685,11 @@ TileGridHasLineOfSight(Grid: List, StartX: Number, StartY: Number, StartZ: Numbe
 TileGridSmoothPath(Grid: List, Path: List) -> List
 Object.SetTerrainGrassVisible(Visible: Bool) // Terrain only; false = no grass on this terrain (deserts/cities/moon), true = grass even while the terrain object is hidden, and counts as grass intent (enables the auto ground tint = full meadow look). Unset default: sparse untinted grass following terrain visibility. Same as declarative grass_visible
 SpawnEffectAimed(Effect: Object, Position: Position, Direction: Vector) -> Object // Spawns with the effect's authored up/emission axis aimed along Direction (e.g. exhaust: SpawnEffectAimed(fx, GetPosition(), -GetFacingDirection())). Zero direction = unrotated.
-Object.SetEmitterLightsEnabled(Enabled: Bool)
+Object.SetEmitterLightsEnabled(Enabled: Bool) // Toggle the lights this object's mesh bakes via emitter(...) sockets (default on) - e.g. lamps dark at day
 Object.GetEmitterLightsEnabled() -> Bool
 SetFogSkyboxAffect(Percent: Number) // Default: 0 (sky ignores distance fog). 100 = distant sky fully fogged, ~30 = horizon haze
 TileGridSetWalkableFromStaticColliders(Grid: List, OriginTile: Vector, ZMin: Number, ZMax: Number)
-Object.SetCursorUiMode(On: Bool)
+Object.SetCursorUiMode(On: Bool) // true: release mouse-look AND show the cursor so players can click UI (menus/shops); false: restore gameplay look. Prefer over toggling SetIsMouseLookOn/SetMouseVisible separately.
 Object.SetBoneRotation(BoneName: Text, EulerDegrees: Vector) // Replace the named bone(...) rig joint's local rotation (Euler degrees Z-up, #clip convention); wins over the playing clip for that bone until cleared. Max 16 bones per object. Display-only: colliders/physics unaffected. Call per-frame in forever{} for tails, breathing, head tracking
 Object.ClearBoneOverrides() // Remove all of this object's bone rotation overrides (SetBoneRotation, Mix, and BoneLookAt)
 Object.SetBoneRotationMix(BoneName: Text, EulerDegrees: Vector, Weight01: Number, BlendSeconds: Number, Additive01: Number) // Weighted, smoothed bone layer over the playing clip: Weight01 blends toward EulerDegrees, BlendSeconds eases changes, Additive01=1 offsets the clip pose instead of replacing it. On a rig with no clip playing it animates from rest - the fully procedural mode. Max 16 bones per object; display-only
@@ -1611,6 +1701,73 @@ AnyBasicType.NearestObjectXYWithTagNotOnTeam(Tag: Number, TeamId: Number, MaxDis
 AnyBasicType.NearestObjectWithTagOnTeam(Tag: Number, TeamId: Number, MaxDistance: Number) -> Object
 AnyBasicType.NearestObjectXYWithTagOnTeam(Tag: Number, TeamId: Number, MaxDistance: Number) -> Object
 AnyBasicType.GetObjectsWithinDistanceWithTagNotOnTeam(Distance: Number, Tag: Number, TeamId: Number) -> List // Tag-carriers with team != TeamId within Distance cm (AoE damage lists); for single-target picks prefer NearestObjectWithTagNotOnTeam
+GetRayHitPosition(Position: Position, Direction: Vector) -> Position // Unfiltered: first hit of anything (dynamic + static). No max-distance param (range-gate on GetRayHitDistance); on miss returns Position + Direction * 1000000.
+GetRayHitObject(Position: Position, Direction: Vector) -> Object // Unfiltered: first hit object. Returns null Object on miss (check .Exists()).
+GetRayHitStaticPosition(Position: Position, Direction: Vector) -> Position // Unfiltered: first STATIC hit (terrain, walls). No max-distance param (range-gate on GetRayHitDistance); on miss returns Position + Direction * 1000000.
+GetRayHitStaticObject(Position: Position, Direction: Vector) -> Object // Unfiltered: first static hit object. Returns null Object on miss (check .Exists()).
+Object.GetAnchorWorldPos(AnchorName: Text) -> Position // World position of a socket/anchor on THIS object's own mesh (declare socket("Name", ...) in its #mesh), scaled with the object — unlike AttachToAnchor offsets, this follows object scale. Bone-bound sockets resolve the rest pose. Errors when the anchor doesn't exist.
+Object.GetAnchorWorldDir(AnchorName: Text) -> Vector // Anchor local +X (forward) rotated to world space; unit vector, unaffected by object scale. The socket axis: parameter is the anchor's local +Z (see GetAnchorWorldUp).
+Object.GetAnchorWorldUp(AnchorName: Text) -> Vector // Anchor local +Z (the socket's declared axis:) rotated to world space; unit vector, unaffected by object scale.
+IsWorldReady() -> Bool // true once the current load's scene OnSpawned batch has fully started (see event OnWorldReady); false again from the start of a new load/restart. Poll it before placing things on procedurally built ground/rooms.
+SetShadowDistance(DistanceMeters: Number) // Crisp sun-shadow range in meters; past it only static geometry casts (coarse cached shadows to ~2km, desktop). Default: 50 (character scale); building-onto-building / city blocks need 200-300. Cost: shadow edges get chunkier as range grows
+SetDebugRenderMode(Mode: Number) // Diagnostic view: renders ONE lighting/material component ungraded instead of the shaded frame, to tell wrong albedo from wrong light from wrong geometry. 0 off, 1 albedo, 2 normal, 3 material ao, 4 ssao, 5 ao*ssao (what ambient is multiplied by - 0 means no ambient can reach the surface), 6 direct sun, 7 ambient/sky, 8 shadow mask, 9 roughness, 10 metallic, 11 emissive, 12 local lights. Ship worlds with 0; the playtest/live_screenshot `debug_view` parameter is the per-capture equivalent. Default: 0
+PersistClear()
+Object.SetInstance(Index: Number, Offset: Vector, RotationEuler: Vector, Size: Vector, ColorRGB: Vector) // Batch only. Overwrites the instance at Index (0..GetInstanceCount-1); args like AddInstance. Errors on out-of-range Index
+Object.RemoveInstance(Index: Number) // Batch only. Swap-remove: the LAST instance moves into Index, count shrinks by 1. Errors on out-of-range Index
+SetSkyboxColor(Color: Vector) // Procedural sky only. Base color multiplied into the sky bake before grading (alien/stylized skies); SetSkyboxTint post-multiplies the graded display instead. Default: (1, 1, 1)
+GetRayHitDistance(Position: Position, Direction: Vector, Tag: Number) -> Number // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. Distance in cm to the first hit, -1 on miss — range gates and damage falloff.
+GetRayHitDistance(Position: Position, Direction: Vector) -> Number // Unfiltered. Distance in cm to the first hit, -1 on miss — range gates and damage falloff; prefer this over measuring to GetRayHitPosition, whose miss sentinel is Position + Direction * 1000000.
+SetSkyboxCloudType(Type: Number) // Procedural sky only. Cloud vertical form. Default: 0.35; 0 = flat haze layer, 1 = towering cumulus
+CreateStaticInstanceBatch(Model: Object, Origin: Position) -> Object // Display-only STATIC scatter batch (see <procedural_generation>); Model: Ori.model.* (basics like Ori.model.cone work) or Ori.alias.model.* - mesh models ONLY (effects/images/spawned Objects are rejected at runtime). Max 128 live per world - Destroy() frees. Never mutate per frame - each edit (SetBatchOrigin included) re-uploads the whole batch. Sway/shimmer: vertex #shader on the model's material; instances that truly move: objects or #particles
+GetRayHitPart(Position: Position, Direction: Vector, Tag: Number) -> Text // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. Names the hit volume posed by the target's current animation: "head"/"torso"/"pelvis"/"upper_arm_l"/"forearm_r"/"thigh_l"/"shin_r"/...; "" on miss, rigless target, or a hit outside every volume (treat as a plain body hit) — gate damage on GetRayHitObject, use the part for multipliers.
+GetRayHitPart(Position: Position, Direction: Vector) -> Text // Unfiltered twin: same part names and "" semantics as GetRayHitPart.
+TileGridFlowFieldBuild(Grid: List, GoalTiles: List) -> List
+Object.StartTileFlowFollow(Field: List, Grid: List, OriginTile: Vector, Speed: Number) -> Bool
+TilePathFollowTakeBlocked() -> List
+Object.SetSubmeshTint(SubmeshIndex: Number, TintRGB: Vector) // THIS object's per-submesh tint (faction colors): same LOD-flattened slot space as SetAssetSubmeshTint; multiplies SetColor and the asset tint (black kills). Tint (1,1,1) clears the slot. Skinned models fully supported; tinted statics leave the LOD-collapse fast path; InstanceBatch/TileMap handles reject
+SetFogOfWarEnabled(Enabled: Bool) // RTS fog of war: per-TEAM vision grid sized from the largest terrain (runtime error without one). Each viewer sees own-team vision; unexplored = black, explored-but-unseen = grey memory (objects hidden), visible = clear. Radius discs only (no line-of-sight blocking); audio is not gated. Enable once at world start; false clears everything. No default sight: until Object.SetSightRadius lands on TEAMED objects, teamed viewers see a near-black stage - grant sight in the same change as the enable
+Object.SetSightRadius(RadiusCm: Number) // THIS object provides fog vision to ITS team (GetTeam) in a RadiusCm disc, refreshed ~every 8 ticks while alive; 0 unregisters. Teamless objects provide no vision. Give it to units/buildings after SetFogOfWarEnabled
+IsPositionVisibleToTeam(Position: Position, TeamId: Number) -> Bool // True when the position is currently in TeamId's live vision (explored-only memory returns false). Unset/no-team viewers see everything; a team that never held vision sees nothing. Fog disabled = always true. For AI/scripting; rendering hides automatically
+GetTerrainBoundsMin() -> Position // World-space min corner of the LARGEST terrain (z = lowest height sample). Errors when no terrain exists. Fog and the minimap snapshot use the same terrain.
+GetTerrainBoundsMax() -> Position // World-space max corner of the LARGEST terrain (z = highest height sample). Minimap math: uv = (P - Min) / (Max - Min).
+GetRayHitNormal(Position: Position, Direction: Vector, Tag: Number) -> Vector // Tag filters to objects WITH that tag; 0 is a real tag index, NOT "no filter" — use the 2-arg overload for unfiltered rays. Unit surface normal at the hit (world axes; box = face normal, sphere = radial); zero Vector on miss.
+GetRayHitNormal(Position: Position, Direction: Vector) -> Vector // Unfiltered twin: same normal and zero-Vector miss semantics as GetRayHitNormal.
+Object.SetSavedToWorld(IsOn: Bool) // Script-spawned objects are TRANSIENT: saving the world never writes them into the scene text (your Spawn code recreates them). SetSavedToWorld(true) makes this one save like an editor-placed object; editor-placed objects always save
+ArcToTarget(From: Position, To: Position, FlightSeconds: Number, GravityCmS2: Number) -> List // Arc handle leaving From and passing through To exactly at FlightSeconds under GravityCmS2 (positive cm/s^2, e.g. 980; captured in the handle - world SetGravity is NOT used). Query with ArcPositionAt/ArcVelocityAt/ArcFlightSeconds.
+ArcToTargetWithPeak(From: Position, To: Position, PeakHeightCm: Number, GravityCmS2: Number) -> List // As ArcToTarget but sized by apex height above From (the 'make it float higher' knob); errors when PeakHeightCm can't reach the target height. Read the flight time back with ArcFlightSeconds.
+ArcFlightSeconds(Arc: List) -> Number // Seconds from launch until the arc reaches its target - the contact time to hand to MoveToArriveIn / PlayAnimationHittingContactIn.
+ArcPositionAt(Arc: List, Seconds: Number) -> Position // Closed-form arc sample at Seconds. Drive the ball each frame with SetPosition(ArcPositionAt(arc, t)) - no drift, no lerp seams between phases. Past the flight time it keeps extrapolating downward; stop driving it yourself.
+ArcVelocityAt(Arc: List, Seconds: Number) -> Vector // Arc velocity at Seconds: face the object along travel, or reflect it on a block/bounce.
+GetAnimationLeadSeconds(AnimationAsset: Object, ContactPercent: Number) -> Number // Seconds from clip start to ContactPercent at normal playback - how early PlayAnimationHittingContactIn can fire. Accounts for SetAnimationAssetSpeedFactor; never derive this from GetAnimationDuration by hand.
+Object.PlayAnimationHittingContactIn(Animation: Object, ContactPercent: Number, SecondsUntilContact: Number) -> Bool // Call every frame with the remaining seconds: false while too early, then plays Animation rate-scaled (0.5x..2x, skipping into the clip when already late) so ContactPercent lands exactly SecondsUntilContact from now, and true from then on. Will not restart a clip it already started, so no 'started' guard var - use a dedicated action clip, not one that may already be playing.
+Object.MoveToArriveIn(Target: Position, SecondsRemaining: Number) // One frame of movement sized to arrive at Target in SecondsRemaining - recompute the remainder each frame like the other continuous movers (a constant argument eases out and never lands; 0 or negative arrives this frame). Auto-move animations see the speed, so characters run instead of sliding. On gravity characters Z is discarded (as with MoveTowardContinuous).
+Object.MoveToArriveInFacing(Target: Position, SecondsRemaining: Number) // MoveToArriveIn, turning the object's forward (+X) along the movement direction.
+Object.AttachToAnchor(Parent: Object, ParentAnchor: Text, ChildAnchor: Text) // Mounts the CHILD's named socket onto the parent's socket (position + orientation) - the part pivots at its socket instead of its center
+GetAllObjectsWithTagOnTeam(Tag: Number, TeamId: Number) -> List // GetAllObjectsWithTag filtered to TeamId (SetTeam / scene team =; unset objects never match). Same allocate-per-call advice
+AdvertiseSession() // List this session in the project's public session browser (hosts can also toggle this in the engine session panel; last write wins). Not a replication/server-authority API.
+StopAdvertisingSession() // Unlist this session (it stays joinable via share link).
+ListSessions() // Request the project's listed sessions (identity automatic, exact content version). Results update Session* getters and fire OnSessionListUpdated; state 2 with 0 sessions = nobody hosts this exact version.
+JoinSession(RelayPubkey: Text) // Join a listed session by SessionRelayPubkey; deterministic shared sim still applies after joining.
+SessionCount() -> Number // Number of listed sessions from the latest ListSessions result.
+SessionRelayPubkey(Index: Number) -> Text // Relay pubkey for a listed session; pass to JoinSession.
+SessionConnectId(Index: Number) -> Text // Debug/connect id for a listed session; usually not needed for gameplay code.
+SessionDisplayName(Index: Number) -> Text // Host display name for a listed session.
+SessionRefreshState() -> Number // Latest list state: 0 idle, 1 pending, 2 ok, 3 error (read SessionErrorText).
+SessionStage(Index: Number) -> Text // #stage name a listed session is currently on (empty for stageless projects); show or filter it in a browser.
+SessionErrorText() -> Text // Reason for state 3 (empty otherwise), e.g. relay unreachable or no loaded world.
+SessionPlayerCount(Index: Number) -> Number // Connected player count for a listed session (0 = unknown).
+OpenSessionBrowser() // Open the engine's built-in session browser UI (no-op in headless/validation).
+Object.ShatterAndDestroy() // Destroy() plus a debris burst from the model's baked chunk set (needs `#mesh Name destructible: <word>`; without it, plain Destroy()). Debris is display-only - no sim collision.
+TerrainSlopeAtXY(X: Number, Y: Number) -> Number // slope01 (g/(1+g); 0.5 = 45deg) of topmost terrain at world XY; 1 if no terrain (void = unwalkable). Walkers wedge above ~0.5
+TileGridSetWalkableFromTerrain(Grid: List, OriginTile: Vector, MaxSlope01: Number)
+TileGridSetEdgesFromTerrain(Grid: List, OriginTile: Vector, MaxStepCm: Number)
+TileGridStampRect(Grid: List, X1: Number, Y1: Number, X2: Number, Y2: Number, Blocked: Bool)
+TileGridStampObject(Grid: List, OriginTile: Vector, Obj: Object, Blocked: Bool)
+TileGridIsReachable(Grid: List, X1: Number, Y1: Number, X2: Number, Y2: Number) -> Bool
+TileGridIsReachable(Grid: List, X1: Number, Y1: Number, Z1: Number, X2: Number, Y2: Number, Z2: Number) -> Bool
+TileGridBakeCrowdObstacles(Grid: List, OriginTile: Vector)
+TerrainHeightsFromTiers(Heights: List, SamplesX: Number, SamplesY: Number, Tiers: Text, TierCm: Number) // REPLACE Heights from an ASCII tier map (digits = tier * TierCm, '.' = 0, 'r' = ramp; first row = max Y). See <terrain_generation>
+RaiseWorldError(Message: Text) // Fail-loud assert: raises a Weave runtime error carrying Message (validation surfaces it; in play the program pauses like any script error)
 
 </built_in_function_list>
 
@@ -1619,7 +1776,7 @@ AnyBasicType.GetObjectsWithinDistanceWithTagNotOnTeam(Distance: Number, Tag: Num
 - X/Y are in cell units: scale world coords down (e.g. Fbm2(pos.X / 800, pos.Y / 800, 4, 7)); features repeat at integer-cell scale. Use a different Seed per layer (trees vs rocks).
 - SpawnTerrainFromHeights spawns a collidable terrain heightfield from code; heights are row-major (iy * SamplesX + ix), in cm relative to Position.Z. Terrain XY is centered on Position.
 - terrain.GetTerrainHeightAt(X, Y) returns the world-space surface Z at world (X, Y) (bilinear); errors if the caller has no heightfield or (X, Y) is outside it.
-- Terrain grass: every terrain grows sparse built-in grass automatically; grass_visible = false / SetTerrainGrassVisible(false) removes it entirely (deserts, cities). The ground under the blades is the terrain's own splat/material — style it with `#terrain_splat` rules or terrain layers. Set from code via terrain.SetTerrainGrass / terrain.SetTerrainGrassWeightmap / terrain.SetTerrainGrassHeightCm / terrain.SetTerrainGrassStyle / terrain.SetTerrainGrassVisible (all per-terrain), or declaratively on terrain blocks (grass_model = "mesh.X", grass_material = "material.X", grass_weightmap = "image.X" or a #texture color, grass_height_cm = 28, grass_visible = true/false, grass_style = "blades"). No model = built-in grass: cheap alpha-cut tuft cards by default, or geometry blades via SetTerrainGrassStyle(1) (heavier, best with SetGrassSpacingCm 8..15 for dense hero fields). Custom #mesh blade budget: tiny tuft (<=100 verts), single material slot, bottom-anchored at Z=0; blade size comes from authoring the mesh at the right cm size, then grass_height_cm rescales it (28 = as-authored). Global tuning calls: SetGrassSpacingCm, SetGrassTerrainActiveDistanceM, SetGrassCullDistanceM, SetGrassFadeDistancePercent, SetGrassFarThinningPower; look calls: SetGrassRootColor, SetGrassTipColor, SetGrassBrightnessVariationPercent, SetGrassSizeVariationPercent, SetGrassHeightMinCm, SetGrassHeightMaxCm, SetGrassBladeWidthPercent, SetGrassWavePeriodCm, SetGrassWindStrengthCm, SetGrassWindSpeedPercent.
+- Terrain grass: every terrain grows sparse built-in grass automatically; grass_visible = false / terrain.SetTerrainGrassVisible(false) removes it entirely (deserts, cities). The ground under the blades is the terrain's own splat/material — style it with `#terrain_splat` rules or terrain layers. Set from code via terrain.SetTerrainGrass / terrain.SetTerrainGrassWeightmap / terrain.SetTerrainGrassHeightCm / terrain.SetTerrainGrassStyle / terrain.SetTerrainGrassVisible (all per-terrain), or declaratively on terrain blocks (grass_model = "mesh.X", grass_material = "material.X", grass_weightmap = "image.X" or a #texture color, grass_height_cm = 28, grass_visible = true/false, grass_style = "blades"). No model = built-in grass: cheap alpha-cut tuft cards by default, or geometry blades via SetTerrainGrassStyle(1) (heavier, best with SetGrassSpacingCm 8..15 for dense hero fields). Custom #mesh blade budget: tiny tuft (<=100 verts), single material slot, bottom-anchored at Z=0; blade size comes from authoring the mesh at the right cm size, then grass_height_cm rescales it (28 = as-authored). Global tuning calls: SetGrassSpacingCm, SetGrassTerrainActiveDistanceM, SetGrassCullDistanceM, SetGrassFadeDistancePercent, SetGrassFarThinningPower; look calls: SetGrassRootColor, SetGrassTipColor, SetGrassBrightnessVariationPercent, SetGrassSizeVariationPercent, SetGrassHeightMinCm, SetGrassHeightMaxCm, SetGrassBladeWidthPercent, SetGrassWavePeriodCm, SetGrassWindStrengthCm, SetGrassWindSpeedPercent.
 - The same noise is available in #shader WGSL: ori_hash2(x, y, seed), ori_value_noise2(x, y, seed), ori_fbm2(x, y, octaves, seed) (f32; seed/octaves u32/i32), ori_hash2_cell(cx, cy, seed) -> u32. Matches the Weave functions exactly at integer lattice points, so sim placement and shader visuals can share one layout.
 Example (hills + deterministic tree scatter):
 #class WorldGen
@@ -1653,6 +1810,8 @@ event OnSpawned {
 - Flat gameplay areas: TerrainHeightsFlattenDisc/Rect/Path AFTER noise/erosion so nothing roughens them again. ThermalErode + RemapCurve make raw noise look natural (erode first, then remap for plateaus/cliffs).
 - Prefer 129..257 samples per axis (513 max; big lists inflate sim state — generate in OnSpawned local vars so they are GC'd after spawn).
 - GroundHeightAtXY(x, y) -> world Z cm of the topmost ground at world XY (downward raycast over terrain + static colliders; 0 if nothing). Use for placing props/villages on generated ground; works immediately after SpawnTerrainFromHeights in the same event.
+- TerrainSlopeAtXY(x, y) -> slope01 of the topmost terrain at world XY (0.5 = 45deg; no terrain = 1, treat void as unwalkable). Slopes steeper than ~0.5 silently immobilize walkers - keep unit routes below it or block those tiles/edges in the nav grid (see <tile_pathfinding>).
+- TerrainHeightsFromTiers(Heights, SamplesX, SamplesY, Tiers, TierCm) REPLACES the field with plateau heights from an ASCII tier map in a triple-quoted Text (digits 0-9 = tier, h = tier * TierCm; '.' = 0; 'r' = ramp graded toward its lower neighbor; rows = lines, FIRST row = MAX Y / north). Hand-drawn RTS cliff maps: one char per nav tile, then TileGridSetEdgesFromTerrain(MaxStepCm = TierCm/3) derives the cliff edges; compose Smooth/Erode/splat after.
 - Realism combo: Warp after base noise (kills grid-straight lines), then ErosionFilter (fast stateless gullies/ridges; run AFTER RemapCurve so the detail lands at final scale, and its look continues sub-cell on the GPU display surface). Avoid HydraulicErode/ThermalErode by default — slow iterative CPU sims; reach for HydraulicErode only when routed drainage or its flow/deposit masks are truly needed. MaskFromFlow gives a wetness mask WITHOUT eroding.
 - Terrain-following rivers: FlowPath traces downhill from a spring cell into a CarvePath-ready point list (stops at sea level = MinHeightCm). Check PathXYOut has >= 4 numbers (2 points) before carving.
 - Roads that climb: GradePath lerps the flatten height start->end along the path (use terrain heights at the endpoints); FlattenPath only does constant height.
@@ -1717,20 +1876,20 @@ Two terrain display types:
 </terrain_generation>
 
 <procedural_generation_batches>
-- InstanceBatch: thousands of decorative copies of one model as ONE display object (petals, pebbles, grass tufts). Far cheaper than SpawnObject; instances have no physics/logic/picking and can't be edited individually (only ClearInstances + re-add). Use SpawnObject for anything interactive.
+- InstanceBatch: thousands of decorative copies of one model as ONE display object (pebbles, rubble, grass tufts). Instances have no physics/logic/picking and are invisible to the editor - never clickable, movable, or saved there; the layout lives in this code (edit by index via SetInstance/RemoveInstance, or ClearInstances + re-add). Identical static meshes already render as one instanced draw either way - a batch saves per-object sim/load cost (spawn, rollback state, join checkpoints), not draw calls. Copies a human should hand-place or that need any interactivity: SpawnObject. Drifting petals/leaves/debris: #particles mesh components, not a batch. Animated look on scatter (sway/shimmer): vertex #shader on the model's material - never per-frame batch edits (SetBatchOrigin included), and batch handles reject Object.* calls like SetRenderOffset.
+- Batches outlive their creator; only Destroy() frees a slot (128 live max). One batch per model kind, edited in place - don't create per region or per round.
 - Model can be a basic primitive (Ori.model.cube/cone/wedge/...); add SetBatchMaterial(Material.X) for textured scatter without any market asset.
-Example (3000 petals):
-var petals = CreateInstanceBatch(Ori.alias.model.petal, Origin())
-for i in 0..3000 {
-    petals.AddInstance(Vector((Hash2(i, 0, 5) - 0.5) * 4000, (Hash2(i, 1, 5) - 0.5) * 4000, 150),
-        Vector(0, 0, Hash2(i, 2, 5) * 360), Vector(14, 14, 2), Vector(0.95, 0.45, 0.78))
+Example (2000 pebbles):
+var pebbles = CreateStaticInstanceBatch(Ori.alias.model.pebble, Origin())
+for i in 0..2000 {
+    var s = 6 + Hash2(i, 3, 5) * 14
+    pebbles.AddInstance(Vector((Hash2(i, 0, 5) - 0.5) * 4000, (Hash2(i, 1, 5) - 0.5) * 4000, 0),
+        Vector(0, 0, Hash2(i, 2, 5) * 360), Vector(s, s, s * 0.7), Vector(0.62, 0.6, 0.55))
 }
 </procedural_generation_batches>
 
 <ternary>
-- Use If(cond, a, b) for ternary (No ?: operator)
-- If(cond, a, b) -> T
-- Only the taken branch is evaluated
+- No ?: operator - use If(cond, a, b) -> T; only the taken branch is evaluated
 </ternary>
 
 <events>
@@ -1745,6 +1904,8 @@ for i in 0..3000 {
 - All OnPreSpawn finish for the frame before the first OnSpawned runs
 - Ordering between objects' OnPreSpawn is unspecified
 - GameCommand fires on every class that declares it when a user sends a command text message (headless build orders or chat-driven commands). Event.Text is the raw command line, Event.Sender the sender's player object. Parse Text yourself (e.g. "build house 3 4").
+- OnWorldReady fires once per load (again after RestartGame) when every scene object's OnSpawned has STARTED (run to its first yield), spilled load batches included. Poll IsWorldReady() for spawn/placement code that depends on procedurally built ground or rooms (terrain, BuildRoom) instead of Wait() timers; a handler that Wait()s mid-body may still be mid-flight at ready.
+- OnPlayerLeft fires on the leaver's player object the moment IsConnected() flips false (the body stays ~90s for reconnect; OnDestroy only at grace expiry): clear SetHoverText labels / roster rows here. OnPlayerReconnected fires when the SAME body resumes within the grace; a post-grace rejoin is a fresh spawn (OnSpawned).
 </events>
 <event_list>
 event OnPreSpawn
@@ -1753,7 +1914,7 @@ event OnDestroy
 event WasAttacked
 	Event.Attacker .. Object
 	Event.Damage .. Number
-event OnLobbySessionListUpdated
+event OnSessionListUpdated
 event GameCommand
 	Event.Text .. Text
 	Event.Sender .. Object
@@ -1775,8 +1936,10 @@ event ClickThisObject
 	Event.Presser .. Object
 event ClickThisUI
 	Event.Presser .. Object
+	Event.ClickFraction .. Vector
 event ClickThisButton
 	Event.Presser .. Object
+	Event.ClickFraction .. Vector
 event ClickButton
 	Event.ButtonClicker .. Object
 	Event.ClickedButton .. Object
@@ -1882,6 +2045,9 @@ event InventoryDropOnWorld
 	Event.SlotIndex .. Number
 	Event.DropObject .. Object
 	Event.DropPosition .. Position
+event OnWorldReady
+event OnPlayerLeft
+event OnPlayerReconnected
 
 </event_list>
 
@@ -1905,7 +2071,7 @@ event InventoryDropOnWorld
     </3. Physics step & motion application>
     <Single-frame overwrite rule>
     - See <movement_laws>: one continuous translation + one rotation per tick, last call wins.
-    - Jump() and gravity own a character's vertical velocity: MoveWithVelocityContinuously on a gravity-affected character never writes Z at all (the component is discarded), so scripted vertical motion there needs SetCharacterGravity(false) first. On DYNAMIC bodies a same-tick SetPhysicsVelocity built from a velocity read taken BEFORE a JumpInDirection writes the old Z back and the jump never lifts - re-read velocity after the jump, or keep script movement XY-only and let physics own Z.
+    - Jump() and gravity own a character's vertical velocity: MoveWithVelocityContinuously on a gravity-affected character never writes Z at all (the component is discarded), so scripted vertical motion there needs EnableCharacterGravity(false) first. On DYNAMIC bodies a same-tick SetPhysicsVelocity built from a velocity read taken BEFORE a JumpInDirection writes the old Z back and the jump never lifts - re-read velocity after the jump, or keep script movement XY-only and let physics own Z.
     </Single-frame overwrite rule>
     <Readback semantics> 
     - Within the same tick, GetPosition()/GetRotation() return the pre-physics values. Updated transforms become visible to script on the next tick.
@@ -1913,6 +2079,7 @@ event InventoryDropOnWorld
     <Notes>
     - OnSpawned ordering across different objects is unspecified.
     - Per-object forever/Update brains are the right default. Past a few hundred always-active objects the per-object dispatch itself dominates the frame - switch to one manager forever loop calling into a kept List of members (u.Tick() per member; ~8x cheaper at 600 objects), and for per-tick targeting call NearestObjectWithTagNotOnTeam(Tag, MyTeam, Range) instead of looping a GetAllObjectsWithTag list per object; if you must scan a list, rescan on a ~0.25s staggered cooldown, not every tick.
+    - Wait()/forever parks a per-object saved continuation (every handler local + call scratch) against one global 262,144-slot budget - hundreds of live instances of one class exhaust it ('continuation slot capacity exceeded' freeze). Swarm classes (pickups, projectiles): use event Update + class vars (a returning handler parks nothing).
     - 1000+ active units: regular colliding objects cap near ~500 (collision pairs). Spawn hordes as ClimbingCrowdObject (lean deterministic crowd bodies; steer with SetAsClimbingCrowdTarget) - or SetCanCollide(false) units picking targets via NearestObjectWithTagNotOnTeam on a staggered ~0.25s cooldown.
     - Dense pickup/particle fields (hundreds+): every spawned object is replicated multiplayer state, so thousands of individual pickups bloat rollback and read as network lag even at healthy ping. Pool + recycle a capped set (destroy/respawn churn also hitches), keep pickups non-colliding (SetCanCollide(false) - solid ones physically shove players; 33+ colliders stacked at one point also overflow crowd steering), collect via distance checks, and bundle several visuals per synced object when you want thousands on screen.
     - See also: <movement_laws> and <time> sections for API-level constraints and examples.
@@ -1921,21 +2088,23 @@ event InventoryDropOnWorld
 
 <ui>
 - Use ClickButton event to detect any button click. Event properties: Event.ButtonClicker, Event.ClickedButton
-- event ClickThisUI fires when any UI element of this class (frame/image/label/button) is clicked; buttons additionally fire ClickThisButton/ClickButton
+- event ClickThisUI fires when any UI element of this class (frame/image/label/button) is clicked; buttons additionally fire ClickThisButton/ClickButton. Both carry Event.ClickFraction: the 0..1 click position inside the element (x right, y down) — minimaps, sliders, pickers
 - Drag-drop: mark elements draggable=true (or SetUiDraggable(true)). Engine handles press+move threshold, drag ghost and click suppression. UiDragStart fires on drag start (Event.Dragger, Event.DragElement); UiDrop on release (Event.Dragger, Event.DragElement, Event.DropElement = UI element under cursor or None, Event.DropObject = world object hit when dropped outside UI, Event.DropPosition). Both broadcast to every class defining the handler (player class or the element's class both work); ClickThisUI instead fires only on the clicked element's own class. A short press without movement still clicks normally.
 - Tooltip/cursor-follow UI lagging behind the mouse: never chase the cursor with per-frame offset loops - call SetUiFollowsCursor(true, dx, dy) once (owned screen canvas); the engine glues it to the real cursor. Scripts only refresh its text.
 - SetCursorImage(ImageAsset) turns the OS hardware cursor into that image (zero-lag, unlike moving a UI element each frame); SetCursorImage(NONE) restores the stock cursor. Overload SetCursorImage(ImageAsset, HotspotX, HotspotY, Opacity): hotspot is 0..1 of the image ((0,0)=top-left default, (0.5,0.5)=image centered on the pointer - ideal drag ghost), opacity 0..1 scales the image alpha. Don't animate opacity per frame (each step builds a new OS cursor). The image is downscaled to <=64px; touch devices have no cursor, so mobile drag ghosts still need a UI element. Pattern: SetCursorImage(ghost, 0.5, 0.5, 0.8) in UiDragStart, SetCursorImage(NONE) in UiDrop.
 - Hit-testing ignores plain images/labels (clicks pass through), BUT any element whose class has script or with draggable=true becomes clickable and blocks hit tests under it. Keep overlay visuals (tooltips, custom drag ghosts) class-free and move them from another class's code, or they will swallow the hover/click you are trying to detect.
 - Inventories/hotbars/chests: see <inventory> — item clauses + BindInventory give a fully engine-synced slot UI.
+- Minimap: an image element with image = "ori.image.engine.minimap" shows an auto-refreshing top-down snapshot of the largest terrain, spanning its XY bounds (terrain only — no objects/fog). Blips/camera rect = child frames placed via GetTerrainBoundsMin/Max; map clicks back to world XY with Event.ClickFraction.
 - ui object tags for world description: screenCanvas/worldCanvas/frame/textLabel/button; elements nest
 - Element handles in script: scene-declared elements resolve as Scene.X; children of a SpawnCanvas canvas via canvas.FindChildUI("Name")
+- Spawning saved UI at runtime: canvas-root saved block -> SpawnCanvas(SavedObject.X, pos); element-root block (frame/textLabel/button...) -> SpawnChildUI(SavedObject.X, ParentUI). SpawnObject rejects both.
 - worldCanvas = screenCanvas anchored to a world position (position = (x, y, z)): children use the same base-unit offsets around the projected anchor and keep constant on-screen size (nameplates, above-object markers); draws under screenCanvas; move the canvas object to follow things
 
 - UI offset and size uses base unit assuming 1600x900 window size. Resize -> ui scales proportionally. Make layouts work in 1600x900 base unit.
 - text align uses words: align=(horizontal, vertical) where horizontal=left|center|right, vertical=top|center|bottom. Defaults: button text is already CENTER, textLabel is top-left; only set align to override (e.g. align=(center, center) to center a label). In script use SetTextAlign(h, v) with 0/1/2 = left/center/right, top/center/bottom.
 - Text off-center in a panel: put the textLabel INSIDE the frame with NO size (a size-less child of a plain frame inherits the frame's full rect) + align=(center, center). Never center by hand-tuned offset - text width is not measurable, guessed offsets are always off.
 - Fonts: SetFont(Ori.font.google.<Family_Name>) uses any Google Font (fonts.google.com) directly, no upload; underscores for spaces, optional weight/style suffix (e.g. Ori.font.google.Roboto_Mono, Ori.font.google.Lobster, Ori.font.google.Roboto_Mono.700italic). Uploaded font assets use SetFont(Ori.font.<creator>.<name>). UI text without a font uses the world default: SetDefaultFont(Ori.font...) sets it, default Nunito.
-- Declarative fonts: textLabel/button clauses accept font_size = N (base units, default 16) and font = "font.google.<Family_Name>" / "font.<creator>.<name>" — prefer these over SetFontSize/SetFont calls in OnSpawned. Inside a saved block font_size works but font urls do not (set custom fonts from script after Spawn). Text never auto-shrinks to fit its rect - match font_size to the rect.
+- Declarative fonts: textLabel/button clauses accept font_size = N (base units, default 16) and font = "font.google.<Family_Name>" / "font.<creator>.<name>" — prefer these over SetFontSize/SetFont calls in OnSpawned. Text never auto-shrinks to fit its rect - match font_size to the rect.
 
 - PREFER auto-layout containers over manual offsets: vStack (stack down) / hStack (stack across) / grid (set columns). They self-arrange children, so you don't hand-place each element.
 - HUG (recommended default): a vStack/hStack with NO `size` auto-sizes to fit its children + padding + gaps. Just author the children; the container grows to wrap them.
@@ -1946,12 +2115,16 @@ event InventoryDropOnWorld
 - padding/gap/margin take N (all sides) or (x, y) with x=left/right, y=top/bottom; per-side: padding_left/right/top/bottom, margin_left/right/top/bottom.
 - Word values: child_align = left|center|right (x) or top|center|bottom (y); align_self_x/y = auto|start|center|end|stretch (per-child override of child_align; stretch fills the cross axis).
 - frame = plain/absolute container (no auto-layout). Use it for screen-anchored HUD corners and for elements you reposition at runtime via SetUiOffset. A frame/grid without `size` inherits the parent's size. Position a child by ONE of: offset; anchor; insets.
-- anchor = (x, y): pin the element to a spot on the parent (x=left|center|right, y=top|center|bottom). It also sets the pivot to match, so anchor=(center,center) centers, anchor=(center,bottom) makes a bottom bar, anchor=(right,bottom) a corner. `offset` still nudges. Decouple with pivot=(x,y) (or anchor_x/y + pivot_x/y) when the element's own pivot must differ from the parent attach point.
+- anchor = (x, y): pin the element to a spot on the parent (x=left|center|right, y=top|center|bottom). It also sets the pivot to match, so anchor=(center,center) centers, anchor=(center,bottom) makes a bottom bar, anchor=(right,bottom) a corner. `offset` still nudges, always in raw screen units (+x right, +y down) regardless of anchor - from a bottom anchor, inward is negative y. Decouple with pivot=(x,y) (or anchor_x/y + pivot_x/y) when the element's own pivot must differ from the parent attach point.
 - inset = N | (x, y): pin all four edges to the parent content rect so the child fills parent - inset (per-side: inset_left/inset_right/inset_top/inset_bottom). Use it to inset content inside a button/frame (e.g. an icon: inset=10). insets differ from margin (a child's outer spacing inside a stack/grid) and padding (a container's inner inset applied to ALL its children); a button is not a container, so inset the child rather than padding the button.
-- clip_to_bounds = true clips children (and hit-testing) to this rect; block_input = true blocks clicks passing through.
+- cover = screen (frame): rect = the player's FULL real window instead of the 1600x900 base box - backdrops/vignettes reach wide-monitor edges (unflagged UI lays out in the centered base box, leaving side bands there). Children anchor inside it normally, so a HUD wrapped in a cover frame hugs true screen corners. Owned screen canvases only.
+- visible = false starts any element hidden (there is no `hidden` field); SetVisible(true) reveals it - same flag.
+- clip_to_bounds = true clips children (and hit-testing) to this rect; block_input = true blocks clicks passing through. Containers (frame/vStack/hStack/grid) default block_input = TRUE - set block_input = false on overlay panels that must not swallow clicks on the world behind them (other elements default false).
+- Interactable elements (buttons, classed elements, draggables) consume clicks before the world: no click-through move/shoot/ClickThisObject under them, so no guard code needed. block_input additionally swallows clicks on non-interactable containers; a decorative classed element that must NOT eat world clicks sets click_through = true.
 - Scrollable container: set clip_to_bounds=true + block_input=true on the container, then SetUiScrollOffset(X, Y) shifts its content (children move by -offset; rect/clip stay). Read back with GetUiScrollOffsetX/Y(). Wire event OnMouseScroll { } (Event.ScrollDelta, positive = wheel up) to adjust Y. Wheel over input-blocking UI does not zoom the camera. Authored start offset: scroll_offset = (x, y).
-- Rounded corners + border work on frame/button/progressBar (ignored by textLabel/image): corner_radius = N (base units, all 4 corners), border_width = N (base units; border shows only when > 0), border_color = #RRGGBB | #RRGGBBAA | (r,g,b).
-- count = N (2..=256, canvas child elements): parse-time repeat — the element and its whole subtree expand into N copies named <Name>0..<Name>N-1 (e.g. `frame Slot { count = 9 ... }` -> Slot0..Slot8, each resolvable by name). Use for marker/gauge/slot pools instead of hand-numbering; copies stack until code positions them via SetUiOffset. Counts nest (rows x cells).
+- Rounded corners + border work on frame/button/progressBar (textLabel: neither; image: corner_radius only): corner_radius = N (base units, all 4 corners), border_width = N (base units; border shows only when > 0), border_color = #RRGGBB | #RRGGBBAA | (r,g,b). Authoring-only: no SetUi* simcall changes these at runtime.
+- progressBar: color = fill, background_color = track; fill ratio via SetProgress(Value, MaxValue).
+- count = N (2..=256, canvas child elements): parse-time repeat — the element and its whole subtree expand into N copies named <Name>0..<Name>N-1 (e.g. `frame Slot { count = 9 ... }` -> Slot0..Slot8, each resolvable by name). Use for marker/gauge/slot pools instead of hand-numbering; copies stack until code positions them via SetUiOffset; resolve copies dynamically via Panel.FindChildUI("Slot" + i). Counts nest (rows x cells).
 - image nine_slice = (uv_frac, border): scalable panel art — the outer uv_frac (0..0.5) of the texture becomes a fixed border-unit rim (corners keep size, edges/center stretch). Use for stretchy frames/panels from one texture.
 - frame/vStack/hStack/grid also accept image = "image.*" as a background fill (drawn over color/border, under children; nine_slice applies). Combine with material= freely.
 - text/button shadows are off by default; set shadow_color = #000000B4 (or any alpha > 0) to enable.
@@ -1960,10 +2133,11 @@ event InventoryDropOnWorld
 - Colors accept optional 8-digit hex alpha (e.g. #3A3A3AFF) in addition to #RRGGBB and (r,g,b).
 - Two-stop gradients: gradient(colorA, colorB[, angle_deg]) (linear; angle 0 = top->bottom, 90 = left->right) or radial(inner, outer) (center->corners). ONLY on frame/vStack/hStack/grid `color` (fill) and on `border_color` of frame-like UI — NOT on button/textLabel colors (wrap the button in a gradient frame instead).
 
-- Example (hugging vStack panel; rounded corners + subtle border):
+- Give visible UI a light theme pass by default: one Google font, one accent color on primary buttons/highlights, corner_radius on panels/buttons, panel colors from the game's palette (not pure black) — a few properties total.
+- Example (hugging vStack panel; themed: font + accent + rounded corners + subtle border):
   vStack Panel { offset=(40,40) padding=12 gap=8 color=#1E1E1EF0 corner_radius=12 border_width=1 border_color=#3A3A3AFF
-    textLabel Title { size=(200,28) text="Shop" }
-    button Buy { size=(200,44) text="Buy" corner_radius=8 }
+    textLabel Title { size=(200,28) text="Shop" font="font.google.Cinzel" font_size=22 }
+    button Buy { size=(200,44) text="Buy" corner_radius=8 color=#7A4FBF }
   }
 - Example (gradient card fill + gradient border):
   frame Card { size=(320,180) color=gradient(#1A2A6C, #B21F1F, 45) corner_radius=16 border_width=2 border_color=radial(#FFFFFF80, #FFFFFF10) }
@@ -2019,6 +2193,8 @@ event InventoryDropOnWorld {
 - use the function PlayAnimationOnRepeat to loop animations like run forever
 - PlayAnimationOnRepeat(Ori.anim.default.goblin.run)
 - PlayAnimation(Ori.anim.default.goblin.attack)
+- a marketplace model's own clips: Ori.anim.<creator>.<model>.<clip> (e.g. Ori.anim.vk7t7mestuxl_5378.murlocfishgi.attack); clip names are exact-case
+- Timing a clip to a moment (hand/bat/racket meeting a ball): call PlayAnimationHittingContactIn(Anim, ContactPercent, SecondsUntilContact) every frame - it returns false and does nothing while still too early, then fires rate-scaled so ContactPercent lands exactly on contact, and refuses to restart a clip it already started (no 'started' guard var needed). GetAnimationLeadSeconds tells how early it can fire. Never derive a trigger delay from GetAnimationDuration by hand.
 
 - Rigged store characters can also play canonical clips (world `#clip Name on canon` blocks -> Ori.anim.canon.Name) and other humanoid rigs' clips (e.g. a template mesh's Ori.anim.mesh.<Mesh>.walk) — the engine retargets by bone-name map, display-only
 
@@ -2026,8 +2202,8 @@ event InventoryDropOnWorld {
 - the clip is picked automatically: .idle when still, .run when moving (falling back to .walk), .jumpHover when airborne; camera-locked players also use .runBack/.runLeft/.runRight by movement direction
 - using PlayAnimation will stop these animations until the animation is finished
 - DisableAutoMoveAnimations() to turn this off
-- Rigged humanoid store characters whose model ships NO clips idle/walk with the built-in canonical clips automatically (display-only retarget); models with their own clips always use them
-- Custom/procedural character: author ONE rigged #mesh (bone(...) joints + idle/walk #clips, standard bone names — see the humanoid example in the mesh skill) and SetModel it; auto move-animations then drive it. AttachTo assembly is for props/machines (turret, arm -> gun), not walking bodies
+- Rigged humanoid models (store characters or DSL rigs) that ship no `.idle` clip idle/walk/run (jumpHover airborne) with the built-in canonical clips automatically (display-only retarget); models with their own clips always use them
+- Custom/procedural character: author ONE rigged #mesh (bone(...) joints + optional idle/walk #clips, standard bone names — see the humanoid example in the mesh skill) and SetModel it; auto move-animations then drive it. AttachTo assembly is for props/machines (turret, arm -> gun), not walking bodies
 - Procedural bone layer on any bone(...) rig (display-only, max 16 bones): SetBoneRotation(Mix) replaces/blends a joint over the playing clip, BoneLookAt aims one at a world point, PlayUpperBodyAnimation layers a clip over the base walk. Head-track + breathe over auto-walk:
     forever {
         BoneLookAt("Head", Friend.GetCenterPosition(), 55, 240)
@@ -2035,13 +2211,2547 @@ event InventoryDropOnWorld {
     }
 
 - Die() auto-spawns a visual-only corpse+animation; non-player deaths dissolve away during the die animation and despawn the object
-- Die() on a PLAYER (human or AI bot) is a warp-only death: corpse at the death spot, body warps to Origin(), class vars/cooldowns SURVIVE, OnSpawned does not re-run, the player is never despawned (attacks landing the same frame are dropped). Respawn pattern: in WasAttacked at HP <= 0 call Die() and start a respawn Timer; when it finishes, restore HP and TeleportTo(your team spawn). Removing a bot needs DespawnAIPlayer()/Destroy(); ResetLogic() is the explicit re-run-OnSpawned-with-fresh-vars reset
+- Die() on a PLAYER (human or AI bot) is a warp-only death: corpse at the death spot, body warps to Origin(), class vars/cooldowns SURVIVE, OnSpawned does not re-run, the player is never despawned (attacks landing the same frame are dropped). Respawn pattern: in WasAttacked at HP <= 0 call Die() and start a respawn Timer; when it finishes, restore HP and TeleportTo(your team spawn). Removing a bot needs DespawnAIPlayer()/Destroy(). No engine call re-runs OnSpawned or resets class vars - put per-life re-init in one func called from both OnSpawned and your respawn point
 </animations>
 
 
 <world_description_examples>
 These examples are trimmed-down teaching games: copy their patterns, not their scope — a real request usually deserves more content and polish than any example here.
 Examples by genre: stardew_valley (farming/life-sim), vampire_survivor (top-down action/swarm), breakout (2D arcade/side-view), dota (top-down hero/lane).
+<example_breakout>
+// Breakout (Fixed-Bounds Top-Down)
+// Multiplayer: shared board.
+//   One shared brick field and one shared ball; each player gets one paddle in the same arena.
+//   Do not duplicate the whole map unless intentionally making parallel solo boards.
+alias model.ball // bare: auto-binds a generated mesh from the library
+
+#class BoardManager
+var TS = 50
+var W  = 12
+var H  = 16
+event OnSpawned {
+    SetVisible(false)
+
+    // Spawn one shared ball for the whole match.
+    var ball = SpawnObject(SavedObject.ball, Position(0, (-H*TS*0.5) + TS*2.6, 0))
+    ball.BoundCenterX = 0
+    ball.BoundHalfX = W*TS*0.5 - TS*0.3
+    ball.BoundTopY  = H*TS*0.5 - TS*0.4
+    ball.BoundBottomY  = -H*TS*0.5
+
+    // Build one shared brick field. Destroyed bricks disappear for everyone.
+    for r in 0..4 {
+        for c in 0..10 {
+            var x = (c - 5) * TS * 0.9
+            var y = (r * TS * 0.7) + TS * 3.5
+            var b = SpawnObject(SavedObject.brick, Position(x, y, 0))
+            b.SetColor(0.6, 0.3 + r*0.1, 0.9 - c*0.05)
+        }
+    }
+}
+#end
+
+#class player
+var TS = 50
+var W  = 12
+var H  = 16
+var pad = 0.6
+var PaddleObj: Object
+event OnSpawned {
+    SetPlayerModeSpectator()
+    SetVisible(false)
+
+    var minX = (-W*TS*0.5 - pad*TS)
+    var maxX = ( W*TS*0.5 + pad*TS)
+    var minY = (-H*TS*0.5 - pad*TS)
+    var maxY = ( H*TS*0.5 + pad*TS)
+    SetCameraToTopDownSpectatorFixedBoundsXY(minX, maxX, minY, maxY)
+    SetCameraCollisionEnabled(false)
+
+    // Each player adds a paddle to the same shared board.
+    // Compact arcade layout: first few players get nearby bottom lanes.
+    var lane = GetPlayerIndex()
+    if lane > 5 { lane = 5 }
+    var laneY = (-H*TS*0.5) + TS*(1.0 + lane*0.8)
+    PaddleObj = SpawnObject(SavedObject.paddle, Position(0, laneY, 0))
+    PaddleObj.SetPlayerOwnerIndex(GetPlayerIndex())
+    PaddleObj.SetColor(0.2 + lane*0.12, 0.8 - lane*0.08, 1.0)
+
+    var PaddleHalf = (W*TS*0.5 - TS*0.6)
+    forever {
+        var move = GetMoveVectorWorld()
+        var vx = move.X * 600
+        var p = PaddleObj.GetPosition()
+        var nextX = p.X + vx*DeltaSecs()
+        if (vx < 0 and nextX <= -PaddleHalf) or (vx > 0 and nextX >= PaddleHalf) {
+            vx = 0
+        }
+        PaddleObj.MoveWithVelocityContinuously(Vector(vx, 0, 0))
+    }
+}
+event OnDestroy {
+    if PaddleObj.Exists() { PaddleObj.Destroy() }
+}
+#end
+
+#class Ball
+var V  = Vector(260, 260, 0)
+var ServePos = Position(0, 0, 0)
+var BoundCenterX = 0
+var BoundHalfX = 0
+var BoundTopY  = 0
+var BoundBottomY = 0
+event OnSpawned {
+    SetSizeTiles(0.5, 0.5, 0.5)
+    SnapToGroundWithTag(Tag.Ground)
+    ServePos = GetPosition()
+}
+event Update {
+    var n = GetPosition() + V * DeltaSecs()
+
+    // Reflect on bounds using predicted next pos.
+    if n.X <= BoundCenterX - BoundHalfX or n.X >= BoundCenterX + BoundHalfX { V.X = -V.X }
+    if n.Y >=  BoundTopY { V.Y = -V.Y }
+    // Missed ball: soft serve reset (RestartGame() would reload the whole project).
+    if n.Y <= BoundBottomY {
+        SetPosition(ServePos)
+        V = Vector(260, 260, 0)
+        return
+    }
+
+    for o in GetTouchedObjects() {
+        if o.HasTag(Tag.Brick) {
+            o.Destroy()
+            V.Y = -V.Y
+            break
+        }
+        if o.HasTag(Tag.Paddle) {
+            V.Y = V.Y.Abs()
+            V.X = V.X + (GetPosition().X - o.GetPosition().X) * 4
+        }
+    }
+
+    MoveWithVelocityContinuously(V)
+}
+#end
+
+saved paddle { object P { model = "alias.model.paddle" size_tiles = (2, 0.6, 0.2) tag = Tag.Paddle } }
+saved ball   { object B : Ball   { model = "alias.model.ball" } }
+saved brick  { object K          { model = "alias.model.brick" size_tiles = (0.8, 0.5, 0.3) tag = Tag.Brick } }
+
+material GroundMat { base = "PolishedConcrete" }
+object ground { model = "cube" material = "GroundMat" position = (0, 0, -100) size = (10000, 10000, 100) tag = Tag.Ground }
+display manager : BoardManager { visible = false }
+screenCanvas HUD { textLabel T { offset = (20, 20) size = (520, 28) align = (left, center) text = "Shared board: move your paddle with A/D or mobile thumbstick" color = (1, 1, 1) } }
+
+</example_breakout>
+
+
+<example_dota>
+// dota.weave
+// Multiplayer: team-based MOBA (per-player heroes via SetPlayerOwnerIndex/SetTeam, ByThisPlayer input).
+//   Caveat: the shop window is a single shared canvas.
+
+alias effect.explosion = "ori.effect.nuttametee_b_2523.w_explosion0"
+alias model.player_unit = "sphere"
+alias model.creep = "sphere"
+alias model.projectile // bare: auto-binds a generated mesh from the library
+
+#class TowerBrain
+var HP = 500
+var MaxHP = 500
+var LastShotTime: Number
+var AttackRange = 270
+event OnSpawned {
+    LastShotTime = TimeSecs() - 1000.0
+    SetHoverHPBar(HP, MaxHP)
+}
+event Update {
+    var team = GetTeam()
+    var bestDist = 1000000
+    var target = None
+    
+    for creep in GetAllObjectsWithSavedType(SavedObject.CreepUnit) {
+        if creep.GetTeam() != team {
+            var dist = DistanceXYTo(creep)
+            if dist < bestDist and dist <= AttackRange {
+                bestDist = dist
+                target = creep
+            }
+        }
+    }
+    if target == None {
+        for pUnit in GetAllObjectsWithSavedType(SavedObject.PlayerUnit) {
+            if pUnit.GetTeam() != team {
+                var dist = DistanceXYTo(pUnit)
+                if dist < bestDist and dist <= AttackRange {
+                    bestDist = dist
+                    target = pUnit
+                }
+            }
+        }
+    }
+    if target == None { return }
+    var now = TimeSecs()
+    if (now - LastShotTime) < 1.5 { return }
+    var start = GetPosition().ShiftUp(50)
+    var proj = SpawnObject(SavedObject.Projectile, start)
+    proj.target = target
+    proj.SetColor(0.40, 0.700, 0.9) 
+    LastShotTime = now
+}
+event WasAttacked {
+    var dmg = Event.Damage.Round()
+    HP = HP - dmg
+    if HP < 0 { HP = 0 }
+    SetHoverHPBar(HP, MaxHP)
+    SpawnFloatingText("-" + dmg, Vector(1, 0, 0))
+    if HP <= 0 {
+        SpawnEffect(Ori.alias.effect.explosion, GetPosition())
+        Die()
+    }
+}
+#end
+
+
+#class GameManager
+event OnSpawned {
+    var MapHalfTiles = 12
+    var WallThicknessTiles = 1
+    var WallHeightTiles = 2
+    var WallLenTiles = (MapHalfTiles * 2 + 2)
+
+    var wTop    = SpawnAtTile(SavedObject.WallCube, 0,  MapHalfTiles + (WallThicknessTiles * 0.5))
+    wTop.SetSizeTiles(WallLenTiles, WallThicknessTiles, WallHeightTiles)
+    var wBottom = SpawnAtTile(SavedObject.WallCube, 0, -MapHalfTiles - (WallThicknessTiles * 0.5))
+    wBottom.SetSizeTiles(WallLenTiles, WallThicknessTiles, WallHeightTiles)
+    var wLeft   = SpawnAtTile(SavedObject.WallCube, -MapHalfTiles - (WallThicknessTiles * 0.5), 0)
+    wLeft.SetSizeTiles(WallThicknessTiles, WallLenTiles, WallHeightTiles)
+    var wRight  = SpawnAtTile(SavedObject.WallCube,  MapHalfTiles + (WallThicknessTiles * 0.5), 0)
+    wRight.SetSizeTiles(WallThicknessTiles, WallLenTiles, WallHeightTiles)
+
+    var marginTiles = 2
+    var CP1TilePos = Vector(-MapHalfTiles + marginTiles, -MapHalfTiles + marginTiles, 0)
+    var CP2TilePos = Vector(-MapHalfTiles + marginTiles,  MapHalfTiles - marginTiles, 0)
+    var CP3TilePos = Vector( MapHalfTiles - marginTiles, -MapHalfTiles + marginTiles, 0)
+    var CP4TilePos = Vector( MapHalfTiles - marginTiles,  MapHalfTiles - marginTiles, 0)
+    var CP5TilePos = Vector(0, 0, 0)
+
+    var CP1 = SpawnAtTile(SavedObject.Checkpoint, CP1TilePos); CP1.AddTag(Tag.CP1)
+    var CP2o = SpawnAtTile(SavedObject.Checkpoint, CP2TilePos); CP2o.AddTag(Tag.CP2)
+    var CP3o = SpawnAtTile(SavedObject.Checkpoint, CP3TilePos); CP3o.AddTag(Tag.CP3)
+    var CP4 = SpawnAtTile(SavedObject.Checkpoint, CP4TilePos); CP4.AddTag(Tag.CP4)
+    var CP5o = SpawnAtTile(SavedObject.Checkpoint, CP5TilePos); CP5o.AddTag(Tag.CP5)
+
+    var laneThicknessTiles = 3.0
+    var laneHeightTiles    = 0.1
+
+    var mid12 = (CP1TilePos + CP2TilePos) * 0.5
+    var d12   = CP1TilePos.DistanceTo(CP2TilePos)
+    var L12   = SpawnAtTile(SavedObject.LaneCube, mid12)
+    L12.SetSizeTiles(d12, laneThicknessTiles, laneHeightTiles)
+    L12.LookAtTileHorizontal(CP2TilePos)
+    var mid15 = (CP1TilePos + CP5TilePos) * 0.5
+    var d15   = CP1TilePos.DistanceTo(CP5TilePos)
+    var L15   = SpawnAtTile(SavedObject.LaneCube, mid15)
+    L15.SetSizeTiles(d15, laneThicknessTiles, laneHeightTiles)
+    L15.LookAtTileHorizontal(CP5TilePos)
+    var mid13 = (CP1TilePos + CP3TilePos) * 0.5
+    var d13   = CP1TilePos.DistanceTo(CP3TilePos)
+    var L13   = SpawnAtTile(SavedObject.LaneCube, mid13)
+    L13.SetSizeTiles(d13, laneThicknessTiles, laneHeightTiles)
+    L13.LookAtTileHorizontal(CP3TilePos)
+    var mid42 = (CP4TilePos + CP2TilePos) * 0.5
+    var d42   = CP4TilePos.DistanceTo(CP2TilePos)
+    var L42   = SpawnAtTile(SavedObject.LaneCube, mid42)
+    L42.SetSizeTiles(d42, laneThicknessTiles, laneHeightTiles)
+    L42.LookAtTileHorizontal(CP2TilePos)
+    var mid45 = (CP4TilePos + CP5TilePos) * 0.5
+    var d45   = CP4TilePos.DistanceTo(CP5TilePos)
+    var L45   = SpawnAtTile(SavedObject.LaneCube, mid45)
+    L45.SetSizeTiles(d45, laneThicknessTiles, laneHeightTiles)
+    L45.LookAtTileHorizontal(CP5TilePos)
+    var mid43 = (CP4TilePos + CP3TilePos) * 0.5
+    var d43   = CP4TilePos.DistanceTo(CP3TilePos)
+    var L43   = SpawnAtTile(SavedObject.LaneCube, mid43)
+    L43.SetSizeTiles(d43, laneThicknessTiles, laneHeightTiles)
+    L43.LookAtTileHorizontal(CP3TilePos)
+
+    var Dir_CP2_to_CP1 = (CP1TilePos - CP2TilePos).GetNormal()
+    var Pos_Tower_A = CP2TilePos + (Dir_CP2_to_CP1 * 6)
+    var TowerA = SpawnAtTile(SavedObject.TowerUnitR350, Pos_Tower_A)
+    TowerA.SetColor(0, 1, 0); TowerA.SetTeam(0)
+    var Dir_CP5_to_CP1 = (CP1TilePos - CP5TilePos).GetNormal()
+    var Pos_Tower_B = CP5TilePos + (Dir_CP5_to_CP1 * 5)
+    var TowerB = SpawnAtTile(SavedObject.TowerUnit, Pos_Tower_B)
+    TowerB.SetColor(0, 1, 0); TowerB.SetTeam(0)
+    var Dir_CP3_to_CP1 = (CP1TilePos - CP3TilePos).GetNormal()
+    var Pos_Tower_C = CP3TilePos + (Dir_CP3_to_CP1 * 6)
+    var TowerC = SpawnAtTile(SavedObject.TowerUnitR350, Pos_Tower_C)
+    TowerC.SetColor(0, 1, 0); TowerC.SetTeam(0)
+    var Dir_CP2_to_CP4 = (CP4TilePos - CP2TilePos).GetNormal()
+    var Pos_Tower_X = CP2TilePos + (Dir_CP2_to_CP4 * 6)
+    var TowerX = SpawnAtTile(SavedObject.TowerUnitR350, Pos_Tower_X)
+    TowerX.SetColor(1, 0, 0); TowerX.SetTeam(1)
+    var Dir_CP5_to_CP4 = (CP4TilePos - CP5TilePos).GetNormal()
+    var Pos_Tower_Y = CP5TilePos + (Dir_CP5_to_CP4 * 5)
+    var TowerY = SpawnAtTile(SavedObject.TowerUnit, Pos_Tower_Y)
+    TowerY.SetColor(1, 0, 0); TowerY.SetTeam(1)
+    var Dir_CP3_to_CP4 = (CP4TilePos - CP3TilePos).GetNormal()
+    var Pos_Tower_Z = CP3TilePos + (Dir_CP3_to_CP4 * 6)
+    var TowerZ = SpawnAtTile(SavedObject.TowerUnitR350, Pos_Tower_Z)
+    TowerZ.SetColor(1, 0, 0); TowerZ.SetTeam(1)
+    // Player heroes spawn per join in '#class player' OnSpawned (any player count works).
+    forever {
+        var cg12a = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(0, 1, 0))
+        cg12a.SetColor(0, 1, 0); cg12a.SetTeam(0); cg12a.AddTag(Tag.PathToCP2)
+        var cg12b = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(0, -1, 0))
+        cg12b.SetColor(0, 1, 0); cg12b.SetTeam(0); cg12b.AddTag(Tag.PathToCP2)
+        var cg15a = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(1, 0, 0))
+        cg15a.SetColor(0, 1, 0); cg15a.SetTeam(0); cg15a.AddTag(Tag.PathToCP5)
+        var cg15b = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(-1, 0, 0))
+        cg15b.SetColor(0, 1, 0); cg15b.SetTeam(0); cg15b.AddTag(Tag.PathToCP5)
+        var cg13a = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(0, 2, 0))
+        cg13a.SetColor(0, 1, 0); cg13a.SetTeam(0); cg13a.AddTag(Tag.PathToCP3)
+        var cg13b = SpawnAtTile(SavedObject.CreepUnit, CP1TilePos + Vector(0, -2, 0))
+        cg13b.SetColor(0, 1, 0); cg13b.SetTeam(0); cg13b.AddTag(Tag.PathToCP3)
+        var cr42a = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(0, 1, 0))
+        cr42a.SetColor(1, 0, 0); cr42a.SetTeam(1); cr42a.AddTag(Tag.PathToCP2)
+        var cr42b = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(0, -1, 0))
+        cr42b.SetColor(1, 0, 0); cr42b.SetTeam(1); cr42b.AddTag(Tag.PathToCP2)
+        var cr45a = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(1, 0, 0))
+        cr45a.SetColor(1, 0, 0); cr45a.SetTeam(1); cr45a.AddTag(Tag.PathToCP5)
+        var cr45b = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(-1, 0, 0))
+        cr45b.SetColor(1, 0, 0); cr45b.SetTeam(1); cr45b.AddTag(Tag.PathToCP5)
+        var cr43a = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(0, 2, 0))
+        cr43a.SetColor(1, 0, 0); cr43a.SetTeam(1); cr43a.AddTag(Tag.PathToCP3)
+        var cr43b = SpawnAtTile(SavedObject.CreepUnit, CP4TilePos + Vector(0, -2, 0))
+        cr43b.SetColor(1, 0, 0); cr43b.SetTeam(1); cr43b.AddTag(Tag.PathToCP3)
+        Wait(5)
+    }
+}
+#end
+#class UnitStats
+var HP = 100
+var MaxHP = 100
+var MP = 100
+var Level = 1
+var XP = 0
+var XPToNextLevel = 100
+var Armor = 3
+var LastShotTime: Number
+var MoveGoal: Position
+var HasMoveGoal = false
+
+event OnSpawned {
+    LastShotTime = TimeSecs() - 1000.0
+    SetHoverHPBar(HP, 100)
+    SetHoverBar(1, MP, 100, Vector(0.2, 0.6, 1.0), Vector(0.1, 0.1, 0.2), 0, 8, 50, 6)
+}
+func LevelUp() {
+    Level += 1
+    XP = XP - XPToNextLevel
+    XPToNextLevel = (XPToNextLevel * 1.1).Round()
+    Armor = 3 + ((Level - 1) * 1.7)
+    
+    var maxHP = 100 + (Level * 10)
+    var maxMP = 100 + (Level * 5)
+    HP = maxHP
+    MP = maxMP
+    SetHoverHPBar(HP, maxHP)
+    SetHoverBar(1, MP, maxMP, Vector(0.2, 0.6, 1.0), Vector(0.1, 0.1, 0.2), 0, 8, 50, 6)
+    SpawnFloatingText("LEVEL UP!", Vector(1, 0.8, 0))
+}
+func GainXP(amount: Number) {
+    XP += amount
+    SpawnFloatingText("+" + amount + " XP", Vector(1, 1, 0))
+    while XP >= XPToNextLevel {
+        LevelUp()
+    }
+}
+event Update {
+    if HasMoveGoal {
+        if DistanceXYTo(MoveGoal) < GetSizeX() * 0.5 { HasMoveGoal = false }
+        else { MoveTowardContinuousHorizontalFacing(MoveGoal, 250) }
+    }
+    var team = GetTeam()
+    var best = 1000000
+    var target = None
+    for e in GetAllObjectsWithSavedType(SavedObject.PlayerUnit) {
+        if e.GetTeam() != team {
+            var d = DistanceXYTo(e)
+            if d < best and d <= 200 { best = d; target = e }
+        }
+    }
+    for c in GetAllObjectsWithSavedType(SavedObject.CreepUnit) {
+        if c.GetTeam() != team {
+            var d2 = DistanceXYTo(c)
+            if d2 < best and d2 <= 200 { best = d2; target = c }
+        }
+    }
+    for t in GetAllObjectsWithSavedType(SavedObject.TowerUnit) {
+        if t.GetTeam() != team {
+            var d3 = DistanceXYTo(t)
+            if d3 < best and d3 <= 200 { best = d3; target = t }
+        }
+    }
+    if target == None { return }
+    var now2 = TimeSecs()
+    if (now2 - LastShotTime) < 0.8 { return }
+    var start = GetPosition().ShiftUp(20)
+    var proj = SpawnObject(SavedObject.Projectile, start)
+    proj.target = target
+    proj.SetColor(0.10, 0.600, 0)
+    LastShotTime = now2
+}
+event WasAttacked {
+    var dmg = Event.Damage.Round()
+    HP = HP - dmg
+    if HP < 0 { HP = 0 }
+    SetHoverHPBar(HP, 100 + (Level * 10))
+    SpawnFloatingText("-" + dmg, Vector(1, 0, 0))
+    if HP <= 0 {
+        SpawnEffect(Ori.alias.effect.explosion, GetPosition())
+        Die()
+    }
+}
+#end
+#class ProjectileBrain
+var target: Object
+event OnSpawned {
+    var col  = GetColor()
+    var dmg  = (col.X * 100).Round()
+    var spd  = (col.Y * 1000).Round()
+    if dmg <= 0 { dmg = 10 }
+    if spd <= 0 { spd = 600 }
+
+    forever {
+        if not target.Exists() { Destroy(); return }
+        var aim = target.GetPosition()
+        MoveTowardContinuousFacing(aim, spd)
+        if DistanceTo(aim) <= 18 {
+            Self.Attack(target, dmg)
+            SpawnEffect(Ori.alias.effect.explosion, aim)
+            Destroy()
+            return
+        }
+    }
+}
+#end
+#class CreepBrain
+var HP = 10
+var LastAttackTime = 0
+var XPReward = 10
+event OnSpawned {
+    SetHoverHPBar(HP, 10)
+}
+event Update {
+    var dest = GetPosition()
+    if HasTag(Tag.PathToCP2) {
+        var rs = GetAllRegionsWithTag(Tag.CP2); if not rs.IsEmpty() { dest = rs.Get(0).GetPosition() }
+    } else if HasTag(Tag.PathToCP5) {
+        var rs2 = GetAllRegionsWithTag(Tag.CP5); if not rs2.IsEmpty() { dest = rs2.Get(0).GetPosition() }
+    } else if HasTag(Tag.PathToCP3) {
+        var rs3 = GetAllRegionsWithTag(Tag.CP3); if not rs3.IsEmpty() { dest = rs3.Get(0).GetPosition() }
+    }
+    if DistanceXYTo(dest) >= GetSizeX() * 0.5 {
+        MoveTowardContinuousHorizontalFacing(dest, 180)
+    }
+    var now = TimeSecs()
+    if (now - LastAttackTime) >= 1.0 {
+        var team = GetTeam()
+        var enemyTeam = 1 - team
+        var target = None
+        var best = 1000000
+        for o in GetObjectsWithinDistanceWithTeam(30, enemyTeam) {
+            if o.IsSavedType(SavedObject.CreepUnit) or o.IsSavedType(SavedObject.PlayerUnit) or o.IsSavedType(SavedObject.TowerUnit) {
+                var dd = DistanceXYTo(o)
+                if dd < best { best = dd; target = o }
+            }
+        }
+        if target != None {
+            var dmg = RandomNumber(1, 3).Round()
+            Self.Attack(target, dmg)
+            LastAttackTime = now
+        }
+    }
+}
+event WasAttacked {
+    var dmg = Event.Damage.Round()
+    HP = HP - dmg
+    if HP < 0 { HP = 0 }
+    SetHoverHPBar(HP, 10)
+    
+    SpawnFloatingText("-" + dmg, Vector(1, 0.5, 0))
+    if HP <= 0 {
+        for unit in GetAllObjectsWithSavedType(SavedObject.PlayerUnit) {
+            unit.GainXP(XPReward)
+        }
+        SpawnEffect(Ori.alias.effect.explosion, GetPosition())
+        Die()
+    }
+}
+#end
+
+
+#class player
+var IsAimingSkill = false
+var LastSkillQTime: Number 
+var IsShowingCooldownIndicator = false
+var Gold = 200
+var GoldTimer: Timer // auto-constructed timer
+event OnSpawned {
+    SetCameraToTopDown()
+    SetVisible(false)
+    SetPlayerModeSpectator()
+    LastSkillQTime = TimeSecs() - 1000.0 
+    GoldTimer.StartCountDown(1)
+
+    var side = GetPlayerIndex() % 2
+    SetTeam(side)
+
+    // Field my hero at my team's corner; slot offset keeps teammates from stacking.
+    var slot = (GetPlayerIndex() / 2).RoundDown()
+    var unitTile = Vector(-10 - slot, -10 + slot, 0)
+    var unitColor = Vector(0, 1, 0)
+    if side == 1 { unitTile = Vector(10 + slot, 10 - slot, 0); unitColor = Vector(1, 0, 0) }
+    var u = SpawnAtTile(SavedObject.PlayerUnit, unitTile)
+    u.SetColor(unitColor)
+    u.SetTeam(side)
+    u.SetPlayerOwnerIndex(GetPlayerIndex())
+    u.SetHoverText(GetPlayerName()) // owner's username above the hero (the spectator body is hidden)
+}
+event OnDestroy {
+    var u = GetMyUnit()
+    if u.Exists() { u.Destroy() }
+}
+event KeyboardDownByThisPlayer[Q] {
+    var cdLeft = 2.5 - (TimeSecs() - LastSkillQTime)
+    if cdLeft <= 0 {
+        IsAimingSkill = not IsAimingSkill
+        IsShowingCooldownIndicator = false
+    } else {
+        IsShowingCooldownIndicator = not IsShowingCooldownIndicator
+        IsAimingSkill = false
+    }
+}
+func GetMyUnit() -> UnitStats {
+    var myIndex = GetPlayerIndex()
+    for unit in GetAllObjectsWithSavedType(SavedObject.PlayerUnit) {
+        if unit.GetPlayerOwnerIndex() == myIndex { return (unit as UnitStats) }
+    }
+    return None
+}
+event Update {
+    var myUnit = GetMyUnit()
+    if myUnit == None { return }
+    SetCameraPivotTargetThisFrame(myUnit.GetPosition())
+    if GoldTimer.IsDone() {
+        Gold += 1
+        GoldTimer.StartCountDown(1)
+    }
+    if IsShowingCooldownIndicator {
+        var p = GetMouseTargetPositionOnPlaneZ(0)
+        DrawSkillAreaCircle(p, 200, Vector(1, 0, 0))
+    } else if IsAimingSkill {
+        var p = GetMouseTargetPositionOnPlaneZ(0)
+        DrawSkillAreaCircle(p, 200, Vector(1, 0.5, 0.2))
+    }
+    var cdLeft = 2.5 - (TimeSecs() - LastSkillQTime)
+    var unitName = ""
+    var myIndex = GetPlayerIndex()
+    if myIndex == 0 { unitName = "A" }
+    if myIndex == 1 { unitName = "B" }
+    if myIndex == 2 { unitName = "C" }
+    if myIndex == 3 { unitName = "X" }
+    if myIndex == 4 { unitName = "Y" }
+    if myIndex >= 5 { unitName = "Z" }
+
+    var statsLine1 = unitName + " | LV: " + myUnit.Level + " | ARM: " + myUnit.Armor + " | Gold: " + Gold
+    var statsLine2 = "XP: " + myUnit.XP + "/" + myUnit.XPToNextLevel
+    
+    var fullText = statsLine1 + "\n" + statsLine2
+    if cdLeft > 0 {
+        fullText = fullText + "\nSkill Cooldown"
+    }
+    myUnit.Say(fullText)
+}
+event ActionDownByThisPlayer[Primary] {
+    var myUnit = GetMyUnit()
+    if myUnit == None { return }
+    var cdLeft = 2.5 - (TimeSecs() - LastSkillQTime)
+    if IsAimingSkill and cdLeft > 0 { 
+        myUnit.SpawnFloatingText("COOLDOWN", Vector(1, 1, 0))
+        return 
+    }
+    if not IsAimingSkill { return }
+    var manaCost = 10
+    if myUnit.MP < manaCost {
+        myUnit.SpawnFloatingText("Not enough mana", Vector(0.2, 0.6, 1.0))
+        IsAimingSkill = false
+        return
+    }
+    
+    myUnit.MP -= manaCost
+    myUnit.SetHoverBar(1, myUnit.MP, 100 + (myUnit.Level * 5), Vector(0.2, 0.6, 1.0), Vector(0.1, 0.1, 0.2), 0, 8, 50, 6)
+    LastSkillQTime = TimeSecs() 
+    var p = GetMouseTargetPositionOnPlaneZ(0)
+    SpawnEffect(Ori.alias.effect.explosion, p)
+    var enemyTeam = 1 - myUnit.GetTeam()
+    for t in p.GetObjectsWithinXYDistanceWithTeam(200, enemyTeam) {
+        if t.IsSavedType(SavedObject.PlayerUnit) or t.IsSavedType(SavedObject.CreepUnit) {
+            myUnit.Attack(t, 5)
+        }
+    }
+    
+    IsAimingSkill = false
+}
+event RightMouseClickByThisPlayer {
+    if IsAimingSkill { IsAimingSkill = false; return }
+
+    var myUnit = GetMyUnit()
+    if myUnit == None { return }
+
+    var p = GetMouseTargetPositionOnPlaneZ(0)
+    var lim = 580
+    var goal = Position(p.X.Clamp(-lim, lim), p.Y.Clamp(-lim, lim), myUnit.GetPosition().Z)
+
+    // issue move order; unit drives itself in its Update (over-time builtins can't run on foreign refs)
+    myUnit.MoveGoal = goal
+    myUnit.HasMoveGoal = true
+}
+#end
+
+
+#class UIManager
+var ShopWindow: Object
+var ShopButton: Object
+var BuyHPButton: Object
+var BuyManaButton: Object
+var RosterRows: List
+
+event OnSpawned {
+    ShopWindow = Scene.ShopWindow
+    ShopButton = Scene.ShopButton
+    BuyHPButton = Scene.BuyHPButton
+    BuyManaButton = Scene.BuyManaButton
+    ShopWindow.SetVisible(false)
+
+    // Roster: cache the count-expanded rows once, then rebind names each second.
+    RosterRows = []
+    var i = 0
+    while i < 6 { RosterRows.Add(FindChildUI("RosterRow" + i.ToText())); i += 1 }
+    forever {
+        var r = 0
+        for p in GetAllPlayers() {
+            if r >= RosterRows.Count() { break }
+            var n = p.GetPlayerName()
+            if n == "" { n = "Player " + (r + 1).ToText() } // validation/headless players have no username
+            var c = Vector(0.4, 0.8, 1.0)
+            if p.GetTeam() == 1 { c = Vector(1.0, 0.45, 0.4) }
+            RosterRows.Get(r).SetText(n); RosterRows.Get(r).SetUiColor(c); RosterRows.Get(r).SetVisible(true)
+            r += 1
+        }
+        while r < RosterRows.Count() { RosterRows.Get(r).SetVisible(false); r += 1 }
+        Wait(1)
+    }
+}
+event ClickButton {
+    var clicked = Event.ClickedButton
+    var player = Event.ButtonClicker
+
+    if clicked == ShopButton {
+        var opened = ShopWindow.IsVisible()
+        ShopWindow.SetVisible(not opened)
+    }
+
+    if clicked == BuyHPButton {
+        var cost = 10
+        var myUnit = player.GetMyUnit()
+        if myUnit.Exists() and player.Gold >= cost {
+            player.Gold = player.Gold - cost
+            var maxHP = 100 + (myUnit.Level * 10)
+            myUnit.HP = maxHP
+            myUnit.SetHoverHPBar(myUnit.HP, maxHP)
+            myUnit.SpawnFloatingText("HP Full!", Vector(0, 1, 0))
+        } else if myUnit.Exists() {
+            myUnit.SpawnFloatingText("Not enough gold!", Vector(1, 1, 0))
+        }
+    }
+
+    if clicked == BuyManaButton {
+        var cost = 5
+        var myUnit = player.GetMyUnit()
+        if myUnit.Exists() and player.Gold >= cost {
+            player.Gold = player.Gold - cost
+            var maxMP = 100 + (myUnit.Level * 5)
+            myUnit.MP = maxMP
+            myUnit.SetHoverBar(1, myUnit.MP, maxMP, Vector(0.2, 0.6, 1.0), Vector(0.1, 0.1, 0.2), 0, 8, 50, 6)
+            myUnit.SpawnFloatingText("MP Full!", Vector(0.2, 0.6, 1.0))
+        } else if myUnit.Exists() {
+            myUnit.SpawnFloatingText("Not enough gold!", Vector(1, 1, 0))
+        }
+    }
+}
+#end
+
+
+material GroundMat { base = "StylizedGrass" }
+object ground { model = "cube" material = "GroundMat" position=(0, 0, -100) size=(10000, 10000, 100) }
+display Manager0 : GameManager { visible = false }
+
+saved Checkpoint {
+    region mark { model="alias.model.checkpoint" size=(20, 20, 60) }
+}
+saved WallCube {
+    object cube { model="alias.model.wall" size=(40, 40, 80) }
+}
+saved LaneCube {
+    object cube { model="alias.model.lane" size=(80, 20, 6) }
+}
+saved PlayerUnit {
+    object hero : UnitStats { model="alias.model.player_unit" size=40 }
+}
+saved CreepUnit {
+    crowd sphere : CreepBrain { model="alias.model.creep" size=20 }
+}
+saved Projectile {
+    object sphere : ProjectileBrain { model="alias.model.projectile" size=6 }
+}
+saved TowerUnit {
+    object tower : TowerBrain { model="alias.model.tower" size=(60, 60, 120) }
+}
+saved TowerUnitR350 {
+    object tower : TowerBrain { 
+        model="alias.model.tower" 
+        size=(60, 60, 120)
+        override AttackRange=350 
+    }
+}
+
+screenCanvas MainUI : UIManager {
+    // Team roster (top-left): who is in the match, colored by team.
+    vStack Roster {
+        offset  = (20, 20)
+        padding = 8
+        gap     = 4
+        color   = (0.1, 0.1, 0.14)
+        textLabel RosterRow { count = 6 size = (200, 22) font_size = 14 }
+    }
+
+    // vStack title over a row of buy buttons; no size = hug to fit content.
+    vStack ShopWindow {
+        offset  = (1200, 600)
+        padding = 10
+        gap     = 10
+        color   = (0.2, 0.2, 0.25)
+        textLabel ShopTitle { size = (180, 30) text = "Item Shop" }
+        hStack BuyRow {
+            gap = (20, 0)
+            button BuyHPButton { size = (80, 80) text = "HP (10G)" }
+            button BuyManaButton { size = (80, 80) text = "MP (5G)" }
+        }
+    }
+
+    // hStack lays the skill buttons across; no size = hug (-> 370x100). Bottom-center anchored ability bar.
+    hStack SkillBar {
+        anchor  = (center, bottom)
+        offset  = (0, -20)
+        padding = 10
+        gap     = 10
+        button SkillButtonQ { size = (80, 80) color = (0.1, 0.1, 0.1) text = "Q (10)" }
+        button SkillButtonW { size = (80, 80) color = (0.1, 0.1, 0.1) text = "W" }
+        button SkillButtonE { size = (80, 80) color = (0.1, 0.1, 0.1) text = "E" }
+        button SkillButtonR { size = (80, 80) color = (0.1, 0.1, 0.1) text = "R" }
+    }
+    frame ShopPanel {
+        anchor = (right, bottom)
+        offset = (-20, -20)
+        size   = (140, 100)
+        button ShopButton {
+            offset = (10, 10)
+            size   = (120, 80)
+            textLabel ShopText {
+                text = "SHOP"
+            }
+        }
+    }
+}
+
+
+</example_dota>
+
+
+<example_fps_viewmodel>
+// Minimal FPS viewmodel skeleton — the engine defaults do the genre work:
+// EquipWeapon seats the hand on the library rifle's grip socket, the built-in canon
+// hold poses the first-person arms (hands + a sliver of forearm), and
+// EnableLocalWeaponView(Offset, RotationDeg, Scale, FovDegrees) renders weapon+arms
+// through the dedicated viewmodel pass (own FOV, never clips into walls).
+// No SetWeaponConfig, no anchors, no clips required.
+
+#class player
+var T: Number
+
+event OnSpawned {
+    SetCameraToFirstPerson()
+    EnableAutoMoveAnimations() // optional (walk/run clips while moving) - the viewmodel renders without it
+    EquipWeapon(Ori.alias.model.rifle)
+    EnableLocalWeaponView(Position(15, -22, 38), Vector(2, 4, 0), 1.0, 55)
+}
+
+event Update {
+    // Walk into the wall ahead: arms stay held, the viewmodel never clips.
+    T = T + 1
+    if T > 120 {
+        if T < 420 {
+            MoveInDirectionContinuously(Vector(0, 1, 0), 620)
+        }
+    }
+}
+#end
+
+object Ground {
+    model = "cube"
+    size = (2400, 2400, 20)
+    position = (0, 0, -10)
+    color = (0.45, 0.5, 0.4)
+}
+
+object Wall {
+    model = "cube"
+    size = (800, 60, 300)
+    position = (0, 300, 150)
+    color = (0.6, 0.55, 0.5)
+}
+
+</example_fps_viewmodel>
+
+
+<example_grass_meadow_adjuster_demo>
+// Grass meadow: built-in tuft-card grass on gentle hills, all global grass/ground
+// look knobs declared (values apply on load; sliders live in the Terrain inspector -
+// click the terrain; Ctrl+S folds edits back into this block). Ground under grass auto-tints.
+
+#adjuster
+section "Grass"
+knob SetGrassRootColor = #41591c
+knob SetGrassTipColor = #93b944
+knob SetGrassBrightnessVariationPercent = 120
+knob SetGrassSizeVariationPercent = 100
+knob SetGrassHeightMinCm = 20
+knob SetGrassHeightMaxCm = 90
+knob SetGrassWavePeriodCm = 700
+knob SetGrassWindStrengthCm = 4 range 0..30
+knob SetGrassWindSpeedPercent = 100 range 0..300
+knob SetGrassBladeWidthPercent = 100
+knob SetGrassSpacingCm = 20 range 0..60
+#end
+
+// Tuft-card atlas (replaces the built-in one via SetTerrainGrass material): 2x2 variant
+// cells, GREYSCALE luminance = root->tip gradient; color comes from the grass color knobs.
+#texture GrassTufts
+mapping = uv;
+wrap = clamp;
+render_mode = cutout;
+param blades = 34.0 range 12.0..60.0;
+let vid = floor(uv.x * 2.0) + floor(uv.y * 2.0) * 2.0;
+let lu = fract(uv.x * 2.0);
+let g = 1.0 - fract(uv.y * 2.0);
+let fan = (lu - 0.5) * (0.3 + 0.3 * rand(vid, seed: 3.0)) * g * g;
+let x = lu - fan;
+let id = floor(x * blades) + vid * 977.0;
+let bell = sat(1.0 - abs((floor(x * blades) + 0.5) / blades - 0.5) * 2.4);
+let h = (0.25 + 0.70 * rand(id)) * (0.25 + 0.75 * bell);
+let t = sat((g - 0.06) / max(h - 0.06, 0.05));
+let curve = (rand(id, seed: 13.0) - 0.5) * 0.55 * t * t;
+let w = (0.34 + 0.30 * rand(id, seed: 7.0)) * (1.0 - 0.75 * t * t) * sat(t * 7.0);
+let strip = 1.0 - smoothstep(w, w + 0.22, abs(fract(x * blades) - 0.5 + curve) * 2.0);
+let a = strip * (1.0 - smoothstep(h - 0.10, h, g)) * step(0.08, h) * smoothstep(0.0, 0.05, t);
+out.color = ramp(t, [0.0: color("#0a0a0a"), 1.0: color("#e6e6e6")]) * (0.85 + 0.30 * rand(id, seed: 5.0));
+out.alpha = sat(a) * smoothstep(0.01, 0.05, lu) * (1.0 - smoothstep(0.95, 0.99, lu));
+out.orm = orm(occlusion: 1.0, roughness: 0.85, metallic: 0.0);
+out.normal = normal_from_height(g * 0.0, strength: 1.0);
+#end
+
+#class MeadowWorld
+event OnSpawned {
+    var heights: List<Number> = []
+    heights.Resize(49 * 49, 0)
+    TerrainHeightsNoise(heights, 49, 49, 0, 16, 3, 7, 220, 0) // gentle fbm hills
+    var t = SpawnTerrainFromHeights(heights, 49, 49, 100, Origin())
+    t.SetTerrainGrass(None, Material.GrassTufts) // (None, None) also fine: built-in atlas, same knobs
+}
+#end
+
+display MeadowWorldObject : MeadowWorld { visible = false }
+
+</example_grass_meadow_adjuster_demo>
+
+
+<example_grassy_eroded_hills>
+#class player
+event OnSpawned {
+    forever {
+        var Direction = GetMoveVectorCamera()
+        MoveInDirectionContinuouslyFacing(Direction, 900)
+    }
+}
+event ActionDownByThisPlayer[Jump] {
+    if IsOnGround() {
+        Jump(1000)
+    }
+}
+#end
+
+// grassy_eroded_hills: a complete outdoor scene from the eroded_mountain terrain preset -
+// rolling eroded hills as one lush grass field, lakes in the valleys, gentle water swell.
+// Pattern notes:
+// - A bare #terrain block (preset only) is a complete terrain; add keys to override.
+// - The visible water level is SetWaterEnabled's sea level. The recipe field never goes
+//   below its own zero, so WorldGen scans the generated heights and drops the terrain so
+//   the deepest valley sits 3m under the sea - that is what makes the lakes.
+// - One #texture ground surface: a single flat color + fine grain only. Low-frequency
+//   color patches tile visibly at distance - avoid them.
+// - The baked ground normal scales live via SetTerrainNormalStrengthPercent.
+
+#terrain GrassLand
+preset = eroded_mountain
+#end
+
+#adjuster
+section "Grass"
+knob SetGrassTipColor = #71b23e
+knob SetGrassRootColor = #66a139
+knob SetGrassBrightnessVariationPercent = 25
+knob SetGrassHeightMaxCm = 100
+knob SetGrassHeightMinCm = 50
+knob SetGrassWavePeriodCm = 700
+knob SetGrassWindStrengthCm = 6 range 0..20
+section "Ground"
+knob SetTerrainNormalStrengthPercent = 20 range 0..300
+#end
+
+#texture GrassGround
+tile_m = 4.0;
+let fine = noise.fbm(uv * 20.0, octaves: 4, seed: 7, period: 20);
+let micro = noise.fbm(uv * 64.0, octaves: 2, seed: 9, period: 64);
+out.color = color("#73aa3e") * (0.96 + fine * 0.05 + micro * 0.03);
+out.height = fine * 0.6 + micro * 0.4;
+out.normal = normal_from_height(fine * 0.5 + micro * 0.5, strength: 0.5);
+out.orm = orm(occlusion: 1.0, roughness: 0.95, metallic: 0.0);
+#end
+
+#terrain_surfaces GrassFieldSurfaces
+surface = baked.GrassGround.color, baked.GrassGround.normal, 4.0, baked.GrassGround.orm, 1.0
+#end
+
+// One surface everywhere (weights pick surface 0; grass density = its affinity 1.0).
+#shader GrassFieldWeights
+fn ori_surface_weights(ctx: OriSurfaceWeightsCtx) -> OriSurfaceWeights {
+    var w: OriSurfaceWeights;
+    w.w0 = vec4<f32>(1.0, 0.0, 0.0, 0.0);
+    w.w1 = vec4<f32>(0.0, 0.0, 0.0, 0.0);
+    return w;
+}
+#end
+
+material GrassFieldWeightsMat { shader = "GrassFieldWeights" }
+
+#class WorldGen
+event OnSpawned {
+    var heights: List<Number> = []
+    var ridges: List<Number> = []
+    TerrainHeightsFromTerrain(heights, ridges, 192, 192, 150)
+    var minH = 99999999
+    for h in heights {
+        if h < minH { minH = h }
+    }
+    var terrain = SpawnTerrainFromHeights(heights, 192, 192, 150, Position(0, 0, 0 - minH - 300))
+    terrain.SetTerrainSurfaces("GrassFieldSurfaces")
+    terrain.SetTerrainSurfaceWeightsMaterial(Material.GrassFieldWeightsMat)
+    SetTerrainDisplayExtension(3000)
+    SetCameraFarDistanceM(3000)
+    SetFogEndDistance(2800)
+    SetSunTilt(33)
+    SetSunRotation(35)
+    SetWaterEnabled(true, 0)
+    SetWaterWaves(5, 800, 0.3, 0, 100)
+}
+#end
+
+display WorldGenObj : WorldGen { visible = false }
+
+</example_grassy_eroded_hills>
+
+
+<example_saved_block_font>
+// Declarative fonts work inside saved blocks (font = "font.google.<Family>" +
+// font_size); spawned copies keep the custom font.
+#class player
+event OnSpawned {
+    SetDefaultPlayerControlsEnabled(true)
+    var hud = SpawnCanvas(SavedObject.StyledHud, Origin())
+    hud.SetPlayerOwnerIndex(GetPlayerIndex())
+}
+#end
+
+object Ground { model = "cube" size = (4000, 4000, 20) position = (0, 0, -10) }
+
+saved StyledHud {
+    screenCanvas C {
+        vStack Panel { offset = (40, 40) padding = 12 gap = 8 color = #1E1E1EF0
+            textLabel T { size = (360, 80) text = "Styled" font = "font.google.Lobster" font_size = 40 }
+            button B { size = (260, 70) text = "Ok" font = "font.google.Roboto_Mono" font_size = 24 }
+        }
+    }
+}
+
+</example_saved_block_font>
+
+
+<example_stardew_valley>
+// Stardew-like Farming Prototype: engine inventory (item clauses + BindInventory hotbar with
+// engine-side drag/swap), tools, crops, resources, drops, selling, energy/day cycle.
+// Pattern notes:
+// - Items are `item` clauses; the hotbar is ONE empty hStack + BindInventory (engine spawns
+//   synced draggable slots; SetInventorySelectable gives hotbar selection). No slot markup,
+//   no per-slot refresh code, no hand-rolled drag: drops land in InventoryDropOnWorld.
+// - Multiplayer: shared farm world (crops/tools/drops are shared and per-player-interactable);
+//   Bag is per-player (created in player OnSpawned).
+//   Caveat: the gold/energy/day HUD and shop are single shared canvases (single-player-shaped UI).
+#set TileSize = 100
+
+// Bare aliases (no target): auto-bound from the generated model / UI-image libraries by name.
+alias model.soil_tile
+alias model.cabbage
+alias model.carrot
+alias model.grape
+alias model.chest
+alias model.shop_counter
+alias model.flat_rock_slab
+alias model.trunk
+alias model.grass_rock_cliff
+alias model.green_maple_tree
+alias model.bed
+alias model.ground_item
+alias model.held_item
+
+alias image.gold_icon
+alias image.energy_icon
+// One icon per item type (referenced by the item clauses below).
+alias image.hoe_icon
+alias image.parsnip_seeds_icon
+alias image.parsnip_icon
+alias image.watering_can_icon
+alias image.pickaxe_icon
+alias image.axe_icon
+alias image.scythe_icon
+alias image.fishing_rod_icon
+alias image.wood_icon
+alias image.stone_icon
+alias image.potato_seeds_icon
+alias image.bean_seeds_icon
+alias image.potato_icon
+alias image.bean_icon
+
+// Item definitions: name/tip/icon show in the bound hotbar; stack= caps per-slot count;
+// value= is what the shipping bin pays (no value = not sellable).
+item hoe           { name="Hoe" tip="Till green plots into soil." icon="alias.image.hoe_icon" tint=(0.7,0.7,0.9) }
+item watering_can  { name="Watering Can" tip="Water planted crops to speed growth. Refill at the pond." icon="alias.image.watering_can_icon" tint=(0.2,0.55,1.0) }
+item pickaxe       { name="Pickaxe" tip="Break rocks for stone." icon="alias.image.pickaxe_icon" tint=(0.65,0.65,0.65) }
+item axe           { name="Axe" tip="Chop trees for wood." icon="alias.image.axe_icon" tint=(0.75,0.35,0.12) }
+item scythe        { name="Scythe" tip="Harvest mature crops quickly." icon="alias.image.scythe_icon" tint=(0.55,1.0,0.55) }
+item fishing_rod   { name="Fishing Rod" tip="A classic Stardew tool placeholder." icon="alias.image.fishing_rod_icon" tint=(0.7,0.45,0.2) }
+item parsnip_seeds { name="Parsnip Seeds" tip="Plant on tilled soil. Grows after watering/time." icon="alias.image.parsnip_seeds_icon" tint=(0.2,0.9,0.2) stack=99 value=2 }
+item potato_seeds  { name="Potato Seeds" tip="Plant on tilled soil. Sells for more than parsnips." icon="alias.image.potato_seeds_icon" tint=(0.75,0.55,0.25) stack=99 }
+item bean_seeds    { name="Bean Seeds" tip="Plant on tilled soil. High value crop." icon="alias.image.bean_seeds_icon" tint=(0.15,0.75,0.35) stack=99 }
+item parsnip       { name="Parsnip" tip="Crop. Drag to the shipping bin to sell for 20g." icon="alias.image.parsnip_icon" tint=(1.0,0.85,0.15) stack=99 value=20 }
+item potato        { name="Potato" tip="Crop. Drag to the shipping bin to sell for 35g." icon="alias.image.potato_icon" tint=(0.85,0.65,0.28) stack=99 value=35 }
+item bean          { name="Bean" tip="Crop. Drag to the shipping bin to sell for 50g." icon="alias.image.bean_icon" tint=(0.15,0.9,0.4) stack=99 value=50 }
+item wood          { name="Wood" tip="Basic crafting material. Drag to the ground to drop." icon="alias.image.wood_icon" tint=(0.45,0.22,0.08) stack=99 value=1 }
+item stone         { name="Stone" tip="Basic crafting material. Drag to the ground to drop." icon="alias.image.stone_icon" tint=(0.55,0.55,0.55) stack=99 value=1 }
+
+#class player
+var Money = 100
+var Energy = 100
+var MaxEnergy = 100
+var Water = 0
+var MaxWater = 20
+var Day = 1
+var Sleeping = false
+
+var Bag: Object
+var LastSelected: Object
+var HeldVisual: Object
+var UseAnimFrames = 0
+
+var StatsLabel: Object
+var EnergyLabel: Object
+var DayLabel: Object
+var SleepFade: Object
+var DayToast: Object
+
+var UsedHoe = false
+var UsedSeeds = false
+var UsedWater = false
+var UsedPickaxe = false
+var UsedAxe = false
+var UsedScythe = false
+var UsedFishing = false
+var HasHarvested = false
+var SleepMoveAllowed = false
+
+var ShopPanel: Object
+var ShopMessage: Object
+
+func SelectedTool() -> Object {
+    return Bag.ItemAt(Bag.GetSelectedIndex())
+}
+
+func IsToolLike(it: Object) -> Bool {
+    if it == Item.hoe or it == Item.watering_can or it == Item.pickaxe or it == Item.axe { return true }
+    if it == Item.scythe or it == Item.fishing_rod { return true }
+    if it == Item.parsnip_seeds or it == Item.potato_seeds or it == Item.bean_seeds { return true }
+    return false
+}
+
+func FirstTimeHint(it: Object) -> Text {
+    if it == Item.hoe and not UsedHoe { return "Hoe: face a green plot, then click anywhere." }
+    if it == Item.parsnip_seeds and not UsedSeeds { return "Seeds: click empty tilled soil to plant." }
+    if it == Item.watering_can and not UsedWater { return "Watering Can: refill at pond, then face crops and click." }
+    if it == Item.pickaxe and not UsedPickaxe { return "Pickaxe: click rocks to break them." }
+    if it == Item.axe and not UsedAxe { return "Axe: click trees to chop wood." }
+    if it == Item.scythe and not UsedScythe { return "Scythe: click mature crops to harvest." }
+    if it == Item.fishing_rod and not UsedFishing { return "Fishing Rod: try it by the pond (F)." }
+    return ""
+}
+
+// Add with overflow feedback; the engine fills existing stacks first.
+func FarmAddItem(it: Object, count: Number) -> Bool {
+    if it == None or count <= 0 { return false }
+    var overflow = Bag.AddItem(it, count)
+    if overflow > 0 {
+        SpawnFloatingText("Inventory full", Vector(1, 1, 0))
+        if overflow == count { return false }
+    }
+    return true
+}
+
+// Remove one of the selected slot's item (seeds on planting).
+func ConsumeSelectedOne() -> Bool {
+    var slot = Bag.GetSelectedIndex()
+    var it = Bag.ItemAt(slot)
+    var c = Bag.CountAt(slot)
+    if it == None or c <= 0 { return false }
+    Bag.SetAt(slot, it, c - 1)
+    return true
+}
+
+func RefreshHud() {
+    var waterText = ""
+    if SelectedTool() == Item.watering_can { waterText = "\n" + Water + "/" + MaxWater }
+    StatsLabel.SetText(Money.ToText())
+    EnergyLabel.SetText(Energy + "/" + MaxEnergy + waterText)
+    DayLabel.SetText("Day " + Day)
+    if SelectedTool() == Item.watering_can { SetHoverSPBar(Water, MaxWater) } else { ClearHoverBars() }
+}
+
+func ShowPickupItem(it: Object) {
+    SpawnFloatingText("+" + ItemName(it), ItemTint(it))
+}
+
+func DropItemInFront(it: Object, count: Number) {
+    var pos = GetPositionFront(70)
+    var d = SpawnObject(SavedObject.groundItem, Position(pos.X, pos.Y, 70))
+    d.ItemDef = it
+    d.Count = count
+    d.RefreshDrop()
+}
+
+func BuySeed(it: Object, count: Number, cost: Number) {
+    if Money < cost {
+        ShopMessage.SetText("Not enough money")
+        ShopMessage.SetUiColor(Vector(1, 0.1, 0.1))
+        return
+    }
+    if FarmAddItem(it, count) {
+        Money -= cost
+        ShopMessage.SetText("Bought " + ItemName(it))
+        ShopMessage.SetUiColor(Vector(0.3, 1, 0.3))
+        SpawnFloatingText("Bought " + ItemName(it), ItemTint(it))
+        RefreshHud()
+    }
+}
+
+event OnSpawned {
+    SetCameraToTopDown()
+    SetCameraZoom(900)
+    SetCameraTiltDown(45)
+    TeleportToTile(0, -4)
+
+    Bag = CreateInventory(12)
+    Bag.AddItem(Item.hoe, 1)
+    Bag.AddItem(Item.watering_can, 1)
+    Bag.AddItem(Item.pickaxe, 1)
+    Bag.AddItem(Item.axe, 1)
+    Bag.AddItem(Item.scythe, 1)
+    Bag.AddItem(Item.parsnip_seeds, 9)
+    Bag.AddItem(Item.fishing_rod, 1)
+    Scene.Hotbar.BindInventory(Bag)           // engine spawns synced draggable slots
+    Scene.Hotbar.SetInventorySelectable(true) // click a slot to equip it
+
+    StatsLabel = Scene.GoldText
+    EnergyLabel = Scene.EnergyText
+    DayLabel = Scene.DayText
+    SleepFade = Scene.SleepFade
+    DayToast = Scene.DayToast
+    ShopPanel = Scene.ShopPanel
+    ShopMessage = Scene.ShopMessage
+    Scene.GoldIcon.SetUiImage(Ori.alias.image.gold_icon)
+    Scene.EnergyIcon.SetUiImage(Ori.alias.image.energy_icon)
+
+    ShopPanel.SetVisible(false)
+    SleepFade.SetVisible(false)
+    SleepFade.SetUiOpacity(0)
+    DayToast.SetVisible(false)
+    HeldVisual = SpawnObject(SavedObject.heldItemVisual, GetPositionFront(80).Up(25))
+    HeldVisual.SetVisible(false)
+    RefreshHud()
+
+    forever {
+        var dir = GetMoveVectorWorld()
+        if not Sleeping or SleepMoveAllowed { MoveInDirectionContinuouslyFacing(dir, 350) }
+
+        var sel = SelectedTool()
+        if sel != LastSelected {
+            LastSelected = sel
+            if sel != None { SpawnFloatingText("Equipped " + ItemName(sel), ItemTint(sel)) }
+            RefreshHud()
+        }
+
+        if sel != None and IsToolLike(sel) {
+            HeldVisual.SetVisible(true)
+            HeldVisual.SetColor(ItemTint(sel))
+            var phase = 0
+            var push = 0
+            var lift = 18
+            var scale = 24
+            if UseAnimFrames > 0 {
+                phase = UseAnimFrames
+                if phase > 6 { phase = 12 - phase }
+                push = phase * 5
+                lift = 18 - phase * 3
+                scale = 24 + phase * 12.7
+                UseAnimFrames -= 1
+            }
+            if phase > 0 {
+                HeldVisual.SetSize(scale, scale, 6)
+                var area = GetPositionFront(32 + push)
+                HeldVisual.SetPosition(Position(area.X, area.Y, lift.Max(0)))
+            } else {
+                HeldVisual.SetSize(24, 24, 24)
+                HeldVisual.SetPosition(GetPositionFront(32).Up(18))
+            }
+            var hint = FirstTimeHint(sel)
+            if hint != "" { Say(hint) } else { ClearSay() }
+        } else {
+            if HeldVisual.Exists() { HeldVisual.SetVisible(false) }
+            ClearSay()
+        }
+
+        var bed = NearestObjectWithTag(Tag.Bed)
+        if bed.Exists() and SurfaceGapXYTo(bed) < 140 {
+            bed.Say("Press E to sleep")
+        } else {
+            if bed.Exists() { bed.ClearSay() }
+        }
+        var counter = NearestObjectWithTag(Tag.ShopCounter)
+        if counter.Exists() and SurfaceGapXYTo(counter) < 180 {
+            counter.Say("Tap/use counter to buy seeds")
+        } else {
+            if counter.Exists() { counter.ClearSay() }
+        }
+        for plotHint in GetAllObjectsWithTag(Tag.Plot) {
+            if not HasHarvested and plotHint.CropStage == 4 and SurfaceGapXYTo(plotHint) < 220 {
+                plotHint.Say("Tap/use to harvest")
+            } else {
+                plotHint.ClearSay()
+            }
+        }
+    }
+}
+
+event ActionDownByThisPlayer[Primary] {
+    if Scene.Hotbar.IsMouseOnUi() { return } // clicking the hotbar selects/drags, not uses
+    UseAnimFrames = 12
+    var sel = SelectedTool()
+    var front = GetPositionFront(90)
+    var readyPlot = front.NearestObjectWithTag(Tag.Plot)
+    if readyPlot.Exists() and front.SurfaceGapXYTo(readyPlot) < 130 and readyPlot.CropStage == 4 {
+        readyPlot.ApplyTool(Self)
+        return
+    }
+    if sel == Item.hoe or sel == Item.watering_can or sel == Item.scythe or sel == Item.parsnip_seeds or sel == Item.potato_seeds or sel == Item.bean_seeds {
+        var plot = front.NearestObjectWithTag(Tag.Plot)
+        if plot.Exists() and front.SurfaceGapXYTo(plot) < 130 {
+            plot.ApplyTool(Self)
+        } else if sel == Item.hoe {
+            SpawnFloatingText("Stand close and face a green plot", Vector(1, 1, 0))
+        } else if sel == Item.watering_can {
+            var pond = front.NearestObjectWithTag(Tag.Pond)
+            if pond.Exists() and front.SurfaceGapXYTo(pond) < 125 {
+                Water = MaxWater
+                UsedWater = true
+                SpawnFloatingText("Water refilled", Vector(0.2, 0.6, 1))
+                RefreshHud()
+            }
+        }
+    } else if sel == Item.pickaxe or sel == Item.axe {
+        var res = front.NearestObjectWithTag(Tag.Resource)
+        if res.Exists() and front.DistanceXYTo(res) < 85 { res.ApplyTool(Self) }
+    }
+}
+
+// Bound-slot drag released over the world: sell on the shipping bin, else drop at the feet.
+// The engine does not mutate the inventory here — the game decides (clear the slot ourselves).
+event InventoryDropOnWorld {
+    if Event.DropObject.Exists() and Event.DropObject.HasTag(Tag.SellBox) {
+        var value = ItemValue(Event.Item) * Event.Count
+        if value > 0 {
+            Money += value
+            SpawnFloatingText("Sold for " + value + "g", Vector(1, 0.9, 0.1))
+            Bag.SetAt(Event.SlotIndex, Event.Item, 0)
+            RefreshHud()
+        } else {
+            SpawnFloatingText("That cannot be sold", Vector(1, 0.4, 0.2))
+        }
+        return
+    }
+    DropItemInFront(Event.Item, Event.Count)
+    Bag.SetAt(Event.SlotIndex, Event.Item, 0)
+}
+
+event ClickButton {
+    var clicked = Event.ClickedButton
+    if clicked == Scene.BuyParsnipButton { BuySeed(Item.parsnip_seeds, 5, 10) }
+    if clicked == Scene.BuyPotatoButton { BuySeed(Item.potato_seeds, 5, 20) }
+    if clicked == Scene.BuyBeanButton { BuySeed(Item.bean_seeds, 5, 30) }
+    if clicked == Scene.CloseShopButton { ShopPanel.SetVisible(false); ShopMessage.SetText("") }
+}
+
+event KeyboardDownByThisPlayer[F] {
+    if SelectedTool() == Item.fishing_rod {
+        UsedFishing = true
+        SpawnFloatingText("Fishing coming soon", ItemTint(Item.fishing_rod))
+    }
+}
+
+event KeyboardDownByThisPlayer[E] {
+    if Sleeping { return }
+    var bed = NearestObjectWithTag(Tag.Bed)
+    if bed.Exists() and SurfaceGapXYTo(bed) < 140 {
+        bed.ClearSay()
+        Sleeping = true
+        SleepMoveAllowed = false
+        SleepFade.SetVisible(true)
+        DayToast.SetVisible(false)
+        for i in 0..11 {
+            SleepFade.SetUiOpacity(i / 10)
+            Wait(0.1)
+        }
+        Day += 1
+        Energy = MaxEnergy
+        for plot in GetAllObjectsWithTag(Tag.Plot) {
+            plot.NewDay()
+        }
+        RefreshHud()
+        DayToast.SetText("Day " + Day)
+        DayToast.SetVisible(true)
+        SleepMoveAllowed = true
+        for j in 0..11 {
+            SleepFade.SetUiOpacity(1 - j / 10)
+            Wait(0.1)
+        }
+        SleepFade.SetVisible(false)
+        Wait(1.0)
+        DayToast.SetVisible(false)
+        SleepMoveAllowed = false
+        Sleeping = false
+    }
+}
+#end
+
+#class FarmPlot
+var Tilled = false
+var CropStage = 0
+var CropAge = 0
+var CropDef: Object
+var Watered = false
+var CropVisual: Object
+
+func CropColor(stage: Number) -> Vector {
+    if CropDef == Item.potato {
+        if stage == 1 { return Vector(0.25, 0.16, 0.06) }
+        if stage == 2 { return Vector(0.55, 0.38, 0.18) }
+        if stage == 3 { return Vector(0.70, 0.50, 0.22) }
+        return Vector(0.82, 0.60, 0.25)
+    }
+    if CropDef == Item.bean {
+        if stage == 1 { return Vector(0.05, 0.22, 0.08) }
+        if stage == 2 { return Vector(0.10, 0.55, 0.18) }
+        if stage == 3 { return Vector(0.10, 0.78, 0.24) }
+        return Vector(0.12, 0.95, 0.35)
+    }
+    if stage == 1 { return Vector(0.16, 0.09, 0.04) }
+    if stage == 2 { return Vector(0.30, 0.70, 0.25) }
+    if stage == 3 { return Vector(0.55, 0.85, 0.22) }
+    return Vector(1.0, 0.85, 0.25)
+}
+
+func UpdateLook() {
+    if not Tilled {
+        SetColor(0.70, 0.90, 0.70)
+    } else {
+        if Watered { SetColor(0.55, 0.50, 0.45) } else { SetColor(1, 1, 1) }
+    }
+    SetSizeTiles(0.9, 0.9, 0.02)
+
+    if CropStage == 0 {
+        if CropVisual.Exists() { CropVisual.Destroy() }
+    } else {
+        if not CropVisual.Exists() { CropVisual = SpawnObject(SavedObject.cropVisual, GetPosition().Up(8)) }
+        CropVisual.SetPosition(GetPosition().Up(8))
+        if CropDef == Item.potato { CropVisual.SetModel(Ori.alias.model.carrot) }
+        else if CropDef == Item.bean { CropVisual.SetModel(Ori.alias.model.grape) }
+        else { CropVisual.SetModel(Ori.alias.model.cabbage) }
+        if CropStage == 1 {
+            CropVisual.SetColor(CropColor(1))
+            CropVisual.SetSize(28, 28, 10)
+        } else if CropStage == 2 {
+            CropVisual.SetColor(CropColor(2))
+            CropVisual.SetSize(55, 55, 25)
+        } else if CropStage == 3 {
+            CropVisual.SetColor(CropColor(3))
+            CropVisual.SetSize(65, 65, 45)
+        } else {
+            CropVisual.SetColor(CropColor(4))
+            CropVisual.SetSize(75, 75, 65)
+        }
+    }
+}
+
+event OnSpawned {
+    AddTag(Tag.Plot)
+    UpdateLook()
+}
+
+func NewDay() {
+    if CropStage > 0 and CropStage < 4 {
+        if Watered {
+            CropAge += 1
+            CropStage = 1 + CropAge
+            if CropStage > 4 { CropStage = 4 }
+        }
+        Watered = false
+        UpdateLook()
+    }
+}
+
+func Harvest(p: Object) {
+    if p.FarmAddItem(CropDef, 1) {
+        if p.SelectedTool() == Item.scythe { p.UsedScythe = true }
+        p.HasHarvested = true
+        var harvested = CropDef
+        CropStage = 0
+        CropAge = 0
+        Watered = false
+        if p.SelectedTool() == Item.scythe { p.SpawnFloatingText("Scythed " + ItemName(harvested), Vector(1, 1, 0.2)) }
+        else { p.SpawnFloatingText("Harvested " + ItemName(harvested), Vector(1, 1, 0.2)) }
+        UpdateLook()
+    }
+}
+
+func ApplyTool(p: Object) {
+    if SurfaceGapXYTo(p) > 120 {
+        p.SpawnFloatingText("Too far", Vector(1, 1, 0))
+        return
+    }
+    if CropStage == 4 {
+        Harvest(p)
+        return
+    }
+    var sel = p.SelectedTool()
+    if sel == Item.hoe {
+        if not Tilled {
+            if p.Energy <= 0 { p.SpawnFloatingText("Too tired", Vector(1, 0, 0)); return }
+            p.UsedHoe = true
+            Tilled = true
+            p.Energy -= 3
+            p.SpawnFloatingText("Tilled soil", Vector(0.7, 0.4, 0.1))
+            p.RefreshHud()
+            UpdateLook()
+        } else {
+            p.SpawnFloatingText("Already tilled", Vector(1, 1, 1))
+        }
+    } else if sel == Item.parsnip_seeds or sel == Item.potato_seeds or sel == Item.bean_seeds {
+        if Tilled and CropStage == 0 {
+            CropDef = Item.parsnip
+            if sel == Item.potato_seeds { CropDef = Item.potato }
+            if sel == Item.bean_seeds { CropDef = Item.bean }
+            if p.ConsumeSelectedOne() {
+                p.UsedSeeds = true
+                CropStage = 1
+                CropAge = 0
+                p.SpawnFloatingText("Planted seeds", Vector(0.2, 1, 0.2))
+                UpdateLook()
+            }
+        } else {
+            p.SpawnFloatingText("Seeds need empty tilled soil", Vector(1, 1, 0))
+        }
+    } else if sel == Item.watering_can {
+        if p.Water <= 0 {
+            p.SpawnFloatingText("Watering can empty. Refill at pond.", Vector(0.2, 0.6, 1))
+            p.RefreshHud()
+            return
+        }
+        if Tilled and CropStage < 4 {
+            p.UsedWater = true
+            Watered = true
+            p.Water -= 1
+            p.Energy -= 1
+            p.SpawnFloatingText("Watered", Vector(0.2, 0.6, 1))
+            p.RefreshHud()
+            UpdateLook()
+        } else {
+            p.SpawnFloatingText("Nothing to water", Vector(1, 1, 1))
+        }
+    } else if sel == Item.scythe {
+        p.SpawnFloatingText("Nothing mature here", Vector(1, 1, 1))
+    } else {
+        p.SpawnFloatingText("Equip hoe, seeds, watering can, or scythe", Vector(1, 1, 1))
+    }
+}
+#end
+
+#class ShippingBin
+event OnSpawned {
+    AddTag(Tag.SellBox)
+    SetColor(0.45, 0.25, 0.05)
+    Say("Shipping Bin\nDrag crops here to sell")
+}
+#end
+
+#class ShopCounter
+event ClickThisObject {
+    var p = Event.Presser
+    p.ShopPanel.SetVisible(true)
+    p.ShopMessage.SetText("")
+}
+#end
+
+#class ToolResource
+var HP = 3
+var IsTree = true // true: axe chops it for wood; false: pickaxe breaks it for stone
+var DropCount = 1
+var Label = "Resource"
+
+event OnSpawned {
+    AddTag(Tag.Resource)
+    Say(Label)
+}
+
+func ApplyTool(p: Object) {
+    var needed = Item.pickaxe
+    if IsTree { needed = Item.axe }
+    if p.SelectedTool() != needed {
+        p.SpawnFloatingText("Use " + ItemName(needed), Vector(1, 1, 1))
+        return
+    }
+    if SurfaceGapXYTo(p) > 125 {
+        p.SpawnFloatingText("Too far", Vector(1, 1, 0))
+        return
+    }
+    HP -= 1
+    if IsTree { p.UsedAxe = true } else { p.UsedPickaxe = true }
+    p.Energy -= 2
+    p.RefreshHud()
+    SpawnFloatingText("-1", Vector(1, 1, 1))
+    if HP <= 0 {
+        var drop = Item.stone
+        if IsTree { drop = Item.wood }
+        if p.FarmAddItem(drop, DropCount) {
+            p.ShowPickupItem(drop)
+        } else {
+            p.DropItemInFront(drop, DropCount)
+        }
+        Destroy()
+    }
+}
+
+event ClickThisObject {
+    ApplyTool(Event.Presser)
+}
+#end
+
+#class GroundItem
+var ItemDef: Object
+var Count = 1
+
+func RefreshDrop() {
+    if ItemDef == Item.parsnip { SetModel(Ori.alias.model.cabbage) }
+    else if ItemDef == Item.wood { SetModel(Ori.alias.model.trunk) }
+    else if ItemDef == Item.stone { SetModel(Ori.alias.model.flat_rock_slab) }
+    else if ItemDef == Item.potato { SetModel(Ori.alias.model.carrot) }
+    else if ItemDef == Item.bean { SetModel(Ori.alias.model.grape) }
+    SetColor(ItemTint(ItemDef))
+    Say(ItemName(ItemDef) + " x" + Count + "\nClick to pick up")
+}
+
+event OnSpawned {
+    AddTag(Tag.Pickup)
+    SetSizeTiles(0.35, 0.35, 0.35)
+    RefreshDrop()
+    var startPos = GetPosition()
+    var restPos = Position(startPos.X, startPos.Y, 9)
+    forever {
+        if GetPosition().DistanceTo(restPos) >= 2 { MoveTowardContinuous(restPos, 260) }
+        var p = NearestPlayer()
+        if p.Exists() and SurfaceGapXYTo(p) < 160 {
+            Say(ItemName(ItemDef) + " x" + Count + "\nClick to pick up")
+        } else {
+            ClearSay()
+        }
+    }
+}
+
+event ClickThisObject {
+    var p = Event.Presser
+    if p.FarmAddItem(ItemDef, Count) {
+        p.SpawnFloatingText("Picked up " + ItemName(ItemDef), ItemTint(ItemDef))
+        Destroy()
+    } else {
+        SpawnFloatingText("Inventory full", Vector(1, 0, 0))
+    }
+}
+#end
+
+#class StardewRoomBuilder
+event OnSpawned {
+    var farmhouseWalls = BuildRoom(Position(-400, 400, 0), Vector(400, 300, 0), 20, 150, Vector(0, -1, 0), 400)
+    for wall in farmhouseWalls {
+        wall.SetColor(Vector(0.65, 0.35, 0.2))
+    }
+
+    var shopWalls = BuildRoom(Position(500, 600, 0), Vector(500, 400, 0), 18, 150, Vector(0, -1, 0), 150)
+    for wall in shopWalls {
+        wall.SetColor(Vector(0.55, 0.30, 0.16))
+    }
+}
+#end
+
+material GroundMat { base = "StylizedGrass" }
+object ground {
+    model = "cube"
+    material = "GroundMat"
+    position = (0, 0, -100)
+    size = (10000, 10000, 100)
+}
+display ___StardewRoomBuilder___ : StardewRoomBuilder { visible = false }
+
+// farm plots
+display plot_1_1 : FarmPlot { model="alias.model.soil_tile" position=(-100, 0, 1) }
+display plot_1_2 : FarmPlot { model="alias.model.soil_tile" position=(0, 0, 1) }
+display plot_1_3 : FarmPlot { model="alias.model.soil_tile" position=(100, 0, 1) }
+display plot_2_1 : FarmPlot { model="alias.model.soil_tile" position=(-100, 100, 1) }
+display plot_2_2 : FarmPlot { model="alias.model.soil_tile" position=(0, 100, 1) }
+display plot_2_3 : FarmPlot { model="alias.model.soil_tile" position=(100, 100, 1) }
+display plot_3_1 : FarmPlot { model="alias.model.soil_tile" position=(-100, 200, 1) }
+display plot_3_2 : FarmPlot { model="alias.model.soil_tile" position=(0, 200, 1) }
+display plot_3_3 : FarmPlot { model="alias.model.soil_tile" position=(100, 200, 1) }
+
+object shipBin : ShippingBin {
+    model="alias.model.chest"
+    position_tiles=(3, 0)
+    size_tiles=(0.8, 0.8, 0.8)
+}
+
+object pond {
+    model="alias.model.pond"
+    position_tiles=(4, 3)
+    size_tiles=(2, 1.5, 0.04)
+    color=(0.1, 0.35, 0.8)
+    tag=Tag.Pond
+}
+object farmhouseFloor {
+    model="alias.model.farmhouse_floor"
+    position_tiles=(-4, 4)
+    size_tiles=(4, 3, 0.08)
+    color=(0.45, 0.28, 0.16)
+}
+object bed {
+    model="alias.model.bed"
+    position_tiles=(-5, 4.6)
+    size=(112, 80, 64)
+    color=(0.2, 0.35, 0.9)
+    tag=Tag.Bed
+}
+object treeA : ToolResource { model="alias.model.green_maple_tree" position_tiles=(-5, -2) height=500 color=(0.25,0.15,0.05) override IsTree=true override DropCount=3 override Label="Tree" }
+object treeB : ToolResource { model="alias.model.green_maple_tree" position_tiles=(5, -2) height=500 color=(0.25,0.15,0.05) override IsTree=true override DropCount=3 override Label="Tree" }
+object rockA : ToolResource { model="alias.model.flat_rock_slab" position_tiles=(-3, -2) size_tiles=(0.7,0.7,0.45) color=(0.45,0.45,0.45) override IsTree=false override DropCount=3 override Label="Rock" }
+object rockB : ToolResource { model="alias.model.grass_rock_cliff" position_tiles=(3, -2) size_tiles=(0.7,0.7,0.45) color=(0.45,0.45,0.45) override IsTree=false override DropCount=3 override Label="Rock" }
+
+object shopFloor { model="alias.model.shop_floor" position_tiles=(5, 6) size_tiles=(5, 4, 0.08) color=(0.42, 0.30, 0.18) }
+object shopCounter : ShopCounter {
+    model="alias.model.shop_counter"
+    position=(563, 658, 73)
+    rotation=(0, 0, -90)
+    size=(80, 215, 130)
+    tag=Tag.ShopCounter
+}
+
+saved groundItem {
+    object drop : GroundItem { model="alias.model.ground_item" size_tiles=(0.35, 0.35, 0.35) }
+}
+saved heldItemVisual {
+    display heldItem { model="alias.model.held_item" size=30 visible=false }
+}
+saved cropVisual {
+    display crop { model="alias.model.crop" size=(28,28,10) }
+}
+
+screenCanvas FarmUI {
+    image GoldIcon {
+        offset = (20, 18)
+        size = (30, 30)
+    }
+    image EnergyIcon {
+        offset = (20, 51)
+        size = (30, 30)
+    }
+    textLabel DayText {
+        offset = (20, 96)
+        text = "Day 1"
+        color = (1, 1, 0.85)
+    }
+    // vStack auto-stacks the rows (centered); no size = hug to fit children. Center-anchored modal.
+    vStack ShopPanel {
+        visible = false
+        anchor = (center, center)
+        padding = 20
+        gap = 12
+        child_align_x = center
+        color = #14100AF2
+        corner_radius = 14
+        border_width  = 1
+        border_color  = #7A5A2EFF
+        textLabel ShopTitle { size=(320, 30) align=(center, center) text="Seed Shop" color=(1, 1, 0.8) }
+        button BuyParsnipButton { size=(300, 48) text="5 Parsnip Seeds - 10g" corner_radius=8 }
+        button BuyPotatoButton { size=(300, 48) text="5 Potato Seeds - 20g" corner_radius=8 }
+        button BuyBeanButton { size=(300, 48) text="5 Bean Seeds - 30g" corner_radius=8 }
+        textLabel ShopMessage { size=(320, 24) align=(center, center) text="" color=(1, 0.1, 0.1) }
+        button CloseShopButton { size=(140, 38) text="Close" corner_radius=8 }
+    }
+    // The whole hotbar: ONE empty hStack. BindInventory in player OnSpawned spawns a synced
+    // draggable 88x88 slot (icon + count + selection highlight) per inventory slot.
+    hStack Hotbar {
+        anchor = (center, bottom)
+        offset = (0, -6)
+        color = (0.12, 0.08, 0.04)
+        padding = 8
+        gap = 4
+    }
+    textLabel GoldText {
+        offset = (58, 22)
+        text = "0"
+        color = (1, 1, 1)
+    }
+    textLabel EnergyText {
+        offset = (58, 55)
+        text = "100/100"
+        color = (1, 1, 1)
+    }
+    frame SleepFade {
+        visible = false
+        offset = (0, 0)
+        size = (1600, 900)
+        color = (0, 0, 0)
+    }
+    textLabel DayToast {
+        visible = false
+        offset = (725, 410)
+        text = "Day 1"
+        color = (1, 1, 1)
+    }
+}
+
+screenCanvas TutorialUI {
+    textLabel HelpText {
+        offset = (20, 130)
+        text = """Move with WASD or mobile thumbstick
+Tap hotbar slots to equip
+Primary action uses the selected item
+Drag items out of slots to sell or drop them"""
+        color = (1, 1, 1)
+    }
+}
+
+</example_stardew_valley>
+
+
+<example_texture_dsl_desert_forest_demo>
+// Procedural texture DSL demo: semi-realistic desert wall + forest ground.
+
+#texture DesertWall
+tile_m = 2.0;
+let tile = pattern.tile(uv * vec2(6.0, 4.0), mortar: 0.065, seed: 3);
+let warp = noise.vec2(uv * 3.0, seed: 11, period: 3) * 0.18;
+let cells = pattern.voronoi(uv * vec2(12.0, 8.0) + warp, jitter: 0.82, seed: 7, period: vec2(12.0, 8.0));
+let cracks = stroke(cells.edge, width: 0.055, aa: 0.012);
+let grain = noise.ridged(uv * 72.0, octaves: 3, seed: 19, period: 72);
+let broad = noise.fbm(uv * vec2(6.0, 4.0), octaves: 4, seed: 23, period: vec2(6.0, 4.0));
+let chips = smoothstep(0.65, 0.95, noise.ridged(uv * 36.0, octaves: 3, seed: 29, period: 36)) * (1.0 - smoothstep(0.02, 0.18, tile.edge));
+let dust = levels(noise.fbm(uv * 5.0 + warp, octaves: 4, seed: 31, period: 5), black: 0.28, white: 0.86, gamma: 1.35);
+let block = contrast(sat(broad * 0.65 + grain * 0.25 + rand(tile.id, seed: 5) * 0.10), amount: 1.25, pivot: 0.45);
+let height = mix(-0.045, 0.11 + grain * 0.018 - chips * 0.06, tile.mask) - cracks * 0.07;
+let stone = ramp(block, [0.0: color("#7d664a"), 0.35: color("#a8875a"), 0.75: color("#c9a66f"), 1.0: color("#ead19c")]);
+let mortar = color("#75614b") * mix(0.82, 1.08, broad);
+out.color = mix(mortar, stone, tile.mask) * mix(0.82, 1.06, dust) - cracks * 0.12;
+out.normal = normal_from_height(height, strength: 1.05);
+out.orm = orm(occlusion: ao_from_height(height, radius: 2.5), roughness: mix(0.94, 0.82, tile.mask) + dust * 0.03, metallic: 0.0);
+#end
+
+#texture ForestGround
+tile_m = 3.0;
+let p = uv * vec2(8.0, 8.0);
+let warp = noise.vec2(uv * 2.0, seed: 41, period: 2) * 0.25;
+let soil = levels(noise.fbm(p + warp, octaves: 4, seed: 43, period: vec2(8.0, 8.0)), black: 0.18, white: 0.88, gamma: 1.2);
+let stones = pattern.voronoi(uv * vec2(7.0, 7.0) + warp * 0.6, jitter: 0.78, seed: 47, period: vec2(7.0, 7.0));
+let stone_shape = 1.0 - smoothstep(0.34, 0.47, stones.dist + noise.fbm(stones.local * 4.0, octaves: 2, seed: 53) * 0.08);
+let cell_guard = smoothstep(0.025, 0.07, stones.edge);
+let stone_mask = stone_shape * cell_guard;
+let moss = levels(noise.fbm(uv * vec2(5.0, 5.0) + warp * 1.4, octaves: 4, seed: 59, period: 5) + (1.0 - stone_mask) * 0.25, black: 0.44, white: 0.92, gamma: 0.85);
+let wet = contrast(noise.fbm(uv * 3.0 + warp, octaves: 3, seed: 61, period: 3), amount: 1.55, pivot: 0.48);
+let height = soil * 0.045 + moss * 0.035 + sat(1.0 - stones.dist * 2.1) * stone_mask * 0.10 - (1.0 - soil) * 0.025;
+let soil_color = ramp(soil, [0.0: color("#211912"), 0.45: color("#3b2b1d"), 1.0: color("#6c5538")]);
+let moss_color = ramp(moss, [0.0: color("#26351d"), 0.55: color("#43622d"), 1.0: color("#7f9b55")]);
+let stone_color = ramp(rand(stones.id, seed: 67), [0.0: color("#3e4039"), 0.5: color("#68675b"), 1.0: color("#918a78")]);
+out.color = mix(mix(soil_color, moss_color, moss * 0.82), stone_color, stone_mask * 0.75);
+out.normal = normal_from_height(height, strength: 0.95);
+out.orm = orm(occlusion: ao_from_height(height, radius: 2.0), roughness: mix(0.92, 0.58, wet), metallic: 0.0);
+#end
+
+object desert_wall {
+    model = "cube"
+    material = "DesertWall"
+    position = (0, -240, 160)
+    size = (700, 40, 320)
+}
+
+object forest_ground {
+    model = "cube"
+    material = "ForestGround"
+    position = (0, 180, -20)
+    size = (900, 520, 40)
+}
+
+</example_texture_dsl_desert_forest_demo>
+
+
+<example_texture_dsl_grunge_demo>
+// Procedural texture DSL demo: scalar mask morphology for grunge and worn painted metal.
+
+#texture GrungeMask
+tile_m = 1.5;
+wrap = repeat;
+let p = uv * vec2(8.0, 8.0);
+let warp = noise.vec2(uv * vec2(3.0, 3.0), seed: 71, period: 3) * 0.35;
+let cloudy = levels(noise.fbm(p + warp, octaves: 5, seed: 73, period: vec2(8.0, 8.0)), black: 0.24, white: 0.82, gamma: 1.18);
+let pepper = levels(noise.ridged(uv * vec2(72.0, 72.0), octaves: 3, seed: 79, period: 72), black: 0.58, white: 0.94, gamma: 0.75);
+let streak = levels(noise.ridged(vec2(uv.x * 160.0, uv.y * 5.0), octaves: 2, seed: 83, period: vec2(160.0, 5.0)), black: 0.66, white: 0.93, gamma: 0.65);
+let pits = dilate(erode(sat(cloudy * 0.62 + pepper * 0.32 + streak * 0.22), radius: 1.0), radius: 1.5);
+let softened = blur(pits, radius: 1.25);
+out.color = vec3(softened, softened, softened);
+out.normal = normal_from_height(softened * 0.05, strength: 0.45);
+out.orm = orm(occlusion: 1.0 - softened * 0.18, roughness: mix(0.55, 0.95, softened), metallic: 0.0);
+#end
+
+#texture WornPaintedMetal
+tile_m = 1.0;
+wrap = repeat;
+let p = uv * vec2(10.0, 10.0);
+let warp = noise.vec2(uv * vec2(4.0, 4.0), seed: 89, period: 4) * 0.28;
+let broad = noise.fbm(uv * vec2(5.0, 5.0) + warp, octaves: 4, seed: 97, period: 5);
+let cells = pattern.voronoi(uv * vec2(14.0, 14.0) + warp * 0.5, jitter: 0.74, seed: 101, period: 14);
+let crack = stroke(cells.edge, width: 0.035, aa: 0.010);
+let scratch = levels(noise.ridged(vec2(uv.x * 180.0, uv.y * 7.0), octaves: 2, seed: 103, period: vec2(180.0, 7.0)), black: 0.68, white: 0.96, gamma: 0.72);
+let chip_seed = levels(noise.ridged(p + warp, octaves: 4, seed: 107, period: 10), black: 0.62, white: 0.92, gamma: 0.85);
+let raw_wear = sat(chip_seed * 0.70 + scratch * 0.32 + crack * 0.55 - broad * 0.18);
+let wear = blur(dilate(erode(raw_wear, radius: 0.75), radius: 2.0), radius: 0.75);
+let rust = levels(noise.fbm(uv * vec2(18.0, 18.0) + warp, octaves: 3, seed: 109, period: 18), black: 0.30, white: 0.90, gamma: 1.35);
+let paint = color("#275f6f") * mix(0.70, 1.15, broad);
+let exposed = mix(color("#6f7473"), color("#8c4a24"), rust * 0.55);
+let height = broad * 0.035 - wear * 0.070 + scratch * 0.018;
+out.color = mix(paint, exposed, wear);
+out.normal = normal_from_height(height, strength: 0.95);
+out.orm = orm(occlusion: ao_from_height(height, radius: 2.0), roughness: mix(0.62, 0.92, wear), metallic: mix(0.02, 0.70, wear * (1.0 - rust * 0.55)));
+#end
+
+object grunge_panel {
+    model = "cube"
+    material = "GrungeMask"
+    position = (-260, 0, 80)
+    size = (260, 40, 180)
+}
+
+object worn_painted_metal_panel {
+    model = "cube"
+    material = "WornPaintedMetal"
+    position = (180, 0, 80)
+    size = (360, 40, 220)
+}
+
+</example_texture_dsl_grunge_demo>
+
+
+<example_tree_species>
+// Curated #tree species gallery. Each recipe is a reference worth copying as a
+// starting point for that habit; keep the shape keys, adjust seed/size per scene.
+// Iterate look changes with preview_tree and watch the foliage_coverage stat.
+
+// European beech: broad asymmetric dome from four overlapping crown lobes, a
+// trunk that persists partway into the crown (leader) then dissolves into forks,
+// slender bole, dense cluster cards.
+#tree Beech
+  seed: 27
+  mode: colonize
+  leader: 62
+  levels: 4
+  children: 7
+  segments: 7
+  trunk_height: 1250
+  trunk_radius: 34
+  points: 1024
+  length_pct: 76
+  radius_pct: 46
+  angle_deg: 46
+  angle_jitter_deg: 20
+  up_bias_pct: 26
+  curve_jitter_pct: 16
+  trunk_noise_pct: 4
+  trunk_lean_deg: 3        // gentle bands: beeches curve, they don't lean hard
+  trunk_sweep_pct: 16
+  trunk_noise_scale_pct: 30 // wavelength as % of height: slow bends, not bark-beat raggedness
+  leaves: 12
+  leaf_size: 178
+  droop_pct: 8
+  root_flare_pct: 34
+  crown_ellipsoid: 0, 0, 1020, 620, 590, 510
+  crown_ellipsoid: -250, 80, 960, 400, 370, 360
+  crown_ellipsoid: 240, -100, 1060, 420, 390, 400
+  crown_ellipsoid: 40, 50, 1380, 380, 350, 300
+#end
+
+// Grand open-grown oak: a dominant central trunk visible deep into the tiered
+// crown, three low limb masses ~120 degrees apart in plan (every viewing angle
+// shows a reaching limb - lobes on one axis collapse to a blob from the thin
+// side), offset upper lobes, real sky gaps. An irregular ellipsoid stack, not
+// one sphere. Open crowns like this read ~35-45% coverage; gaps are the character.
+#tree Oak
+  seed: 5
+  mode: colonize
+  leader: 35
+  levels: 4
+  children: 6
+  segments: 7
+  trunk_height: 950
+  trunk_radius: 44
+  points: 1024
+  length_pct: 80
+  radius_pct: 52
+  angle_deg: 55
+  angle_jitter_deg: 28
+  up_bias_pct: 22
+  curve_jitter_pct: 26
+  trunk_noise_pct: 7
+  trunk_lean_deg: 5      // low bands: a real oak is never a plumb pole
+  trunk_sweep_pct: 20    // one slow arc; seed picks C vs S
+  trunk_gnarl_pct: 40    // lobed lower-bole silhouette for hero close-ups (display-only)
+  leaves: 13
+  leaf_size: 190
+  droop_pct: 12
+  root_flare_pct: 45
+  crown_ellipsoid: 0, 0, 1120, 700, 660, 560
+  crown_ellipsoid: 435, 115, 930, 480, 430, 340
+  crown_ellipsoid: -320, 320, 900, 470, 420, 330
+  crown_ellipsoid: -115, -435, 1000, 450, 410, 350
+  crown_ellipsoid: -200, -190, 1500, 450, 410, 340
+  crown_ellipsoid: 230, 180, 1620, 390, 360, 300
+#end
+
+// Fir: the dense layered conifer - whorl rings of downswept shelf branches
+// (angle_deg > 90 + up_bias swoop) rendered as whole-branch frond ribbons,
+// clear bole below crown_base, trunk-only collider. crown_base ~120 instead
+// gives the ground-sweeping park look.
+#tree Fir
+  seed: 11
+  mode: whorl
+  leaf_mode: frond
+  levels: 2
+  children: 12
+  rings: 30
+  fill: 10
+  segments: 8
+  trunk_height: 1400
+  trunk_radius: 22
+  trunk_noise_pct: 2
+  trunk_lean_deg: 1      // conifer spires stand near-plumb; kill the default lean/sweep
+  trunk_sweep_pct: 3
+  curve_jitter_pct: 5
+  angle_deg: 106
+  up_bias_pct: 8
+  length_pct: 18
+  length_taper_pct: 70
+  droop_pct: 34
+  leaf_size: 200
+  root_flare_pct: 25
+  crown_base: 300
+  collider_levels: 1
+#end
+
+// Weeping willow: spiral limbs arch up (up_bias) then cascade (droop) carrying
+// gravity-hung strand curtains (leaf_mode weeping). Long falls come from
+// leaf_size (the curtain card side, cm) - ~300 reaches near the ground from a
+// stout mid-height fork.
+#tree Willow
+  seed: 9
+  mode: spiral
+  leaf_mode: weeping
+  levels: 3
+  children: 10
+  segments: 8
+  trunk_height: 750
+  trunk_radius: 46
+  length_pct: 82
+  radius_pct: 50
+  angle_deg: 40
+  angle_jitter_deg: 18
+  up_bias_pct: 34
+  curve_jitter_pct: 18
+  trunk_noise_pct: 5
+  trunk_lean_deg: 4
+  trunk_sweep_pct: 25    // waterside willows arc; pairs with the cascading crown
+  droop_pct: 85
+  leaves: 20
+  leaf_size: 300
+  root_flare_pct: 48
+#end
+
+// Umbrella-thorn acacia: crown_dome mushroom cap on a bare fanning scaffold. The
+// short trunk + high cap forces colonize to bridge with long limbs; the TWO bare
+// guide ellipsoids make them diverge early and fork again mid-way (a lone
+// overhead cap pulls one straight vertical reach instead - attraction averages
+// out). children raises the forks per node. leaf_base at the dome cut with a
+// short fade keeps every guide bare and the cap underside crisp and flat.
+#tree Acacia
+  seed: 4
+  mode: colonize
+  children: 7
+  trunk_height: 260
+  trunk_radius: 36
+  points: 1024
+  length_pct: 80
+  radius_pct: 60
+  curve_jitter_pct: 18
+  trunk_noise_pct: 6
+  trunk_lean_deg: 8      // savanna wind-shaped bole; crown_follow keeps the cap on it
+  leaves: 13
+  leaf_size: 185
+  leaf_base: 740
+  leaf_base_fade: 60
+  root_flare_pct: 35
+  crown_ellipsoid: 0, 0, 520, 300, 300, 160
+  crown_ellipsoid: 0, 0, 690, 460, 460, 90
+  crown_dome: 0, 0, 750, 800, 800, 360
+#end
+
+object Beech1  { model = "tree.Beech"  position = (0, 0, 0) }
+object Oak1    { model = "tree.Oak"    position = (2200, 0, 0) }
+object Fir1    { model = "tree.Fir"    position = (4000, 0, 0) }
+object Willow1 { model = "tree.Willow" position = (5800, 0, 0) }
+object Acacia1 { model = "tree.Acacia" position = (8000, 0, 0) }
+
+</example_tree_species>
+
+
+<example_vampire_survivor>
+// Vampire Survivor Lite
+//  Player: movement, auto-attack, level-up choices
+// Multiplayer: co-op shared arena.
+//   Enemies/gems target the nearest player; per-player auto-attack and leveling.
+//   Caveat: the level-up panel (LevelUpUI) is a single shared canvas and gates all players' attacks while open.
+alias model.goblin = "ori.model.nattawut_rea_6383.goblina"
+alias model.fox = "ori.default.fox"
+alias model.raptor = "ori.default.raptor"
+alias model.dragon = "ori.default.dragon"
+alias model.exp_gem // bare: auto-binds a generated mesh from the library
+alias effect.fireball = "ori.effect.worapat_supa_4983.w_fireball_2821"
+alias effect.poisonball = "ori.effect.worapat_supa_4983.w_poisonball_6320"
+alias effect.magicball = "ori.effect.nuttametee_b_2523.w_magicbulle"
+alias effect.snowball = "ori.effect.worapat_supa_4983.w_snowball_7592"
+alias effect.fire_area = "ori.effect.worapat_supa_4983.w_fireaura"
+alias effect.snowball_burst = "ori.effect.akkarawut_sa_2573.w_snowballbu41"
+
+#class player
+    var HP = 500
+    var MaxHP = 500
+    var XP = 0
+    var NextLevelXP = 5
+
+    var AttackCooldown = 1.0 // seconds
+    var AttackDamage = 35 // base damage
+
+    var WeaponLevel = 1
+    var LevelUpPanel: Object
+    var Choices: List<Object>
+
+    event OnSpawned {
+        SetCameraToTopDown()
+        TeleportToTile(0, 0)
+
+        HP = MaxHP
+        SetHoverHPBar(HP, MaxHP)
+        LevelUpPanel = Scene.LevelUpPanel
+        LevelUpPanel.SetVisible(false)
+        Choices.Add(LevelUpPanel.FindChildUI("Choice1"))
+        Choices.Add(LevelUpPanel.FindChildUI("Choice2"))
+        Choices.Add(LevelUpPanel.FindChildUI("Choice3"))
+
+        var FireballTimer = Timer()
+        var PoisonballTimer = Timer()
+        var MagicballTimer = Timer()
+        var FireFieldTimer = Timer()
+
+        forever {
+            // movement
+            var dir = GetMoveVectorWorld()
+            MoveInDirectionContinuouslyFacing(dir, 400)
+
+            // auto-attack
+            if not LevelUpPanel.IsVisible() {
+                // Fireball shoot nearest
+                if FireballTimer.IsDone() and WeaponLevel >= 1 {
+                    FireballTimer.StartCountDown(AttackCooldown)
+                    var target = NearestObjectWithTag(Tag.Monster)
+                    if target.Exists() {
+                        var b = SpawnObject(SavedObject.snowball, GetPosition())
+                        b.Target = target
+                        b.Damage = AttackDamage
+                    }
+                }
+                // Poisonball shoot faster, less damage
+                if PoisonballTimer.IsDone() and WeaponLevel >= 2 {
+                    PoisonballTimer.StartCountDown(AttackCooldown * 0.65)
+                    var target = NearestObjectWithTag(Tag.Monster)
+                    if target.Exists() {
+                        var b = SpawnObject(SavedObject.poisonball, GetPosition())
+                        b.Target = target
+                        b.Speed = 500
+                        b.Damage = (AttackDamage * 0.5).Round()
+                    }
+                }
+                // Magicball shoot multiple
+                if MagicballTimer.IsDone() and WeaponLevel >= 3 {
+                    MagicballTimer.StartCountDown(AttackCooldown * 3.0)
+
+                    var picks = GetAllObjectsWithTag(Tag.Monster).GetRandomElements(5)
+                    for t in picks {
+                        var f = SpawnObject(SavedObject.magicball, GetPosition())
+                        f.Target = t
+                        f.Speed = 300
+                        f.Damage = AttackDamage
+                    }
+                }
+                // Fire field on impact: slow cooldown, persistent area damage
+                if FireFieldTimer.IsDone() and WeaponLevel >= 4 {
+                    FireFieldTimer.StartCountDown(AttackCooldown * 5.5)
+
+                    var target = NearestObjectWithTag(Tag.Monster)
+                    if target.Exists() {
+                        var s = SpawnObject(SavedObject.fireball, GetPosition())
+                        s.Target = target
+                        s.AreaObject = SavedObject.fireField
+                    }
+                }
+            }
+
+            // level-up check
+            if not LevelUpPanel.IsVisible() and XP >= NextLevelXP {
+                XP          -= NextLevelXP
+                NextLevelXP += 5
+                LevelUpPanel.SetVisible(true)
+            }
+        }
+    }
+    // take damage
+    event WasAttacked {
+        HP -= Event.Damage
+        SetHoverHPBar(HP, MaxHP)
+        if HP <= 0 { 
+            SpawnFloatingText("YOU DIED!", Vector(1,0,0)) 
+            Destroy() 
+        } else {
+            SpawnFloatingText("-" + Event.Damage, Vector(1,0,0))
+        }
+    }
+    // handle level-up via UI buttons
+    event ClickButton {
+        var choice = Choices.IndexOf(Event.ClickedButton) // -1 when not one of ours
+        if choice == 0 {
+            AttackCooldown = AttackCooldown * 0.9
+            SpawnFloatingText("Cooldown -> " + AttackCooldown + " s", Vector(0, 1, 0))
+        } else if choice == 1 {
+            if WeaponLevel == 1 {
+                SpawnFloatingText("Unlocked: Lv 2 Poison Orb", Vector(0, 1, 0))
+            } else if WeaponLevel == 2 {
+                SpawnFloatingText("Unlocked: Lv 3 Magic Orb", Vector(0, 1, 0))
+            } else {
+                SpawnFloatingText("Unlocked: Lv 4 Fire Field", Vector(0, 1, 0))
+            }
+            WeaponLevel = WeaponLevel + 1
+        } else if choice == 2 {
+            HP = (HP + 100).Min(MaxHP)
+            SetHoverHPBar(HP, MaxHP)
+            SpawnFloatingText("Healed!  HP " + HP + "/" + MaxHP, Vector(0, 1, 0))
+        } else {
+            return
+        }
+        LevelUpPanel.SetVisible(false)
+    }
+#end
+
+
+#class FireField
+    var Radius         = 150
+    var Duration       = 5.0
+    var TickInterval   = 0.5
+    var DamagePerTick  = 18
+
+    event OnSpawned {
+        SnapToGroundWithTag(Tag.Ground)
+        SetSize(Radius, Radius, 1)
+        var LifeTimer = StartCountDownWithNewTimer(Duration)
+        var TickTimer = Timer()
+        forever {
+            if LifeTimer.IsDone() { Destroy() }
+            if TickTimer.IsDone() {
+                TickTimer.StartCountDown(TickInterval)
+                for m in GetObjectsWithinXYDistanceWithTag(Radius, Tag.Monster) {
+                    Attack(m, DamagePerTick)
+                }
+            }
+        }
+    }
+#end
+
+#class Projectile
+    var Target : Object
+    var Speed  = 800
+    var Damage = 1 // set later
+    var AreaObject: Object
+    event OnSpawned {
+        forever {
+            if not Target.Exists() { Destroy() }
+            else {
+                MoveTowardContinuousFacing(Target.GetPosition(), Speed)
+                if SurfaceGapTo(Target) < 25 {
+                    if AreaObject != None {
+                        SpawnEffectWithAutoDestroy(Ori.alias.effect.snowball_burst, GetPosition())
+                        SpawnObject(AreaObject, GetPosition())
+                    } else {
+                        Attack(Target, Damage)
+                    }
+                    Destroy()
+                }
+            }
+        }
+    }
+#end
+
+
+#class ExpGem
+    var Value        = 1
+    var MagnetRange  = 120
+    var PullSpeed    = 500 
+    var PickupRange  = 40
+    var TargetPlayer : Object
+    var Pulled       = false
+
+    event OnSpawned {
+
+        forever {
+            if not Pulled {
+                var p = NearestPlayer()
+                if p.Exists() and SurfaceGapTo(p) < MagnetRange {
+                    Pulled       = true
+                    TargetPlayer = p
+                }
+            } else {
+                if not TargetPlayer.Exists() {
+                    TargetPlayer = NearestPlayer()
+                    if not TargetPlayer.Exists() { Pulled = false; continue }
+                }
+
+                MoveTowardContinuousHorizontal(TargetPlayer.GetPosition(), PullSpeed)
+
+                if SurfaceGapTo(TargetPlayer) < PickupRange {
+                    TargetPlayer.XP += Value
+                    TargetPlayer.SpawnFloatingText("+XP", Vector(0,1,0))
+                    Destroy()
+                }
+            }
+        }
+    }
+#end
+
+
+#class HealPickup
+    var HealAmount   = 50
+    var MagnetRange  = 120
+    var PullSpeed    = 500
+    var PickupRange  = 40
+    var TargetPlayer : Object
+    var Pulled       = false
+
+    event OnSpawned {
+        forever {
+            if not Pulled {
+                var p = NearestPlayer()
+                if p.Exists() and SurfaceGapTo(p) < MagnetRange {
+                    Pulled       = true
+                    TargetPlayer = p
+                }
+            } else {
+                if not TargetPlayer.Exists() {
+                    TargetPlayer = NearestPlayer()
+                    if not TargetPlayer.Exists() { 
+                        Pulled = false
+                        continue 
+                    }
+                }
+                MoveTowardContinuousHorizontal(TargetPlayer.GetPosition(), PullSpeed)
+
+                if SurfaceGapTo(TargetPlayer) < PickupRange {
+                    TargetPlayer.HP = (TargetPlayer.HP + HealAmount).Min(TargetPlayer.MaxHP)
+                    TargetPlayer.SpawnFloatingText("+HP", Vector(0,1,0))
+                    TargetPlayer.SetHoverHPBar(TargetPlayer.HP, TargetPlayer.MaxHP)
+                    Destroy()
+                }
+            }
+        }
+    }
+#end
+
+#class MeleeEnemy
+    var HP          = 80
+    var MaxHP       = 80
+    var Damage      = 12
+    var MeleeRange  = 75
+    var Speed       = 70
+    var AttackCooldown = 1.0
+    var ExpDropCount = 1
+    var DropHealChancePercent = 0
+
+    event OnPreSpawn {
+        AddTag(Tag.Monster)
+    }
+    event OnSpawned {
+        HP = MaxHP // in case of override
+        SetHoverHPBar(HP, MaxHP)
+
+        var AttackTimer = Timer()
+        forever {
+            var p = NearestPlayer()
+            if p.Exists() {
+                MoveTowardContinuousHorizontalFacing(p.GetPosition(), Speed)
+                if AttackTimer.IsDone() and SurfaceGapTo(p) < MeleeRange {
+                    AttackTimer.StartCountDown(AttackCooldown)
+                    PlayAttackAnimation()
+                    Attack(p, Damage)
+                }
+            }
+        }
+    }
+    event WasAttacked {
+        HP -= Event.Damage
+        SpawnFloatingText("-" + Event.Damage, Vector(1,0,0))
+        SetHoverHPBar(HP, MaxHP)
+        if HP <= 0 {
+            if RandomChancePercent(DropHealChancePercent) { 
+                SpawnObject(SavedObject.healPickup, GetPosition()) 
+            }
+            for i in 0..ExpDropCount {
+                SpawnObject(SavedObject.expGem, GetPosition().ShiftX(i * 10))
+            }
+            Die()
+        }
+    }
+#end
+
+#class EnemyManager
+    var SpawnInterval    = 2 
+    var MaxAlive         = 30 
+    var DespawnDistance  = 1500
+
+    event OnSpawned {
+        var SpawnTimer = StartCountDownWithNewTimer(SpawnInterval)
+        var DespawnTmr = StartCountDownWithNewTimer(2)
+        forever {
+            // Despawn monsters too far from every player
+            if DespawnTmr.IsDone() {
+                for m in GetAllObjectsWithTag(Tag.Monster) {
+                    var nearest = 999999
+                    for p in GetAllPlayers() {
+                        nearest = nearest.Min(m.DistanceTo(p))
+                    }
+                    if nearest > DespawnDistance { m.Destroy() }
+                }
+                DespawnTmr.StartCountDown(2)
+            }
+
+            // Spawn new monsters but respect cap
+            if SpawnTimer.IsDone() {
+                var p = NearestPlayer()
+                if p.Exists() {
+                    if MaxAlive - GetAllObjectsWithTag(Tag.Monster).Count() > 0 {
+                        var pos  = p.GetPosition()
+                                        .ShiftX(RandomNumber(-600,600))
+                                        .ShiftY(RandomNumber(-600,600))
+                        var roll = RandomNumber(0,100)
+                        if roll < 30      { SpawnObject(SavedObject.goblin, pos) }
+                        else if roll < 60 { SpawnObject(SavedObject.raptor, pos) }
+                        else if roll < 90 { SpawnObject(SavedObject.fox   , pos) }
+                        else              { SpawnObject(SavedObject.dragon, pos) }
+                    }
+                }
+                SpawnTimer.StartCountDown(SpawnInterval)
+            }
+        }
+    }
+#end
+
+saved fireball {
+    effect fireball : Projectile {
+        effect = "alias.effect.fireball"
+    }
+}
+saved poisonball {
+    effect poisonball : Projectile {
+        effect = "alias.effect.poisonball"
+    }
+}
+saved magicball {
+    effect magicball : Projectile {
+        effect = "alias.effect.magicball"
+    }
+}
+saved snowball {
+    effect snowball : Projectile {
+        effect = "alias.effect.snowball"
+    }
+}
+saved fireField {
+    effect fireField : FireField {
+        effect = "alias.effect.fire_area"
+    }
+}
+saved expGem {
+    display gem : ExpGem { model="alias.model.exp_gem" size=14 color=(0,1,1) tag=Tag.ExpGem }
+}
+saved healPickup {
+    display chicken : HealPickup { model="alias.model.heal_pickup" size=12 color=(1,0.8,0.3) tag=Tag.Item }
+}
+saved goblin {
+    crowd goblin : MeleeEnemy { 
+        model = "alias.model.goblin", 
+        height = 50, 
+        override MaxHP = 80, 
+        override Damage = 12, 
+        override MeleeRange = 75, 
+        override Speed = 70, 
+        override AttackCooldown = 1.0 
+    }
+}
+saved fox {
+    crowd fox : MeleeEnemy { 
+        model = "alias.model.fox"
+        height = 60
+        override MaxHP = 150
+        override Damage = 8
+        override MeleeRange = 60
+        override Speed = 140
+        override AttackCooldown = 0.8
+        override DropHealChancePercent = 20 
+        override ExpDropCount = 2
+    }
+}
+saved raptor {
+    crowd raptor : MeleeEnemy { 
+        model = "alias.model.raptor"
+        height = 70
+        override MaxHP = 120
+        override Damage = 20
+        override MeleeRange = 80
+        override Speed = 180
+        override AttackCooldown = 0.8
+        override DropHealChancePercent = 10
+        override ExpDropCount = 2
+    }
+}
+saved dragon {
+    crowd dragon : MeleeEnemy { 
+        model = "alias.model.dragon"
+        height = 200
+        override MaxHP = 1000
+        override Damage = 80
+        override MeleeRange = 120
+        override Speed = 50
+        override AttackCooldown = 1.5
+        override DropHealChancePercent = 100
+        override ExpDropCount = 10
+    }
+}
+
+material GroundMat { base = "StylizedGrass" }
+object ground { model="cube" material="GroundMat" position=(0, 0, -100) size=(10000, 10000, 100) tag = Tag.Ground}
+display manager: EnemyManager { visible = false }
+
+screenCanvas LevelUpUI {
+    // vStack with no size hugs its children (200x260 here); children set explicit sizes. Center-anchored modal.
+    vStack LevelUpPanel {
+        anchor = (center, center)
+        padding = 10
+        gap = 10
+        color         = #1A1024F0
+        corner_radius = 14
+        border_width  = 1
+        border_color  = #6A3FB0FF
+        textLabel Title { size=(180, 30) align=(center, center) text="Leveled Up!" }
+        button Choice1 { size=(180, 60) text="-10% Cooldown" corner_radius=10 }
+        button Choice2 { size=(180, 60) text="+Elemental Orb" corner_radius=10 }
+        button Choice3 { size=(180, 60) text="Heal 100 HP" corner_radius=10 }
+    }
+}
+screenCanvas TutorialUI {
+    textLabel Text {
+        offset = (20, 80)
+        text   = "Move with WASD or mobile thumbstick"
+    }
+}
+
+</example_vampire_survivor>
+
+
 
 </world_description_examples>
 
@@ -2060,6 +4770,7 @@ Worlds may carry `#doc_version N` = the doc version they were last authored/upgr
 - Cannot do ClassName() to construct object
 - No emoticon in Text and comments
 - only use '//' for comments
+- Destroy() also ends the current function body (a value-returning func returns its type default); the caller keeps running this frame.
 - Object member calls (including Destroy()) on a None or already-despawned Object are runtime errors (a second Destroy() before the queued despawn runs is fine). Avoid spamming Exists(); prefer fail-fast. Use Exists() only when absence is expected (mouse/crosshair miss, destroyed mid-loop). Note: Object.Exists() is safe on None (returns false), so `o == None or not o.Exists()` is redundant; write `not o.Exists()`.
 - Reference a named scene object with Scene.X (e.g. Scene.Hotbar, Scene.EnemyBase.SetVisible(true)). It resolves once at world load; Exists() is false if no such object. Runtime-spawned objects are not reachable this way - keep the SpawnObject result in a var.
 - Never write saved_origin inside a saved clause (wrong: saved BrickBlock { object BrickBlock { saved_origin = "BrickBlock" } })
@@ -2077,10 +4788,10 @@ Weave2 is the only engine: a world with '#set Weave2 0' at the top refuses to lo
 - Remove the '#set Weave2 0' line, recompile, and fix diagnostics; the language is the same, typing is stricter.
 - A saved asset stored under Weave1 fails spawn with "saved clone VARS reference a retired Weave1 code chunk": open the world that owns it, fix its class diagnostics, and re-save the asset under Weave2.
 - W2C0605 unknown function, or W2C0614 whose message says the simcall is not in the allowlist: that simcall isn't ported to Weave2 (most have a ported replacement — see below). W2C0614 is also used for other type/usage errors; read the message, not just the code.
-- "retired in Weave2" errors name the replacement in the message; apply it at the call site. Common ones: HasArrivedXY -> DistanceXYTo(goal) <= radius; RotateTowardContinuous(Horizontal) -> LookAtHorizontal or MoveTowardContinuousHorizontalFacing.
+- "retired in Weave2" errors name the replacement in the message; apply it at the call site. Common ones: HasArrivedXY -> DistanceXYTo(goal) <= radius; RotateTowardContinuous(Horizontal) -> LookAtHorizontal or MoveTowardContinuousHorizontalFacing; ResetLogic/ResetAllLogic -> your own re-init func (no engine call re-runs OnSpawned).
 - Never work around a missing or retired simcall by defining a local func with its name (e.g. an empty 'func SetCastShadow(enabled: Bool) { }'): it silently disables engine behavior and breaks again when the engine call changes. Migrate the call site, or stop and report the gap.
 - Over-time controllers (MoveToOverTime etc.) and Move*Continuously directional variants are retired: drive movement from an Update loop or MoveInDirectionContinuously.
-- TeleportUp/Down/Left/Right/Forward/Backward, TeleportCenterTo, TeleportOnTopOf, TeleportGroupWithPivot are retired: use TeleportTo with a computed Position, e.g. TeleportTo(GetPosition().ShiftUp(300)) or TeleportTo(Base.GetPosition().ShiftUp(Base.GetSizeZ())).
+- TeleportUp/Down/Left/Right/Forward/Backward, TeleportCenterTo, TeleportOnTopOf, TeleportGroupWithPivot are retired: use TeleportTo with a computed Position, e.g. TeleportTo(GetPosition().ShiftUp(300)) or TeleportTo(Base.GetPosition().ShiftUp(Base.GetHeight())).
 - SetDisplayPosition/SetDisplayCenterPosition are legacy and DisplayObject-only (worldCanvas tags etc.); on any other receiver they hard-error at spawn. Prefer SetPosition/SetCenterPosition (any object); for a visual-only offset that leaves the collider in place, use SetRenderOffset.
 - Untyped 'var X: List' now infers element type; annotate 'List<T>' if inference errors (W2C0620/W2C0621). Lists can now hold Vector/Position/Timer/class types directly (un-unroll old parallel-array workarounds).
 - A migration pass must be behavior-preserving: port call sites 1:1 and verify, then do architecture cleanups (pooling, query changes, debug removal) as a separate pass.