Modelli procedurali

ProceduralModels sono un tipo di Model guidato da parametri che ti consente di costruire e generare oggetti 3D utilizzando codice. Invece di modificare manualmente il contenuto di un modello, definisci la sua struttura attraverso un modulo generatore e un insieme di attributi. Quando quegli attributi cambiano, o quando il modello viene ridimensionato, il generatore viene eseguito automaticamente per aggiornare il modello.

I modelli procedurali rendono più facile:

• Modificare i modelli in modo non distruttivo cambiando i parametri anziché ricostruirli. Ad esempio, cambiare il valore di StepSize su una scala a chiocciola rigenera automaticamente la scala con il numero aggiornato di gradini.
• Integrare automaticamente con i sistemi esistenti di Studio come annulla/rifai, Team Create e strumenti di trascinamento implementando una singola funzione OnGenerate.
• Mantenere alte le prestazioni, con modelli che si comportano come oggetti standard fino a quando i loro parametri non cambiano.
• Generare contenuti sia in fase di modifica che in fase di esecuzione, utilizzando lo stesso sistema in Studio e nel gioco.
• Condividere modelli parametrizzati nel Creator Store, rendendo gli asset più flessibili e personalizzabili.

Inserire modelli procedurali

Puoi aggiungere modelli procedurali al tuo gioco nei seguenti modi:

• Inserisci manualmente un oggetto ProceduralModel nello Workspace. Questa opzione include un generatore di modelli ModuleScript per aiutarti a iniziare.

  

• Genera un modello procedurale utilizzando Assistant o il server MCP di Roblox Studio.

• Inserisci un modello procedurale dal Creator Store per utilizzare o personalizzare un modello esistente.

Per personalizzare come vengono generati i modelli procedurali, puoi definire i tuoi moduli generatore.

Funzione OnGenerate

La funzione OnGenerate è al centro di ogni ProceduralModel nella forma di OnGenerate(params, targetContainer).

Questa funzione definita dallo sviluppatore è responsabile della generazione del contenuto del modello basato sui parametri forniti e della scrittura dei risultati nel contenitore dato.

OnGenerate ha due principali responsabilità:

• Elaborare i parametri di input per determinare la struttura del modello
• Scrivere i risultati generati in base a quella struttura nel targetContainer fornito

Le seguenti sezioni descrivono:

• Quando e come il motore invoca OnGenerate
• Come il motore elabora i contenuti scritti nel targetContainer

Moduli generatore

La funzione OnGenerate è definita all'interno di un ModuleScript noto come modulo generatore. Il ProceduralModel identifica quale modulo generatore utilizzare tramite la sua proprietà Generator.

I moduli generatore sono moduli standard Luau, ma sono richiesti direttamente dal motore come parte del processo di generazione. Seguono una struttura definita e restituiscono una tabella con campi standardizzati.

Struttura del modulo generatore
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

I campi standardizzati includono:

• Attributes: Una mappa che definisce i nomi dei parametri e i loro valori predefiniti.
• OnGenerate: La funzione che riceve una tabella params e un targetContainer.

La tabella params all'interno di OnGenerate include:

• Attributes: Una tabella che contiene gli attributi definiti dal modulo o tutti gli attributi del modello se nessuno è specificato.
• Size: Un parametro che riflette le dimensioni del modello su una scala di uno.
• Pause: Un metodo che consente alla generazione di cedere in modo efficiente durante compiti di generazione complessi.

La funzione OnGenerate dovrebbe generare contenuti attorno all'origine nel targetContainer. Non dovrebbe mai modificare direttamente la gerarchia principale di DataModel.

Parametri

I parametri sono gli input che controllano la generazione. Questi includono la proprietà incorporata Size di ProceduralModel, così come gli attributi personalizzati specificati nel modulo generatore. Questi parametri espliciti vengono passati direttamente a OnGenerate. I parametri impliciti, come il codice sorgente del modulo o lo stato di sandboxing, attivano anche la rigenerazione quando cambiano ma non vengono passati a OnGenerate.

L'insieme completo di parametri include:

• Espliciti:

  • Size: Definisce la regione attorno all'origine in cui vengono generati i contenuti.
  • Attributes: Una mappa contenente i valori degli attributi di input correnti.
• Impliciti:

  • Generatore: Il modulo che fornisce la logica di generazione.
  • Codice sorgente: Modifiche al codice Luau del modulo generatore.
  • Sandboxing: Modifiche allo stato di sandboxing del modulo generatore.

Comportamento di rigenerazione

Per mantenere le prestazioni e semplificare le interazioni API, OnGenerate non viene chiamata immediatamente quando i parametri cambiano. Invece, il ProceduralModel viene contrassegnato come sporco, indicando che la rigenerazione è in sospeso. Questa rigenerazione in sospeso avviene solitamente più tardi nello stesso frame.

