AI 튜토리얼

포털 실행, 빌드 및 탐험: 생성된 3D 세계 471개

이 튜토리얼에서는 Portals를 소스에서 실행하고, 배포 가능한 정적 빌드를 만들며, 생성된 471개의 세계를 탐험하고, 세계·포털·사운드·그래픽·선택 시스템을 이해하는 방법을 설명합니다. 또한 주요 코드가 어디에 있는지와 프로젝트 확장 방법도 알아봅니다.

2026년 11월 10일약 13분 소요

Portals란?

Portals는 생성된 3D 세계 471곳을 자동으로 비행하는 브라우저 기반 체험입니다. 카메라는 미리 정해진 경로를 따라 포털에 도달한 뒤, 화면 전환이나 페이드 없이 실행 중인 다음 세계로 곧장 들어갑니다. 비행 방향을 직접 조종할 수는 없지만, 속도, 화면 표시 방식, 사운드, 그래픽 품질, 세계 선택은 제어할 수 있습니다.

이 프로젝트는 JavaScript와 three.js로 제작되었습니다. 각 세계의 지오메트리와 텍스처는 브라우저에서 생성되며, 오디오도 재생 중에 합성됩니다. 외부 3D 모델, 텍스처 이미지, 사운드 파일은 불러오지 않습니다. 또한 정적 사이트이므로 계정, 애플리케이션 서버, 추적 서비스가 필요하지 않습니다.

이 저장소는 2026년 11월 9일 기준 s8f 릴리스를 나타냅니다. 해당 릴리스에는 약 140만 줄의 JavaScript 코드와 471개의 세계가 포함되어 있습니다.

주요 기능

생성된 세계 471곳: 야생, 도시, 바다, 실내, 하늘, 외계 환경, 선사시대 장면, 예술에서 영감을 받은 장소, 문학 속 세계, 영화 및 TV에서 영감을 받은 장면, 고대 불가사의, AI 관련 농담까지 다양한 세계로 구성되어 있습니다.
끊김 없는 포털: 현재 세계와 포털 너머의 세계가 동시에 실행되므로, 전환 화면 없이 카메라가 포털을 통과할 수 있습니다.
절차적 에셋: 지오메트리, 텍스처, 사운드를 일반적인 세계 에셋으로 불러오는 대신 브라우저에서 생성합니다.
자동 비행: 각 세계가 카메라 경로와 지속 시간을 제공합니다. 대부분의 비행은 약 40~50초 동안 진행됩니다.
적응형 그래픽: 자동 모드는 그래픽 카드에서 품질 수준을 추정하고, 부드러운 움직임을 유지하도록 렌더링 해상도를 조정합니다.
로컬 설정: 방문한 세계, 즐겨찾기, 설정은 브라우저 저장소에 유지됩니다.
갤러리와 여정: 갤러리에서는 모든 세계를 확인할 수 있으며, 엄선된 20개의 여정은 선택된 세계를 정해진 순서로 재생합니다.
정적 배포: 프로덕션 빌드는 정적 웹 호스트에서 제공할 수 있는 일반 파일을 dist에 생성합니다.

사전 요구 사항

Node.js 18 이상과 Git이 필요합니다. 소스 미리보기는 설치나 빌드 단계 없이 바로 실행할 수 있습니다. 전용 그래픽 카드를 사용하는 것이 좋지만, 휴대폰과 오래된 노트북에서도 품질을 낮추면 프로젝트를 실행할 수 있습니다.

Node.js 버전을 확인합니다.

node --version

결과가 18보다 낮으면 계속하기 전에 Node.js를 업데이트하세요.

소스에서 Portals 직접 실행하기

1. 저장소 복제

git clone https://github.com/emollick/ai-portals.git
cd ai-portals

2. 로컬 소스 서버 시작

npm start

브라우저에서 http://localhost:8000을 엽니다. 패키지를 먼저 설치하거나 컴파일하지 않아도 현재 상태의 소스 트리를 제공합니다.

