Modelos Procedurais

ProceduralModels são um tipo de Model dirigido por parâmetros que permitem construir e gerar objetos 3D usando código. Em vez de editar manualmente o conteúdo de um modelo, você define sua estrutura através de um módulo gerador e um conjunto de atributos. Quando esses atributos mudam, ou quando o modelo é redimensionado, o gerador é executado automaticamente para atualizar o modelo.

Modelos procedurais facilitam:

• Ajustar modelos de forma não destrutiva, alterando parâmetros em vez de reconstruí-los. Por exemplo, mudar o valor de StepSize em uma escada espiral regenera automaticamente a escada com o número atualizado de degraus.
• Integrar automaticamente com sistemas existentes do Studio, como desfazer/refazer, Team Create e ferramentas de arrastar, implementando uma única função OnGenerate.
• Manter o desempenho alto, com modelos se comportando como objetos padrão até que seus parâmetros mudem.
• Gerar conteúdo tanto em tempo de edição quanto em tempo de execução, usando o mesmo sistema no Studio e no jogo.
• Compartilhar modelos parametrizados no Creator Store, tornando os ativos mais flexíveis e personalizáveis.

Inserir modelos procedurais

Você pode adicionar modelos procedurais ao seu jogo das seguintes maneiras:

• Inserir manualmente um objeto ProceduralModel no Workspace. Esta opção inclui um gerador de template ModuleScript para ajudá-lo a começar.

  

• Gerar um modelo procedural usando Assistant ou o servidor MCP do Roblox Studio.

• Inserir um modelo procedural da Creator Store para usar ou personalizar um modelo existente.

Para personalizar como os modelos procedurais são gerados, você pode definir seus próprios módulos geradores.

Função OnGenerate

A função OnGenerate está no cerne de cada ProceduralModel na forma de OnGenerate(params, targetContainer).

Esta função definida pelo desenvolvedor é responsável por gerar o conteúdo do modelo com base nos parâmetros fornecidos e gravar os resultados no container dado.

OnGenerate tem duas responsabilidades principais:

• Processar os parâmetros de entrada para determinar a estrutura do modelo
• Escrever os resultados gerados de acordo com essa estrutura no targetContainer fornecido.

As seções a seguir descrevem:

• Quando e como o mecanismo invoca OnGenerate
• Como o mecanismo processa o conteúdo escrito no targetContainer

Módulos geradores

A função OnGenerate é definida dentro de um ModuleScript conhecido como módulo gerador. O ProceduralModel identifica qual módulo gerador usar através da sua propriedade Generator.

Módulos geradores são módulos padrão de Luau, mas são requeridos diretamente pelo mecanismo como parte do processo de geração. Eles seguem uma estrutura definida e retornam uma tabela com campos padronizados.

Estrutura do módulo gerador
local MyGenerator = {}

MyGenerator.Attributes = {
    DoSomething = true,
    AmountOfSomething = 137,
}

type Params = {
    Size: Vector3,
    Attributes: typeof(MyGenerator.Attributes),
    Pause: (self: any) -> (),
}
function MyGenerator.OnGenerate(params: Params, targetContainer: GeneratedFolder)
    
end

return MyGenerator

Os campos padronizados incluem:

• Attributes: Um mapa que define os nomes dos parâmetros e seus valores padrão.
• OnGenerate: A função que recebe uma tabela params e um targetContainer.

A tabela params dentro de OnGenerate inclui:

• Attributes: Uma tabela que contém os atributos definidos pelo módulo ou todos os atributos do modelo se nenhum for especificado.
• Size: Um parâmetro que reflete as dimensões do modelo em uma escala de um.
• Pause: Um método que permite que a geração pause de forma eficiente durante tarefas de geração complexas.

A função OnGenerate deve gerar conteúdo em torno da origem no targetContainer. Ela nunca deve modificar diretamente a hierarquia principal do DataModel.

Parâmetros

Parâmetros são as entradas que controlam a geração. Estes incluem a propriedade Size embutida do ProceduralModel, bem como atributos personalizados especificados no módulo gerador. Esses parâmetros explícitos são passados diretamente para OnGenerate. Parâmetros implícitos, como o código-fonte do módulo ou o status de sandboxing, também disparam regeneração quando alterados, mas não são passados para OnGenerate.

O conjunto completo de parâmetros inclui:

• Explícitos:

  • Size: Define a região em torno da origem onde o conteúdo é gerado.
  • Attributes: Um mapa contendo os valores atuais dos atributos de entrada.
• Implícitos:

  • Gerador: O módulo que fornece a lógica de geração.
  • Código fonte: Mudanças no código Luau do módulo gerador.
  • Sandboxing: Mudanças no status de sandboxing do módulo gerador.

Comportamento de regeneração

