MANUAL 01

Make a molecular film

Molstudio is a molecular director: assemble a cast, describe or draw what each part does, sculpt missing illustrative assets, add sound, then render on your device. Your Molstudio account is the identity layer across Studio, Lab and future community features; Studio adds private cloud projects and explicit share links. AI Director is a separate reviewed connection that always begins with a visible context preview.

01 · Your first film

Hosted

Open the studio and press Director in the top bar. The lightweight launch project is a finished, editable four-addition PrimPol primer extension, so it starts comfortably on modest hardware. Open the larger T7 replication fork from Examples whenever you need the full replisome.

Launch the studio

On your machine

Everything runs in the tab. Structures, saved projects and imported audio stay on your device. The only exception is an explicit AI Director connection: it sends the sanitized context shown in its preview directly from this browser to the external model endpoint you choose.

How rendering works

Open Director. The same live viewport and timeline move into a full-screen filmmaking workspace; closing Director returns them to the normal studio unchanged.
Create the cast. In Create, use + Molecule, drop a local PDB/mmCIF into the studio, or start with an existing scene. Every molecule, independent rig, generated unit and Shape Lab object can be directed separately.
Select the mover. Click or tap it in the viewport. Open Animate; the Guided animation asks six plain-language questions, beginning with What should move?
Describe one action. Pick Move somewhere, Approach / meet, Bind / follow, Rotate / flex, Grow / assemble or Custom behaviour. Draw a path in the viewport or choose a target, timing and what should happen afterward.
Create and check it. At Review, choose Create + play. The guide compiles the answer into unrestricted ordinary pose keys, clips, contacts, constraints, relationships or generator records. Nothing is locked inside a preset.
Make contact. Use Connect for an Approach, Dock, Bind & follow or Follow relationship. Start with the restrained physical ripple or turn it off; both timing and amplitude remain editable.
Cut the story. In Shots, add a shot, key the camera, track a selected component and add optional captions or callouts.
Finish safely. In Finish, press Save now, then Export project before moving devices. Add audio if needed, render a still or animation, and decide independently whether annotations appear in the output. Every exported image and video carries a small Molstudio mark in the lower-right corner, plus an invisible provenance signature in the pixels; anyone can check a file at molstudio.app/verify.

Try the worked scene. The cartoon-led T7 film and molecular-surface version use deposited 6N9V/6N7W coordinates inside an explicitly authored mechanistic composite. Open one, select a cast member and inspect its ordinary records.

02 · The Molecular Director

Director puts the work in seven task-oriented modes while retaining the production viewport, timeline, undo history, selection and render state.

CreateBuild the molecular cast. Import experimental structures, begin blank, add annotations or open Shape Lab.
AnimateDirect what changes. Use Guided animation first; open More control for direct tools, every operator, Process composer and exact records.
ConnectMake components interact. Author point-to-point approach, docking, constraints, dwell, release and physical response.
BuildGrow and repeat matter. Create retained chains, curves, helices, rings, sheets, lattices, shells, filled volumes and radial arrangements.
SculptCreate what is not deposited. Model an explicitly illustrative Å-scale asset and reusable binding ports in Shape Lab.
ShotsTell the story in shots. Add camera keys, tracking, focus, captions and callouts.
FinishSave, revise and render. Manage local recovery, sound, captions and production output.

Focus viewport

Press Focus viewport in Animate to give the live frame maximum room while keeping its tool strip. Press Restore workspace or Esc to bring back the cast, task panel and timeline. This layout control is separate from a camera’s Focus only depth-of-field rig.

Orbit or Free camera

Orbit turns and pans around the current view target. Choose Free camera to travel independently of any target: drag empty viewport space to look, use W/A/S/D to translate, Q/E to move down/up, and the wheel to dolly. With the viewport focused, arrows look around and Page Up/Page Down or +/− dolly; Shift makes a finer step. The on-screen touch pad mirrors movement. Press K to key the current view, then choose Orbit to return to target-based orbit and pan.

Find any command

Press ⌘ K on macOS or Ctrl K elsewhere for Search commands. Type a mode or action, use ↑/↓, then Enter. Esc closes the palette before it closes Director.

The Director toolbar contains Navigate, Pick, Move, Path, Rotate, Depth, Scale, Auto-key, Focus viewport, Cast and Timeline. On a narrow screen, Cast and Timeline open as drawers over the viewport. The timeline bar supplies Play, Start, Fit, −, +, All cast, Key camera, + Shot, Both, Shots and Tracks.

03 · AI Director, with the author still in control

AI Director gives a language model a small, self-describing view of the scene and asks it for typed Molstudio actions. It does not hand the model the application, execute prose or hide an edit behind a chat response. The author sees the exact context, the proposed steps and the resulting records before choosing whether to Apply.

01 · ScopePreview context

Project, selection or current shot.

02 · ProposeReceive a plan

