절차적 모델 | 설명서 - Roblox 크리에이터 허브

ProceduralModels는 코드 사용을 통해 3D 개체를 구축하고 생성하는 매개변수 기반 Model의 일종입니다. 모델의 내용을 수동으로 편집하는 대신, 생성기 모듈과 일련의 속성을 통해 구조를 정의합니다. 이러한 속성이 변경되거나 모델의 크기가 조정될 때마다 생성기가 자동으로 실행되어 모델을 업데이트합니다.

절차적 모델을 사용하면 다음과 같은 작업이 수월해집니다:

모델을 재구성하는 대신 매개변수를 변경하여 비파괴적으로 모델을 조정할 수 있습니다. 예를 들어, 나선형 계단의 StepSize 값을 변경하면 자동으로 업데이트된 단계를 가진 계단이 재생성됩니다.
단일 OnGenerate 함수를 구현하여 기존 스튜디오 시스템(예: 실행 취소/다시 실행, 팀 생성, 드래거 도구)과 자동 통합됩니다.
모델의 매개변수가 변경될 때까지 일반 객체처럼 동작하여 높은 성능을 유지합니다.
스튜디오와 게임에서 동일한 시스템을 사용하여 편집 시간 및 런타임 모두에서 콘텐츠를 생성할 수 있습니다.
Creator Store에서 매개변수화된 모델을 공유하여 자산을 보다 유연하고 사용자 정의 가능하게 만듭니다.

예시: 테이블의 너비나 길이가 증가함에 따라 동적으로 더 많은 의자를 추가하는 절차적 모델입니다.

절차적 모델 삽입

다음과 같은 방법으로 게임에 절차적 모델을 추가할 수 있습니다:

ProceduralModel 객체를 Workspace에 수동으로 삽입합니다. 이 옵션에는 시작하는 데 도움이 되는 템플릿 생성기 ModuleScript가 포함됩니다.
Assistant 또는 Roblox Studio MCP 서버를 사용하여 절차적 모델을 생성합니다.
Creator Store에서 절차적 모델을 삽입하여 기존 모델을 사용하거나 사용자 정의합니다.

절차적 모델은 편집 시간에 게임에 영구적인 변경을 가할 수 있습니다. 원하지 않는 변경으로부터 보호하기 위해, Creator Store에서 삽입된 모든 절차적 모델은 생성기 모듈에서 Sandboxed = true가 자동으로 활성화됩니다.

절차적 모델이 생성되는 방식을 사용자 정의하려면, 자신만의 생성기 모듈을 정의할 수 있습니다.

OnGenerate 함수

OnGenerate 함수는 OnGenerate(params, targetContainer)의 형태로 모든 ProceduralModel의 핵심입니다.

이 개발자가 정의한 함수는 제공된 매개변수를 기반으로 모델의 내용을 생성하고 결과를 지정된 컨테이너에 기록하는 역할을 합니다.

OnGenerate의 두 가지 주요 책임은 다음과 같습니다:

입력 매개변수를 처리하여 모델의 구조를 결정합니다.
제공된 targetContainer에 따라 구조에 따라 생성된 결과를 기록합니다.

다음 섹션에서는 다음을 설명합니다:

엔진이 OnGenerate를 호출하는 시점과 방법
엔진이 targetContainer에 기록된 내용을 처리하는 방법

생성기 모듈

OnGenerate 함수는 생성기 모듈로 알려진 ModuleScript 내에서 정의됩니다. ProceduralModel은 Generator 속성을 통해 사용할 생성기 모듈을 식별합니다.

생성기 모듈은 표준 Luau 모듈이지만, 생성 프로세스의 일환으로 엔진에서 직접 요구됩니다. 정의된 구조를 따르며 표준화된 필드가 포함된 테이블을 반환합니다.

생성기 모듈 구조
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

표준화된 필드는 다음과 같습니다:

Attributes: 매개변수 이름과 해당 기본 값을 정의하는 맵입니다.
OnGenerate: params 테이블과 targetContainer를 수신하는 함수입니다.

OnGenerate 내의 params 테이블에는 다음이 포함됩니다:

Attributes: 모듈에서 정의한 속성이나 지정되지 않은 경우 모든 모델 속성을 포함하는 테이블입니다.
Size: 모델의 크기를 1의 비율로 반영하는 매개변수입니다.
Pause: 복잡한 생성 작업 중 효율적으로 생성이 일시 중지되도록 허용하는 메소드입니다.

OnGenerate 함수는 targetContainer 내에서 원점 주위에 콘텐츠를 생성해야 하며, 기본 DataModel 계층을 직접 수정해서는 안 됩니다.

매개변수는 생성을 제어하는 입력입니다. 여기에는 ProceduralModel의 내장 Size 속성과 생성기 모듈에서 지정된 사용자 정의 속성이 포함됩니다. 이러한 명시적 매개변수는 OnGenerate에 직접 전달됩니다. 암시적 매개변수는 모듈의 소스 코드 또는 샌드박스 상태와 같은 매개변수로, 변경될 경우에도 재생성을 트리거하지만 OnGenerate에 전달되지는 않습니다.

전체 매개변수 세트는 다음과 같습니다:

명시적:
- Size: 원주위에서 콘텐츠가 생성되는 영역을 정의합니다.
- Attributes: 현재 입력 속성 값을 포함하는 맵입니다.
암시적:
- Generator: 생성을 공급하는 모듈입니다.
- 소스 코드: 생성기 모듈의 Luau 코드 변경 사항입니다.
- 샌드박싱: 생성기 모듈의 샌드박싱 상태 변경 사항입니다.

재생성 동작

