---
title: "Elements, versions and @handles"
description: "Cast members, sets, props and styles are elements with versions and reference pictures, called in any shot by their @handle."
url: https://www.filmsquare.ai/docs/concepts/elements/
lang: en
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# Elements, versions and @handles

An element is something that must look the same in every shot: a cast member, a set, a prop or a style. Each
element has an `@handle`, reference pictures, and versions. Sign one off once, then call it in any shot with its
handle.

![The Elements screen with cast, sets and props as cards and a filter per kind](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## Kinds of element

| Kind | In the app | Department |
| --- | --- | --- |
| Character | Cast member | [Casting](https://www.filmsquare.ai/docs/departments/casting/), [Wardrobe](https://www.filmsquare.ai/docs/departments/wardrobe/) |
| Location | Set | [Sets](https://www.filmsquare.ai/docs/departments/sets/) |
| Prop | Prop | [Props](https://www.filmsquare.ai/docs/departments/props/) |
| Style | Style | A look: camera, lens, light, grade, film stock. See [Styles](https://www.filmsquare.ai/docs/concepts/styles/) |

A costume is not an element of its own: it is a [look](https://www.filmsquare.ai/docs/departments/wardrobe/) on a cast member, per scene.

## @handles

Every element has a handle, such as `@anna` or `@backlot-street`. Type `@` in a prompt, a shot description or the
composer to bring an element in. Filmsquare then adds the element's reference pictures to the take for you, chosen
for the shot's size and angle.

On the **Elements** screen, **Copy @handle** copies it. **Search elements or @handle** finds one.

## Where elements live

An element belongs to one production, or to the whole workspace ("Every production in this workspace"). A
workspace-wide element can be used in every production; a production's own element only there. In a production you
work on them under **Cast & sets → Cast**, **Locations** and **Props**, and on styles under **Create → Mood**. A
production also has its own **Elements** page, with a button on the **Home** of a new production: it shows that production's elements and the workspace-wide ones it uses (marked **Every
production**), such as the ones its imported takes name. What you add there stays in that production. A change to a
workspace-wide element counts everywhere, and you assign crew only to a production's own elements.

## Making an element

- **From a breakdown:** a script breakdown brings in the cast, sets and props it finds.
- **Add elements:** on the Elements page, drop photos anywhere (or pick several). Each becomes a draft card with a
  kind and a name read from the file name (`chr_ines_v3.png` is the cast member Ines). Check both, then **Add**
  them all at once. Each photo becomes the element's first reference.
- **Describe one:** pick a **Kind** and a **Name** and write a sentence. Filmsquare renders a reference sheet and
  uses the first one.
- **Save as element:** turn a take you like into a cast member, set or prop. The take becomes its first reference.
- **From a tag:** **Create** next to a tag under **Script → Tagging** makes the cast member, set or prop it names.
- **New look:** under **Create → Mood**, make a style from images you select. See
  [The canvas](https://www.filmsquare.ai/docs/working-together/canvas/#looks).
- **New style:** under **Create → Styles**, write a style guide and add reference pictures, or use one from the
  library. See [Styles](https://www.filmsquare.ai/docs/concepts/styles/).

## Versions

Every change to how an element looks is a new version. Versions never change once made, so shots that used one stay
reproducible. The newest version is **Current**; shots use the current version unless a shot is pinned to an
older one.

On the element's page, **New version** copies the current version, with every reference, as the next one. Then add
or change references on it.

![An element's page with its versions, reference pictures and sheets](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> Once a take has been made with a version, that version's references are frozen. To add a reference, make a new
> version. The API answers `409 element_version_frozen` with the way out.

## References and sheets

A reference is a picture of the element with a role: front, three-quarter, profile, back, full body, turnaround,
expression, detail, wide, and a few more. **Add reference** uploads one. The
cross next to a picture of the current version removes it: Filmsquare makes a new version without it, and older
versions keep it.

A **sheet** is a clean view of the element, rendered to use as a reference. Render one from the element's page;
when it is right, **Sign off as reference**: Filmsquare makes a new version with that picture added.

## Versions and sign-off

A new version (v2 and up) of an element is a change of signed-off work. It makes its department stale in every
episode still in work that uses the element:

| Element | Departments that go stale |
| --- | --- |
| Cast member | Casting, Wardrobe, Voices |
| Set | Sets |
| Prop | Props |

A new element (v1) does not: the breakdown that brought it in was already signed off. See
[Sign-off and gates](https://www.filmsquare.ai/docs/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale).

## Archiving

**Archive…** takes an element out of the lists. Shots and takes that used it keep their history. Nothing is
deleted.

## With your own Claude

`get_script` returns the handles a production already has, so a breakdown reuses them. `view_media` shows Claude a
reference picture; `upload_file` adds a picture as a production asset for a reference. Versions, references and
sheets go through `find_actions` and `run_action` (for example `forkElementVersion`, `generateForElement`,
`acceptElementTake`). `removeElementReferences` takes old pictures off an element: a new version without them
becomes current, and earlier versions keep theirs. See [What Claude can do](https://www.filmsquare.ai/docs/claude/tools/).