Only molstudio.llm-plan/1 tools.

03 · CheckValidate + preview

Readable steps, warnings and handoffs.

04 · DecideExplicit Apply

Approve each visible stage; Undo stays separate.

Choose how the plan reaches Molstudio

Direct browser endpoint

Choose OpenAI-compatible, Anthropic-compatible, Ollama or generic JSON; enter an HTTPS endpoint, model and optional browser-scoped token; then ask for the scene you want. The request goes directly from this tab to that endpoint. Its server must permit the browser’s CORS request; providers that block direct browser calls require Copy / paste, a local model or a browser-safe relay. Only explicit localhost development may use HTTP.

Copy / paste

Copy the same sanitized scene brief into any model, then paste its returned molstudio.llm-plan/1 JSON into AI Director. Use this when the provider blocks browser CORS, when a chat product has no endpoint, or when you prefer not to type a key into Molstudio.

Origin-scoped window bridge

Enable a live link for one exact companion-page origin. The bridge uses an ephemeral tab token and can provide sanitized context or stage a proposed plan through postMessage. It cannot press Apply, access the raw creator bridge or silently mutate the project.

No connection is permanent

Close the panel or disable the window bridge to end that handoff. Endpoint and model preferences can remain local convenience settings. A direct-mode key stays in memory by default; the optional session setting lasts only for this browser session and is never written into a project.

Review or autonomous. The four-step flow above is review mode, the default: every mutating plan waits for an explicit Apply. The Autonomous checkbox beside the prompt opts into a run loop instead: each plan executes as it arrives, and after every pass the model receives a molstudio.llm-result/1 payload naming each step that executed, each step that was skipped and why, any error with its exact path, and the refreshed environment — so it corrects its own next pass. A run ends when a pass changes nothing, when the same failing plan repeats, or at the visible Stop; the finished run offers one Undo covering everything it changed. Steps that need a person — the guided viewport pickers and the local file chooser — are skipped and reported rather than hanging the run, and destructive confirmations are taken as given, which is exactly why autonomy is opt-in. In review mode a failed Apply is not a dead end either: the failure and the refreshed context go back to the model once, and its corrected plan stages for the usual Apply.

The director can see. After every applied plan Molstudio captures one downscaled viewport frame per shot. A connected vision-capable model receives those frames with its next request — as native image input on Ollama, Anthropic and OpenAI-compatible endpoints — and is asked to judge them like a director: subject filling the frame, site visible at this zoom, motion reading, captions legible. A text-only model refuses images once, gets a notice, and the session continues without them. In Copy/paste mode the clipboard cannot carry pictures, so Save film frames downloads the same frames as one labelled contact sheet to attach in the chat beside the pasted request.

Multi-state films. Separate depositions of one molecule sit in different crystal frames and jump on screen when a film cuts between them. structure.align superposes one imported actor onto another with a sequence-guided rigid fit — only the moving actor’s transform changes, never deposited coordinates. Imports accept assemblyId (“1” is the authors’ recommended biological assembly, “asu” the asymmetric unit); leaving it out opens the visible chooser, and an autonomous run defaults to “1” rather than waiting on a dialog. The selection resolvers persist a named selection and publish its selectionId, which later steps consume through the ordinary $result grammar — so a plan can resolve a ligand or catalytic site and stage the camera on it with camera.frame. To keep those queries honest, each imported component lists its displayed non-polymer chemistry — exact comp codes with names — in the environment, and a failed resolve names the candidates it could have matched.

Local Ollama setup. Choose Use local Ollama, then Test + find models. Molstudio normalizes the native request endpoint to http://127.0.0.1:11434/api/chat, checks Ollama’s /api/tags endpoint and selects an installed model; a local Ollama connection does not need a token. A Studio page served from localhost is permitted by Ollama by default. A hosted page such as https://molstudio.app is a different browser origin, and it needs two separate permissions that are granted in different places. Both must be in place before Test + find models succeeds, and each fails with its own distinct symptom.

1. The browser. Whether a hosted page may reach loopback at all is decided by the browser before Ollama ever sees the request, and each engine decides it differently. Molstudio detects the browser and prints the matching instruction in the connection panel.

Chrome, Edge, Brave, Arc, Opera. Chromium blocks a hosted page from reaching loopback until the site holds Local network access, so the request never arrives and no amount of Ollama configuration changes it. The symptom is distinctive: while the permission is ungranted the request stalls and then times out rather than failing immediately with a CORS error. To grant it, open the site controls at the left of the address bar, choose Site settings, set Local network access to Allow, then reload. Dismissing the prompt is not the same as denying it; either way requests keep stalling until it is allowed explicitly.

Firefox. Firefox has no local-network permission, so there is nothing to grant and nothing to click. A hosted page reaches loopback as soon as Ollama allows the origin. Measured on Firefox 150: the request returns in about four milliseconds. If a test fails in Firefox, the cause is step 2 below, not the browser.

