DocumentaçãoSubstance 3DSubstance 3D Designer

Referência da API de script

Última atualização: 11 de setembro de 2026

Esta página descreve os principais conceitos da API.

Para obter informações mais detalhadas, consulte a documentação que acompanha o aplicativo que está acessível em Ajuda > Documentação da API Python…. Nesta documentação, faça uma Pesquisa rápida para os nomes de módulos (entre parênteses abaixo) para encontrar facilmente sua definição.

Contexto

O objeto de contexto (Contexto) é o ponto de entrada principal para a API. É criado na primeira vez que o usuário o obtém usando o método ‘getContext()’ do módulo ‘sd’.

Este objeto permite essencialmente recuperar o objeto de aplicativo (SDApplication).

Aplicativo (SDApplication)

O aplicativo (SDApplication) é o objeto que permite o acesso aos principais gerenciadores de API, como:

  • o Gerenciador do Pacote (SDPackageMgr) que gerencia todos os pacotes do aplicativo;
  • o Gerenciador do Módulo (SDModuleMgr) que gerencia todos os módulos do aplicativo;
  • o Gerente de IU (SDUIMgr) que pode criar menus e docks na janela do aplicativo.

Você pode registrar retornos de chamada com o aplicativo que será chamado quando determinados eventos ocorrerem.

Gerenciador de Pacotes (SDPackageMgr)

Este objeto gerencia todos os pacotes do aplicativo. Os pacotes são exibidos no componente ‘Explorer’.

Ele permite:

  • criar um novo pacote;
  • carregar/descarregar um pacote;
  • salvar um pacote;
  • encontre um pacote.

Pacote (SDPackage)

Um pacote (SDPackage) é uma coleção de recursos (SDResource).

O conteúdo de um pacote pode ser armazenado em um arquivo com a extensão .sbs por meio do objeto ‘SDPackageMgr’. Este objeto permite que você recupere recursos específicos.

Para criar um recurso específico, consulte os métodos estáticos de objeto relacionados (por exemplo: ‘SDSBSCompGraph.sNew()’).

Um pacote também contém um dicionário de metadados (SDMetadataDict). Você pode encontrar mais informações sobre metadados aqui.

Recurso (SDResource)

Um recurso (SDResource) é um objeto que pode ser referenciado por outro recurso.

Há vários tipos de recursos:

  • Pastas (SDResourceFolder);
  • Gráficos (SDGraph);
  • Bitmaps (SDResourceBitmap);
  • Imagens SVG (SDResourceSVG);
  • Fontes (SDResourceFont);
  • Cenas (SDResourceScene);
  • Medições BSDF (SDResourceBSDFMeasurement);
  • Perfis Light (SDResourceLightProfile).

Um recurso pode ser criado do método estático ‘sNew()’ em:

  • uma viagem organizada;
  • uma pasta.

Um recurso pode ter várias propriedades (SDProperty).

Gerenciador de interface de usuário (SDUIMgr)

O gerenciador de interface de usuário permite criar elementos de interface de usuário na janela principal do Substance Designer, como menus, docks, e permite registrar retornos de chamada quando ocorrerem eventos relacionados à interface de usuário.

Além disso, o gerenciador de interface do usuário tem acesso ao gráfico ativo atual e à seleção do gráfico ativo.

Gráficos (SDGraph)

Um gráfico (SDGraph) é um objeto que contém:

  • nós (SDNode);
  • objetos de gráfico (SDGraphObjects);
  • propriedades (SDProperty).

Existem 4 tipos diferentes de gráficos:

  • Gráfico de Substance (SDSBSCompGraph)
  • Gráfico de função de Substance (SDSBSFunctionGraph)
  • Gráfico Substance FXMap (SDSBSFxMapGraph)

Um gráfico pode ter um ou vários nós de saída. Os nós de saída representam os resultados do gráfico.

Todos os nós disponíveis para um gráfico podem ser recuperados com o método ‘getNodeDefinitions()’.

Um novo nó pode ser criado com o método ‘newNode()’.

Um novo nó instância pode ser criado a partir de um recurso (SDResource) com o método ‘newInstanceNode()’.

Nó (SDNode)

Um nó (SDNode) representa uma operação realizada em um objeto.

Ele pode ser criado a partir de:

  • uma definição (SDDefinition) (consulte 'SDGraph.newNode()');
  • um recurso (SDResource) (consulte 'SDGraph.newInstanceNode()').

Um nó pode ter várias propriedades.

Há vários tipos de nó:

  • SDSBSCompNode: um nó do Gráfico do Substance (SDSBSCompGraph);
  • SDSBSFunctionNode: um nó do Gráfico de função do Substance (SDSBSFunctionGraph);
  • SDSBSFxMapNode: um nó do gráfico Substance FXMap (SDSBSFxMapGraph);

Objetos de gráfico (SDGraphObjects)

Um objeto de gráfico (SDGraphObject) é um objeto que adiciona informações adicionais ao gráfico, mas que não é levado em consideração durante o processo de avaliação do gráfico.

Há 3 tipos de objetos de gráfico:

  • Fixar (SDGraphObjectPin)
  • Comentário (SDGraphObjectComment)
  • Quadro (SDGraphObjectFrame)

Consulte o método estático ‘sNew()’ nesses objetos para obter mais informações sobre como criá-los.

Propriedades (SDProperty)

