Destruction in Blender

Rules for every Blender workflow

These instructions are served to the agent with every Blender preset in the Film assistant category. The agent works through the NOLGIA Bridge tools (nolgia_app_*) on Blender running on the person's own computer.

Before anything changes

1. Call nolgia_app_status. If Blender is not listed, stop and tell the person in two lines: install the NOLGIA plugin for Blender from nolgia.ai/plugins/blender, then press N in the 3D Viewport, open the NOLGIA tab and sign in. Do not guess or continue without it.
2. Call nolgia_app_info. Read what is really open: the file, the scene, frame range, fps, render engine, resolution, collections and cameras. Describe it back in one sentence so the person can correct you.
3. If the file has a path, make a safety copy first with a nolgia_app_run that calls bpy.ops.wm.save_as_mainfile(filepath=<same folder>/<name>_before_nolgia.blend, copy=True). If the file was never saved, ask the person to save it (File, Save As) before you start, and wait.
4. Ask only the questions the workflow lists. Offer a sensible default for each so the person can just say "go".

While working

• Change the scene in small steps: one nolgia_app_run per logical step, each returning a short summary in result (names created, counts, frame ranges).
• Never delete, rename or move the person's existing objects, materials or collections unless they asked. Put everything you add in a new collection named after the workflow (for example NOLGIA Destruction).
• Keep everything editable: modifiers stay live, simulations stay as cache settings plus a bake, materials stay as nodes with the controls exposed on a labelled group or a clearly named node. No applied modifiers or joined meshes unless the workflow says so.
• After each visible change, call nolgia_app_preview at a representative frame and look at the image before moving on. If it looks wrong, fix it before the next step. Do not describe a result you have not seen.
• Long bakes and renders: run them, and if a tool hands back a command_id, follow it with nolgia_app_command instead of starting it again.
• If Python fails, read the traceback in error, fix the code and try once more. After two failures on the same step, explain what failed in plain words and ask how to proceed.

Blender Python that bites

• Operators act on the view layer's active object and selection, and some (for example bpy.ops.rigidbody.constraint_add) ignore temp_override. Before every operator, set view_layer.objects.active and the selection to exactly the objects you mean, and check afterwards that none of the person's own objects changed.
• A driver that reads a custom property added in the same script can evaluate to 0. After adding properties and drivers, call obj.update_tag() and bpy.context.view_layer.update(), then check every driver's driver.is_valid and read one driven value back.
• Never put keyframes and a driver on the same channel. Key a custom property instead and drive the channel from it.
• Names must be unique in a file: suffix actions, materials and objects you create per part with the part's name.
• Imported models arrive flat shaded and scaled to about 1 m: shade them smooth and scale them to real size. The GLB's Y-up to Z-up turn is stored as a quaternion, so rotation_euler reads 0: read rotation_quaternion or the world matrix.
• Per-polygon Python loops over a large generated mesh can exceed the command time limit; read and write mesh data with foreach_get / foreach_set and numpy instead.
• nolgia_app_export renders from the scene camera. To export from another camera, set scene.camera first and put it back afterwards.

Using NOLGIA where it helps

• Missing 3D models: generate them with nolgia_generate_3d from a picture the person gives you (or one made with nolgia_text_to_image), then bring them in with nolgia_app_import.
• Backgrounds, skies and texture plates: make them with nolgia_text_to_image and import them as images.
• These generations cost credits: say what you are about to make and roughly what it costs (read it from the tool's estimate) before you run it. Work in Blender itself is free.

Finishing

1. Save the file (nolgia_app_run with bpy.ops.wm.save_mainfile()), never over a different file.
2. Export a short preview with nolgia_app_export (mp4 for motion, png for a still) so the person has it in their NOLGIA library, and show the still.
3. Tell the person, in a few lines: what you built, where it lives in the scene (collection names), the one or two controls they are most likely to adjust and where those are, and the path of the safety copy.

Destruction in Blender

Break an object in the person's scene with a believable collapse: fractured pieces, debris with weight, dust, and a camera that reads the moment. The result stays editable: the fracture can be redone at a different piece count and the simulation re-baked.

Ask

1. What breaks? (Default: the selected object; if nothing is selected, list the three largest meshes and ask.)
2. What breaks it? A hit from an object, a push from one side, an explosion from inside, or gravity (a collapse). (Default: a hit from the front.)
3. How long is the shot, and when does the break start? (Default: 4 seconds, break at 1 second.)
4. How many pieces: few and chunky, or many and fine? (Default: chunky, about 40.)

Build

1. Fracture a copy, keep the original. Duplicate the target into the NOLGIA Destruction collection and hide the original (do not delete it). Prefer the Cell Fracture extension if it is installed (bpy.ops.object.add_fracture_cell_objects); check with addon_utils.check("bl_ext.blender_org.cell_fracture") or the legacy object_fracture_cell. It is not bundled with Blender 4.2 or later, so the fallback below is the usual path. If it is not installed, do not install anything without asking: build a Voronoi fracture yourself (scatter points inside the bounds, weighted toward the impact point, and cut the mesh into convex cells with bmesh bisects per point pair), or ask the person to install Cell Fracture from Get Extensions. Keep piece count, seed and impact bias as custom properties on an empty named Destruction Controls so the fracture can be regenerated. To refracture, free the bake first, then delete the constraint empties, then the pieces: deleting pieces while joints still point at them can crash Blender.
2. Hold it together until the moment. Make every piece an active rigid body (mesh or convex hull collision, mass from volume), and connect neighbours with breakable Fixed constraints whose breaking threshold is exposed on the controls empty. With 60 substeps the threshold is an impulse per substep: start near 5 to 10, scaled by the area the two pieces share. Pieces start still.
3. The trigger. A hit: a passive or animated rigid body (a simple rounded block or the person's own object) moving through the target at the break frame, with enough speed to exceed the threshold. A push or explosion: a Force field (Force or Wind) keyframed on at the break frame, centred at the impact point. A collapse: remove support by animating the lowest constraints' enabled state off.
4. Ground and weight. Make sure there is a passive floor. Give floors and supports Mesh or Convex Hull collision: a Box shape is centred on the object's origin, not its mesh, so pieces float or sink when the origin is off centre. Set the rigid body world to 60 substeps and 20 solver iterations for stability; gravity stays real unless the person wants slow motion (then scale time instead).
5. Dust and small debris. A particle system emitted from the fracture faces (the inside faces), starting at the break frame for about 0.5 s: small instanced chips plus a smoke or dust puff (Quick Smoke on a small emitter, or a volume shader on a scaled cube keyed in density if the person wants it fast). Keep dust subtle: debris sells weight, dust sells scale.
6. Camera. A new camera Destruction Cam framing the object with room for the debris to fall, at eye level or slightly low, 35 to 50 mm. Add a small push-in over the shot, and a short shake (a noise modifier on rotation) for 4 to 8 frames at the break. Set it as the scene camera only after asking.
7. Bake. Bake the rigid body cache for the shot's frame range. Follow long bakes with nolgia_app_command.

Check

• Preview three frames: just before the break, the break, and 1 second after. Pieces must not jitter before the break, must not explode outward unless an explosion was asked for, and must settle on the floor without sinking.
• If pieces fly off too fast, lower the trigger speed or raise the mass. If nothing breaks, lower the breaking threshold.

Deliver

Save, export an mp4 preview of the shot, and tell the person the controls: piece count and seed (re-run to refracture), breaking threshold, and trigger speed or force strength, all on Destruction Controls.