Safari — use Copy/paste mode, or another browser. Safari refuses to load anything over plain HTTP from a secure page and, unlike Chrome and Firefox, applies that rule to 127.0.0.1 as well. Measured on Safari 26.4: the request fails in about one millisecond and never leaves the browser, so Ollama records nothing. It is not a permission and cannot be granted — Safari exposes neither a local-network permission nor a per-site mixed-content override. Two routes need nothing installed. Copy/paste mode works in Safari today: it copies the sanitized request for any model you already use and takes the returned plan back, with no connection, no certificate and no setup. Or open Molstudio in Chrome, Edge or Firefox, where a direct connection to a local model works — Firefox needs no permission at all.

Safari, a direct connection. This one is for people running Molstudio themselves; it needs a terminal and a certificate your machine trusts. Serving the same Ollama over https removes the scheme mismatch and Safari then behaves normally: it dials 127.0.0.1, completes TLS and returns 200. Nothing leaves the machine; proxy and model both stay on loopback. Create a trusted loopback certificate with mkcert -install && mkcert localhost 127.0.0.1, which installs a local authority and writes the pair. Without mkcert, generate one with openssl req -x509 -newkey rsa:2048 -nodes -keyout local.key -out local.crt -days 365 -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" and trust it for SSL in Keychain Access by setting Secure Sockets Layer (SSL) to Always Trust. Trusting a certificate changes what your machine accepts, so run that step yourself and keep the key private to this machine. Then start the front door with node scripts/ollama-https-proxy.mjs --cert local.crt --key local.key --origin https://molstudio.app and set the request endpoint to https://127.0.0.1:11435/api/chat. The proxy listens on loopback only, accepts that one exact origin and answers anything else with 403; a wildcard origin is refused outright. It sets the CORS header itself, so OLLAMA_ORIGINS is not needed on this path. If Safari still fails instantly with Load failed, the certificate is not trusted yet — that is the only thing this setup gets wrong in practice.

2. Ollama: the origin allowlist. Ollama rejects an unknown browser origin until that exact origin is allowed, which fails immediately rather than stalling. On macOS run launchctl setenv OLLAMA_ORIGINS "https://molstudio.app"; on Windows run setx OLLAMA_ORIGINS "https://molstudio.app"; on Linux add Environment="OLLAMA_ORIGINS=https://molstudio.app" to the Ollama systemd service. Fully restart Ollama afterwards; a running instance does not pick up the new value. On macOS, launchctl setenv lasts only until the Mac restarts — if a working setup stops after a reboot, re-run the command and fully reopen Ollama again. To confirm the allowlist independently of the browser, run curl -i -H "Origin: https://molstudio.app" http://127.0.0.1:11434/api/tags and check for a matching Access-Control-Allow-Origin header. If curl succeeds while the page still times out, the browser permission above is the remaining cause. The in-app message uses the page’s actual origin for preview or custom deployments. Do not grant a wildcard origin.

Open AI Director. Choose Project, Selection or Shot scope. The current selection and playhead make a focused prompt possible without serializing the scene.
Read Context preview. Check the components, active selection, shot, timeline, camera and available capabilities the model will see. Narrow the scope if the request does not need the whole cast.
Ask for an outcome. Describe the visible story—who moves, what it meets, when it happens and what the camera should explain. The model returns an allowlisted semantic plan rather than JavaScript, HTML, arbitrary JSON Patch or raw application edits.
Inspect the plan. Molstudio parses and validates every step against a fresh environment snapshot, shows risk and interactive handoff labels, and refuses unknown tools, malformed arguments or stale scene references. Acquisition, construction and destructive prerequisites must be first.
Choose the visible Apply action. A scene-only plan uses the normal explicit Apply. A plan that must import, build, remove or begin blank first shows Apply construction; its future scene edits remain paused.
Review the refreshed scene. After prerequisites finish, Molstudio rebuilds Context preview and revalidates the remaining steps against the actual new IDs. Only a valid new preview exposes Apply scene edits. Authored scene edits then become one atomic history record with Undo this plan while that edit is newest.
Finish exact choices in the viewport. When a task needs a surface point, residue range, flex region, route or composed camera view, the plan opens the relevant full Director guide and leaves the visible choice to you.

From an empty project to a complete scene

The model can propose the cast, locally authored forms and later animation in one molstudio.llm-plan/1 document, but Molstudio deliberately executes it across two reviewed stages. The prerequisite stage changes what exists; the scene stage can only refer to what the refreshed browser actually created.

Six bounded prerequisite tools

project.blank creates the empty stage and, if present, must be first and occur once. structure.import_rcsb, structure.import_file and structure.import_url acquire molecular structures. shape.create constructs and installs a bounded illustrative Shape Lab asset from semantic primitives, paths or twisted bundles. asset.remove removes one named cast member and dependent authored records.

