World Builder 파일 포맷¶

Custom World Builder의 출력물은 두 가지이고, 트랙의 waypoints 파일(.npy)도 함께 나옵니다.

출력	결과물	용도
Publish	월드 CDN에 올라간 트랙 파일(worlds/models/meshes)과 월드 ID	월드 ID로 시뮬레이터에 설치, 빌더에서 리믹스
Print	고해상도 탑다운 `.jpg`	실물 바닥 트랙 인쇄

파일을 내려받아 올리는 단계는 없습니다: Publish가 트랙을 32자리 16진수 월드 ID로 업로드하고, 시뮬레이터는 CDN에서 바로 설치합니다 (App의 월드 모달 또는 POST /sim/api/worlds/install, 둘 다 월드 ID 기반). 배포된 월드는 불변입니다 — Publish 할 때마다 새 월드 ID가 생성되고(한 프로젝트에서 여러 월드 배포 가능), 배포 후에는 Published 탭에서 접근 권한(과 이름)만 바꿀 수 있습니다.

평가 (Evaluation)¶

월드에는 선택적으로 평가를 실을 수 있습니다 (빌더 우측 패널의 Evaluation 섹션에서 활성화): 학생 주행을 채점하는 config + Python 스크립트가 월드 번들에 두 파일로 동봉됩니다 (routes/처럼 월드명이 경로에 구워져 시뮬레이터의 일반 설치 루프가 그대로 배치합니다):

evaluations/custom_<월드ID>.json — config 문서 (사람이 읽는 파일):

{ "version": 1,
  "config": { "description": "...", "better": "lower" | "higher",
              "time_limit_s": 180, "robot": "physicar" } }

evaluations/custom_<월드ID>.py — 채점 스크립트 본문(def initialize/def evaluate), 진짜 Python 파일이라 DEV 모드에서 그대로 편집합니다. 브라우저에서는 실행되지 않고 시뮬레이터가 평가마다 새 컨테이너에서 실행합니다(Python 3.14, 표준 라이브러리; 파일 쓰기·인터넷 가능).

시뮬레이터에서 평가가 있는 월드는 ⚑ 버튼이 나타납니다 (sim의 로봇 세대가 config.robot과 일치할 때만). 누르면 차량을 출발선 뒤에 배치하고 initialize 실행 → 학생 코드 실행(학생이 시작할 때 입력하는 run command; 끝나면 그 프로세스는 죽입니다) → 매 관측마다 evaluate(sim) 호출 — sim.finish() 또는 sim 시간 기준 제한시간 초과(실격)로 종료됩니다. 스크립트가 보는 계약: 관측 sim.state(time·paused·rtf·pose(roll/pitch 포함)·objects·lights·brightness·run·audio — 로봇이 내는 소리: .playing과 직전 관측 이후의 .events, 재생한 파일의 바이트와 실시간 스트림 청크 포함) + 정적 sim.config/sim.track(.bounds 포함)/sim.objects(물체 목록)/sim.origins, 개입 sim.teleport/sim.move_object(둘 다 duration= 또는 path=, speed=, loop= 로 시뮬레이터가 이어서 움직이는 연속 이동)/sim.set_light/sim.overlay(text, secs, size)/sim.set_brightness/sim.pause, 판정 sim.record(value)/sim.finish(). 판정 로직(선분 통과·이탈·충돌)은 스크립트 안에서 직접 구현합니다 — 기본 템플릿이 +5초 페널티 포함 완주 기록 평가의 완성본입니다. 실행은 시뮬레이터가 소유하므로 모든 뷰어가 같은 실행을 보고, 기록은 시뮬레이터에 저장됩니다(GET /sim/api/evaluation/record).

트랙 호환성¶

배포된 트랙 파일은 시뮬레이터에서 로드됩니다.

오브젝트 (Objects)¶

빌더에서 배치한 3D 오브젝트는 .world 파일의 인라인 모델로 내보내집니다. 모델 이름 = 에디터에서 지정한 이름(속성 카드에서 변경 가능, 기본값 box1, cylinder2, signal1 식, 중복 불가, A-Za-z0-9_)이고, 오브젝트 종류는 SDF link 이름 마커로 표시되어 도구들이 모델명에 의존하지 않습니다:

오브젝트 타입	link 마커	비고
Box (`box`)	`object`	박스 collision + 면별 텍스처(선택). 기본 PhysiCar 스킨을 쓰는 박스는 새 메시를 동봉하지 않고 내장 `physicar_box_obstacle` 메시(시뮬레이터에 이미 존재)를 참조합니다 — 커스터마이즈한 박스만 자체 COLLADA+텍스처를 동봉합니다.
Cylinder / Sphere (`cylinder`, `sphere`)	`object`	SDF 프리미티브 collision + visual, 전개도 텍스처(side/top/bottom, surface) 선택. 원기둥 기본값은 A4 비율(높이 21cm, 둘레 29.7cm) — 옆면 텍스처를 인쇄해 말면 실물이 됩니다. 구는 기본이 내장 축구공 스킨(공용 `physicar_ball` 메시 참조, 기본 지름 22cm)입니다.
Traffic Cone (`cone`)	`object`	정사각 받침판 + 위가 잘린 원뿔, 실물 라바콘 비율(기본 받침 13.5cm·높이 23cm). 텍스처는 경사 옆면 랩 전용이고 받침과 절단면은 색상을 씁니다. 기본 외형은 내장 `physicar_cone` 메시 참조(주황+흰 띠), 커스터마이즈하면 자체 COLLADA를 동봉합니다. Gazebo Classic엔 cone 프리미티브가 없어 collision은 외접 박스이며, `<collision name="cone">` 마커로 종류를 알립니다(`objects` 파라미터의 `type: "cone"`).
Traffic Light (`light`)	`light`	파라메트릭 기기 스탠드(SDF 프리미티브) — 가로와 뒤 기울기를 조정하면 세로·화면·램프가 16:9 비율(폰과 태블릿의 중간)로 닮음꼴 비례합니다(기본 18×32cm·15°). 익스포트된 모델의 `lamp_red`/`lamp_green` visual과 `screen` visual(pose+size)이 계약: 시뮬레이터가 런타임에 램프 색을 바꿔 빨강/초록을 표시하고, 노랑 경유 3초 동안은 화면 앞 중앙에 밝은 노란 원을 겹칩니다 — Remote Traffic Light 앱과 동일한 문법입니다. 여느 물체처럼 crash 판정에 참여합니다(`type: "light"`). 구 월드의 legacy `signal` 마커도 계속 인식됩니다.
둘레 펜스	`wall` (모델 `wall_0..3`)	자동 생성 collision 마커 — 펜스에 부딪히면 crash 로 판정됩니다. 펜스 시각(racetrack 모델의 일부)은 사용자 지정 단색, 두께 3 cm, 높이는 사용자 지정 0.2–1 m(기본 0.25 m)입니다(Objects 목록의 Wall 행).

마커가 있는 모든 오브젝트는 충돌(crash) 판정에 참여합니다. 월드의 평가·자동화 스크립트는 이 목록을 sim.objects — {이름: {type, static, movable, origin, size}} — 로, 공개된 원위치를 sim.origins, 실시간 포즈를 sim.state.objects 로 받습니다.

바닥(Field) — 1m 타일 바닥면은 빌트인 프리셋(카펫/잔디) 또는 사용자 업로드 이미지 중에서 선택합니다(Decals 목록의 Field 행). 프리셋 필드와 표준 트랙 텍스처(도로·경계선·시작선)는 익스포트에 동봉되지 않고 시뮬레이터에 이미 설치된 공용 meshes/world_builder/textures/ 폴더를 참조합니다. 커스텀 업로드 필드만 트랙에 동봉됩니다(textures/field.png).

바닥 그래픽(데칼)은 모델로 내보내지 않고 레이어 순서대로 트랙 시각 메시에 베이크됩니다.

Waypoints (`.npy`)¶

각 공식/커스텀 트랙은 Waypoints 다운로드를 제공합니다 — (N, 6) NumPy 배열로, 트랙을 따라 놓인 점마다 한 행입니다:

[ center_x, center_y, inner_x, inner_y, outer_x, outer_y ]

스크립트의 sim.track.waypoints 가 0, 1번 열(중앙선)이고 inner·outer 가 나머지입니다. 트랙 모양 분석에 쓰세요.