성능을 유지하고 API 상호 작용을 단순하게 하기 위해, 매개변수가 변경되면 OnGenerate가 즉시 호출되지 않습니다. 대신, ProceduralModel은 더러운 상태로 표시되며, 이는 재생성이 대기 중임을 나타냅니다. 이 대기 중인 재생성은 일반적으로 동일한 프레임 내에서 나중에 발생합니다.

재생성에 실패하면 더러운 상태가 다시 초기화될 때까지 대기 상태로 유지됩니다. 모델이 더러운 상태일 때 장소를 저장하면 상태가 지속되며, 게임이 다음에 로드될 때 모델이 생성 대기열에 추가됩니다.

실행 프로세스

처리할 시간이 있을 때, 엔진은 다음 단계를 실행하여 더러운 모델을 재생성합니다:

생성기 모듈을 요구하며 필요시 일시 중지합니다.
생성 프로세스를 위한 새 스레드를 시작합니다.
매개변수 테이블을 작성하고 모델의 현재 크기에 따라 Size를 정규화합니다.
누락된 속성에 기본 속성 값을 적용합니다.
targetContainer로 사용할 임시 GeneratedFolder를 초기화합니다.
OnGenerate를 호출합니다.
OnGenerate가 반환된 후:
- 성공한 경우, targetContainer의 결과를 ProceduralModel로 이동합니다.
- 생성에 실패한 경우, 대신 실패 자리 표시자를 사용합니다.

생성 스레드가 일시 중지되어 있는 동안 매개변수가 다시 변경되면, outstanding generation이 취소되고 업데이트된 매개변수를 사용하여 다시 시작됩니다.

생성 결과

모델에 생성된 결과를 배치하는 과정은 다음 단계로 구성됩니다:

생성 중에 누출된 모든 자식 스레드를 종료합니다.
PivotTo를 사용하여 결과를 적절한 위치에 배치합니다.
모델의 Scale이 1이 아닌 경우, ScaleTo를 사용하여 크기 정규화를 되돌립니다.
결과를 모델의 GeneratedFolder에 부모로 설정합니다.
생성기 모듈이 샌드박스로 설정된 경우, 결과 내의 ModuleScripts가 생성기 모듈의 능력을 초과하지 않도록 합니다.
모델에서 누락된 속성을 기본 값으로 채웁니다.
모델의 더러운 상태를 초기화합니다.

생성 세부정보

핵심 생성 흐름 외에도, 다음 세부정보는 ProceduralModel 생성을 어떻게 작동하는지에 영향을 미치는 동작 및 고려 사항을 설명합니다.

크기 조정

생성 중에 적용된 크기 정규화로 인해 ProceduralModel은 여러 크기 조정 워크플로를 지원합니다:

Size 속성을 변경하면 모델이 새로운 콘텐츠로 재생성됩니다.
Scale을 변경하면 기존 결과가 ScaleTo를 사용하여 균일하게 스케일링됩니다.

타임아웃

안전 장치로서, 너무 많은 작업을 수행하면서 일시 중지하지 않는 생성기 모듈은 종료됩니다. 생성이 "스크립트 타임아웃" 오류에 도달하면, 엔진이 나머지 작업을 나중의 프레임으로 연기할 수 있도록 parameters:Pause()에 추가 호출을 하십시오.

parameters:Pause()를 호출하는 것은 매우 비용 효율적이며 일반적으로 정상 생성기 실행 중 즉시 반환되므로, 성능에 영향을 미치지 않고 루프의 시작에서 자유롭게 호출할 수 있습니다.

실행 취소 기록

생성된 결과는 이를 트리거한 매개변수 변경과 함께 실행 취소 지점 오버라이드를 사용하여 그룹화됩니다. 여러 매개변수 변경이 단일 프레임 내에서 발생하면, 결과는 가장 최근의 지점과 관련됩니다.

샌드박싱

ProceduralModel은 샌드박싱을 지원합니다. Creator Store에서 삽입한 모든 서드파티 절차적 모델은 기본적으로 샌드박스 처리되어, 게임에 대한 의도치 않은 변경을 방지합니다.

생성 코드가 생성기 모듈의 컨텍스트 내에서 실행되며, 해당 모듈의 샌드박싱 상태를 사용합니다. 이 설정은 기본적으로 볼 수 없습니다. 볼륨을 보거나 수정하려면 Workspace.SandboxedInstanceMode = Experimental로 설정하십시오. 이로 인해 ModuleScript의 Sandboxed 및 Capabilities 속성이 노출됩니다.

샌드박싱된 생성기 모듈은 일반적으로 다음과 같은 능력을 필요로 합니다:

RunServerScript (모듈 실행을 위해)
CreateInstances
Basic

ProceduralModel과 그 생성기 모듈의 샌드박싱은 독립적입니다. 생성기 모듈에 적용된 샌드박싱은 ProceduralModel 내에서 일반 런타임 스크립트에 영향을 미치지 않습니다. 이를 통해 편집 시간 생성을 엄격히 제한하면서도 게임 내 동작에는 영향이 없도록 할 수 있습니다.

중첩

ProceduralModels는 다른 ProceduralModels를 생성할 수 있습니다. 이렇게 발생하면, 엔진은 가능한 경우 동일한 생성 단계 내에서 위에서 아래로 계층 구조를 처리하며, 더 깊이 중첩된 모델이 마지막에 생성됩니다.

제한 사항

Actor 인스턴스 내에서는 생성이 지원되지 않습니다.
모델은 패키지로 변환할 수 없습니다.
Joint Surfaces가 활성화된 드래거를 사용할 때 생성된 조인트는 ProceduralModel 재생성 간에 보존되지 않습니다.