Source choices stay visible

A local-file step exposes Choose file and cannot run until the PDB or PDBx/mmCIF is selected; its bytes never enter the plan or model context. RCSB and local-file loaders show the biological-assembly chooser when alternatives exist. URL acquisition is limited to credential-free HTTPS RCSB or AlphaFold locations and depends on browser CORS; use the local chooser for another provider.

Refresh before choreography

After Apply construction, Molstudio takes a new sanitized environment snapshot, substitutes only safe returned IDs into declared scene-ID fields and revalidates every animation, appearance and camera step. A dependent top-level ID argument may be exactly $result.<stepId>.actorId, .componentId, .selectionId, .assetId or .id. It cannot be embedded in prose, a URL, a nested record or another string. For example, a shape.create step named cable can feed "actorId":"$result.cable.actorId" to a later animation.add_motion step. Missing actors or changed capabilities stop the sequence with no later scene edit; the model can plan again from the refreshed context.

Separate consent and recovery

project.blank and asset.remove require both a literal safety token and their own visible exact-target confirmation. Construction and scene edits have separate Apply decisions and history boundaries. If construction is the final requested stage, or the refreshed scene plan cannot proceed, Undo imported/build stage restores the exact pre-stage project while safe. Undo this plan reverses the newest atomic authored scene edit.

What the model can—and cannot—see

Whitelisted scene brief

The context contains compact IDs, names and summaries for relevant components, selections, shots, timing, camera state and supported semantic tools. It is rebuilt from the live document for each request and can be limited to the selection or current shot.

No raw App or structure data

AI Director excludes the raw App document, atom coordinates, PDB/mmCIF text, trajectory frames, mesh buffers, audio bytes, local filenames and file payloads, credentials and internal adapter envelopes. Prerequisite receipts contain only safe semantic IDs and small provenance labels. A model never receives MolstudioCreatorBridge.

The key is browser-visible

A key entered in a static web app cannot be made into a server secret. The page, browser extensions and provider request can observe it. Prefer a short-lived browser token, keep it in memory, and use the session-only option only on a device you trust. Molstudio does not send a browser-entered token directly to api.openai.com; use Copy / paste or a browser-safe relay.

Science still needs the picker

A model may resolve a known sequence or ligand and open the correct guide. It may not invent a molecular-surface triangle, cartoon residue envelope, atomic site, folding path, affinity, docking energy or preferred pose. Exact contact and flex choices return to Molstudio’s representation-aware picker.

Static-site truth. /llms.txt and the files under /api/ are static GET discovery documents for the protocol, tools, schema, examples and planning rules. They are not a live HTTP control API: this deployment cannot receive POST tool calls, webhooks, protect provider secrets or address an open browser tab. Live control happens only inside the user’s tab through direct outbound requests, copy/paste, or the explicitly enabled origin-scoped window bridge.

For model builders. Plans use schema molstudio.llm-plan/1. Start with llms.txt, then read /api/manifest.json, /api/tools.json, /api/environment-schema.json, /api/environment-example.json, /api/plan-schema.json, /api/examples.json, /api/openapi.json and /api/system-prompt.txt. Discovery is public; live project context appears only after the user opens and scopes AI Director.

04 · Guided animation, step by step

Guided animation is a transparent authoring shortcut, not a library of canned biology. It asks one question at a time and previews the intended handoff in the viewport.

Step	What you choose	What stays editable
1 · What should move?	Use the component selected in the viewport or choose another cast member.	The actor or independent generated unit.
2 · What do you want it to do?	Move somewhere; Approach / meet; Bind / follow; Rotate / flex; Grow / assemble; or Custom behaviour.	The low-level operator or relationship type.
3 · Where or how should it move?	Draw the route, use Straight movement, choose or pick a target, select a flex action, or choose an assembly origin.	Pose points, distance and direction, target, pivot, unit count and layout.
4 · When should this happen?	At the playhead; After its last action; At this shot’s opening; Halfway through this shot; or exact Start and Duration. Pace can be Quick beat, Natural or Deliberate.	Start, duration and all later retiming.
5 · What should happen afterward?	No added response; Brief highlight; Soft physical contact; or Pause, then release. Physical contact appears only when Dock or Bind makes a real surface meeting.	Response record, Ripple Å, Ripple time or dwell.
6 · Does this describe your step?	Read the plain-language sentence, then choose Create step or Create + play.	Every generated key, clip, contact port, constraint, relationship, generator and Transparent Motion Block.

Unrestricted by design. A guided step compiles to the same ordinary editable records used by the rest of Molstudio. Change them in the timeline or under More control, combine them with direct gestures, or delete the Motion Block metadata without losing access to the underlying work.

