Skip to content

Instruments

The Instruments section holds the Key Shape tools for editing the built-in key, in both editions. In Marble Studio Pro it also swaps the look of your keys and bases for models of your own (a xylophone bar, a bell, a drum). It is folded by default.

In Marble Studio Free the section is one line, "Key and base: Standard", with the Key Shape fold under it.

Parts Pro

A part is a model that can stand in for a key (a Key Part) or a base (a Base Part). The marble's path does not change: a part only changes what each key looks like.

The top of the section:

  • Key: and Base: pickers: click to choose a part. The picker shows names, a live search, and a large preview of the highlighted part ("(no thumbnail yet)" before a part has a picture; with an empty library the list holds only (leave alone) and Standard). Standard is the built-in key or base ("The built-in standard model"); (leave alone) keeps what each key has now ("Do not change this part"). Hovering a part shows its mount type, for example "Mount: Standard (in your library)".
  • Preview Key + Base (See This Key and Base Together in its tooltip): shows the chosen pair as they will sit when applied ("Shown flat; each key tilts to its own angle.").
  • Apply to Selected: puts the chosen parts on the selected course keys.
  • Apply to All: puts them on every course key.
  • The roster line: what the course wears now, for example "Bell x12 | Standard x20", or "All keys are Standard".

Grayed with "Generate a course to apply parts" until a course exists.

Recipe: bells on the high notes. Select the high-note keys, choose your bell in the Key: picker, and press Apply to Selected. The low notes keep their bars.

Authoring & Library Pro

Authoring & Library is a fold inside Instruments, closed until you open it, where you make your own parts and keep them in your library. Top to bottom:

  • A line about the active object: the part it is (for example "Bell - Key part - mount 'Standard'"), or "'Cube' is not a part yet".
  • Spawn Part to Model and Mark as Part (Mark as Part).
  • Set Part's Strike Height (Set Part's Strike Height) and Save Part (Parts library).
  • Refresh Library and Check Thumbnails (Check Thumbnails).
  • How much your library holds.
  • With a course: Parked assignments and Refresh Parts from Source (Parts library).

To delete a saved part, open the Key: or Base: picker and select it: the delete button sits under its thumbnail.

Mark as Part Pro

Open Authoring & Library to make your own parts. With your model selected, click Mark as Part. The dialog asks:

  • Role: Key Part or Base Part.
  • Name.
  • Mount Type (default "Standard"): parts only pair up when their mount types match.
  • Tilt is part of the shape: shown when the object is tilted. On keeps the tilt in the part; off uses the shape as modeled, and each key tilts to its own angle like the standard keys.
  • The objects parented to it are part of it: saves and applies the object and its children as one part.
  • Move out of Generated Course: on by default, because a re-Generate deletes everything in that collection.

Spawn Part to Model gives you an independent copy of a part to model on. Its dialog asks:

  • Kind: Key Part or Base Part.
  • Start from: which part to copy (Standard, or a part in this file or your library). The dialog notes whether Standard comes from this file's template or is the built-in shape.
  • Place it: Off to the side (a clear spot next to the course) or Fitted to the selected key (exactly where it would sit on the key you have selected; select a course key first, or it says "Select a course key to fit it to.").
  • Look at it: snap the view to the new copy.

The section names the active object, for example "Bell - Key part - mount 'Standard'", or says "'Cube' is not a part yet". The same two actions are on the object's right-click menu in the 3D Viewport: Mark as Marble Studio Part and Save Part to Library.

When the object is tilted, the Mark dialog explains the Tilt is part of the shape choice in its own words, and it shows the part's size. The report then says what it kept.

The exact words

The dialog: "This object is tilted", ""Bell" is sitting at a 12 degree tilt. Is that tilt part of the" / "instrument's shape, or just how the object happens to be" / "sitting in your scene?", then for the box (The tilt is part of the shape) "Keeps the tilt in the part, on top of each key's own angle." or a line saying the shape is used as it was made and each key tilts to its own angle, the way the standard keys do, and "If you duplicated this from a key in your course, it's just how it's sitting." For an object with children: "This part has 3 pieces:" and either "They are saved and applied as one part." or "Only 'Bell' is the part; the rest are ignored.", with one line per piece (a piece that will not be saved reads "Clapper -- ..., so it will not be saved"). The size line: "Shape: 0.4 wide, 0.08 deep, front face at 0.04".

