# Forge 3D — agent guide Forge 3D is a live 3D scene editor (phone + PC) with an agent API and Python workers (Google Colab / Kaggle) that generate game-ready GLB models. Everything an agent does shows up in open editors within ~2 seconds. Auth: every call needs the access key — `Authorization: Bearer mk_...` (or `X-Modeler-Key`, or `?key=`). ## MCP (recommended) URL: https://forge3d-xcam.onrender.com/mcp?key=mk_... (Streamable HTTP, stateless, JSON) Tools: describe_types, list_scenes, create_scene, duplicate_scene, get_scene, add_objects, update_object, delete_objects, apply_ops, build_car, make_from_words, generate_model, get_job, list_jobs, list_workers, editor_link, lookup_concept, import_blender_scene, import_unreal_level, blender_modify, run_blender_script ## Coordinates - Y is up. Ground is y = 0. Rotation is in DEGREES. Units ≈ meters. - Primitives are 1 unit before scale, centered on their position (so a 1x1x1 box resting on the ground has position y = 0.5). - `plane` and `ring` are horizontal (XZ) by default. A 20x20 ground = {type:"plane", scale:[20,1,20]}. - Generated models (type "mesh") have their origin at the bottom center, so position y = 0 sits them on the ground. ## Build anything — object types (call describe_types for every parameter, range and preset) Shapes: box sphere cylinder cone torus capsule plane ico ring pyramid ramp stairs arch tube light mesh group shape (custom: lathe / extrude / loft a 2D profile "x,y; x,y; …") · sign (3D text, neon) · prop (crate, barrel, cone, barrier, bench, lamp, …) Vehicles: vehicle (any car/truck from words — build_car) · aircraft (prop, warbird, jet, airliner, glider, helicopter) · boat Characters: character (full human: body, face, every part editable via params.edits {nose:{s:[1.3,1,1]}}) · blob (creature from melted parts) Weapons: weapon (pistol … minigun, attachments: optic, muzzle, under, mag, stock, finish) World: terrain · water (ocean/lake/river/pool/lava) · road · city · building · scatter (forests, grass, rocks) · dragstrip · track · stunt · spawn Scene settings: the object with id "__env", type "env": style (photoreal, cinematic, stylized, toon, anime, lowpoly, blocky, retro, pixel, comic, noir, neon, clay, blueprint), time 0-24, weather, clouds, fog, hdri (Poly Haven id), ground, gravity, gameMode (sandbox, race, drag, collect, survival, deathmatch), timeLimit, winScore, allowScripts. Wind (real physics, not just visuals): windSpeed m/s at 10 m (rain/storm/snow raise it), windDir (degrees the wind blows FROM, 0 = +Z), gusts 0-1, turbulence 0-1. It bends vegetation downwind, drifts clouds, slants rain/snow, carries smoke/dust/spray, raises ocean swell, pushes loose props (physics.drag multiplies an object's drag area), and changes car top speed / crosswind, plane airspeed (headwind take-offs, crabbing), helicopter drift and boat windage. Realism: wetness 0-1 (wet roads + puddles that mirror the sky, automatic in rain), puddles 0-1, snowCover 0-1 (automatic in snow), sunShafts 0-2 (god rays), aerial 0-2 (sunlit distance haze), motionBlur 0-2 (play mode). Any object can also have: params {…type params…}, physics {mode: auto|static|dynamic|none, mass, bounce, friction, drag (wind drag-area multiplier)}, behaviors [{type: spin|bob|move|collectible|trigger|checkpoint|explosive|health|enemy|spawner|pickup|script, …}], parent "" (attach: position becomes relative), repeat {count, offset:[x,y,z], rotate:[x,y,z]} (rows/arrays), material (preset name), texture (Poly Haven texture id). The editor's ▶ Play turns the scene into a game. ## Object fields id (optional), type: any of the types above, name, position [x,y,z], rotation [x,y,z] degrees, scale [x,y,z] (or a number), color "#rrggbb", metalness 0-1, roughness 0-1, opacity, emissive "#rrggbb", flatShading, wireframe, visible, light: intensity (default 8), distance (0 = infinite); mesh: url (https .glb/.obj/.stl), tint (recolor with color); tags [..], meta {..} ## REST GET /api/scenes list scenes GET /api/scenes?id=ID one scene with objects POST /api/scenes {name, id?, objects?} POST /api/scenes {duplicate: ID, name?} copy a scene (fresh id, version 1) PATCH /api/scenes?id=ID {name} DELETE /api/scenes?id=ID archive POST /api/ops {scene, ops:[...]} atomic ops: {op:"add",object} | {op:"update",id,set} | {op:"delete",id} | {op:"clear"} | {op:"replace",objects} POST /api/jobs {scene, kind, params} queue a Python worker job GET /api/jobs?id=UUID | ?scene=ID job status / list DELETE /api/jobs?id=UUID cancel GET /api/workers online workers (platform, gpu, capabilities) ## Cars — build_car (any car, nothing pre-made) Every car/truck body is generated from design numbers; there are no stored car models. build_car {scene, description?, design?, seed?, position?, rotation?, name?} description: plain English — body type, size, shape, color, engine, wheels, parts. e.g. "lifted 4x4 pickup, army green, 6 inch lift, beadlocks, light bar" "800 hp mid-engine supercar, orange, gt wing" "tiny red city car" "long low matte black fastback, twin turbo v8, 20 inch rims" design: exact numbers that override the description — length/width/height (m), wheelbase (share of length), clearance (m), hood, windshield, roofLength, rearWindow (0 upright … 1 fastback), noseHeight, cowlHeight, deckHeight, tailHeight, beltLine, tumblehome, boxy, bed, layout front|mid|rear, frame closed|rail|tube, headlights slim|round, plus paint/wheels/engine/parts keys. Same description + seed = same car. No description = a random new design. Vehicles can also be added directly: {type:"vehicle", params:{...design}}. ## Make anything from words (no worker needed) make_from_words {scene, description, seed?, position?} people, animals/monsters (blob parts), cars, planes, boats, guns — built from the words, nothing pre-made. Anything else queues a text_to_3d job. Characters/blobs keep params.describe; same words + seed = same result. ## Physics (object.physics) mode auto|static|dynamic|none · material auto|wood|metal|stone|rubber|plastic|glass|ice|cloth|foam|flesh (sets density, friction, bounce) mass (kg, 0 = from size × material) · bounce · friction · drag · joint {type: hinge|ball|fixed|rope|spring, to: object id or "" (world), pivot: center|top|bottom|left|right|front|back, axis: x|y|z, stiffness}. Dynamic models use a convex hull of the real mesh. ## Generation jobs (run on the user's Colab/Kaggle worker) procedural CPU, seconds. params: generator (rock, rocks, tree, pine, bush, mushroom, terrain, house, tower, crate, barrel, chest, fence, wall, column, crystal, sword, lamp_post), seed, size, detail 1-3, color, length (fence/wall), height (terrain) No GPU is needed for any kind — a CPU-only worker runs everything; a GPU only speeds up the optional AI engines. text_to_3d params: prompt, size, seed, max_faces, engine: "auto" (default: CPU = words → procedural asset instantly, else SDXL → TripoSR), "parts" (procedural only), "sdxl_triposr", "shap-e" image_to_3d params: image_url (https), size, engine: "auto" (CPU = "relief": cut-out + inflate with photo colours, seconds; GPU = "triposr"), "relief", "triposr" (also runs on CPU, slower), "shap-e"; quality low|medium|high, thickness render Blender Cycles path tracing, up to 7680×4320, on GPU or CPU (adaptive sampling + albedo/normal-guided denoise; CPU renders big frames at half size and upscales, time_limit default 1800 s). params: scene_url (GLB of the scene), camera {position,target,fov}, width, height, samples, sun [x,y,z], hdri (Poly Haven id), exposure, style, cpu_samples, cpu_scale, time_limit. result.image_url. Easiest from the editor: Graphics → Path-traced render. text_to_texture seamless PBR texture. params: prompt, resolution (up to 4096), seed, apply_to (object id or "__ground"), engine "auto" (CPU = procedural material synth in 1-3 s: brick, stone, cobblestone, tiles, wood, planks, bark, metal, rust, chrome, concrete, asphalt, plaster, grass, moss, dirt, mud, gravel, sand, snow, rock, marble, lava, ice, leather, fabric, scales, carbon + colour words + mossy/weathered/cracked/wet), "procedural", "sdxl". Sets object.texMaps {map, normal, rough, metal?}. The editor can also make these in the browser with no worker. terrain_erosion CPU. params: object_id (terrain), n, size, heights (base64 Int16 metres×100), iterations. Updates the terrain in place. voxelize CPU. params: url, pitch (block size m), position, name. Adds a blocky copy. optimize params: url, target_faces, object_id + replace:true to swap the model in place python params: code (must set `result` to a trimesh mesh / list / Scene), name. Only on workers with allow_python=True. blender_ops real Blender modifier stack. params: url | start, ops [...] (see blender_modify below), object_id + replace:true to swap in place, time_limit. result: url, faces, vertices, bounds, steps. blender bpy script. params: code, url?, params?. Only on workers with allow_python=True. All kinds accept params.position [x,y,z]. When done, the model is added to the scene; job.result has url, object_id, faces. Jobs wait in the queue until a worker that supports that kind is online (check list_workers). ## Coming from Blender or Unreal Engine (full guide: docs/blender-unreal.md) lookup_concept {query?, source?: blender|unreal} how any Blender / Unreal feature is done here + status: native (in the browser) | worker (real Blender on the user's cloud worker) | approx | missing. No query = full list. REST: GET /api/dcc?q=boolean&source=blender import_blender_scene {scene, objects, dry_run?} Blender conventions in: Z-up, rotation_euler RADIANS, cube size 2. object: {name, type MESH|LIGHT|EMPTY, primitive cube|uv_sphere|ico_sphere|cylinder|cone|torus|plane|grid|circle|monkey (+ size, radius, depth, major_radius, minor_radius), location, rotation_euler | rotation_degrees, scale, material {base_color [r,g,b] linear | "#hex", metallic, roughness, emission, alpha}, light {type POINT|SUN|SPOT|AREA, energy W, color, spot_size}, url (https .glb instead of primitive)} import_unreal_level {scene, actors, dry_run?} Unreal conventions in: cm, Z-up, left-handed, rotation {pitch,yaw,roll} degrees. actor: {label, class StaticMeshActor|PointLight|SpotLight|RectLight|DirectionalLight|PlayerStart|Landscape|WaterBodyOcean| WaterBodyLake|WaterBodyRiver|TriggerBox|TriggerSphere|Character|ExponentialHeightFog…, mesh "/Engine/BasicShapes/Cube" (Cube, Sphere, Cylinder, Cone, Plane; other meshes need url = https .glb exported from Unreal), location, rotation, scale, material, intensity + units, light_color, attenuation_radius, outer_cone_angle, simulate_physics, mass} REST for both: POST /api/dcc {scene, blender:[…]} or {scene, unreal:[…]}. Both return ids, skipped[] (with what to do), notes[]. blender_modify {scene, object_id | url | start, ops, replace?, name?, position?} REAL Blender modifiers on the worker, no code. object_id = a mesh in the scene (edited in place; replace:false adds a copy) · url = https .glb/.gltf/.obj/.stl/.ply/.fbx · start = {primitive cube|uv_sphere|ico_sphere|cylinder|cone|torus|plane|grid|monkey|text, size [x,y,z], text, color}. ops run in order, Forge axes (Y up, metres, degrees): subdivide {levels, simple} · bevel {width, segments, angle} · boolean {operation difference|union|intersect, with {primitive,size,position,rotation} | with_url} · decimate {ratio | target_faces | planar, angle} · remesh {voxel_size | mode blocks|smooth|sharp, octree_depth} · solidify {thickness} · mirror {axis, bisect} · array {count, offset} · displace {strength, scale, kind} · smooth {factor, iterations, laplacian} · deform {method twist|bend|taper|stretch, angle | factor, axis} · wireframe {thickness} · screw {angle, steps, axis} · cast {shape, factor} · weld {distance} · triangulate · edge_split {angle} · shade_smooth {angle} · shade_flat · uv_unwrap {method smart|cube|sphere|cylinder} · recalc_normals · fill_holes · convex_hull · limited_dissolve {angle} · material {color, metallic, roughness, emission, emission_strength, alpha, transmission} · transform {translate, rotate, scale} · origin {to bottom|center}. Max 40 ops. Job kind: blender_ops. object_id may also be a basic shape (box, sphere, cylinder, cone, plane, ico): it is rebuilt in Blender at its size and becomes a mesh. Built objects (vehicle, character, terrain…) are not mesh files: bake them in the editor first (Edit → Bake to mesh). run_blender_script {scene, code, url? | object_id?, params?, name?, position?} your bpy script in headless Blender 4.2. Globals: bpy, bmesh, math, Vector, Euler, Matrix, params, forge_to_blender. Blender is Z-up; every mesh left in the scene is exported as one GLB (Y-up) and added. Needs a worker started with allow_python=True. Job kind: blender. Not available (say so rather than promise it): Unreal itself, Nanite, Lumen, Blueprint graphs, World Partition, .blend/.uasset files, live vertex edit mode. Real-time quality = what the device's browser can draw; film quality = the Cycles render job (stills). ## Example POST /api/ops {"scene":"demo","ops":[ {"op":"add","object":{"type":"box","name":"Crate","position":[0,0.5,0],"color":"#b07a3c"}}, {"op":"add","object":{"type":"light","position":[2,3,1],"intensity":12}}]} POST /api/jobs {"scene":"demo","kind":"procedural","params":{"generator":"pine","seed":42,"size":3,"position":[4,0,-2]}}