FAQ & Troubleshooting¶

Practical answers to the questions that come up most often. If something doesn't behave as expected, the Troubleshooting block at the bottom covers the typical causes.

How do I…?¶

…trigger destruction from my own script?¶

Hold a reference to the Breaker and call Break():

[SerializeField] private Breaker _target;

public void OnDamageReceived() => _target.Break();

That's the whole API — no init, no flag checks needed in normal use.

…play sound or particles when something breaks?¶

Expand Events on the Breaker. Wire your handlers onto: - Break Started — fires immediately when Break() succeeds. Default choice for sound, particles, screen shake, loot spawn, score, cleanup. - Shard Lifetime Ended — fires after the Shard Lifetime feature finishes (all shards have lived out their lifetime). Does not fire when Shard Lifetime is disabled. Use only for things that must wait for the visual destruction to conclude — respawning the source object, opening gates, cinematic sequencing.

Both are standard UnityEvents and can be wired entirely in the inspector — no code needed.

…control how many shards I get?¶

The iterations value in the bake dialog is the main control — it's the number of slice planes, so roughly N iterations → about N + 1 shards. Raise it for fine debris, lower it for chunky pieces. Every extra cut also means more physics at runtime, so keep it as low as the look allows.

…control how long shards stay before disappearing?¶

Open the Shard Lifetime feature. Each shard lives for a random time between Shards Lifetime Min and Shards Lifetime Max (seconds), then is removed. The Original Object option decides what happens to the source object on break — Destroy it or just Disable it. Disabling the feature stops shards from being cleaned up on a timer.

…get more variety in the shards?¶

Two complementary knobs: - Enable Chaotic Slicing in Advanced. Shard sizes and slice offsets become uneven — closer to natural breakage of wood or stone. - Bake several variations into a Collection so each Break() picks a different layout.

You can combine both for maximum variety.

…tweak a shard after baking?¶

The baked result is editable like any other Unity prefab — open it from the Project window (or, for To game object, expand the hidden child under the Breaker in the hierarchy) and move shards, delete the ones you don't like, swap their meshes or materials, drop in extra components. The next Break() picks up the changes automatically; the parts list rebuilds on activation. For a BrokenSourceCollection, each variation is a nested prefab inside the collection asset — edit them the same way.

…make destruction deterministic (same shards every time)?¶

For baked modes: pick a specific id in the bake dialog and stay on it. Same id + same iterations → identical shards.

For Runtime (beta) mode: disable Randomize and set Variation Id to a fixed value. The same value reproduces the same fracture exactly — useful for replays, tests, and cinematic moments.

…reuse the same destruction across many identical objects?¶

Bake once to To prefab or To collection. Then either turn the prototype into a Unity Prefab (instances inherit the Broken Source field), or manually drag the produced BrokenSource* asset into each Breaker's Broken Source field. No need to re-bake. See the "Reuse the same destruction across many identical objects" section of the Scenarios guide.

…optimise destruction for mobile / VR?¶

Break only low-poly objects — slicing cost scales with the source mesh's triangle count.
Use a baked mode (Prefab or Collection), never Runtime (beta).
Enable Use pools on the BrokenSourceCollection component, and prewarm pools from code at scene load (BrokenObjectPools.EnsureInstance().PrewarmForCollection(collection, count)). count is the number of pre-built instances per prefab in the collection.
Keep iterations modest — the right number also depends on the mesh's poly count, so a denser object needs fewer.
Switch Shard Collider → Collider Type to Box or Sphere (cheaper than Mesh).
Shorten Shard Lifetime so shards free up faster.

…make shards pass through floors and other geometry?¶

Disable the Shard Collider feature (Enabled = false). Shards keep their visuals and rigidbodies, but no colliders are added — they fall through everything. Useful for cosmetic-only shatter effects where the shards should not interact with the world.

…break objects whose walls have zero thickness (single-plane shells like pottery or eggshells)?¶

In the Bake dialog, open Settings → Inner Surface, enable it and set Scale = 1, then disable Slice Surface. The shards get an inner skin instead of a solid cut, turning the zero-thickness shell into thin-walled pieces.

Troubleshooting¶

Bake button is disabled or shows a red error¶

The Breaker has nothing to bake. Either: - The GameObject (and its non-Breaker children) has no MeshFilter, or - All meshes underneath belong to nested Breakers, so the current Breaker owns no geometry.

Add a MeshFilter + MeshRenderer, or rearrange the hierarchy so this Breaker owns at least one mesh.

The object disappears instead of breaking¶

The Breaker is misconfigured: Broken Source is empty and Mode is not Runtime. Bake the destruction or pick Runtime (beta) in the bake dialog. Check the console for a BreakNotPrepared log.

`BreakByCollision` doesn't react to bullets¶

Check, in order: - The bullet has the tag that you listed in Tags (or Tags is empty to match anything). - Both objects have a Collider. The bullet additionally has a Rigidbody. - The Breaker is assigned to the Breakers array on the BreakByCollision component. - Neither side is IsTrigger (collision uses OnCollisionEnter, not OnTriggerEnter).

`BreakByCollision` reacts to everything — I want only certain objects to break it¶

Tag the objects that should break it (e.g. Bullet), then list that tag in the Tags field of BreakByCollision. An empty Tags list matches anything.

Shards spawn but don't move¶

The Explosion feature is disabled, or the force is too small for the mesh's scale. Re-enable Explosion, raise Min/Max Force proportionally to the object size, and increase Explosion Radius so outer shards still receive the impulse.

Shards fall through the floor when you didn't expect it¶

Check the Shard Collider feature first — if Enabled is off, no colliders are added at all. If it's on, the typical cause is fast-moving shards tunneling through thin geometry: set the floor's collider to Continuous collision detection, or thicken the floor so shards can't pass it in a single physics step.

Shards collide with the player or with each other¶

In Advanced → Tags and Layers set Layer Mode to Custom and pick a dedicated layer for the shards, then untick that layer against itself — and against the player's layer — in the Physics collision matrix (Project Settings → Physics).

Shards have visible gaps, missing pieces, or weird geometry¶

Slicing quality follows the source mesh: clean, well-formed meshes shatter cleanly on the defaults. On heavier or messier geometry you may need to nudge a couple of Advanced knobs to taste — slicing is partly stochastic, so a little trial-and-error here is normal rather than a sign something is broken. Turn Preview on to see each change instantly:

Precision Digits — try raising it, then try lowering it. Either direction can help depending on the mesh's scale and topology.
Use Custom Clusterization Epsilon + Custom Clusterization Epsilon — same idea. Smaller values tighten clustering, larger values loosen it; both can resolve or introduce artefacts depending on the geometry.
Merge Meshes Before Slicing — for composite objects (several child meshes meant to behave as one).
Split Islands Before Slicing — toggle if the source mesh has disconnected pieces.

Usually one knob — or a small combination — does it; which one depends on the specific mesh.

The editor stutters or freezes while previewing¶

Preview slices the mesh in real time, so high iterations are expensive. Turn Preview off while you adjust parameters, then turn it back on to see the result with the new settings. Lowering iterations during preview also helps.