The report after Mark as Part: "Marked 'Bell' as a Key part.", with "Moved it out of Generated Course so a re-Generate can't delete it.", "It has 2 piece(s) parented to it, saved and applied as one part.", or "The 2 object(s) parented to it are NOT part of it.", and "The 12 degree tilt is kept in the part, on top of each key's own angle." or "The 12 degree tilt was ignored; the part sits square on each key, and each key keeps its own angle."

Mark as Part and Spawn Part to Model refuse, changing nothing, when the object cannot be a part. What to do:

  • Leave Edit Mode first. Pieces can only be combined in Object Mode.
  • Un-parent what is not part of the instrument. The object has too deep or too large a family under it.
  • Fix or apply the scale. A zero scale cannot be baked.
The exact words

"Leave Edit Mode first, then try again.", "'Bell' is made of 3 pieces, and they can only be combined in Object Mode. Leave Edit Mode first, then try again.", "Could not leave Edit Mode (...). Leave it by hand, then press again.", "'Bell' is parented more than 8 levels deep. Un-parent what is not part of the instrument and try again.", "'Bell' has more than 64 objects parented under it. If your whole scene is parented to this object, un-parent what is not part of the instrument and try again.", "'Bell' has a zero scale on one axis, so it cannot be baked.", "No Standard key found to size this part against -- generate a course first.", "Can't find the Standard key model -- generate a course first.", "Can't find the Standard base model -- generate a course first.", "'Bell' is not a tagged part.", "Could not bake 'Bell' -- it produced no geometry.", and "That object has no mesh to copy." Pieces that are not meshes are skipped with their reason, for example "light objects are not part of a shape". Combining the pieces can fail with "Could not combine this part's 3 pieces (...)." or "The pieces of this part did not combine as expected (... vertices, expected ...)." (or "The pieces of this part did not combine as expected (Clapper landed somewhere else). Nothing was changed.", "The pieces of this part did not combine as expected (Clapper's faces did not line up). Nothing was changed.", "The pieces of this part did not combine as expected (Clapper's materials were remapped). Nothing was changed.", "The pieces of this part did not combine as expected (Clapper ran past the end).", or "Could not combine this part's pieces: ...").

In the Spawn dialog, each saved part reads "Model a copy of this part"; its notes can say "Made from the built-in standard shape (this file has no template).", "Made from this file's template.", "This is a new part -- saving it will not change 'Bell'.", and "It shares its material with your course -- editing that material changes them too."

Parts library Pro

  • Save Part: saves the part to your Marble Studio library with a thumbnail, so every song can use it. The dialog lets you pick a Mount Type or type a New Mount Type, and offers Overwrite the saved part with this name (when the name is taken) and Replace the part I started from (for a part you spawned from a saved one; otherwise it saves as a new part). It also lists what each piece of the part does. Names that are too long for your library folder are refused with the limit.
  • Delete: inside the Key or Base picker, choose a saved part and use the bin beneath its thumbnail. It warns "This removes the file, its thumbnail and its record. It cannot be undone." and says how many keys wear it: they keep working, because each key carries its own copy of the shape. If this file has no copy of the part, it warns that after a re-Generate those keys go back to Standard.
  • Refresh Library: re-reads the library folder.
  • A size line shows how much space your saved parts take: "Parts library: 12 parts, 4.3 MB" (Refresh adds "(cleaned up 2 leftover file(s))" when it removed stray files).

What the Save and Delete dialogs and the pickers can say:

The exact words

Save Part: "What each part of it does:" with one line per piece and "All of them take the Key Material in this build."; a name that is too long, "Too long for your library folder -- up to 60 characters fit here" (or the hint "Names here can be up to 60 characters"); a name already saved, "'Bell' already exists in your library."; a spawned copy, "This saves as a NEW part."; and when another object in the file claims the same part, "Another object in this file also claims this part." / "Saving here creates a NEW part, and any keys wearing" / "the old one will be left without it." / "Do this in a new empty file instead." After saving in that case: "Another object in this file already claimed that part, so this was saved as a new one." A renamed copy left in the file shows as "Bell (superseded)".

