Manual 01

Make a molecular film

Docs

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. One account covers deliberately saved Studio and Lab projects, a public-by-choice profile, moderated community features, export receipts, saved AI Director runs and private classroom rooms. Local autosave never becomes a cloud upload by itself.

Your first film

Hosted

Open the studio on a clean stage, add the molecules involved, then build the sequence by selecting them and adding what happens next. Every action remains editable on the timeline.

Launch the studio

On your machine

The renderer, open working document, local recovery and imported audio stay in the tab. Only an explicit action crosses that boundary: a manual cloud save, share or publication; receipt registration; an AI request; or joining a private live room.

How rendering works

Add the molecules. Start from an empty stage, add a PDB entry or local PDB/mmCIF, and select components directly in the viewport or cast.
Build what happens. Add movement, contact, binding, release, conformational motion, assembly or a clearly labelled visual reaction cue from the same authoring workflow.
Build it as Steps. Select a molecule; its Action pane lists the animation as ordered sentences — who · does · whom · at where. Choose a verb under Add a step (moves to, moves away from, approaches, meets, binds, follows, releases, turns, flexes, grows, reveals, conceals, highlights, ripples), pick the site from saved selections, a Residue range or the viewport, and press Add step. Each step starts when the previous one ends and writes an ordinary editable clip. Shift-click a range of steps and choose Repeat these steps ×N to repeat them as editable copies.
Add a phase. Guided animation asks what moves, what it does, where it goes, when it happens and what follows. Draw a path in the viewport or choose a target and timing.
Add and check it. At Review, choose Add + play. You can then adjust the route, timing, contact and appearance like any other part of the scene.
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. Rendered stills and cinematic animation frames carry the keyed pixel mark; real-time quick video carries the visible corner mark only. A signed-in browser also attempts an exact-file receipt after the download, which can be retried from Export receipts and checked at 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 explore how it moves and interacts.

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. Add a biological phase with Guided animation, or open Fine controls to adjust its path, timing and movement in detail.
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.

AI Director, with the author still in control

AI Director gives a language model a focused description of the scene and asks it for specific Molstudio actions. It does not hand the model control of the application or hide an edit behind a chat response. You see what is shared, the proposed steps and the previewed changes 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 a supported structured-JSON endpoint or local model service; 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.

Save an AI Director run

Save now, run when ready

A saved run keeps your prompt and a focused description of the scene. Return later and choose Run in AI Director. Keep that tab open while your model works: Molstudio does not run a model for you in the background.

Your model connection stays in the tab

Direct uses the endpoint, model and optional browser token already configured in AI Director; Copy / paste needs no key. Molstudio never stores those connection details with your account or project.

Examples stay private

Molstudio can use up to three of your recent accepted results as private examples for a saved run. Rejected results are not reused, and examples are never public or shared with another account.

Checked before it is ready

Molstudio checks a returned plan in the current tab before marking the run ready. You still see the proposed changes and choose whether to Apply them; saving or completing a run never edits the scene by itself.

Scheduled scene ideas still need a person. An administrator can schedule a prompt, but a team member must run it in Studio using their own model connection. A moderator or administrator then reviews the result, and approval never publishes it automatically.

Review or autonomous. The four-step flow above is review mode, the default: every mutating plan waits for an explicit Apply. Saved account runs always use this reviewed path. For an ordinary unsaved request, 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 endpoint receives those frames with its next request 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. Named selections provide a selectionId that later steps can reuse through $result, so a plan can find a ligand or catalytic site and frame it with camera.frame. Each imported component lists its displayed non-polymer chemistry with exact component codes and names; if a selection fails, Molstudio shows 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. If a test fails in Firefox, the cause is step 2 below, not a site permission.

Safari — use Copy/paste mode, or another browser. Safari refuses plain HTTP from a secure page and applies that rule to 127.0.0.1. The request never leaves the browser, and Safari exposes neither a local-network permission nor a per-site mixed-content override. Copy/paste mode works without a connection, certificate or setup. Or open Molstudio in Chrome, Edge or Firefox, where a direct connection to a local model is supported.

Safari, a direct connection. This route is for people running Molstudio themselves; it needs a terminal and a certificate your machine trusts. Create a trusted loopback certificate with mkcert -install && mkcert localhost 127.0.0.1, then start the loopback-only 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. Without mkcert, import the self-signed certificate in Keychain Access and set it to Always Trust for SSL. Keep its key private. The proxy accepts one exact origin, rejects a wildcard, and keeps both proxy and model on loopback. If Safari fails immediately with Load failed, the certificate is not trusted yet.

