7.4 KiB
Blender → Forma
Forma accepts GLB, glTF with companion files, and ZIP containing one GLB/glTF scene and its resources. Native .blend files are converted locally by Blender; the browser does not execute Blender or its node graphs.
Use Импорт модели to add an asset to the current scene. Select a glTF and its adjacent .bin/images together, or use ZIP to preserve subdirectories. Открыть сцену Blender opens a model as a new project, selects the converter's active camera (or the first imported camera) and autoplays its first timeline on Play. If lights are present, Forma's default sun and ambient light are disabled. Undo restores the preceding project. Cameras can be selected in the model entity's Camera component. Internal glTF nodes remain inside the model entity rather than becoming individually editable Forma entities.
Direct export
Requires a Blender glTF exporter with Animation Pointer and Scene animation support. The integration test was run with Blender 5.2.1 LTS. Older versions without those options fail with a diagnostic.
npm run blender:export -- /path/to/Scene.blend --output ./work/Scene.glb
Set FORMA_BLENDER or pass --blender /path/to/blender if Blender is not on PATH. The command launches a separate background process, disables automatic Python execution and never saves the source .blend or touches the open Blender session.
The converter exports the selected Blender scene and its frame range, converts curves/text/surfaces into meshes, applies render-enabled mesh modifiers when there are no shape keys, retains armatures and shape keys, embeds textures, and exports cameras, punctual lights, extras and supported property animation. --scene NAME chooses a scene; repeated --objects 'Name*' options restrict the objects. Include the rig and other dependencies when exporting a subset.
The converter defaults to Blender's Unitless lighting mode (--lighting compat), matching Forma's ordinary exposure and avoiding overexposed physical lamps. --lighting spec preserves physical glTF light units and requires suitable runtime exposure. When using Blender's own exporter, choose Unitless lighting for the same result.
The exporter emits one sampled scene timeline. It is not an Action/NLA clip library exporter. Alternatively, use Blender's own GLB export to retain separately named Actions, enable Animation Pointer for supported material properties, then select the desired autoplay clip in Forma's Animator component.
Animated procedural materials
npm run blender:export -- /path/to/Scene.blend \
--output ./work/Scene.glb --bake-materials \
--resolution 128 --samples 8 \
--start-frame 1 --end-frame 240 --frame-step 4
The baker evaluates the material in Cycles at each sampled frame, including supported drivers, image sequences/movie frames and procedural inputs such as Noise, Voronoi, ColorRamp and Bump. It creates per-object UV atlases for base color/alpha, metallic/roughness, tangent-space normals and emission. It adds STEP animation of KHR_texture_transform offsets through KHR_animation_pointer. Forma plays these animations with the model timeline; pause also pauses materials.
Supported bake surfaces are Principled BSDF and Emission, optionally mixed with one Transparent shader. Existing UVs are used; meshes without UVs get a smart unwrap. Existing overlapping UV islands may produce artifacts and should be unwrapped before baking. Node groups feeding these inputs work through Cycles; arbitrary groups/mixes that produce a surface closure need conversion to a supported surface first. Unsupported closures fail explicitly.
--resolution is 16–1024 pixels per frame; --samples is 1–256; at most 256 sampled frames and an 8192px atlas edge are allowed. Two-pixel borders and linear filtering without mipmaps prevent adjacent frame bleeding. Smaller frame steps produce smoother animation and larger files. Static procedural materials use one atlas cell. Animated geometry can change a procedural material's appearance even without material drivers; add material animation or bake it explicitly as an animated source before relying on that case.
Compatibility and limits
| Blender feature | Transfer |
|---|---|
| Mesh hierarchy, UVs, textures, transforms, extras | glTF model hierarchy; extras retained |
| Armature, skinning, shape keys | Native glTF, including animation; no retargeting |
| Curves, text, surfaces | Converted to mesh at export |
| Compatible PBR, transparency, normal/emission textures | Native glTF materials |
| Supported material, UV, camera and light keyframes | KHR_animation_pointer; independent targets per model instance |
| Noise/Voronoi/ColorRamp/Bump and driver-driven surface inputs | Sampled texture baking for supported surface closures |
| Movie/image sequence inputs | Sampled into atlases; no audio or live video playback |
| Point, spot, sun lights; perspective/orthographic cameras | Native glTF; rendering differs from Cycles/EEVEE |
| Area lights | Optional point-light approximation, listed in report |
| Geometry Nodes and physics simulations | Evaluated start-frame geometry; no live simulation/cache playback |
| Modifiers on meshes with shape keys | Preserved shape keys; unsupported modifier application is reported |
| Volume shaders, World node graphs, compositor, render effects | No equivalent full transfer; use Forma fog/lighting or render baking |
| View-dependent shading, true displacement, baked coat/transmission/thin-film etc. | Reported limitations; base PBR baking cannot reproduce them exactly |
| Arbitrary OSL/Python nodes, custom Python drivers, Blender scripts | No runtime execution in Forma; complex disabled drivers need authoring-side preparation |
The converter writes Scene.report.json and embeds warnings in the GLB. Recognized unsupported features stop export by default. Inspect the report and use --allow-lossy to accept its listed approximations. This flag does not turn unsupported features into equivalents, and unsupported shader closures can still fail. Always inspect Blender's own exporter log too. A successful export is not a guarantee of pixel-identical Cycles/EEVEE rendering.
Current portable model limit: 25 MiB, ZIP expansion budget: 80 MiB. Split large scenes or reduce texture/frame resolution. External resources must be supplied locally inside the import bundle/project directory; network URLs and escaping paths are rejected. Draco, Meshopt and KTX2 are rejected because offline decoders are not bundled.
MCP
asset_import_glb keeps its name for compatibility and accepts .glb, .gltf, or .zip. Supply base64 or a path inside the Forma project directory. instantiate: true adds a model and Animator; asScene: true performs an undoable project replacement using imported cameras/lights. The browser editor has the same import pipeline.
Verification
npm run build
npm run typecheck
npm test
FORMA_BLENDER=/path/to/blender node --import tsx --test tests/blender.test.ts
The optional Blender integration test generates its own scene, exports driver-baked textures, a curve, shape keys, a camera and a light, and verifies that the source file is unchanged. Runtime tests exercise actual material/camera/light/morph animation and instance isolation. The shipped repository contains no personal Blender projects or baked game assets.
Reference: Blender glTF exporter manual.