씬 스크립트 문법 (umx_parametric_shape)

파라메트릭 쉐이프를 생성·편집하는 umx_parametric_shape 스크립트의 전체 문법 참조입니다.

umx_parametric_shape 는 스크립트 한 장으로 씬의 파라메트릭 쉐이프를 만들고 편집하는 툴입니다. 스크립트 윈도우 도 같은 문법을 사용합니다.

group "Table" @0,0,0
  box "Top" w=2 h=.1 d=1 @0,1,0
    mod subdivide
  cylinder "Vase" r=.15 h=.4 pivot=bottom @0,1.05,0

문장 종류

문장	하는 일
`<kind> ["name"] [k=v ...]`	쉐이프 생성
`group ["name"]`	빈 GameObject 그룹 생성
`mod <type> [k=v ...]`	직전 노드에 모디파이어 추가
`@"name"` / `@#id`	기존 오브젝트 편집
`del "name"` / `del #id`	삭제
`prefab "Asset" ["inst"]`	프리팹 인스턴스 배치
`save prefab "name" ["path"]`	대상을 프리팹 에셋으로 저장

기본 규칙

한 줄에 한 문장을 씁니다.
들여쓰기 2칸 = 자식. 한 번에 두 단계 이상 깊어질 수 없고 탭은 쓸 수 없습니다.
# 로 시작하는 줄은 주석입니다.
이름은 큰따옴표로 감쌉니다. 공백을 포함해도 됩니다.
kind 와 파라미터 키(k=v 의 k)는 반드시 소문자로 씁니다. Box 나 Width=2 는 오류입니다.
숫자의 소수점은 마침표입니다. .1 처럼 앞자리를 생략해도 됩니다.

쉐이프 생성

box "Crate" w=1 h=1 d=1 @0,0,0

사용할 수 있는 kind 는 다음과 같습니다.

box  sphere  cylinder  capsule  cone  torus  pipe  icosphere
stair  spiralstair  room  wedge  arch  dome  regpoly
superellipsoid  nurbs  gear  quadstrip (별칭 strip)  ngon  layout
group

각 종류가 어떤 파라미터를 쓰는지는 쉐이프 종류와 파라미터 에 정리되어 있습니다.

트랜스폼 토큰

토큰	의미
`@x,y,z`	위치. 부모 줄이 있으면 로컬, 최상위면 월드 좌표입니다.
`rot=x,y,z`	오일러 회전(도)
`sc=k`	균등 스케일. `sc=x,y,z` 로 축별 지정도 가능합니다.

세 토큰은 모두 오브젝트의 Transform 에 적용됩니다. 파라메트릭 파라미터와는 독립입니다.

파라미터 키

값은 k=v 형태로 씁니다. 짧은 별칭과 정식 이름을 모두 쓸 수 있습니다.

별칭	정식 이름	타입
`w`	`width`	실수
`h`	`height`	실수
`d`	`depth`	실수
`r`	`radius`	실수
`r1`	`radius1`	실수
`r2`	`radius2`	실수
`th`	`thickness`	실수
`sh`	`stepheight`	실수
`sw`	`stepwidth`	실수
`ang`	`angle`	실수
—	`rotation`	실수
`seg`	`segments`	정수
—	`sides`	정수
—	`rings`	정수
`ord`	`order`	정수
`sweep`	`sweepangle`	정수
`e1`	`roundness1`	실수
`e2`	`roundness2`	실수
`cu`	`controlsu`	정수
`cv`	`controlsv`	정수
—	`widthsegs` · `depthsegs` · `heightsegs`	정수
—	`heightsegment` · `disksegments` · `heightsegments`	정수
`ccw`	`counterclockwise`	불리언
—	`closed`	불리언
—	`curved`	불리언
—	`collider` / `collidermode`	불리언
`poly`	`polyhedrontype`	문자열
`mat`	`material`	에셋 경로 또는 이름
`hs`	`hotspot`	에셋 경로 또는 이름

불리언은 1 / true 로 켜고 0 / false 로 끕니다.

종류별로 의미가 달라지는 키