Uma propriedade (SDProperty) é um objeto que descreve uma propriedade de outro objeto (um gráfico, um nó, um recurso etc.).

Pertence a uma categoria específica (SDPropertyCategory):

  • Entrada: classifica as propriedades de entrada de um objeto, que geralmente afetam a operação realizada pelo objeto atual;
    • Exemplo: a propriedade ‘color’ de um nó de Cor uniforme em um gráfico de Substance é uma propriedade de entrada;
  • Saída: classifica as propriedades de saída de um objeto. É usado para identificar um resultado de um objeto;
  • Anotação: classifica propriedades que não afetam a operação realizada por um objeto;
    • Exemplo: o ‘rótulo’ de um gráfico é uma propriedade de anotação, pois não afeta o cálculo do gráfico.

Contém os membros a seguir:

  • Id: o identificador da propriedade no contexto desta categoria;
  • Tipos: os tipos suportados pela propriedade atual. Algumas propriedades podem suportar vários tipos: ‘int’, ‘float’, etc.;
    • Ex: as propriedades de entrada de um nó ‘sbs::add’ podem suportar tipos diferentes: 'int’, 'int2’, 'int3’, 'int4’, 'float’, 'float2’, 'float3’, 'float4’, etc.;
  • Categoria: a categoria à qual a propriedade pertence (entrada, saída, anotação);
  • Rótulo: o rótulo da propriedade, usado para exibição somente;
  • Descrição: a descrição da propriedade;
  • DefaultValue: O valor padrão;
  • IsConnectable: indica se uma conexão (SDConnection) pode ser realizada nesta propriedade;
  • isReadyOnly: indica se a propriedade é somente leitura. Se for true, o valor associado a ele não poderá ser modificado;
  • isVariadic: se for true, esta propriedade será representada como várias propriedades no objeto;
  • isPrimary: indica se a propriedade especificada é a propriedade principal que controla algumas outras propriedades. Observação: isto é específico para nós de Substance Composição (SDSBSCompNode)).

Exemplos:

  • Propriedades do nó ‘sbs::input’:
sbs::input
Entrada
Anotação
Saída
$outputsize
rótulo
unique_filter_output (CONNECTABLE)
$format
descrição
$pixelsize
identificador
$pixelratio
userdata
$tiling
grupo
$randomseed
visibleif
bitmapresourcepath
usos
  • Propriedades do nó ‘sbs::blend’:
sbs::blend
Entrada
Anotação
Saída
$outputsize
unique_filter_output (CONNECTABLE)
$format
$pixelsize
$pixelratio
$tiling
$randomseed
source.connector (CONNECTABLE)
destination.connector (CONNECTABLE)
opacity.connector (CONNECTABLE)
opacitymult
blendingmode
colorblending
maskretangle

Tipo (SDType)

Um tipo (SDType) contém informações de um valor tipo, como:

  • Id: o identificador do tipo;

  • Modificador: o modificador de tipo que pode ser um dos valores 'SDTypeModifier’ enum:

    • Automático;
    • Uniforme: o valor é avaliado uma vez por operação;
    • Variável: o valor é avaliado várias vezes por operação (por exemplo, para cada texel).

Vários tipos são definidos, como:

  • enums (SDTypeEnum): descreve um tipo enumeração com todas as suas propriedades;
  • estruturas (SDTypeStruct): descreve um tipo estrutura com todas as suas propriedades;
  • matriz (SDTypeArray): descreve uma matriz.
  • etc.

Consulte Documentação da API Python para ver uma lista completa.

Valores (SDValue)

Um valor (SDValue) é um objeto que encapsula um valor de tipo base.

Por exemplo:

  • um objeto ‘SDValueInt’ encapsula um valor ‘int’;
  • um objeto ‘SDValueFloat4’ encapsula um valor ‘float4’;
  • etc.

O valor do tipo base geralmente pode ser recuperado com o método ‘get()’, mas isso pode depender do tipo de 'SDValue’ que foi retornado.

Conexão (SDConnection)

Uma conexão (SDConnection) representa um link entre duas propriedades diferentes de dois nós diferentes.

Contém:

  • O nó de destino;
  • A propriedade de destino do nó de destino;

Todas as operações de conexão são executadas em um nó:

  • criando uma nova conexão, consulte ‘SDNode.newPropertyConnection()’
  • excluindo uma conexão existente, consulte ‘SDNode.deletePropertyConnection()’
  • recuperando as conexões de uma propriedade, consulte ‘SDNode.getPropertyConnections()’

Módulo (SDModule)

Um módulo é uma coleção de definições e tipos.

Ele permite uma fácil recuperação de todas as informações sobre os nós que podem ser criados, bem como sobre enumerações e estruturas.

Contém:

  • um identificador (Id) exclusivo no contexto do gerenciador de módulo (SDModuleMgr);
  • uma lista de definições (SDDefinition);
  • uma lista de tipos (TipoDT).

Definição (SDDefinition)

Um objeto de definição (SDDefinition) contém informações sobre a definição de um objeto específico com base nas propriedades ('SDNode’ etc.).

Contém:

  • Id: o identificador da definição;
  • Rótulo: o rótulo da definição;
  • Descrição: a descrição da definição;
  • Propriedades: as propriedades de todas as categorias de propriedade disponíveis (SDPropertyCategory).
recommendation-more-help
substance-3d-designer-help-guide