---
title: "Elementos, versões e @nomes"
description: "Personagens, cenários, objetos de cena e estilos são elementos com versões e imagens de referência, chamados em qualquer plano pelo seu @nome."
url: https://www.filmsquare.ai/docs/pt-br/concepts/elements/
lang: pt-BR
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# Elementos, versões e @nomes

Um elemento é algo que precisa ter a mesma cara em todos os planos: um personagem, um cenário, um objeto de cena ou um estilo. Cada
elemento tem um `@handle`, imagens de referência e versões. Aprove um uma vez e chame-o em qualquer plano pelo seu
@nome.

![A tela Elements com elenco, cenários e objetos de cena em cartões e um filtro por tipo](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## Tipos de elemento

| Tipo | No app | Departamento |
| --- | --- | --- |
| Character | Personagem | [Casting](https://www.filmsquare.ai/docs/pt-br/departments/casting/), [Figurino](https://www.filmsquare.ai/docs/pt-br/departments/wardrobe/) |
| Location | Cenário | [Cenários](https://www.filmsquare.ai/docs/pt-br/departments/sets/) |
| Prop | Objeto de cena | [Objetos de cena](https://www.filmsquare.ai/docs/pt-br/departments/props/) |
| Style | Estilo | Um look: câmera, lente, luz, correção de cor, filme. Veja [Estilos](https://www.filmsquare.ai/docs/pt-br/concepts/styles/) |

Um figurino não é um elemento próprio: é um [look](https://www.filmsquare.ai/docs/pt-br/departments/wardrobe/) de um personagem, por cena.

## @nomes

Todo elemento tem um @nome, como `@anna` ou `@backlot-street`. Digite `@` em um prompt, na descrição de um plano ou no
compositor para trazer um elemento. O Filmsquare então acrescenta ao take as imagens de referência do elemento, escolhidas
pelo enquadramento e pelo ângulo do plano.

Na tela **Elements**, **Copy @handle** (copiar @nome) copia o nome. **Search elements or @handle** (buscar elementos ou @nome) acha um.

## Onde os elementos ficam

Um elemento pertence a uma produção ou ao espaço de trabalho inteiro ("Every production in this workspace"). Um
elemento do espaço de trabalho pode ser usado em todas as produções; o elemento próprio de uma produção, só nela. Em uma produção você
trabalha neles em **Cast & sets → Cast**, **Locations** e **Props**, e nos estilos em **Create → Mood**. Uma
produção também tem a sua própria página **Elements**, com um botão na **Home** de uma produção nova: ela mostra os elementos da produção e os do espaço de trabalho que ela usa (marcados **Every
production**), como os que os seus takes importados citam. O que você acrescenta ali fica naquela produção. Uma mudança em um
elemento do espaço de trabalho vale em todo lugar, e você escala a equipe só para os elementos próprios de uma produção.

## Como fazer um elemento

- **A partir de uma decupagem:** a decupagem de um roteiro traz o elenco, os cenários e os objetos de cena que encontra.
- **Add elements** (adicionar elementos): na página Elements, solte fotos em qualquer lugar (ou escolha várias). Cada uma vira um cartão de rascunho com
  um tipo e um nome lido do nome do arquivo (`chr_ines_v3.png` é a personagem Ines). Confira os dois e use **Add**
  para adicionar todos de uma vez. Cada foto vira a primeira referência do elemento.
- **Descreva um:** escolha um **Kind** (tipo) e um **Name** (nome) e escreva uma frase. O Filmsquare renderiza uma ficha de referência e
  usa a primeira.
- **Save as element** (salvar como elemento): transforme um take de que você gostou em personagem, cenário ou objeto de cena. O take vira a sua primeira referência.
- **A partir de uma marcação:** **Create** (criar) ao lado de uma marcação em **Script → Tagging** faz o personagem, cenário ou objeto de cena que ela cita.
- **New look** (novo look): em **Create → Mood**, faça um estilo a partir de imagens que você seleciona. Veja
  [O canvas](https://www.filmsquare.ai/docs/pt-br/working-together/canvas/#looks).
- **New style** (novo estilo): em **Create → Styles**, escreva um guia de estilo e acrescente imagens de referência, ou use um da
  biblioteca. Veja [Estilos](https://www.filmsquare.ai/docs/pt-br/concepts/styles/).

## Versões

Toda mudança na aparência de um elemento é uma nova versão. As versões nunca mudam depois de feitas, então os planos que usaram uma continuam
reproduzíveis. A versão mais nova é a **Current** (atual); os planos usam a versão atual, a menos que um plano esteja fixado em uma
mais antiga.

Na página do elemento, **New version** (nova versão) copia a versão atual, com todas as referências, como a seguinte. Depois acrescente
ou mude referências nela.

![A página de um elemento com as suas versões, imagens de referência e fichas](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> Depois que um take é feito com uma versão, as referências dessa versão ficam congeladas. Para acrescentar uma referência, faça uma nova
> versão. A API responde `409 element_version_frozen` com o caminho de saída.

## Referências e fichas

Uma referência é uma imagem do elemento com uma função: frente, três quartos, perfil, costas, corpo inteiro, turnaround,
expressão, detalhe, plano aberto e mais alguns. **Add reference** (adicionar referência) envia uma. A
cruz ao lado de uma imagem da versão atual a remove: o Filmsquare faz uma nova versão sem ela, e as versões
mais antigas a mantêm.

Uma **ficha** é uma visão limpa do elemento, renderizada para servir de referência. Renderize uma na página do elemento;
quando estiver certa, use **Sign off as reference** (aprovar como referência): o Filmsquare faz uma nova versão com essa imagem acrescentada.

## Versões e aprovação

Uma nova versão (v2 em diante) de um elemento é uma mudança em um trabalho aprovado. Ela deixa o seu departamento desatualizado em todo
episódio ainda em andamento que usa o elemento:

| Elemento | Departamentos que ficam desatualizados |
| --- | --- |
| Personagem | Casting, Figurino, Vozes |
| Cenário | Cenários |
| Objeto de cena | Objetos de cena |

Um elemento novo (v1) não faz isso: a decupagem que o trouxe já estava aprovada. Veja
[Aprovação e liberação](https://www.filmsquare.ai/docs/pt-br/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale).

## Arquivar

**Archive…** (arquivar) tira um elemento das listas. Os planos e takes que o usaram mantêm o histórico. Nada é
apagado.

## Com o seu próprio Claude

`get_script` devolve os @nomes que uma produção já tem, para a decupagem reaproveitá-los. `view_media` mostra ao Claude uma
imagem de referência; `upload_file` acrescenta uma imagem como material da produção para uma referência. Versões, referências e
fichas passam por `find_actions` e `run_action` (por exemplo `forkElementVersion`, `generateForElement`,
`acceptElementTake`). `removeElementReferences` tira imagens antigas de um elemento: uma nova versão sem elas
passa a ser a atual, e as versões anteriores mantêm as suas. Veja [O que o Claude faz](https://www.filmsquare.ai/docs/pt-br/claude/tools/).
