Modelos procedimentales

ProceduralModels son un tipo de Model impulsado por parámetros que te permiten construir y generar objetos 3D utilizando código. En lugar de editar manualmente el contenido de un modelo, defines su estructura a través de un módulo generador y un conjunto de atributos. Cuando esos atributos cambian, o cuando se redimensiona el modelo, el generador se ejecuta automáticamente para actualizar el modelo.

Los modelos procedimentales facilitan:

• Ajustar modelos de forma no destructiva cambiando parámetros en lugar de reconstruirlos. Por ejemplo, cambiar el valor de StepSize en una escalera en espiral regenera automáticamente la escalera con el número actualizado de escalones.
• Integrarse automáticamente con los sistemas existentes de Studio como deshacer/rehacer, Team Create, y herramientas de arrastre al implementar una única función OnGenerate.
• Mantener un alto rendimiento, con modelos que se comportan como objetos estándar hasta que cambian sus parámetros.
• Generar contenido tanto en tiempo de edición como en tiempo de ejecución, utilizando el mismo sistema en Studio y en el juego.
• Compartir modelos parametrizados en la Creator Store, haciendo los activos más flexibles y personalizables.

Insertar modelos procedimentales

Puedes añadir modelos procedimentales a tu juego de las siguientes maneras:

• Insertar manualmente un objeto ProceduralModel en el Workspace. Esta opción incluye un generador de plantillas ModuleScript para ayudarte a comenzar.

  

• Generar un modelo procedimental utilizando Assistant o el servidor MCP de Roblox Studio.

• Insertar un modelo procedimental de la Creator Store para usar o personalizar un modelo existente.

Para personalizar cómo se generan los modelos procedimentales, puedes definir tus propios módulos generadores.

Función OnGenerate

La función OnGenerate es el núcleo de cada ProceduralModel en la forma de OnGenerate(params, targetContainer).

Esta función definida por el desarrollador es responsable de generar el contenido del modelo basado en los parámetros proporcionados y escribir los resultados en el contenedor dado.

OnGenerate tiene dos responsabilidades principales:

• Procesar los parámetros de entrada para determinar la estructura del modelo.
• Escribir los resultados generados de acuerdo con esa estructura en el targetContainer proporcionado.

Las siguientes secciones describen:

• Cuándo y cómo el motor invoca OnGenerate.
• Cómo el motor procesa el contenido escrito en el targetContainer.

Módulos generadores

La función OnGenerate se define dentro de un ModuleScript conocido como un módulo generador. El ProceduralModel identifica qué módulo generador utilizar a través de su propiedad Generator.

Los módulos generadores son módulos estándar de Luau, pero son requeridos directamente por el motor como parte del proceso de generación. Siguen una estructura definida y devuelven una tabla con campos estandarizados.

Estructura del módulo generador
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

Los campos estandarizados incluyen:

• Attributes: Un mapa que define los nombres de los parámetros y sus valores predeterminados.
• OnGenerate: La función que recibe una tabla de params y un targetContainer.

La tabla de params dentro de OnGenerate incluye:

• Attributes: Una tabla que contiene ya sea los atributos definidos por el módulo o todos los atributos del modelo si no se especifican.
• Size: Un parámetro que refleja las dimensiones del modelo a una escala de uno.
• Pause: Un método que permite que la generación ceda eficientemente durante tareas de generación complejas.

La función OnGenerate debería generar contenido alrededor del origen en el targetContainer. Nunca debería modificar directamente la jerarquía principal del DataModel.

Parámetros

Parámetros son las entradas que controlan la generación. Estos incluyen la propiedad Size incorporada de ProceduralModel, así como atributos personalizados especificados en el módulo generador. Estos parámetros explícitos se pasan directamente a OnGenerate. Los parámetros implícitos, como el código fuente del módulo o el estado de sandboxing, también desencadenan la regeneración cuando se cambian, pero no se pasan a OnGenerate.

El conjunto completo de parámetros incluye:

• Explícitos:

  • Size: Define la región alrededor del origen donde se genera contenido.
  • Attributes: Un mapa que contiene los valores actuales de los atributos de entrada.
• Implícitos:

  • Generador: El módulo que suministra la lógica de generación.
  • Código fuente: Cambios en el código Luau del módulo generador.
  • Sandboxing: Cambios en el estado de sandboxing del módulo generador.

Comportamiento de regeneración

Para mantener el rendimiento y simplificar las interacciones de API, OnGenerate no se llama inmediatamente cuando cambian los parámetros. En cambio, el ProceduralModel se marca como sucio, lo que indica que la regeneración está pendiente. Esta regeneración pendiente generalmente ocurre más tarde en el mismo fotograma.

