Filmsquare HelpDocs

2.0 How a film is organised2.6 Elements, versions and @handles

Elements, versions and @handles

Cast members, sets, props and styles are elements with versions and reference pictures, called in any shot by their @handle.

Updated 4 min read.md

On this page
  1. Kinds of element
  2. @handles
  3. Where elements live
  4. Making an element
  5. Versions
  6. References and sheets
  7. Versions and sign-off
  8. Archiving
  9. With your own Claude

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 (open the full screenshot)
Fig. 1 The Elements screen with cast, sets and props as cards and a filter per kind

Kinds of element #

KindIn the appDepartment
CharacterCast memberCasting, Wardrobe
LocationSetSets
PropPropProps
StyleStyleA look: camera, lens, light, grade, film stock. See Styles

A costume is not an element of its own: it is a look 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.
  • New style: under Create → Styles, write a style guide and add reference pictures, or use one from the library. See 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 (open the full screenshot)
Fig. 2 An element's page with its versions, reference pictures and sheets

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:

ElementDepartments that go stale
Cast memberCasting, Wardrobe, Voices
SetSets
PropProps

A new element (v1) does not: the breakdown that brought it in was already signed off. See Sign-off and gates.

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.

With Claude

MCP

Your own Claude does this over MCP, in your name and with your role:

  • get_script

    Reads the latest script revision of an episode, with the @handles that already exist.

    Ask: Read the script of episode 2 and tell me which characters have no @handle yet.

  • view_media

    Looks at a still, keyframe or take; video comes back as its poster plus a download link.

    Ask: Show me the picked still of shot 3 and tell me if it matches its references.

  • upload_file

    Adds a file you have as a new take on a shot or scene, or as a production asset (10 MB at most).

    Ask: Upload this reference photo to the assets of the production.

  • find_actions

    Searches everything the API can do and returns the matching actions with their inputs.

    Ask: Find the action that changes a step's sign-off rule.

  • run_action

    Runs one action found with find_actions, as you, with your role and rights.

    Ask: Pick the second take of shot 5 on episode 2.

Connect Claude 5.1

This page as Markdown: /docs/concepts/elements.md