Draw the route asks you to press Start drawing in viewport and drag the chosen component through the frame. Molstudio samples a smooth editable route; the guide then retimes those pose keys into the chosen interval. Straight movement exposes Distance Å and Direction X/Y/Z under More control. For component targets, press Pick in viewport, tap or click the intended actor, then Use selected.

For open-ended construction, More control exposes Drag + record, Draw a path, all motion operators, the Process composer and exact Editable records. Process composer sentences also compile to ordinary clips, anchors and relationships; the sentence is never needed to edit the result.

One visual recipe for every outcome

Move through the scene

Select the mover, choose Move somewhere, then Draw the route. Press Start drawing in viewport and drag the component through every turn. For a direct move, choose Straight movement, press Place destination ghost, and click where it should end. Choose timing and Create + play; the result is editable Pose keys, not a baked path.

Meet, dock or bind

Choose Approach / meet for Stop nearby or Meet and settle, or Bind / follow for Bind after arrival or Follow from here. Pick a target, optionally set two exact points, preview the docking ghost, then choose whether the relationship settles, follows, releases or produces a restrained contact response.

Flex around a chosen place

Right-click the visible hinge cue and choose Flex around this point…, or choose Rotate / flex in the guide. Press Pick region endpoints, then click two points on one component. The marked owned residue range becomes an editable child component with an explicit pivot, axis and bend arc. Choose Flex and return, Rotate, Organic drift, Breathe or Step / ratchet; the behaviour and its exact controls remain editable.

Grow or assemble matter

Right-click the intended origin and choose Grow or assemble from here…. In Grow / assemble, select the Assembly origin and press Place path. Place the endpoint, adjust depth, and optionally add a bend; the measured target-local path genuinely drives the retained-unit placement. Set Units, Layout, Rise Å, Twist ° and Radius Å under More control. Creation writes an ordinary editable generator.

Reveal or change appearance

For full material work, right-click and choose Change appearance…. For a timed change, choose Custom behaviour → Appearance / reveal, then Reveal, Conceal or Pulse highlight. Press Pick appearance cue on the component: the cue identifies the active representation that will change. The resulting effect clip deletes neither atoms nor representations.

Make contact feel physical

On a Dock or Bind arrival, choose Soft physical contact. Preview and tune Ripple Å, Travel radius Å and Ripple time before creation. For another response choose Custom behaviour → Component response, choose its motion, then Pick response origin. Choose This component only or Through completed contacts; the latter retains ordinary hops, delay and falloff.

Direct the camera

Right-click the subject and choose Make the camera follow…, or choose Custom behaviour → Camera move. Choose Compose a camera move and a Camera focus target, then press Compose destination view. The handoff preserves the chosen camera mode, framing and focus metadata beside ordinary camera tracks.

Keep going after creation

Review never closes off the result. Create step writes it without playback; Create + play checks only that interval. Afterwards use Play this step, Make another step, the Pose lane, Editable records or Process composer. Transparent Motion Block metadata records the intention, while the actual keys, clips, anchors, constraints, relationships and generators remain independently editable.

05 · Viewport, touch and context menus

Intent	Mouse / trackpad	Touch	Keyboard
Navigate the camera	Choose Orbit for target-based orbit/pan, or Free camera and drag empty space to look. The wheel dollies in either workflow.	Choose Free camera and use its on-screen touch pad to move while dragging empty space to look.	In Free camera use W/A/S/D, Q/E down/up, arrows to look, Page Up/Page Down or +/− to dolly, and K to key. Shift makes look/dolly finer. Choose Orbit to leave Free camera.
Select	Choose Pick, then click visible molecular or generated geometry.	Choose Pick, then tap.	Move focus to the canvas; the Context Menu key or Shift+F10 opens actions for the current selection.
Manipulate	Choose Move, Path, Rotate, Depth or Scale, then drag.	Choose the same tool, then drag with one finger.	Use the toolbar or Search commands; K keys the camera, not the molecule.
Context menu	Right-click without right-dragging.	Touch long-press for about half a second without moving.	Context Menu or Shift F10; arrows navigate, Home/End jump, Enter activates and Esc closes.
Timeline	Drag the playhead or a Pose diamond; Fit/−/+ change the view.	Drag; use the Timeline drawer on narrow screens.	Space plays/pauses in the studio; Director also provides Play and Start.

Auto-key off makes a setup change. Auto-key on records one grouped Pose key at the current playhead for position, orientation and uniform scale. A complete drag or path gesture is one undoable edit. Select a Pose diamond to change its values, easing and direct/smooth spatial interpolation, or drag it to retime it.

Right-click a component

Manipulate: Move, Path, Rotate, Depth, Scale and Auto-key. Animate outcome: Move along a route…, Meet at chosen points…, Bind at chosen points…, Flex around this point…, and Grow or assemble from here…. Object: Frame selection, Open guided animation, Change appearance…, Make the camera follow…, and Generate an assembly from here (or Edit procedural assembly). Representation: Cartoon, Surface, Ball + stick, Spacefill and Open full Style controls. Scene/Edit: hide, isolate, show all, lock/unlock, duplicate or safely remove.