종류	키 해석
`spiralstair`	`r` = 중심 반지름, `sw` = 계단(트레드) 너비, `ang` = 시작 각도, `sweep` = 총 회전각(1 ~ 360), `ccw=1` = 반시계 방향
`superellipsoid`	`e1` / `e2` = 세로 · 가로 라운드니스 지수 (0.01 ≈ 큐브, 1 = 타원체, 2 초과 = 오목한 별)
`nurbs`	`cu` / `cv` = 컨트롤 포인트 개수, `ord` = 차수, `widthsegs` / `depthsegs` = 테셀레이션
`quadstrip`	`cu` = 컨트롤 포인트 개수(2 ~ 32), `depthsegs` = 스팬당 곡선 분할, `w` = 리본 폭, `th` = 두께(0 = 단면 스트립), `ang` = 총 비틀림, `r1` / `r2` = 시작 · 끝 폭 배율, `closed=1` = 닫힌 루프
`ngon`	`r` = 외접원 반지름, `sides` = 버텍스 수(3 ~ 128), `th` = 두께(0 = 평면 한 장), `curved=1` = 닫힌 곡선 윤곽, `depthsegs` = 곡선 모드 분할 수
`layout`	`w` / `d` / `h` = 메시 없는 AABB 박스 크기 (씬뷰에 와이어 박스로 표시)
`gear`	`r1` = 이끝원, `r2` = 이뿌리원, `r` = 축 구멍, `h` = 두께, `sides` = 잇수, `th` = 이끝 두께 비율, `ang` = 압력각

피벗과 앵커링

토큰	의미
`pivot=<키워드>`	부모 바운즈의 앵커점에 붙입니다.
`pivot=<퍼센트>`	부모 바운즈 안의 상대 위치(%)에 붙입니다.
`pivot=x,y,z`	이 쉐이프 자신의 절대 피벗입니다.
`offset=x,y,z`	앵커점으로부터의 로컬 오프셋
`ratio=필드,필드`	지정한 크기 필드를 부모 대비 비율로 해석합니다.

앵커 키워드

left right (X축) · bottom top (Y축) · back front (Z축) · center

여러 축을 지정할 때는 하이픈으로 잇습니다. 지정하지 않은 축은 center 입니다.

pivot=bottom          # Y만 min, X·Z는 center
pivot=top-right       # Y는 max, X는 max
pivot=bottom-left-back

퍼센트

값에 % 가 하나라도 들어 있으면 퍼센트 모드로 해석되고, 각 성분은 100으로 나눠집니다.

pivot=50%,0%,50%     # 바닥면 중앙

% 가 없는 0.5,0,0.5 는 퍼센트가 아니라 절대 좌표 피벗입니다.

비율 크기

ratio= 에 적은 필드는 값 자체가 부모 축 대비 비율이 됩니다. h=0.5 이고 ratio=height 이면 부모 높이의 절반이 됩니다.

지정할 수 있는 필드 이름은 다음뿐이며, 대소문자를 구분합니다.

width  depth  height  radius  radius1  radius2  thickness  stepWidth  stepHeight

layout "Room" w=6 d=4 h=3 @0,0,0
  box "Ceiling" pivot=top ratio=width,depth w=1 d=1 h=0.2

앵커링은 부모가 파라메트릭 쉐이프이거나 layout 일 때만 동작합니다. 자세한 개념은 피벗과 앵커링 을 참고하세요.

머티리얼과 핫스팟

box "Wall" w=4 h=3 d=.2 mat=Wood hs=Walls
box "Wall2" w=4 h=3 d=.2 mat="Assets/Materials/Wood.mat"

mat= — 적용할 머티리얼. 에셋 경로 또는 에셋 이름으로 지정합니다.
hs= — UV를 피팅할 핫스팟 레이아웃 에셋. 지정하면 모든 페이스가 기본 절차적 언랩 대신 핫스팟 사각형에 맞춰집니다. 생략하면 기본 UV가 유지됩니다.

컬라이더 모드

box "TriggerVolume" w=2 h=2 d=2 collider=1

collider=1 을 주면 렌더러블이 숨겨지고 컬라이더가 형태를 대표합니다. Box · Sphere · Icosphere · Capsule · Layout 은 메시를 만들지 않고 프리미티브 컬라이더를 사용하고, 그 외 종류는 메시를 만든 뒤 MeshCollider 로 노출합니다. 크기는 파라미터와 계속 동기화되며 isTrigger · convex 설정은 유지됩니다.

모디파이어 (mod)

직전 노드 아래에 2칸 들여써서 추가합니다.

cylinder "Column" r=.3 h=4
  mod twist angle=360 twistaxis=Y
  mod subdivide

사용할 수 있는 종류는 다음과 같습니다.

Twist  Bend  Push  Mirror  Screw  Subdivide  Shell  Decimate
LinearArray  RadialArray  FFD2x2x2  FFD3x3x3  FFD4x4x4

