# Projects and experiments

Open projects, edit goals and reuse saved starting points.

Canonical: https://roboty.dev/guide/use/experiments
Content revision: 39
Platforms: iphone, mac, browser

## Choose a storage location

Choose **This device** or your selected Mac before creating work. A project groups related experiments in that location. **Templates** keeps reusable starting inputs. **Library** holds saved reusable ingredients. Connecting to a Mac does not transfer a project.

## Choose a goal

Choose a task you want the robot to attempt. Review the project and starting inputs before creating it. Follow the instructions for your device below.

## Edit and save

Edit a project's name, description and tags in **Project details**. Limits and field messages explain invalid input. Save retains the submitted details. Newer typing stays unsaved until its own Save finishes. On iPhone, leaving unsaved project details offers **Save**, **Discard changes** and **Keep Editing**. A failed or uncertain Save keeps its original request and fields available. Do not repeat an uncertain operation as a new request.

## Add related work and continue

Open a project to continue its named experiment or choose a specific row. Draft, saved goal and recorded result describe different states. Returning from an editor keeps the originating project and browsing context. An empty active project offers a new experiment. Restore an archived project before adding work. A combined source points to its named destination.

**Duplicate experiment** creates one independent experiment without adding a template. Choose **Move to project** or **Combine into another project** to search and review a named destination. Recent choices help with repeated organization. The named recent organization action remains available after navigation or reopening. Undo refuses later conflicting changes. Only the most recent 100 local organization recovery handles are retained, with invalidated handles retired first. Saved experiments and results remain intact.

## Review imports and selected sharing

Import review names its destination. Choose a new project, an existing project or Templates where offered without selecting the file again. Changing the destination requires a fresh review before creating a copy. Recognized browser experiment files open the supported experiment review with their project context retained. Unsupported items remain in the original file.

Open **Share selected contents** when needed. Select the saved experiments, leave recorded results off unless wanted, and review the named versions and exclusions. Raw JSON is available under **Exact included file**. Changing a selection invalidates its review. **Download reviewed file** is separate from review and does not send or publish it. Private notes and device credentials are excluded from this project export.

## Projects and Templates

Projects group experiments and their saved versions. Open a project to continue, or use Search, Pin and Archive to organize your library. Archive preserves its experiments and results. All experiments also includes unfinished drafts and imported work. Compact rows show the name, experiment count or task, and abbreviated date. Dates from earlier years retain the year. On Mac, hover over the date for the full value. Select a saved experiment to inspect it, then choose Open experiment or press Return.

On Mac, Roboty uses one main workspace window. Settings and Help keep your current project, search and unfinished fields available. Project details require **Save**. Before replacing a project or closing with unsent changes, choose **Save**, **Discard changes** or **Cancel**. Discard does not undo a Save already sent. If its result is unknown, inspect or retry that original request before choosing another mutation.

Templates reuse saved inputs to create independent experiments. Their source results remain with the originals. Using a template does not start a simulation.

Each device or selected Mac keeps its own library. Connecting does not transfer work. Linking robot preparation to a project does not establish readiness to move a robot.

## Organize projects

Move keeps an experiment's saved versions and results together. Combine moves the source project's experiments into the selected project and archives the emptied source. Review the named projects and affected experiments before applying either action. Cancel keeps the current organization. Undo works while no later change conflicts.

## Make a variation

Choose Duplicate experiment or Duplicate project to start independent work from saved inputs. The source stays available. Results from the source remain reference evidence. They do not become successful attempts in your copy.

Use with another setup opens a compatibility review. Read what carries over, what changes and what is missing or unsupported. A physical intention retains the goal in words. It does not copy simulation coordinates, calibration or permission to move a robot. Complete the selected setup through Robots before considering physical work.

## Reusable setup

Open **Library** to keep reusable robot configurations, tasks, methods and scenes. **Robots** opens your physical robots directly. On Mac, Roboty opens its local storage when needed. This does not start a simulation or connect a robot. A workspace is the computer or device that owns those records. It is not a robot profile or an online account.