2. Ollama: the origin allowlist. Ollama rejects an unknown browser origin immediately. 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 afterward; a running instance does not pick up the new value. On macOS the launchctl value lasts only until restart, so re-run it and reopen Ollama after a reboot. Confirm independently with curl -i -H "Origin: https://molstudio.app" http://127.0.0.1:11434/api/tags and check for the matching Access-Control-Allow-Origin header. If curl succeeds while the page still times out, the browser permission above remains the cause. 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 checks the remaining steps against the new scene. Only a valid new preview exposes Apply scene edits. Those edits become one undoable change while they remain the newest work.
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 its dependent scene work.

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 value 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 direct-mode 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. Saved account runs use that same browser connection; Molstudio never transfers it to Supabase.

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.

Reference files, not remote control. /llms.txt and the files under /api/ describe the tools, examples and planning rules. They cannot control an open browser tab. Saved runs stay private to your account, only your browser calls your model, and every plan still requires validation and review in the current tab.

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.

Connect your own AI

Molstudio does not sell or bundle a model. If you already use one, wherever it runs, there are two routes in, and both end with you reviewing the result.

The AI workbench

The workbench assembles a briefing built from the shipped pathways, so it describes what the software accepts today rather than what a model remembers. Copy it into any chat, paste the reply back, and the validator checks the document against the current vocabulary before you take it to Studio. Nothing to install.

A direct connection (MCP)

In claude.ai or ChatGPT, add a custom connector with the address below and the client walks you through it: you approve the connection on a Molstudio page while signed in, and the client receives its own token. Command-line and local MCP clients can instead use a personal access token from the Connected AI section of your account page; it is shown once, expires after 90 days, and revoking it on that page cuts any client off immediately. Either way the address is: https://emejbmoctjdqyiknvhbd.supabase.co/functions/v1/mcp. The address sits on Molstudio’s backend domain because the site itself is static pages; your account and projects already live there. Every signed-in member can connect. There is no plan, reviewer or verification requirement.

What a connected AI can and cannot do

It can list and read your projects, look up a PDB entry’s chains and lengths so its residue ranges match the deposited structure, check Steps documents against the shipped vocabulary, leave draft pathways and read its own drafts back to revise them, and save new projects to your account. It can also see what it has spent against your limits, so a long job paces itself instead of stopping at a refusal. Drafts wait in the workbench until you approve them. There is no tool that changes or deletes existing work: anything it saves arrives as a new project that you open, keep or delete like any other.

Add one phase at a time

Guided animation turns one part of a molecular story into visible motion. It asks one question at a time and previews the result in the viewport before you add it.

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, ripple strength, ripple time or dwell.
6 · Does this describe the phase?	Read the plain-language sentence, then choose Add phase or Add + play.	The route, timing, contact, response and appearance.

Change any part later. A guided phase uses the same timeline as the rest of Molstudio. Adjust it under Fine controls, combine it with direct movement, or remove it without disturbing the rest of the film.

Draw the route asks you to press Start drawing in viewport and drag the chosen component through the frame. Molstudio turns that gesture into a smooth route over the chosen time. Straight movement exposes distance and direction under Fine controls. For component targets, press Pick in viewport, tap or click the intended molecule, then Use selected.

Fine controls lets you draw paths, move components directly and adjust exact animation settings. Quick sequence turns a short sentence into a sequence you can continue changing on the timeline.

Steps is the everyday way to build a mechanism. A step is one sentence over the same clips, relationships and pivots as the rest of the timeline; remove the grouping and each one stays exactly where it was. Sites come from saved selections or a typed residue range, so a ligand buried in a pocket can bind without a viewport click; Pick in viewport remains for an exact point on steps that move, approach, meet, bind, follow or flex.

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 Add + play; you can reshape or retime the route afterwards.

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. Set the number of units, layout, spacing, twist and radius under Fine controls, then preview the result in the viewport.

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. Add phase adds it without playback; Add + play checks only that interval. Afterwards use Play this phase, Add next phase, Fine controls or Quick sequence, or select the molecule and use its Action controls to add what happens next.

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 Action controls, 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 anything.

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.

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 add the anchors, relationship, constraint and optional response.

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.

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.

Sound, captions and local recovery

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 place audio markers. 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. Nothing uploads through browser autosave: Studio and Lab each require 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.

Account, cloud projects and community

Signing in gives you the same account across the website, but it never uploads the work you have open. There is no background cloud sync. Projects shows your saved Studio and Lab work. Open, rename and delete from there; use Save new project or Save current project inside Studio or Lab when you decide to save online.

Saving in Studio

Save new project creates a saved project; Save current project updates it. Molstudio checks a project before opening it and warns you if another device has already saved a newer version.

Saving in Lab

Lab saves the project and its source files together, avoids uploading the same file twice, and keeps a revision history up to your account’s per-project limit.

Sharing is a separate choice

Saved projects stay private until you choose Share current version. Publishing to the scene gallery is another step and requires review. Later private edits do not change a published scene, and you can withdraw it. Browse Published scenes.

Your community profile

