3D world

Build 3D levels in few calls: primitive meshes with material + collision, CSG blockouts (nested boolean trees), materials (files or on nodes), lights, WorldEnvironment/sky presets with a sun, cameras aimed at targets, model import options + instancing, GridMap painting and MeshLibrary creation, and scattering props/vegetation over terrain. Every scene change is undoable. Positions are [x, y, z] in meters (Y up; a Node3D looks down its -Z axis). Colors are hex strings like '#aa8844' or names like 'orange'. Numbers and vectors are validated: a malformed value returns an error instead of a zero/NaN result.

Actions:

• mesh: {shape: box|sphere|capsule|cylinder|cone|plane|prism|torus|quad|text (default box), parent?='.', name?, size? (box/prism [x,y,z] or one number; plane [w,d]; quad [w,h]; sphere/cylinder: diameter from size), radius?, height?, top_radius?, bottom_radius?, inner_radius?, outer_radius?, text?, font_size?, depth?, pixel_size?, font?, mesh_props?: {raw PrimitiveMesh props}, mesh?: 'res://x.tres' (a Mesh resource instead of shape), material?, position?, rotation_degrees?, scale?, look_at?: [x,y,z] | node path, cast_shadow?, props?: {raw MeshInstance3D props}, collision?: none|static|convex|trimesh} MeshInstance3D in one call. collision='static' adds StaticBody3D > CollisionShape3D with a best-fit shape (box/sphere/capsule/cylinder; plane/torus/text -> trimesh, cone/prism -> convex). Defaults: box 1m, sphere r=0.5, plane 2x2.

• csg: {type: box|sphere|cylinder|cone|torus|polygon|mesh|combiner, parent?, name?, operation?: union|intersection|subtraction, size? (box [x,y,z]; sphere/cylinder diameter), radius?, height?, inner_radius?, outer_radius?, sides?, polygon?: [[x,y],...], depth?, mode?, mesh?: {shape, size...} | 'res://x.tres', material?, use_collision? (root only), position?, rotation_degrees?, scale?, props?, children?: [same spec...]} CSG blockout. Build a whole shape in one call, e.g. {type: 'combiner', name: 'House', use_collision: true, children: [{type: 'box', name: 'Walls', size: [4,3,4]}, {type: 'box', operation: 'subtraction', size: [1,2,1], position: [0,1,2]}]}. A material on a combiner becomes its material_override. Parent can be an existing CSG node.

• material: {path: 'res://mat.tres' | node path, type?: standard|orm|shader (default: edit the existing material, else standard), props?: {albedo_color, albedo_texture, metallic, roughness, emission: '#hex', emission_energy, emission_texture, normal_texture, normal_scale, ao_texture, height_texture, unshaded, transparent, double_sided, uv_scale, triplanar, billboard, rim, clearcoat, filter: 'nearest', ...any BaseMaterial3D property; for shader: shader, params}, albedo_color?/color?/albedo_texture?/metallic?/roughness?/emission?/shader?/params? (shortcuts for props), material?: 'res://existing.tres' | '#hex' | {props} (node mode: what to assign), surface? (surface override index), save_as? (node mode: also save the material to this .tres and assign the file), assign_to? (file mode: also assign to this node), overwrite?} With a .tres path: create, or edit in place (every user of the file changes; a bad key changes nothing). With a node path: assign to material_override (meshes), material (CSG, CanvasItem, FogVolume) or a surface override; editing a node whose material is a shared file edits an embedded copy (reported in 'note').

• light: {type: directional|omni|spot (default omni), parent?, name?, color?, energy?, range? (omni/spot), angle? (spot cone degrees 0-180), attenuation?, indirect_energy?, specular?, shadows?, position?, rotation_degrees?, look_at?: [x,y,z] | node path, props?: {raw Light3D props}} add a light. Directional defaults to rotation [-50,-30,0] with shadows.