Right-click empty space

Use Frame all molecules, Show all molecules, Add molecular component…, Open Motion Lab or Render a still…. Direct changes act immediately. Larger outcomes open the relevant full Director workspace instead of sending you to a cramped side panel.

Work viewport-first

Press Focus viewport, direct the shot with the tool strip and context menu, then press Restore workspace only when you want the cast, questions or timeline. A pin, hinge cue, destination ghost, growth preview or camera frame remains visible while its full workspace is open, so switching panels does not erase the decision.

Phone and tablet

Tap to select and long-press without moving for the same outcome menu. Cast and Timeline open as drawers instead of shrinking the frame; tap Back to stage to close a drawer. Focus viewport leaves the essential tool strip available. In Free camera, drag empty space to look and use the on-screen touch pad to travel; choose Orbit to return. During point picking, touch and drag to preview beneath your finger, then release to fix the requested pin; the prompt names the next action. Keyboard users move the visible crosshair with arrows and press Enter, with the hovered component and scientific site announced. Cancel or Esc exits without creating records.

Dragging a dropped component near another also offers Place, Dock or Bind & Follow. A generated unit keeps a stable numbered identity, but deletion and duplication belong to its generator so the retained schedule stays coherent.

06 · Point-to-point interaction and response

Connect begins with two participants: Moving and Target. Choose Approach, Dock, Bind & follow or Follow. Automatic contact uses the nearest visible atoms at the chosen time.

Fast point-to-point path: right-click the exact visible site on the moving component and choose Meet at chosen points… or Bind at chosen points…. That first point stays pinned; move over a different component and click its exact target site. Molstudio opens the guided relationship with both coloured pins, normals and docking ghost retained. In the guide you can also expand Pick exact surface points, use Pick moving pin and Pick target pin, then Preview contact and Confirm points. Gap or clash feedback remains visible, and either pin can be repicked.

What an exact point means in each representation

Molecular Surface

The pin lands on the visible surface triangle at the click, stores its barycentric position and outward normal, and remains in actor-local coordinates so it follows later motion. The amber moving pin and cyan target pin show which side of the contact each frame belongs to.

Cartoon or trace

A ribbon is a visual path through the backbone, not the physical molecular boundary. Molstudio keeps the clicked ribbon location as a dashed cue, resolves its residue, and connects that cue to an atom/probe envelope used for contact. This prevents a cartoon-centre click from being silently treated as a solvent surface.

Atoms and sticks

Spacefill, Ball + stick and Sticks resolve the visible atom and place the contact on its envelope along the picked direction. The atom and residue identity stay with the point, so the marker can be inspected and repicked instead of collapsing to a component pivot.

Shape Lab and fallbacks

A custom Shape Lab mesh uses its actual visible triangle and normal. A visible atom may be labelled as an atomic-site fallback. A missing molecular-surface or custom-mesh hit never invents a component-centre pin; the guide asks you to repick or change representation.

Read the preview before creating. Normal arrows show orientation; the line and readout show separation; the dock ghost previews the solved placement; gap/clash feedback warns about overlap. These are authoring aids, not an affinity or steric-energy calculation. Confirm points only after the visible handoff matches the intended story.

Set Start, Approach time and Gap (Å); choose the Contact constraint; decide Stay connected or Release after dwell; then set Dwell. Point, rigid, soft, hinge and slider constraints control which parts of the contact frame are held. Press Create editable interaction to write ordinary anchors, relationship, constraint and optional response records.

Choice	What it does	Use it for
Soft physical contact / Physical ripple on arrival	Creates a deforming Å-scale wave on the receiving ribbon, surface, atoms and sticks. The travelling geometry also drives tint, roughness and micro-normal; optional glow is separate.	A contact that should feel mechanically present. Edit Amplitude Å/Ripple Å and Ripple time; the restrained default is intentional.
Brief highlight	Changes material appearance without moving the geometry.	A quiet viewer cue when physical deformation would imply too much.
Contact Flash, Molecular Ripple, Energy Arc, Particle Burst	Adds timeline VFX around an event. These are visual overlays or cues, not a substitute for physical surface deformation.	Explanatory emphasis, stylised energy transfer or presentation graphics.

Scientific classification. A physical ripple really displaces evaluated render geometry, but it is still deterministic illustrative deformation—not molecular dynamics, an elastic calculation or evidence of an allosteric pathway. It never rewrites deposited atoms or imported trajectory coordinates. Dock and Bind stage a chosen contact; they do not calculate affinity, free energy or a preferred pose.

07 · Shape Lab draw and sculpt

