Gems

from ArtisanPlugin.Scripting import GemApi as gem, GemToolsApi as gemtools, Transaction

Stones as first-class scriptable objects: create them, query them, mutate them through live handles — and group the whole script into one clean undo step. Each part has its own page.

• CreateDiscover the valid shapes and materials, then place a stone.
• QueriesFind stones by id, layer, material or selection — and collisions.
• The gem handleA live view of one gem: read it, resize it, move it.
• Gem toolsThe ribbon's gem utilities, headless.
• Toi et MoiTwo stones straddling the ring top.
• TransactionGroup every mutation into one undo step.

Facades and handles

Gems are where the API’s two shapes meet, and the distinction runs through the whole reference:

• GemApi is a facade — a static entry point that discovers valid values, queries the document and creates stones.
• IGem is a handle — a live view of one stone in the document, carrying its properties and its mutations. See The gem handle, or the full interface under Handles.

Create, Find, All and friends all hand you handles, not raw Guids.

Conventions

Millimetres and carats. Shape and material strings come from Shapes() and Materials() — call them rather than guessing; parsing is case-insensitive and tolerates dashes and spaces.

Read-only queries need nothing; every mutation belongs inside a Transaction so the whole script lands as one undo step.

Not scriptable yet

Tool	Why
Three Stones / Trilogy	The trilogy composer (three stones with their settings) is UI-only — no scripting surface yet
Trilogy bezel set	Same: panel-only for now

To build a three-stone composition from a script today, compose it yourself: create the three gems on their planes, then wrap each in its setting.