Para manter o desempenho e simplificar as interações da API, OnGenerate não é chamado imediatamente quando os parâmetros mudam. Em vez disso, o ProceduralModel é marcado como dirty, indicando que a regeneração está pendente. Essa regeneração pendente normalmente ocorre mais tarde no mesmo quadro.

Se a regeneração falhar, o estado dirty é limpo até que outra mudança de parâmetro ocorra. Se um lugar for salvo enquanto o modelo estiver dirty, o estado persiste e o modelo é adicionado à fila de geração na próxima vez que o jogo carregar.

Processo de execução

Quando houver tempo de processamento disponível, o mecanismo regenera modelos dirty executando os seguintes passos:

1. Requer o módulo gerador, pausando se necessário.
2. Inicia uma nova thread para o processo de geração.
3. Constrói a tabela de parâmetros, normalizando o Size pela escala atual do modelo.
4. Aplica valores padrão dos atributos a quaisquer atributos ausentes.
5. Inicializa um GeneratedFolder temporário como o targetContainer.
6. Invoca OnGenerate.
7. Após OnGenerate retornar:

   • Se bem-sucedido, migra os resultados no targetContainer para o ProceduralModel.
   • Se a geração falhar, usa um espaço reservado de falha em vez disso.

Se os parâmetros mudarem novamente enquanto uma thread de geração estiver pausada, a geração pendente é cancelada e reiniciada com os parâmetros atualizados.

Resultados da geração

Colocar os resultados gerados no modelo envolve os seguintes passos:

1. Termina quaisquer threads filhas vazadas durante a geração.
2. Posiciona os resultados usando PivotTo.
3. Se a Scale do modelo não for 1, usa ScaleTo para desfazer a normalização do tamanho.
4. Torna os resultados filhos da GeneratedFolder do modelo.
5. Se o módulo gerador for sandboxed, garante que os ModuleScripts no resultado não excedam as capacidades do módulo gerador.
6. Preenche quaisquer atributos ausentes no modelo com seus valores padrão.
7. Limpa o estado dirty do modelo.

Detalhes da geração

Além do fluxo de geração principal, os seguintes detalhes descrevem comportamentos e considerações que afetam como a geração do ProceduralModel funciona.

Dimensionamento

Devido à normalização da escala aplicada durante a geração, ProceduralModel suporta múltiplos fluxos de trabalho de dimensionamento:

• Alterar a propriedade Size regenera o modelo com novo conteúdo.
• Alterar a Scale escala uniformemente os resultados existentes usando ScaleTo.

Timeouts

Como uma medida de segurança, um módulo gerador que realiza trabalho demais sem pausar é terminado. Se a geração atingir um erro "Script Timeout", adicione chamadas adicionais para parameters:Pause() para permitir que o mecanismo adie o trabalho restante para um quadro posterior.

Chamar parameters:Pause() é muito barato e normalmente retorna imediatamente durante a execução normal do gerador, então pode ser chamado liberalmente no início de loops sem impactar o desempenho.

Histórico de desfazer

Resultados gerados são agrupados com a mudança de parâmetro que os disparou usando substituições de ponto de verificação de desfazer. Se múltiplas mudanças de parâmetro ocorrerem em um único quadro, os resultados são associados ao ponto de verificação mais recente.

Sandboxing

ProceduralModel suporta sandboxing. Todos os modelos procedurais de terceiros que você insere da Creator Store são sandboxed por padrão para ajudar a prevenir mudanças indesejadas no seu jogo.

O código de geração é executado no contexto do módulo gerador e usa o status de sandboxing desse módulo. Essas configurações não são visíveis por padrão. Para visualizá-las ou modificá-las, defina Workspace.SandboxedInstanceMode = Experimental. Isso expõe as propriedades Sandboxed e Capabilities no ModuleScript.

Um módulo gerador sandboxed normalmente requer pelo menos as seguintes capacidades:

• RunServerScript (para executar o módulo)
• CreateInstances
• Basic

O sandboxing para o ProceduralModel e seu módulo gerador são independentes um do outro. Quando aplicado ao módulo gerador, o sandboxing não afeta scripts normais em tempo de execução dentro do ProceduralModel. Isso permite que você mantenha a geração em tempo de edição rigidamente restrita sem impactar o comportamento no jogo.

Aninhamento

ProceduralModels podem gerar outros ProceduralModels. Quando isso acontece, o mecanismo processa a hierarquia de cima para baixo dentro do mesmo passo de geração sempre que possível, com modelos mais profundamente aninhados sendo gerados por último.

Limitações

• A geração não é suportada dentro de instâncias de Actor.
• Modelos não podem ser convertidos em pacotes.
• Juntas criadas ao usar arrastadores com Superfícies de Junta habilitadas não são preservadas em regenerações de ProceduralModel.