소스 미리보기에는 두 가지 알려진 제한이 있습니다. 갤러리에서 새로 추가된 세계를 식별할 수 없으며, 생성된 설명 페이지도 표시되지 않습니다. 또한 처음 방문하면 빌드 과정에서만 생성되는 atlas.json 파일이 없다는 내용이 브라우저 콘솔에 표시됩니다.

프로덕션 빌드 생성 및 미리보기

빌드 의존성을 설치하고, 배포 패키지를 생성한 다음 미리보기 서버를 시작합니다.

npm install
npm run build
npm run preview

생성된 정적 사이트는 dist에 기록됩니다. http://localhost:8001을 열어 확인하세요.

빌드는 esbuild로 프로젝트 스크립트를 압축하고, 다음과 같은 배포 전용 리소스를 생성합니다.

각 세계와 여정에 대한 작은 공유 미리보기 페이지
모든 세계와 설명을 나열하는 일반 페이지
새로운 세계를 기록하는 갤러리 데이터
호스팅 설정 파일

릴리스 s8f 재현

빌드는 릴리스 스탬프를 허용합니다. 저장소 문서에 따르면 다음 명령은 2026년 11월 9일에 실제 운영 중인 s8f 릴리스 파일을 파일 단위 및 바이트 단위로 재현했습니다.

npm run build -- --stamp s8f

개발 중에는 일반 빌드를 사용하세요. 릴리스 메타데이터가 필요하거나 문서에 기록된 릴리스를 재현하려는 경우에만 스탬프를 사용하세요.

기본 조작 및 사용법

Portals는 자동으로 비행을 시작합니다. 사운드는 기본적으로 비활성화되어 있으므로 합성 사운드트랙을 들으려면 S를 누르세요. 키보드 조작은 다음과 같습니다.

스페이스: 비행을 일시 정지하거나 다시 시작합니다.
오른쪽 화살표: 다음 포털로 빠르게 이동합니다.
S: 사운드를 켜거나 끕니다.
G: 카메라를 더 안정적으로 유지하고 수평을 맞추는 부드러운 모드를 활성화합니다.
H: 현재 세계를 즐겨찾기로 저장합니다.
P: 이미지를 저장합니다.
I: 갤러리, 여정, 검색 인터페이스를 엽니다.
O: 그래픽, 카메라, 아트 스타일, 탑승 방식, 동반자, 시간대 옵션을 엽니다.
F: 전체 화면 모드로 들어가거나 나옵니다.

마우스를 움직이면 화면 하단에 컨트롤 바가 나타납니다. 여기에는 키보드 조작에 해당하는 버튼과 속도 슬라이더, 현실적 세계에서 낯선 세계로 슬라이더가 있습니다. 창이 좁으면 슬라이더가 옵션 인터페이스로 이동합니다.

유용한 첫 탐험

소스 또는 프로덕션 미리보기를 시작합니다.
S를 눌러 오디오를 활성화합니다.
한 세계를 끝까지 재생하며 일반적인 포털 통과를 관찰합니다.
카메라 움직임이 불편하면 G를 누릅니다.
I로 갤러리를 열고 전체 컬렉션을 검색하거나 둘러봅니다.
현실적 세계에서 낯선 세계로를 조정해 특이한 세계가 선택되는 빈도를 바꿉니다.
간직하고 싶은 세계를 발견하면 H를 눌러 즐겨찾기에 추가합니다.

매끄러운 포털의 작동 방식

통과 후 약 1초가 지나면 엔진이 다음 세계를 선택합니다. 렌더링된 프레임 사이에서 몇 밀리초씩 다음 세계를 생성한 뒤, 화면에 보이지 않는 동안 셰이더와 텍스처를 미리 준비합니다.