Se la rigenerazione fallisce, lo stato sporco viene cancellato fino a quando non si verifica un'altra modifica di parametro. Se un luogo viene salvato mentre il modello è sporco, lo stato persiste e il modello viene aggiunto alla coda di generazione la prossima volta che il gioco viene caricato.

Processo di esecuzione

Quando si è disponibile del tempo di elaborazione, il motore rigenera i modelli sporchi eseguendo i seguenti passaggi:

1. Richiede il modulo generatore, cedendo se necessario.
2. Avvia un nuovo thread per il processo di generazione.
3. Costruisce la tabella dei parametri, normalizzando il Size in base alla scala attuale del modello.
4. Applica i valori predefiniti degli attributi a qualsiasi attributo mancante.
5. Inizializza una GeneratedFolder temporanea come targetContainer.
6. Invoca OnGenerate.
7. Dopo che OnGenerate ritorna:

   • Se ha successo, migra i risultati nel targetContainer al ProceduralModel.
   • Se la generazione fallisce, utilizza un segnaposto di fallimento invece.

Se i parametri cambiano di nuovo mentre un thread di generazione è in pausa, la generazione pendente viene annullata e riavviata con i parametri aggiornati.

Risultati della generazione

Posizionare i risultati generati nel modello coinvolge i seguenti passaggi:

1. Termina eventuali thread secondari perduti durante la generazione.
2. Posiziona i risultati utilizzando PivotTo.
3. Se la Scale del modello non è 1, utilizza ScaleTo per annullare la normalizzazione delle dimensioni.
4. Genitore i risultati alla GeneratedFolder del modello.
5. Se il modulo generatore è sandoxato, si assicura che i ModuleScripts nel risultato non superino le capacità del modulo generatore.
6. Popola eventuali attributi mancanti nel modello con i loro valori predefiniti.
7. Cancella lo stato sporco del modello.

Dettagli della generazione

Oltre al flusso di generazione principale, i seguenti dettagli descrivono comportamenti e considerazioni che influenzano come funziona la generazione di ProceduralModel.

Dimensionamento

A causa della normalizzazione della scala applicata durante la generazione, ProceduralModel supporta più flussi di lavoro di dimensionamento:

• Cambiare la proprietà Size rigenera il modello con nuovi contenuti.
• Cambiare la Scale scala uniformemente i risultati esistenti usando ScaleTo.

Timeout

Come fail-safe, un modulo generatore che esegue troppi lavori senza cedere viene terminato. Se la generazione genera un errore "Timeout dello script", aggiungi chiamate aggiuntive a parameters:Pause() per consentire al motore di deferire il lavoro rimanente a un frame successivo.

Chiamare parameters:Pause() è molto economico e di solito restituisce immediatamente durante l'esecuzione normale del generatore, quindi può essere chiamato liberamente all'inizio dei loop senza influire sulle prestazioni.

Cronologia di annullamento

I risultati generati sono raggruppati con la modifica di parametro che li ha attivati utilizzando sovrascritture del waypoint di annullamento. Se più modifiche di parametri avvengono in un singolo frame, i risultati sono associati al waypoint più recente.

Sandboxing

ProceduralModel supporta il sandboxing. Tutti i modelli procedurali di terze parti che inserisci dal Creator Store sono sandoxati per impostazione predefinita per aiutare a prevenire modifiche indesiderate al tuo gioco.

Il codice di generazione viene eseguito nel contesto del modulo generatore e utilizza lo stato di sandboxing di quel modulo. Queste impostazioni non sono visibili per impostazione predefinita. Per visualizzarle o modificarle, imposta Workspace.SandboxedInstanceMode = Experimental. Questo espone le proprietà Sandboxed e Capabilities sul ModuleScript.

Un modulo generatore sandboxato richiede tipicamente almeno le seguenti capacità:

• RunServerScript (per eseguire il modulo)
• CreateInstances
• Basic

Il sandboxing per il ProceduralModel e il suo modulo generatore sono indipendenti l'uno dall'altro. Quando applicato al modulo generatore, il sandboxing non influisce sugli script di runtime normali all'interno del ProceduralModel. Questo ti consente di mantenere la generazione in fase di modifica strettamente limitata senza influire sul comportamento in gioco.

Nidificazione

I ProceduralModels possono generare altri ProceduralModels. Quando ciò accade, il motore elabora la gerarchia dall'alto verso il basso all'interno della stessa fase di generazione quando possibile, con modelli più profondamente annidati generati per ultimi.

Limitazioni

• La generazione non è supportata all'interno delle istanze Actor.
• I modelli non possono essere convertiti in pacchetti.
• Le giunzioni create quando si utilizzano i dragger con Joint Surfaces abilitati non vengono preservate attraverso le rigenerazioni di ProceduralModel.