Delete (in the picker): "Delete "Bell" from your library?", "Mount: Standard", "in your library", and "3 key(s) are wearing it. They keep working --" / "each key carries its own baked copy of the shape.", or "3 key(s) are wearing it and this file has no" / "copy: after a re-Generate they go back to Standard.", or "No keys are wearing it." / "The copy in this file is untouched." The report repeats it: "Deleted 'Bell' from the library. 3 key(s) were wearing it; they keep working.", "Deleted 'Bell' from the library. 3 key(s) were wearing it and this file has no copy -- after a re-Generate those keys go back to Standard.", or "Deleted 'Bell' from the library. Your Key pick went back to (leave alone). Undo will not bring the file back." (each can end "Undo will not bring the file back.") It refuses with "Open a picker and choose a saved part first." or "That part is not in your library any more."

Pickers and Apply. "That part is no longer available.", "Generate a course first.", "Select some course keys first.", "Pick a key part or a base part to apply."; Preview Key + Base without both chosen: "Pick a key part and a base part first.", and if the picture fails, "(could not draw the preview)". Spawn Part to Model notes "Standard comes from this file's template." or "No template here -- Standard is the built-in shape."

What Save Part refuses, and what to do:

  • Name it, mark it, and pick a mount type. "Give the part a name.", "Mark this as a Key part or a Base part first.", "Mount type is required -- it is what lets a key and a base find each other later.", "That name is too long to save as a file (72 characters). Your library folder allows up to 60 here -- try a shorter name.", "You already have a saved part called 'Bell'. Tick 'Overwrite' to replace it, or pick another name."
  • Bring its pieces back first. "'Bell' has 3 piece(s) in your library and none of them are in this file -- it looks like it was dragged in from the Asset Browser. Saving now would replace the saved part with an incomplete one. Choose it in the picker, or apply it once, so the other pieces come back. Nothing was saved.", "2 piece(s) were confirmed for this part and 1 are here. If you removed one on purpose, Mark it again so the part knows.", "'Bell' is made of 3 pieces. Save it with the Save Part button so the pieces can be confirmed before they are written.", "This part had 3 piece(s) when the dialog opened and has 2 now (...). Nothing was saved. Check what is parented to 'Bell'.", and "This part produced no geometry, so there is nothing to save."

  • Unhook it from your scene. The part would have carried something else from your file into the library.

    The exact words

    "Saving 'Bell' would also have saved 'Camera'." followed by the reason: "The material 'Brass' uses it: node 'Image Texture', field 'Image'. Materials are saved exactly as they are -- changing that node would change how your part looks -- so point that field at nothing, or give this part a material that does not reference your scene, then save again.", "The material 'Brass' has a driver that points at 'Camera'. Remove that driver, or give this part a different material, then save again.", "It is used by Scatter.object (modifier). Clear that field on this part's own copy of the tree, or apply the modifier, then save again.", or "Something on this part still points at it; check its modifiers, its node trees and its materials. Nothing was changed -- not your scene, and not what is already in your library." Also "The saved file came out at 48.0 MB; this part's own shapes and textures account for about 2.1 MB. Something else was pulled in with it. Nothing was saved." and "Could not write the library file: ...".

On success it reports "Saved 'Bell' to the library (1.2 MB, 2 image textures)." with any notes about the part:

The exact words