목적지는 정지된 미리보기가 아닙니다. 두 번째 카메라가 매 프레임 포털 입구 안에 다음 세계를 실시간으로 렌더링합니다. 카메라가 관문에 도달하기 직전에 엔진은 목적지를 현재 세계로 전환하고 비행을 계속합니다. 준비가 끝나지 않았다면 현재 비행은 느려지고 포털 앞에서 대기합니다.

세계가 선택되는 방식

선택기는 방문자가 아직 보지 않은 세계를 우선합니다. 방문 중 처음 12개 정도의 세계에서는 프로젝트의 평가 에이전트들이 가장 높은 점수를 준 세계를 선호합니다. 각 세계에는 1부터 5까지의 품질 등급이 있으며, 이 등급은 어떤 경험이 초반에 나타날지 결정하는 데 사용됩니다.

선택기는 대비도 추구합니다. 현재 배경과 유형, 밝기 또는 온도가 다른 목적지를 선택하는 경향이 있습니다. 현실적 세계에서 낯선 세계로 설정은 더 특이한 항목이 나타나는 빈도를 조절합니다.

프로젝트 구조 이해하기

가장 중요한 파일과 디렉터리는 다음과 같습니다.

index.html: 애플리케이션 페이지입니다.
src/main.js: 키보드 조작, 옵션 및 하단 컨트롤 바를 담당합니다.
src/core: 비행, 포털, 세계 선택, 사운드 및 그래픽 품질 시스템을 포함합니다.
src/kit: 하늘, 물, 지형, 식물, 동물, 건물 및 내부 공간 같은 공용 세계 제작 구성 요소를 포함합니다.
src/worlds: 세계별 모듈, 세계 레지스트리 및 시작 홀을 포함합니다.
src/parts: 개별 세계에서 사용하는 주요 세트 조각을 포함합니다.
src/extras.js: 놀이기구, 동반자 및 아트 스타일 목록을 포함합니다.
src/rides, src/companions 및 src/styles: 해당 추가 요소의 구현을 포함합니다.
src/ui: 갤러리 및 공유 코드와 사이트의 유일한 스타일시트인 ui.css를 포함합니다.
vendor/three: 번들로 포함된 three.js 라이브러리입니다.
thumbs: 갤러리 썸네일 이미지입니다.
design: 빌드에서 읽는 세계 텍스트 및 출시 도착 표를 포함합니다.
tools: 빌드 스크립트 및 로컬 서버를 포함합니다.

세계 모듈의 구조

세계는 src/worlds 아래에 있는 파일입니다. 기본 내보내기는 build 함수를 포함한 객체입니다. 선택기와 갤러리가 모두 해당 목록을 읽기 때문에, 세계는 제목, 종류 및 설명과 함께 src/worlds/index.js에도 등록해야 합니다.

build 함수는 다음 세 가지 필수 요소를 반환합니다.

three.js 장면
카메라 경로
비행 시간

대부분의 세계는 주요 세트 조각을 src/parts 아래의 별도 파일에 배치합니다. src/kit의 공용 기능은 재사용 가능한 구성 요소를 제공하므로, 모든 세계가 공통 배경을 각각 구현할 필요가 없습니다.

세계를 살펴보거나 확장할 때의 안전한 작업 흐름

이해하려는 환경 유형과 비슷한 기존 세계를 src/worlds에서 선택합니다.
해당 세계의 import를 따라가며 src/parts와 src/kit에서 장면이 어떻게 구성되는지 확인합니다.
기본 내보내기와 build 함수를 살펴 저장소의 실제 객체 구조와 카메라 경로 규칙을 익힙니다.
src/worlds/index.js에서 해당 등록 항목을 확인해 필요한 제목, 종류 및 설명 메타데이터를 파악합니다.
빠르게 소스를 테스트하려면 npm start를 실행합니다.
프로덕션 빌드를 만들어 생성된 갤러리 및 공유 리소스를 확인합니다.

이 저장소는 매우 크기 때문에 문서화되지 않은 API를 추측하거나 모듈을 처음부터 만드는 것보다 가까운 기존 세계를 바탕으로 수정하는 편이 안전합니다.