Open Sculpt or choose Shape Lab from Create when the object you need is not in PDB or a predicted source. The full-screen workspace labels every result Illustrative geometry, keeps dimensions in ångströms and stores a non-destructive graph. Draw is a general path-to-geometry tool, not a helix preset: the authored centreline and graph remain editable.

Begin from anything—or nothing. Use Clear canvas for the blank canvas, then draw freely or add Sphere, Ellipsoid, Capsule, Rounded box, Cylinder, Torus, Tube or Ribbon layers. Shape Lab stores a local editable working draft after changes and automatically restores the latest draft for this project after an interruption. That recovery stays in this browser; export a portable asset for another device.
Draw an arbitrary centreline in 3D. Press Draw or D and drag anywhere in the viewport. Choose Solid stroke, Ribbon or Twisted bundle. Set 1–12 strands, turns and orbit radius; optional Add physical cross-links makes ladders and connected cables. All strands follow the route you draw. Enable Snap start to visible surface to anchor the first point to the shown mesh. Hold Shift + wheel while drawing, or change Depth plane (Å), to carry the stroke toward or away from the camera.
Decide how the form meets the asset. Choose Blend, Fuse, Cut or Start fresh in the compact dock—the inspector names these Blend into current, Hard-fuse to current, Cut from current and Start a fresh object. Draw more paths to branch or cross instead of selecting a special molecular preset.
Edit the path as geometry. A completed path exposes draggable control handles; releasing one handle is one Undo step. Select a plain path and choose Continue from end, or choose Reverse selected path for any authored path or bundle. Delete selected removes the entire logical form, including the hidden children of a twisted bundle, and Undo restores its exact geometry and dependencies. The toolbar Undo and Redo apply to graph edits, strokes and handle moves.
Sculpt the visible result. Press Live preview, then use Pull (1), Push (2), Inflate (3), Smooth (4) or Flatten (5). Set Radius (Å), Strength and Soft edge. Pointer pressure adjusts the stroke on supported pens; a cancellable live brush mesh follows the stroke before release commits one reversible layer. No symmetry, Mirror X, Mirror Y and Mirror Z mirror the completed stroke across the chosen local axis.
Finish semantics without guessing. Under Paint or Ports, press Pick surface point, then click or tap the exact visible surface. A cyan pin remains while you confirm Paint at pinned surface or Add at pinned surface; this one-shot picker never sculpts. Paint stores a named material region with colour and Radius Å. Ports store stable surface probes so the asset can Dock, Bind and seed assemblies. Coordinate entry remains available when you already know the Å position.
Build, export or install. Choose Preview, Draft, Final or Ultra from Mesh quality, then press Build mesh. Preview and Draft are interactive meshes; Final and Ultra produce the installable production mesh and save it to the local Library. Export asset offers two local downloads: an editable .molasset master preserving the graph, drawn paths, sculpt layers, ports, regions and provenance, or a baked Wavefront OBJ with full Final vertices, normals, indexed faces and an illustrative provenance header. OBJ cannot retain those editable semantics; exporting never installs or changes the Studio scene. Add to scene is the separate explicit install action. It creates one ordinary selectable actor and Director returns to Animate.

Navigate while authoring

Mouse/pen: right-drag or Alt-drag to orbit; middle-drag, Pan, or Shift while navigating to pan; wheel to zoom. In Draw, Shift + wheel changes the active depth instead. Touch: one finger draws, sculpts or orbits according to the active tool; two fingers pinch to zoom and pan. Keyboard: D Draw, O Orbit, P Pan, [ / ] brush radius, Ctrl/Cmd+Z Undo, Shift+Ctrl/Cmd+Z or Ctrl/Cmd+Y Redo, Delete deletes the selected logical layer, Esc cancels, Home frames, and ? Help opens the shortcut panel. Opening, importing or resetting an asset auto-frames its scale; Home repeats that framing at any time.

Deform without baking

The Deform tab can add Mirror, Shell, seeded Organic detail, Twist, Taper, Bend, Linear array, Radial array and Helix array modifiers. The Shape, Deform, Paint and Ports tabs describe one portable asset rather than destructively rewriting a source structure.

Graph edits schedule a local Worker preview after a short pause. New requests coalesce and stale jobs are cancelled; browsers without a Worker use the same CPU mesher on the main thread. Shape Lab does not currently use WebGPU to mesh, so preview and final output remain identical for a chosen LOD across supported devices.

08 · Sound, captions and local projects

In Finish → Audio and narration, the Sound + captions workspace imports local audio without uploading it. If the browser blocks playback until a gesture, press Enable sound.

Audio tracksImport a browser-decodable WAV, MP3, M4A/AAC, OGG/Opus, WebM audio or FLAC file. A compact waveform appears against the molecular timeline.
EditName each track and set Timeline start, Trim in, Trim out, Gain, Fade in, Fade out and Mute. Playback follows play, pause, seek, loop and visibility changes.
CuesUse Cue here or Add cue at playhead to make ordinary audio cue marker records. Export shot captions and labels as SRT or VTT.
StorageThe live document keeps editable audio metadata; ProjectStore keeps the original Blob/ArrayBuffer as a project asset rather than embedding base64 in the working timeline.