On Mac, Library initially shows all saved work. Use **Show** to filter robot configurations, tasks, methods, scenes or experiments. **New → New robot configuration** creates a reusable description. In **Robots**, select your robot in the list or choose **Add a robot** to prepare another. Its page shows the current setup step, connection status and next action. A project is optional for setup and practice. Opening a saved experiment's reusable setup keeps that experiment selected, including when it uses another category. A failed read shows its reason and **Retry reading** rather than an empty library.

Choose Add, then Experiment to combine saved ingredients. Choose later leaves a slot unfinished. Save the draft without installing a runtime. Edit an ingredient to create a new version. Existing experiments keep their selected version until you adopt a newer one. Duplicate configuration creates independent local work.

Select an experiment to review Use with my setup. Unknown facts need confirmation. Unsupported means this build has no matching execution integration. Open experiment appears for a supported simulation selection. Preparation and Start still check current availability and permission separately. In a saved experiment, choose More, then Reuse saved setup to open its exact ingredients. In an empty Library, open **Reuse existing experiments**, then choose **Add existing experiments** to copy saved inputs into Library. Use **Import → Import file…** for a selected reusable file. **Import → From existing experiments…** is also available when Library already contains work. Original records stay unchanged.

Choose Intended use when saving an experiment. Physical preparation keeps the goal and ingredients as a recipe. Its checklist separates the actual unit, your environment observations and missing registration or method qualification. Open physical preparation to use the existing setup guide. A recipe does not convert simulation coordinates into robot commands.

Copied or changed setups need fresh confirmation of inherited observations. In the ingredient editor, open Confirm setup facts after checking the actual setup. Your confirmation is recorded separately from Roboty's automatic checks.

A task describes the goal and success check. A method describes how to attempt it. A scene describes relevant surroundings and conditions. Changing the robot or scene may leave earlier data useful for inspection while making direct comparison, training or control unsuitable.

## Keep reusable starts

Save a valid saved version as a personal template. Save new version keeps the earlier template inputs available. Existing projects keep the version they used. Preview a selected version before using it. A project template creates related experiments together. Getting started groups templates and guides without running them in sequence.

## This device

Open All experiments to search saved experiments, unfinished drafts, recorded attempts and imported source work in this device's library. The search scope is shown above the results. If simulation preparation is unavailable, a valid changed goal can still be retained with Save revision. Saving a goal does not qualify it for simulation or start an attempt.

## iPhone and iPad

Choose New project, select a starting goal and choose Use template. Cancel creates nothing. New project creates separate work even when another project is open. In a project, New experiment adds the chosen goal to that project. Add from Template Library reuses a personal or imported template there.

Choose Continue for the named retained experiment, or Open beside another experiment. Empty and archived projects offer the applicable creation or restoration action. Project details contains its name, description and tags. The actions button beside each experiment contains Move and Duplicate. Template previews keep the primary action visible. More details contains the source, version and exact inputs.

## Home on Mac

**Recent projects** lists projects by their latest change or saved experiment. Choose **Grid** or **List**; Roboty remembers the layout. Each project shows its experiment count and last change. **Resume experiment** returns to your current draft, saved goal or result. Work without a saved experiment is labeled **Unsaved draft**.

If projects cannot load, choose **Retry** or **All projects**. Previously loaded projects can remain visible for the same workspace. Switching workspaces clears the list until the selected workspace loads. If asked to **Open workspace**, do so before browsing its library.

## On Mac