"'Lamp' is parented to this part but light objects are not part of a shape, so it was not saved with it", a note when a material slot is empty (that part of the model renders in Blender's default material), "'Clapper' has no material of its own, so it took 'Brass' -- the material of the piece before it. Give it its own material if that is not what you want." (or "... so it took the first material in the part ..."), "'Clapper' is not where it is drawn (0.050 m out). It may be placed by a delta transform, an animation or a constraint -- the saved part uses its resting position -- or a modifier on it uses a fixed size", "this part looks different when it is saved (by 0.020 m). A modifier on it uses a fixed size and this object's scale is not 1 -- apply the scale (Ctrl+A -> Scale) so what you see is what you get", "'Clapper' is in this part's saved shape but is not in this file any more, so it could not be checked against what you see", "'Clapper' could not be evaluated, so it was not checked against what you see", and about its thumbnail, a note when the picture came out too dark to tell apart (with its brightness, for example 0.42 of 255): the part saved, but the picture will not tell it from a similar part (or "came out washed out (251.20 of 255) -- the whole part reads as one bright shape", "rendered nothing visible") or "could not render a thumbnail (...), so there will be no preview for 'Bell' in the Asset Browser". When the first renderer's picture was unreadable it says which it used instead: "EEVEE rendered this almost black (0.42 of 255), so its thumbnail was drawn with Cycles instead.", or, for glass (which renders near-black against a transparent background), that the thumbnail was drawn with Workbench instead, using each material's own color where that is a plain color: it shows shape and color value, not surface finish (also "EEVEE rendered nothing visible", "EEVEE rendered this washed out (251.20 of 255)", that no render was clear enough (with the closest one), "Workbench rendered it; Cycles not attempted", "no geometry to preview"). The Save dialog lists each piece, for example "Clapper (saved separately -- its own name is not kept)".

Loading a saved part reports "Loaded 'Bell' from the library." or "'Bell' only had its main piece in this file -- brought in the other 2 (Clapper, Stand).", and refuses with "That part is not in your library folder any more.", "'Bell' is no longer in your library folder.", "That library file holds no part.", "Could not load 'Bell': ...", "Could not bring in the rest of 'Bell': ...", "Load reported success but the part is missing.", or "That part is not in this file. Open the picker and choose it again." Deleting reports "Deleted 'Bell' from the library." with "The copy in this file is untouched, so any keys wearing it keep working.", or refuses with "That part is not in your library." The Base picker's last entries are "None -- this key needs no base" ("Keys wearing this part show no base, in the viewport and in renders"; its preview reads "This key needs no base.") and New mount type... ("Type a new one below"). A preview that fails says "Could not build the preview." or "Could not render the preview (...)."; a pair whose mount types differ says "These mounts do not match ('Bell' vs 'Standard'). Applying them anyway is your call." A long note under the pickers ends "... (note shortened - 3 more line(s))".

Apply reports what it did, part by part, and anything to check:

The exact words

Refusals and skips: "Part 'Bell' is missing from this file.", "'Bell' is a Base part; it can't be applied as a key.", "'Stand' is a Key part; it can't be applied as a base.", "Key.012 has no resolvable base; its base was not changed." Notes: "The loop note follows note 1, so it was not changed directly.", "You had key bases selected; the parts were applied to the keys they belong to.", "Bell: applied as 2 pieces (Bell, Clapper)", "Bell: its pieces changed since it was last applied (gone: Clapper)" (or "new: ..."), "Bell: its own materials were used (2 region(s))", "Bell: the Key Material was applied to all 2 slot(s) across 3 pieces, because none of its materials is wired to Marble Studio's color or strike", "Bell: 'Bell' has a modifier ('Array') that uses 'Empty', so its saved shape may not match what you see -- apply that modifier first" (or "... uses 'Clapper' from this same part ..."), "Bell: your library copy of this part has 3 piece(s) and only 1 are in this file -- it was probably dragged in from the Asset Browser. Choose it in the picker, or apply it once, so the rest come back", "Bell: 2 piece(s) were confirmed for this part and 1 are in this file. If you removed one on purpose, Mark it again so the part knows; if they are missing, choose it in the picker or apply it once so they come back", "Bell: 'Lamp' is parented to it but light objects are not part of a shape", "Stand: no 'Brace Distance' input, so it will not follow the wall depth", "2 key(s) have been scaled by hand (Key.004, Key.009); parts are sized against the template key.", "Part 'Bell' is missing -- 3 key(s) left Standard.", "2 parked assignment(s): the course is shorter than when they were made.", "Key.012: more than one child is tagged as a base", and "Key.012: 3 mesh children and no single one at this key's origin -- tag the base explicitly".

After a re-Generate with a changed song: "The note count changed (40 -> 42). Instrument groups are matched by note order, so check the group boundaries from note 40 on." or "The notes under your instrument groups have moved (note 17 is off by more than half a note). The song changed -- check the group boundaries."

Size and contact, prefixed "Footprint: " when the marble may touch the part: "This key part is 0.600 m wide along the face; the collision check assumes about 0.400 m. The marble can pass through the extra 0.200 m without the clip warning noticing.", "This base is 0.600 m wide along the face; the collision check assumes about 0.400 m. The marble can pass through the extra 0.200 m without the clip warning noticing.", "This base reaches 0.300 m behind the key; the collision check assumes about 0.200 m.", "This base comes 0.050 m closer to the marble than the collision check assumes.", "This part's geometry sits 0.030 m in front of the contact face, where the marble passes.", "'Clapper' sits 0.030 m in front of the contact face, where the marble passes.", and "'Clapper' reaches 0.012 m into the marble at the strike point. The collision check only knows the main shape, so the marble passes through this piece."

Under Authoring & Library, a line warns when a part shares a material with your course ("Shares 'Gold' with your course -- editing it changes them too."), and Parked assignments counts parts assigned to keys beyond the end of the current course ("Parked assignments: 2"), with an X (Clear Parked) to clear them. The roster line caps long lists: "Bell x12 | Drum x8 | Gong x3 ... and 2 more".

Other part warnings are yellow rows in Course Check, under Materials: Part claimed twice (two objects claim one part), Duplicate groups (duplicated Marble Studio node groups; Apply or Save Part repairs them) and Part too big (bigger than the collision check assumes: the marble's path is planned around the standard key's size, so a much bigger part may be touched).

  • Refresh Parts from Source: re-bakes every part in use from its source object. "Scaling a part re-bakes by itself; mesh edits need Refresh".
  • Load from Library: shown when the course uses a part this file no longer holds.

Set Part's Strike Height Pro

The marble must strike a part exactly where it would strike a standard key. Place the 3D cursor on the point of the part the marble should touch, then click Set Part's Strike Height: the part's origin moves to the cursor and up by the marble's radius.

It reports that the origin was set to the 3D cursor and raised by the marble's radius (for example 0.200 m) along the part's own Z, where the marble's center sits when it strikes. It refuses when no part is selected, and with "Leave Edit Mode first, then use this button.", "'Bell' has a zero scale on one axis; fix or apply the scale first.", or "'Bell' gets its shape from Geometry Nodes, so moving its origin would move the shape. Move the object instead, or apply the modifier, then use this button." The contact check that follows a Mark or Save says "Marble sits 0.002 m off the struck surface." or warns "This part reaches 0.010 m inside the marble at the strike point -- the marble would pass through it. Check the origin height.", and can note "the template scale is not uniform, so the marble check used its smallest axis -- it will warn early rather than late", "this part has no geometry, so the marble check could not run", "this part has 8 vertices but no faces, so the marble check could not run (and a part with no faces draws nothing)", "2 vertex coordinate(s) are not real numbers (NaN or infinite) -- the marble check and the size check cannot be trusted on this part", or "the marble check could not run on this part's geometry".

Recipe: make a bell part. Model the bell, select it, Mark as Part as a Key Part, snap the 3D cursor to the top of the bell (Shift+S > Cursor to Selected, in Edit Mode on the top vertex), press Set Part's Strike Height, then Save Part.

Check Thumbnails Pro

Check Thumbnails lists every saved part and material whose picture is out of date, and what to do about it. If some are missing or blank, Course Check shows a yellow row, Thumbnails stale; its action is the same list. Pictures made by an older version are noted as a plain fact (Old thumbnails) but are not broken.

The list says "Every saved thumbnail is up to date.", or one line per item and then "3 saved item(s) have out-of-date pictures -- see the list above." (if the material library cannot be checked: "Could not check the material library: ..."). Each line names the item and what is wrong, with what to do:

The exact words

Parts: "Part 'Bell': it has no thumbnail file. Load it into a new empty file, then press Save Part and leave the name exactly as it is.", a picture too dark to tell apart (with its brightness), measured now, with "Load it into a new empty file, then press Save Part and leave the name exactly as it is." (or, measured when it was made: "Re-saving it renders the same picture -- give its materials a Viewport Display color if you need to tell it from a similar part."), "... it was made by an older version of the thumbnail renderer. ...", "... it was saved before parts appeared in the Asset Browser, so the browser has nothing to draw for it. ...", "... its thumbnail file has changed since the record was written, so what we recorded no longer describes it.", and "... its record does not say what the thumbnail measured, so it was measured again just now."

Materials: "Key Materials 'Gold': it carries no preview at all, so the Asset Browser has nothing to draw for it. Re-save it from a file where it is loaded.", "... its preview is allocated but empty, so the Asset Browser draws nothing for it. ...", "... it shows Blender's own generic preview rather than a picture of the material. Re-save it when you happen to be in there.", with "Its name here ends in a number ('Gold.001'), so re-saving it would write a NEW library file and leave this one as it is -- rename it first." when that applies; or "... its file holds no material we could read, so nothing was changed" and "... could not be read (...); nothing was changed".

Key Shape

The Key Shape fold, inside Instruments, edits the built-in key. It is in both editions. Every key in a course (and its seam ghosts) shares one mesh, so one edit changes them all. The default key is a clean bar, 0.4 × 2 × 0.08 m.

The fold's first line says which key the course uses: "Keys: the editable key shape", or "No course yet: the next Generate uses the editable key".

  • Edit Key Shape: selects a course key and enters Edit Mode on the shared mesh (with no course key: "No course key wears the key shape."). Edit it with any Blender tool: bevel it, round it, move faces. When you leave Edit Mode every key follows.
  • Reset to Default: puts the built-in bar back on every key, after a confirmation ("Key shape reset to the default bar on 40 key(s)."). If something outside the course still uses the old shape it is kept: "The old key shape 'Key Shape' is kept: 1 other object(s) outside the course still use it (a duplicate, a spawned part or a hand-made copy)." Nothing you do to the shape can ruin the course: this is always one click away.
  • Apply Modifiers to Key Shape: a modifier (a Bevel modifier, say) only changes the one key it is on. Select that key and press this to apply the modifier to the shared shape so every key follows. Blender's own Apply would split that key off. It reports "Applied Key.012's modifiers to the key shape on 40 key(s).", or refuses with "Select a course key first." or "'Key.012' has no modifiers to apply."

The fold ends with a hint: "A modifier (e.g. Bevel) changes only its own key. Use Apply Modifiers to Key Shape so every key follows; Blender's own Apply would split that key off. After a bevel, use Shade Smooth for a clean look."

What the shape needs is reported in Course Check, under Course. The marble strikes the key as a thin rod at the strike point (the center of the key's top), so a face you pull toward the marble elsewhere is passed through rather than struck; a top surface 0.1 to 2 mm toward the marble, away from the center, is on neither row. The strike row is checked when you press Check, not live: after editing the key shape, press Check in Course Check.

  • Key top off strike (red): the top face has moved, for example "The key's top is 4.0 mm above where the marble strikes." Press Fix Contact Height, the button beside Go To on this row: it moves the shape (never a key) up or down so the marble strikes the center of its top at exactly the marble radius ("Moved the key shape 4.0 mm down so the marble strikes its top at 0.200 m. The base did not move."). When the key has no surface under the strike point, the row says so and offers no button: give the key a top over its center.
  • Key reaches out (yellow): "The key reaches 6.0 mm outside the space the marble's path is planned around: the marble may touch it." The marble's path is planned around the default key's size; a thicker, wider, or taller shape may be touched. This row stays after Fix Contact Height if the key is still bigger: it is about size, not height.
  • Keys split off (yellow): "3 key(s) don't follow the key shape: ..." (for example after Blender's own Apply). Press Go To on the row; its pages list each key.

Recipe: beveled keys. Press Edit Key Shape, select all (A), Ctrl+B, and drag a small bevel, then Tab out. Every key is beveled. Right-click a key > Shade Smooth for a clean look. (A key that carries its own modifier is shaded on its own: press Apply Modifiers to Key Shape first, so every key follows.)