Si la regeneración falla, el estado sucio se borra hasta que ocurre otro cambio de parámetro. Si se guarda un lugar mientras el modelo está sucio, el estado persiste y el modelo se agrega a la cola de generación la próxima vez que se carga el juego.

Proceso de ejecución

Al procesar tiempo disponible, el motor regenera modelos sucios ejecutando los siguientes pasos:

1. Requiere el módulo generador, cediendo si es necesario.
2. Inicia un nuevo hilo para el proceso de generación.
3. Construye la tabla de parámetros, normalizando el Size según la escala actual del modelo.
4. Aplica valores de atributo predeterminados a cualquier atributo que falte.
5. Inicializa una GeneratedFolder temporal como el targetContainer.
6. Invoca OnGenerate.
7. Después de que OnGenerate devuelve:

   • Si tiene éxito, migra los resultados en el targetContainer al ProceduralModel.
   • Si la generación falla, usa un marcador de posición de falla en su lugar.

Si los parámetros cambian nuevamente mientras se cede un hilo de generación, la generación pendiente se cancela y se reinicia con los parámetros actualizados.

Resultados de la generación

Colocar los resultados generados en el modelo implica los siguientes pasos:

1. Termina cualquier hilo hijo que se fugó durante la generación.
2. Posiciona los resultados usando PivotTo.
3. Si la Scale del modelo no es 1, utiliza ScaleTo para deshacer la normalización del tamaño.
4. Padres los resultados a la GeneratedFolder del modelo.
5. Si el módulo generador está en sandbox, asegura que los ModuleScripts en el resultado no superen las capacidades del módulo generador.
6. Completa cualquier atributo que falte en el modelo con sus valores predeterminados.
7. Borra el estado sucio del modelo.

Detalles de generación

Además del flujo central de generación, los siguientes detalles describen comportamientos y consideraciones que afectan cómo funciona la generación de ProceduralModel.

Tamaños

Debido a la normalización de escala aplicada durante la generación, ProceduralModel soporta múltiples flujos de trabajo de tamaño:

• Cambiar la propiedad Size regenera el modelo con nuevo contenido.
• Cambiar la Scale escala uniformemente los resultados existentes utilizando ScaleTo.

Tiempos de espera

Como medida de seguridad, un módulo generador que realiza demasiada trabajo sin ceder es terminado. Si la generación alcanza un error de "Timeout de Script", agrega llamadas adicionales a parameters:Pause() para permitir que el motor difiera el trabajo restante a un fotograma posterior.

Llamar a parameters:Pause() es muy económico y típicamente regresa inmediatamente durante la ejecución normal del generador, por lo que se puede llamar liberamente al inicio de bucles sin impactar el rendimiento.

Historial de deshacer

Los resultados generados se agrupan con el cambio de parámetro que los desencadenó utilizando sobrescrituras de puntos de control de deshacer. Si múltiples cambios de parámetros ocurren en un solo fotograma, los resultados se asocian con el punto de control más reciente.

Sandboxing

ProceduralModel soporta sandboxing. Todos los modelos procedimentales de terceros que insertes desde la Creator Store son sandboxed por defecto para ayudar a prevenir cambios no intencionados en tu juego.

El código de generación se ejecuta en el contexto del módulo generador y usa el estado de sandboxing de ese módulo. Estos ajustes no son visibles por defecto. Para ver o modificar, establece Workspace.SandboxedInstanceMode = Experimental. Esto expone las propiedades Sandboxed y Capabilities en el ModuleScript.

Un módulo generador en sandbox típicamente requiere al menos las siguientes capacidades:

• RunServerScript (para ejecutar el módulo)
• CreateInstances
• Basic

El sandboxing para el ProceduralModel y su módulo generador son independientes entre sí. Cuando se aplica al módulo generador, el sandboxing no afecta los scripts de tiempo de ejecución normales dentro del ProceduralModel. Esto te permite mantener la generación en tiempo de edición estrictamente restringida sin impactar el comportamiento en el juego.

Anidamiento

ProceduralModels pueden generar otros ProceduralModels. Cuando esto sucede, el motor procesa la jerarquía de arriba hacia abajo dentro del mismo paso de generación cuando es posible, generando los modelos más profundamente anidados al final.

Limitaciones

• La generación no es compatible dentro de instancias Actor.
• Los modelos no pueden convertirse en paquetes.
• Las uniones creadas al usar arrastradores con Superficies de Unión habilitadas no se conservan a través de regeneraciones de ProceduralModel.