• environment: {preset?: default|sunny|night|foggy|studio|space, sky?: {type: procedural|panorama|physical|shader, top_color, horizon_color, ground_color, ground_horizon_color, energy, sun_size, panorama: 'res://sky.hdr', shader, params} | 'res://sky.hdr' | 'res://sky.gdshader' | false, ambient?: '#hex' | energy | {color, energy, source, sky_contribution}, fog?: bool | density | {density, color, height, height_density, sky_affect, ...fog_* without prefix}, volumetric_fog?, glow?: bool | intensity | {intensity, bloom, threshold, ...}, ssao?, ssil?, ssr?, sdfgi?, tonemap?: 'filmic'|'aces'|'agx'|'linear' | {mode, exposure, white}, adjustment?: {brightness, contrast, saturation}, background?: 'sky' | '#hex', props?: {raw Environment props}, sun?: bool | {color, energy, rotation_degrees, shadows, name, props}, update_sun?=true, save_path?, reset?, keep?, parent?, name?} Creates or updates the scene's single WorldEnvironment (+ Sky, + a DirectionalLight3D sun unless one exists, which is updated instead). A preset replaces the current look (keep=true layers it on top); other keys tweak the current one.

• camera: {parent?, name?='Camera3D', position?=[0,2,5], look_at?: [x,y,z] | node path, rotation_degrees?, fov? (1-179), projection?: perspective|orthographic, size? (orthographic), near?, far?, current?=true, props?} add a Camera3D aimed at a point/node; becomes the current camera (others are un-set, undoably).

• look_at: {path, target: [x,y,z] | node path, model_front?} rotate a Node3D so its -Z (or +Z with model_front=true, for imported models facing +Z) points at the target.

• import: {path: 'res://model.glb', props?: {root_type: 'StaticBody3D', root_name, root_scale, root_script, generate_collisions: true, collision_shape: trimesh|convex|decompose_convex|box|sphere|cylinder|capsule|auto, body_type: static|rigid|area, fps, import_animation, generate_lods, light_baking: disabled|static|static_lightmaps|dynamic, or raw keys like 'meshes/ensure_tangents'} (the friendly keys also work at top level)} edit the asset's .import options and reimport. Without props: lists current options. Works for any importer (textures too, with raw keys like 'compress/mode').

• instance: {model: 'res://x.glb' | 'res://x.tscn', parent?, name?, position?, positions?: [[x,y,z], ...] (several copies, max 500), rotation_degrees?, scale?, props?} instance an imported model or scene.

• gridmap: {path? (existing GridMap) | parent?+name? (new), mesh_library: 'res://tiles.tres' (required for a new map), cell_size?=[2,2,2], cells?: [{pos: [x,y,z], item: 'Floor' | id, orientation?} or [x,y,z,item,orientation?]], fill?: [{from, to, item, orientation?}] (inclusive boxes, e.g. floors), erase?: [[x,y,z], ...], clear? (wipe first), position?, props?} create or paint a GridMap (undoable). Cells are integer grid coordinates. orientation: 0/90/180/270 (Y degrees), 'x90'/'z-90'/'y180', [rx,ry,rz] multiples of 90, or a raw index 0-23. item -1 erases.

• mesh_library: {path: 'res://tiles.tres', from_scene?: 'res://tiles.tscn' (each MeshInstance3D becomes an item named after the node; StaticBody3D>CollisionShape3D children become its collision, NavigationRegion3D its navmesh; like Scene > Export As > MeshLibrary; CSG nodes are skipped), items?: [{name, shape|mesh, size?, radius?, height?, material?, collision?: true|false|convex|trimesh (default true), offset?}], replace?} create/merge a MeshLibrary for GridMap. Existing libraries are merged by item name unless replace=true; nothing changes if any item is invalid.

• scatter: {source: 'res://tree.tscn' | 'res://rock.glb' | 'res://m.tres' (Mesh) | {shape, radius?, size?, material?}, parent?, name?='Scatter', count?=50, area?: {center: [x,y,z], size: [w,d] | [w,h,d] | w, radius?}, seed?, align_to_ground? (raycast down: lands on the LOWEST collider/visible mesh under each point, so props don't stack on roofs, trees or earlier props), ground?: node path | [paths] (only land on these; implies align_to_ground), align_to_normal?, y_offset?, random_rotation_y?=true, scale_range?=[1,1], min_distance?, mode?: multimesh (default for meshes; fast, visual only) | instances (default for scenes; real nodes with collision/scripts, max 2000), material?, item_name?, cast_shadow?} scatter props/vegetation.