종류 이름과 파라미터 이름은 대소문자를 구분하지 않습니다.
파라미터는 인스펙터에 노출되는 항목과 같습니다. 값은 실수 · 정수 · 불리언 · 벡터(x,y,z) · 열거형(이름) 을 받습니다.
없는 종류나 없는 파라미터를 쓰면 실행되지 않고 사용 가능한 목록과 함께 오류로 돌아옵니다.

group 에는 모디파이어를 붙일 수 없습니다.

그룹

group "Chair" @0,0,0
  box "Seat" w=.5 h=.05 d=.5 @0,.45,0
  box "Leg" w=.05 h=.45 d=.05 @-.2,0,-.2

group 은 빈 GameObject 입니다. 위치 · 회전 · 스케일만 받고, 쉐이프 파라미터 · pivot · offset · ratio · 모디파이어는 쓸 수 없습니다. 지정하면 조용히 무시되지 않고 오류로 돌아옵니다.

기존 오브젝트 편집

@"이름" 또는 @#id 로 이미 씬에 있는 오브젝트를 엽니다.

@"Top" w=2.4 h=.08
@"Top" @0,1.2,0 rot=0,45,0
@"Top"
  mod shell thickness=.02
  cylinder "Knob" r=.03 h=.05 @0,.08,0

파라미터 · 피벗 · 로컬 트랜스폼을 바꿀 수 있습니다.
아래에 자식 쉐이프나 mod 줄을 둘 수 있습니다. 자식은 대상의 자식으로 편입됩니다.
부모는 바뀌지 않습니다.
대상이 파라메트릭 쉐이프가 아니면 트랜스폼만 적용되고, 파라미터 · 모디파이어는 경고와 함께 무시됩니다.

삭제

del "Knob"
del #-8123

del 은 대상만 받습니다. 파라미터 · 트랜스폼 · 피벗을 함께 쓰면 오류입니다.

프리팹

prefab "Chair" "Chair_A" @2,0,0
save prefab "Table" "Assets/Props/Table.prefab"

prefab — 기존 프리팹 에셋의 인스턴스를 배치합니다. 첫 번째 문자열은 프리팹 이름 또는 경로, 두 번째(생략 가능)는 인스턴스 이름입니다. 트랜스폼만 받고 자식 · 모디파이어 · 파라미터는 쓸 수 없습니다.

save prefab — 씬 오브젝트를 프리팹 에셋으로 저장합니다. 경로를 생략하면 Assets/<오브젝트이름>.prefab 이 되고, 지정할 경우 .prefab 으로 끝나야 합니다. 하위의 파라메트릭 쉐이프까지 함께 저장됩니다.

오브젝트 참조와 #id

실행 결과의 생성 · 수정 목록은 "이름#id" 형식으로 돌아옵니다.

Created: Table#-8120, Top#-8123

#id 는 "이름" 이 쓰이는 모든 자리에 사용할 수 있습니다 — del #-8123, @#-8123.

동일한 이름이 여러 개면 첫 번째 대상이 사용되고 경고가 함께 돌아옵니다. 정확히 하나를 지정해야 할 때 #id 를 쓰세요.

결과 데이터

실행이 끝나면 다음 정보가 함께 돌아옵니다.

항목	내용
`created`	생성된 오브젝트 목록 (`"이름#id"`)
`updated`	수정된 오브젝트 목록
`deleted`	삭제된 오브젝트 이름 목록
`modifiersAdded`	추가된 모디파이어 수
`failed`	실패한 노드 — 줄 번호와 이유
`warnings`	경고 목록

파싱 · 검증 · 프리플라이트 단계에서 오류가 나면 씬은 전혀 바뀌지 않습니다. 실행 중 개별 노드가 실패하면 그 노드와 자식만 건너뛰고 나머지는 계속 진행되며, 성공한 부분은 그대로 남습니다.

전체 예시

# 벤치 한 세트
group "Bench" @0,0,0
  box "Seat" w=1.8 h=0.06 d=0.45 @0,0.44,0
  box "LegLeft" w=0.06 h=0.44 d=0.4 @-0.8,0,0
  box "LegRight" w=0.06 h=0.44 d=0.4 @0.8,0,0
  cylinder "BackRail" r=0.03 h=1.7 rot=0,0,90 @0,0.85,0.2
    mod twist angle=20 twistaxis=Y

# 방 안쪽에 비율로 붙는 천장 패널
layout "Room" w=6 d=4 h=3 @10,0,0
  box "CeilingPanel" pivot=top ratio=width,depth w=0.9 d=0.9 h=0.1

# 이미 만든 좌판을 두껍게 수정
@"Seat" h=0.09