Choose **Home → Try a simulation** for a Reach draft, or **Projects → New project** to choose a task. In a project, **New experiment** adds work there. Follow [Open and edit on Mac](#open-and-edit-on-mac) to save, preview and run it. Use [Templates on Mac](#templates-on-mac) for saved starting points.

If the workspace is closed, choose Open workspace before viewing projects. A failed library read shows its reason and a retry action. An empty library is shown only after a successful read. Projects shows descriptions, experiment counts and edited dates when available. Select a row to keep your place, then press Return or choose Open. You can also double-click a project.

In a project, choose Open beside the experiment you want. Its task and saved date help distinguish experiments with the same name. Project details contains its name, description and tags. Experiment actions contains Move and Duplicate. The project’s More menu contains pin, archive, duplication and combination controls. Library actions in the toolbar contains Import project and All experiments.

To reuse saved ingredients in the current goal, choose More → Reuse saved setup. Library opens with the saved source selected. Return to experiment brings you back to your unfinished goal. Editing reusable definitions or reviewing variations stays in the main window. Save applies the reviewed change, and Cancel returns without applying it.

Help opens in the main content area. Choose a topic under More details for extra instructions. Back to your task returns to the editor, including after reading a related topic. The sidebar and any active Stop action remain available.

Open All experiments to search saved experiments, unfinished drafts and received experiments by title. Search, filters and your selected record remain when you inspect a result and return. An unchanged retained draft does not need another copy.

If retained drafts fill the available space, inspect a draft you no longer need and choose Move to Trash. Confirm the named retained copy or choose Cancel. This leaves your current draft, saved experiments and results intact. Restore the retained copy with Put Back in Finder’s Trash, then reopen the workspace.

In this guide, a draft is editable work, a saved revision is one retained version of its goal, and an attempt is one execution of a frozen revision. Editing a later draft leaves an earlier attempt unchanged. [The storage reference](/guide/setup/devices#requirements-and-where-work-is-saved) identifies the device that keeps each copy.

## Templates on Mac

1. Choose **New project** or a project’s **New experiment**, then **Use saved setup**.
2. Choose **Preview** beside a starter or saved template. Review its inputs, then **Use template** or **Add experiment**. This does not start a simulation.
3. To save your own template, open a saved experiment and choose **More → Save as template**. Review its source and saved version, then **Save template**. Unsaved edits, personal notes and recorded results are excluded. Cancel creates nothing.
4. Use **Manage templates** in Library actions or More to inspect saved starts and review new versions.

## Open and edit on Mac

1. Open a project, then choose **Open** beside an experiment.
2. Edit the goal in the diagram and Goal inspector. Click the experiment name in the header to rename it. Robot and simulation context remain visible. Position fields use centimetres. Your draft is retained locally on this Mac. Use the fixed toolbar Save action to confirm a saved version. Its status explains unchanged, pending or blocked work.
3. Choose **Preview goal** to check the setup. This does not start a simulation.
4. Choose **Start simulation** when ready. Confirm one attempt at the saved version.
5. Inspect recorded attempts in **History**. Choose **Edit goal** to return to editing.

## Choose where work stays

The steps below are for **iPhone connected to a Mac**. Phone-local work stays separate. Changing storage location does not move a draft.

## When to use it

Use a draft to change a goal. Use a saved experiment to continue an ongoing question or compare attempts. A run is one attempt at a frozen revision.

## Steps

1. Choose New experiment, or choose a saved experiment to continue it. Give the experiment a recognizable name and edit its supported goal.
2. Your editable work is saved locally. Drafts on this device lets you restore earlier local drafts when you switch experiments or create a new one.
3. When ready and connected, choose **Prepare simulation** on iPhone. Then Start simulation asks for explicit confirmation of one attempt at the saved revision. Editing a draft cannot change an attempt already running.
4. Open Experiments and attempts for Recent runs or History. Use Edit goal to return from a workspace result to editing.

## What to expect

Draft edits remain on this phone in the selected computer’s workspace. Saved revisions and runs remain on their owning Mac. Reopening a result shows its executed revision, rather than silently substituting the latest draft.

## If something goes wrong

- Offline, continue editing or reopen a retained local draft. Reconnect to the same Mac for saved records that are not cached and for new attempts.
- If a save or Start response is lost, reconnect and check the original operation. Do not start replacement work while its outcome is uncertain.
- If a new goal was created on the selected Mac but your current draft could not be saved, keep the editor open and resolve the save problem. Choose Retry opening selected saved goal to reopen that same goal without creating another copy.
- If another client changed the experiment, follow the conflict message and review the newer revision. If saved workspace recovery is required, original data is preserved and writes pause. Use Retry saved workspace after resolving the reported problem.

Content ID: experiments
Compiled digest: 516510bd5d2b27a66582d4f508712cf01eaa773613dab4f1dc9f37ef0266debd
Language: en