Autosave is browser-local and non-blocking. The header reports Local, Saving or Saved locally. Finish provides Save now, Export project, Import project and up to 24 local revisions; Restore first preserves the current state as another revision. An interrupted newer session can be offered for recovery.

The account belongs to the whole website. In Studio it adds a private library for complete portable projects, lets you reopen them on another device and enables revocable snapshot links. Nothing uploads through browser autosave: choose Save new project or Save current project. Cloud conflicts are reported instead of silently replacing another device's version. Signing out ends the shared website session without deleting the browser recovery copy.

Keep a local recovery path. Clearing site data removes browser-local projects and audio assets. Export a .molstudio.json bundle before clearing the browser. Local autosave and portable export continue to work signed out or offline.

09 · Render, export and graphics backend

Use Finish → Render still for a tiled high-resolution frame or Render animation for a finished film. Interactive previews can adapt to the device; explicit final resolution, samples, materials and effects remain authored output settings. AgX/ACES grading, depth of field, bloom, fog, material microdetail and opt-in traced passes are evaluated by the production renderer.

AnnotationsOptional annotations is independent of the project’s labels and captions. Turn inclusion off for a clean plate without deleting editorial work.
VideoH.264 MP4 through WebCodecs is preferred. If the browser cannot provide that path, Molstudio tries a native MP4 recorder and then WebM as a compatibility fallback.
Authored soundWhere the selected browser and recorder codec support mixed MediaStream audio, animation capture can include authored sound. Diagnostics explain codec limitations; a visual render can continue silently rather than fail.
Large stillsFrames larger than GPU memory are split into pixel-consistent tiles. 16-bit PNG and linear OpenEXR are available where the selected render path supports them.

WebGPU hybrid

On a secure, supported browser Molstudio asynchronously negotiates WebGPU after the first studio paint. The badge says WebGPU hybrid only when its compute device is ready. It currently accelerates supported residue-bounds and contact-field work and prewarms those pipelines.

WebGL2 compatibility

The production visual renderer remains WebGL2 for parity. Unsupported or insecure WebGPU, preference off, adapter failure or device loss leaves the live canvas on WebGL2 compatibility; it does not blank the viewport. Click the badge to toggle WebGPU-first/off and use its accessible tooltip for the reason.

WebGPU selection is a truthful hybrid, not a claim that the full visual renderer has been ported. Device-loss recovery and compatibility fallback are automatic and do not block studio startup. Developers can inspect the staged capability report, diagnostics, subscriptions and compute hooks through window.MolstudioGPU.

10 · Keep the science legible

Coordinates and authorship are different layers. Deposited experimental coordinates, predicted/imported structures, imported trajectory frames and authored illustrative geometry retain distinct provenance. Molstudio helps you stage an explanation; it does not silently turn choreography into evidence.

Guided motion, contacts and procedural assemblies are authored visual records unless backed by an imported simulation. They do not calculate thermodynamics, kinetics, docking scores or binding affinity.
Rotate / flex, Organic drift, Breathe and Step / ratchet are deterministic authored motions. A chosen hinge cue and bend arc do not predict a conformational pathway or its energetics.
Grow / assemble retains copies of chosen geometry according to an editable construction rule. It does not infer polymer chemistry, sequence, stoichiometry, assembly order or biological feasibility.
Appearance / reveal and Camera move are editorial. A highlight, conceal, camera track, rack focus or framing change makes no molecular claim unless its caption cites underlying data.
Sequence & chemistry director resolves exact displayed motifs, deposited residue ranges, ligand/component names and formulas into selections. It does not predict sequence, folding, binding sites or conformational pathways.
Shape Lab assets are always illustrative. Å-scale units make them compatible with the scene, not experimentally determined.
Physical ripple deforms evaluated render geometry but leaves source and trajectory coordinates unchanged. A visual Molecular Ripple VFX is an explanatory overlay.
Morph between states chemically matches and aligns two coordinate sets, then interpolates the matched atoms. Intermediate frames are not a physical pathway. Play trajectory uses imported multi-model PDB/mmCIF or matching DCD/XTC frames; periodic coordinates are not automatically unwrapped or made whole.
Generated units are newly authored retained geometry. Reveal/Hide instead exposes geometry already loaded from a source. Keep captions and citations explicit about which one the film uses.

11 · Local reference

Material atlas

The packed 2K PBR atlas covers protein, membrane, ceramic and machined-metal families with world-space projection. Channels are R height, G roughness, B albedo and A cavity.

For deeper animation examples and mechanism notes, continue to the Motion Lab manual and gallery. For image-pipeline detail, see Rendering.