A public handle, display name, short biography and bundled molecular avatar are optional. Your login email stays private and there is no profile-photo upload. Members can report discussions, and moderators can lock or remove content when needed. Join in at the Forum.

Deleting is immediate; file cleanup can take longer. A deleted project disappears from your library straight away. Files used by a published scene can remain until that scene is withdrawn; other unused cloud files may take a short time to clear and release storage space.

Receipts match exact files, not authorship

The file downloads first. Molstudio then creates a fingerprint for the completed file and, while signed in, attempts to register it with the file type, size and time. The image, project, source file, filename, email and public profile are not included. Export receipts keeps up to 250 recent items on this device so a failed registration can be tried again.

What a match means. A matching receipt shows that the same file was registered by a signed-in Molstudio account at the time shown. It does not prove identity, authorship, ownership, originality or scientific validity. Editing or converting a file changes its fingerprint.

Private rooms share playback, not project files

Room members can see who is present and share the playhead, playback, selection and current document revision. Optional checkpoints preserve that presentation state. Molecular files, the project document, audio and sign-in details never enter the room. Classroom and presentation modes do not save or sync a project in the background.

Account tools and current limits

Account exportExport my account data downloads your account details, profile, project list, receipts, community activity, saved AI runs and room memberships. Export Studio and Lab project files separately.
Account deletionAfter a fresh sign-in and typed DELETE confirmation, your account is disabled and private cloud files are scheduled for secure cleanup. Forum text can remain anonymously so other members do not lose their replies. Browser recovery copies and files already downloaded by other people cannot be remotely erased.
ProjectsUp to 100 saved Studio and Lab projects, with 1 GiB of private cloud space by default.
RevisionsLab keeps up to 100 saved revisions per project by default.
Daily workUp to 100 new export receipts and 20 new saved AI runs per UTC day by default. Limits may change as the service develops.

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.
Marks + receiptsRendered PNG stills and cinematic animation frames receive the keyed pixel mark. Real-time quick video has the visible corner mark but no per-frame invisible mark; scene-linear OpenEXR has no display-referred mark. Exact-file receipt registration is a separate account-backed step and can remain pending without blocking the download.

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.

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 sequences 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.

The animation repository

The repository is where a molecular animation becomes a citable scientific record. A record has a permanent accession such as MOLANIM-000124, numbered versions that never change once published, a creator list frozen exactly as it stood at publication, and a declared licence. The aim is simple to state: a stranger should be able to watch the animation, tell data from interpretation, see who made it and from what, retrieve the exact version, cite it and know how they may reuse it.

The centre of every record is honesty about what the film shows. Molecular animations routinely mix solved structures, authored motion and drawn illustration, and a viewer deserves to know which is which. Each record labels its elements:

Experimental: solved structures or measured data, cited by identifier (a PDB entry, for example).
Simulation: motion computed by a physical model, with the source declared.
Interpolated: authored motion between known states. The endpoints may be solid evidence; the path between them is the animator's.
Illustrative: drawn to communicate. A proton path or a signal pulse can be honest and still not be data.
Procedural: generated set dressing, such as a membrane field.
Compressed: time, distance or scale condensed so the film stays watchable.

Records also carry a creator disclosure, which answers one blunt question: what should viewers not conclude from this animation? Video plays through a YouTube embed, while the repository keeps the scientific record itself, the render's SHA-256 fingerprint and, where the creator attached one, the editable Molstudio project. If a video ever disappears from YouTube, the record, its citation and its history stay put.

Publishing

Upload your render to YouTube, then declare the science on the publish page: sources, evidence labels, disclosure, credit and licence. The team checks that the declarations are complete and the sources are real before anything goes public. Publishing is free.

Versions and withdrawal

A correction is a new version, and the old one stays readable, so a citation always points at what the reader actually saw. A withdrawn record keeps its page, with the reason stated in the open. Links here do not rot into nothing.

Citing

Every record page offers a formatted citation and BibTeX for the exact version, plus a downloadable release manifest: the same frozen file the team reviewed, with its digest.

Reviews are named and public. A reviewer never reviews their own work; beyond that, they state who they are, which version they read and what they checked: whether the cited sources support the description, whether interpolated and illustrative motion is clearly labelled, whether the limitations are disclosed. Each review ends in a verdict: approve, revisions required, or reject, the way journal reviews do. There is no anonymous approval stamp anywhere in the repository. When a record says it was reviewed, you can open the review, read the reviewer's name and see their verdict. If you work with molecular structures, animation or the underlying science and want to help, apply to become a reviewer; applications need a verified ORCID iD, and the team reads every one. Connecting an ORCID iD on your account page lets your records and reviews carry it as verified, which means you signed in at orcid.org rather than typed a number into a box.

Casual sharing has its own home: the community gallery stays the lighter place to show scenes and talk technique. The repository is for work you want cited.

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.