Skip to content

Marble Replacement Pro

the Marble Replacement section before a swap: 'Swap any ball in as the marble', the Ball field filled, Use as Marble.

Show any ball-like model as the marble: a planet, a character, a fruit. It takes over the marble's motion and spin; the original marble stays as the invisible driver underneath, so the course does not change and you can switch back any time. The Marble Replacement section is folded by default.

Use as Marble

  1. Bring your ball into the scene first (append or import it).
  2. In Ball, pick it. Only mesh objects are offered.
  3. If the ball carries things that would fight the swap, the section lists them under "Clear these first (asset untouched):". Clear them on your object, then come back.
  4. Click Use as Marble. It is grayed until there is a course and a ball is set; without a course the section says "Generate a course first" (or "Set the Marble in Setup first" when Setup shows the Marble field).

It reports "Displaying the marble as 'Planet'." It refuses, changing nothing, with "No marble yet: press Generate first." (or "No marble set (Setup > Marble)." when Setup shows the Marble field), "Pick a mesh object to use as the marble.", "That object already IS the marble.", "That object is already the active replacement.", "That object is managed by Marble Studio -- pick your own imported ball.", "'Planet' has its own animation 'Spin' -- clear these first (they would fight the marble motion). The swap will not touch your asset.", or "Could not fit 'Planet': picked object has no measurable geometry." (or "measured body radius is ~0").

The ball is fitted to the marble's size and takes over its motion and spin. The marble (and its rotation cage) are hidden. The section now reads "Displaying: Planet" (before a swap: "Displaying: the course marble", or "Displaying: the course marble (hidden)" if you hid it) and shows:

  • Scale Nudge: scales the ball up or down about the marble's center after the fit (1.0 = the fitted size).
  • Steer Geometry From Key Strikes: for balls with things sticking out (a fin, a horn, a wing). At every strike, the ball's roll is nudged by the smallest amount that lifts any rendering part parented to it clear of the key. Off by default; unticking gives back the un-nudged tumble exactly. A strike it could not clear is an yellow Fin clearance row in Course Check, one page per strike; what it did at the other strikes is listed under Course Check's Details.
  • Flip Rotation (strike N): with Steer on and a key selected, flips which way the ball turns to clear that key. Both ways use the smallest turn that clears it; this picks the other one. The button reads "- FLIPPED" when flipped. A flip that would stall the tumble is refused: "Flip refused at strike 12: it would stall the tumble. Kept the automatic direction." The button is grayed, with its reason, when there is nothing to flip: "Steer Geometry From Key Strikes is off", "this strike needs no correction", "no roll angle clears this key - the strike is skipped", or "this strike is skipped - nothing to flip".

"Rotate the ball to move a bump off the +/-Y roll axis": a bump that sits on the axis the ball rolls around barely moves; rotate your object so it is easier to see.

What the Fin clearance row and the Details list can say. Fix the first kind (they say how); the rest are notes.

The exact words

Problems (one page each on the Fin clearance row): "The marble body sits up to 3 mm INSIDE the key on 2 strike(s) (worst: strike 7) - fix the key's origin height before trusting anything above", a note that some keys' struck faces sit a little nearer or farther than the marble radius (for example 0.198/0.204 m instead of 0.200 m), measured and used as they are, "3 key(s) are narrower than the geometry reaches, so the rotation there is larger than it strictly needs to be ..." (the key is treated as one flat face, never as a solid) (the reason can also be "not flat where the geometry passes (about 4.0 deg of extra rotation)" or "a shape this feature could not profile"), "This feature and the Instruments check disagree about where the struck face of 2 key(s) is, by up to 4 mm - do not trust either number", "A track sits in the flight around strike(s) 9, 10 - the nudge adds up to 6 deg/frame across it, including the rolling section", "1 part(s) added since the swap are not protected: Horn.002", "Fin deforms (shape keys) - measured at its captured pose; it may not hold on every frame" (the reason can also be "its own animation", "a constraint (copy rotation)", "a rigid body the simulation drives", "a armature modifier that follows something that moves", "an animated parent ('Rig')", "a constrained parent ('Rig')", "a parent rigid body ('Rig')", or "a deforming parent ('Rig')"), "Strike 12 (frame 540): flip refused - it would stall the tumble; kept the automatic direction", "Strike 12 (frame 540): skipped - the tumble could not absorb it", and "Strike 12 (frame 540): skipped - this key's shape does not match what the marble is striking, so no rotation here would be trustworthy".

Notes (under Details): "Protected (2): Fin, Horn", "Ignored (1): Fin.001 - render disabled", the mesh pieces of your ball that do not render and so are not protected (the reason can also be "collection 'Props' render off", "not in the rendered scene", "excluded from view layer 'ViewLayer'", or "does not render"), "Nudged 14 of 40 strikes - largest 3.2 deg", and when it could not measure the ball "could not force render settings on 1 modifier(s) -- measured from the viewport mesh instead" or "could not measure the character (...)", for example "could not measure the character (Fin did not reach the evaluated scene)".

Recipe: a planet marble. Append a planet model, pick it in Ball and press Use as Marble. Then nudge Scale Nudge to 1.05 so its rings clear the keys. Turn on Steer Geometry From Key Strikes if the rings still touch.

Revert to Marble

Revert to Marble brings the built-in Hero Marble (and its cage) back and returns your ball to you untouched.

If you delete the replacement ball while it is in use, the section offers Restore Marble to bring the marble back, and Course Check shows a yellow row, Swap object gone: "Replacement object was deleted - Restore Marble (Marble Replacement) brings the marble back."