Scenario Zbrush Expert

ZBrush expert (router and agent protocol)

An agent does expert ZBrush work as a loop: deterministic palette operations, synthesized strokes and canvas renders from fixed views, gated at every stage. One long script is not the method. This skill is the protocol every ZBrush task follows, the shared toolkit in scripts/, and the map to the team skills. Target: ZBrush 2026.2.1 on macOS, driven through the project's Python bridge. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

1. Execution channel

Rules for the bridge:

• Main thread only. Every zbc call runs in main mode, which is the default of run and call. The embedded VM keeps the GIL on ZBrush's main thread, so a socket thread alone starves. The proven design is a serve loop on the main thread that calls update(redraw_ui=True) between polls (README).
• One driver. Only one agent drives ZBrush at a time. ZBrush is single-instance: start() refuses a second instance and never kills a ZBrush it did not spawn.
• Short, measured calls. Each call returns numbers (faces, volume, file bytes). Long operations such as ZRemesher, Decimation or Divide into millions get minute-scale timeouts. A timeout does not cancel queued code: it still runs when the main thread frees. Ping and read state before sending anything else.
• No blocking UI. Never call message_*, ask_* or show_note(..., 0). For visible progress use set_notebar_text(text, progress).
• One shared interpreter. ZBrush keeps one embedded Python for the whole session: what a call leaves behind stays until restart. run and call leave sys.path, sys.modules, stdout and the working directory as found and pop every toolkit module, also after an error (Maxon Style Guide; the server runs the restore hook). Never add a folder to sys.path for good, never import toolkit code outside zb_launch.run. zb_launch.hygiene() must return empty lists; purge() removes a leak.
• Long sequences. Group deterministic steps into one call: zb_ops.sequence([["divide", [2]], ["polish", [10]]]) runs them inside freeze with show_actions(0); quiet() and frozen(fn) are the parts (SDK GUI reference). Never freeze a plugin press or a canvas export; call update(redraw_ui=True) before a snapshot.
• Locked screen. Document:Export still writes the canvas PNG (v03); screencapture shows only the lock screen. At 05:30 on 2026-09-24 a launch stalled after the Home Page press, while the 05:20 launch under the same lock worked. start() detects the stall, terminates the process it spawned and reports a diagnosis (details in zb_launch.py).
• Check zbrush_info(0) = 2026.2 before trusting anything below.

2. Capability matrix (ZBrush 2026.2.1, 2026-09-24)

3. The expert loop in ZBrush

1. Brief in numbers. Purpose (film, game, print, concept), polycount per stage, print height in mm, style, references. When the brief is silent, pick the domain skill's documented default and write it down.
2. Plan big to small. Block with primitives, ZSpheres or low DynaMesh; then primary, secondary and tertiary forms. Topology, UVs and export come last (Pablo Munoz Gomez's order in Understanding ZBrush's Logic).
3. Build one stage with deterministic operations first; they are exact and cheap. Use strokes only where the form needs them. Before any stroke: Edit mode on, symmetry state chosen on purpose, brush and Draw values set and read back, view fixed with set_transform. Record the volume before and after as evidence that the stroke sculpted.
4. Gate the stage.
   • Numbers: zb_ops.stats(), plus zb_audit.audit() on an OBJ export. Every destructive wrapper (DynaMesh, ZRemesher, Divide, Decimate, Polish, Project All) returns a gate: volume ratio from get_polymesh3d_volume() and watertightness from is_polymesh3d_solid(). A collapsed or exploded remesh is a problem, a lost watertight state a warning; zb_ops.require_gate(r) raises. Bands are [added] start values.
   • Review sheet: zb_review.review(out_dir) renders front, right, back, three-quarter and top with a neutral MatCap (MatCap Gray) and tiles one labeled sheet (the triples beyond front are [verify live_03]; an upside-down or wrong-side tile is visible on the sheet). Open it with the image reader and judge it with the domain skill's critique. Experts orbit constantly; the sheet is the agent's orbit.
5. Fix before detail. A proportion error found at blockout costs one call; found after projection it costs the stage.
6. Checkpoint before anything destructive. Save a versioned ZTL before DynaMesh, ZRemesher, Project All, Booleans, merges and Decimation. There is no undo control. zb_ops.project_all(checkpoint="/abs/x.ztl") refuses to run without one, since Project All "might crash the program" (cgside). It then stores a morph target and a New Layer at the top level (FlippedNormals), sets Dist 0.1 (Drust) and flags spikes (a vertex outside the visible bbox). Repair with morph_repair(points) (Morph brush back to the stored target) or the layer, never by smoothing (FlippedNormals).
7. Deliver with evidence: the final sheet, audit numbers, file paths, and what was not verified.

Never report a model as done without having looked at a canvas render of its final state.