Skip to content

Troubleshooting and known issues

The known issues in this version that you can run into, and what to do about each. For a specific row in Course Check, see Course Check and warnings.

Undo right after Generate

What happens: pressing Ctrl+Z straight after Generate Course from MIDI or Next Seed can crash Blender. Treat it as unsafe on every version.

What to do: do not press Ctrl+Z straight after Generate or Next Seed. Save before you Generate. To get back the course you had, re-open the saved file. To try another layout, use Next Seed; the "made with" line under Seed keeps the seed of the course you have, so you can type it back (minus one) into Seed and press Next Seed to return to it.

Undo after an edit

The one rule: never press Ctrl+Z right after Generate or Next Seed (above). Everything else undoes as usual, but some edits take two presses to step back: the course re-flows a moment after the edit, and that re-flow is a step of its own ("Settle after Edit"). When one press is not enough, Course Check shows a plain-fact row, Edit not settled ("This is the edit before its settle (or a save made mid-settle): Ctrl+Z again to undo it fully, or Re-solve to settle it."). Press Ctrl+Z once more, or Re-solve Course to keep the edit.

Keys only turn. Blender's move (G) and scale (S) do nothing to a course key, its base, or a ghost key: the course places every key, and only turning changes one. The exception is note 1, whose position places the whole course. This is by design, not a fault.

The fps guard

What happens: after changing Output > Frame Rate in a file that has a course, nothing re-solves and Course Check shows a Frame rate changed row: "Scene frame rate is X fps but this course was made at Y fps. Nothing was re-solved...".

Why: every strike sits on a frame of the rate the course was generated at. Re-solving at a different rate would move every strike off its note.

What to do: set the frame rate back to the course's rate. To make the song at a different rate, start a new file, choose the rate in the Generate section, and Generate again. See Frame rate.

Version limits

  • Supported versions: Blender 4.2 and newer, tested on 4.2, 4.5, and 5.2. On a Blender older than 4.2 the add-on does not turn on, and says so.
  • Files travel forward only. A song saved in 4.2 opens in 4.5 and 5.2; a song saved in 5.2 cannot be opened in 4.2. In Marble Studio Pro the same goes for materials, palettes, and parts saved to the library: in an older Blender they are listed as "saved by Blender 5.2 - open it in 5.2". If you move between versions, save library items from the oldest one.
  • Pictures can differ slightly between versions. Blender's own renderer changed between 4.2, 4.5, and 5.2. The course itself (every key, bounce, and frame) is identical on all three.
  • Blender 5.2 crash window. If Blender 5.2 crashes, it shows its own crash report window instead of closing straight away. Close it before restarting Blender.

Free and Pro files

  • A Pro song in Marble Studio Free plays and renders as saved, and Course Check shows a Made in the full edition row. Editing it in Marble Studio Free drops its Pro parts (tracks, Camera Director keys, palettes, and so on); close without saving to keep them. A Pro camera with points of interest plays at one angle in Marble Studio Free.
  • After installing Pro over Marble Studio Free, restart Blender completely before you work.

Other known issues

  • The course looks gray or dark the first time. The first time a Blender session shows the course in Material Preview or Rendered, EEVEE compiles its shaders. The status bar shows "Compiling Shaders", and Course Check shows a Shaders compiling row while it lasts. It is quicker after that.
  • Ctrl+T names a collection and refuses. In Pro, the course's collection is switched off in a way that stops Marble Studio checking the new track against the marble, either the monitor icon (Disable in Viewports) or the checkbox (Exclude from View Layer) in the Outliner. Turn it back on and press Ctrl+T again; the eye icon alone does not stop it. See When an insert is refused.

  • Generate says the built-in pieces are missing. The install is incomplete: remove the add-on and install the zip again.

    The exact words

    "The add-on's built-in course pieces could not be read. Reinstall the add-on; nothing was changed.", "The add-on's built-in course pieces (MMS_Builtins_v1.blend) are missing from this install. Reinstall the add-on; nothing was changed.", "The add-on's built-in course pieces file is damaged. Reinstall the add-on; nothing was changed.", "The add-on's built-in course pieces file lacks Hero Marble. Reinstall the add-on; nothing was changed.", "The add-on's lighting image is missing (expected one image in its hdri folder). Reinstall the add-on; nothing was changed.", "The add-on's built-in course pieces could not be loaded; nothing was changed. Reinstall the add-on.", "The add-on's built-in course pieces could not be read; nothing was changed. Reinstall the add-on.", or "The add-on's built-in course pieces are not available."

  • Wall tile size: some presses change nothing (Pro). About one press in four of the Tile size − / + buttons lands on the same seamless tiling as before. Press again.

  • The Key reaches out row stays after Fix Contact Height (the button on the Key top off strike row) when the key is bigger than the default. That is correct: Fix Contact Height fixes the height, not the size. Make the key smaller or press Reset to Default to clear it.
  • Ghost keys you delete by hand come back on the next course edit, not straight away. Toggle Seam Mirror off and on to rebuild them now.
  • Deleting a course by hand (selecting its objects and deleting them) can leave a few unused data-blocks in the file. File > Clean Up > Purge Unused Data removes them.
  • Keyframing Z Movement does nothing. The Z-Hop dials apply to the whole song; animating Z Movement over time has no effect.
  • Auto Speed replaces a hand-shaped speed curve when you reshape the track (Pro). (Re-propose Speed asks before it replaces your keys; Auto Speed does not.) Turn off Auto Speed on a track whose speed you shaped by hand.

Still stuck?

See Support. Include your Blender version, the add-on edition and version (in Preferences > Add-ons), and any red or yellow rows from Course Check (the MMS Course Check text block holds them all as text you can copy).