사운드 및 그래픽 동작

사운드 합성

모든 세계에는 느린 화음과 여러 종소리가 적용됩니다. 대부분은 바람, 물, 실내 잔향 또는 일정한 우주 공간의 울림 같은 조용한 앰비언트 사운드도 사용합니다. 세계는 비, 파도, 새소리 및 먼 곳의 종소리를 포함해 19가지 효과 중 최대 3개를 선택하여 추가할 수 있습니다. 브라우저 오디오 엔진은 오디오 파일을 불러오는 대신 이러한 소리를 합성합니다.

자동 그래픽 품질

그래픽이 자동으로 설정되면 Portals는 그래픽 카드에 맞는 품질 수준을 추정합니다. 그런 다음 원활한 비행을 유지하도록 그리기 해상도를 높이거나 낮춥니다. 오래된 노트북이나 휴대전화에서는 더 높은 성능을 요구하는 설정을 시도하기 전에 자동 모드를 유지하세요.

고급 팁

접근성을 위해 부드러운 모드 사용

더 안정적인 카메라와 수평선을 유지하려면 G를 누르세요. 일반 비행으로 불편함이 느껴질 때 가장 먼저 시도해 볼 설정입니다.

소스 버전과 빌드 버전을 모두 테스트하세요

빠르게 반복 작업을 하려면 소스 서버를 사용하되, 배포 전에 항상 dist 빌드를 확인하세요. 일부 갤러리 데이터, 설명 페이지, 공유 미리보기, 호스팅 설정은 빌드 후에만 생성됩니다.

장면의 외관뿐 아니라 포털 준비 상태도 테스트하세요

세계를 이동하려면 먼저 해당 세계가 준비되어 있어야 합니다. 세계 코드를 변경할 때는 목적지 장면 자체뿐 아니라 해당 포털로 접근하는 과정도 확인하세요. 무거운 생성 작업이나 셰이더 준비로 인해 비행이 대기하면서 느려질 수 있습니다.

반복 가능한 시퀀스에는 여정을 사용하세요

Portals에는 세계를 정해진 순서로 재생하는 20개의 여정이 있습니다. 예를 들어 One Drop of Water는 우박에서 깊은 바다까지 이동하며, Zooming Out은 살아 있는 세포 안에서 시작합니다. 일반 선택기가 제공하는 것보다 더 연출된 경험을 원할 때 고정된 시퀀스가 유용합니다.

저장 공간과 개인정보 보호의 경계를 지키세요

이 애플리케이션에는 백엔드가 없으며 계정, 추적, 즐겨찾기 또는 설정 데이터를 서버로 전송하지 않습니다. 즐겨찾기나 확인한 세계 관련 동작을 디버깅할 때 이러한 값이 브라우저에 저장된다는 점을 기억하세요.

변경 사항을 게시하기 전에 라이선스를 검토하세요

이 저장소는 CC BY-NC-SA 4.0에 따라 배포되며, 저작자 표시와 동일한 라이선스를 조건으로 비상업적 공유 및 변경을 허용합니다. three.js와 일부 짧은 함수에는 별도의 조건이 적용됩니다. 수정된 빌드를 재배포하기 전에 LICENSE와 THIRD-PARTY-NOTICES.txt를 읽으세요. 특히 README에는 추가 셰이더와 유틸리티 함수의 출처가 기록되어 있습니다.

결론

Portals는 절차적으로 생성되는 three.js 장면, 합성 오디오, 적응형 그래픽, 백그라운드 세계 생성, 두 세계의 동시 렌더링을 결합해 끊김 없는 브라우저 여정을 만듭니다. npm start로 소스를 즉시 탐색하고, npm run build로 배포 가능한 전체 사이트를 생성할 수 있으며, 프로젝트 구조와 기존 세계 모듈을 참고해 아키텍처를 학습하거나 확장할 수 있습니다.