바이브 코딩으로 메타버스를 만들었습니다 — Three.js · Colyseus 원리와 Redis 분산 처리

김팔복 2026-11-15 22:58:29
조회 29 추천 0 댓글 0

영상: 유튜브 「김팔복TV」 팔복메타 편 (9분)
직접 들어가 보기: https://palbokmeta.palboksoft.com/


1. 시작은 온라인 절 '산사'였습니다

서울신문 기사 — 사찰 '산사' 1주 만에 100만명 방문

요즘 온라인 절 '산사'가 화제입니다. 서울신문 기사(2026-11-05)에 따르면 문을 연 지 일주일도 안 돼 100만 명이 넘게 다녀갔다고 합니다.

03_sansa_temple.jpg

기사에서 눈에 띈 건 숫자보다 이 부분이었습니다. 이런 온라인 사찰, 예배당, 사우나 같은 작은 가상 공간을 개인 개발자가 AI로 간단하게 만든다는 것.

그래서 저도 바이브 코딩으로 저만의 메타버스를 만들어 봤습니다. 이름은 팔복메타입니다.

04_palbokmeta.jpg

이 글은 세 부분입니다.

  1. 팔복메타 한 바퀴
  2. 어떻게 돌아가는지 — Three.js와 Colyseus
  3. 사람이 몰리면 서버를 어떻게 늘리는지 — Redis 분산 처리

2. 팔복메타 한 바퀴

맵은 크게 세 곳입니다. 메인 광장 → 카페 맵 → 놀이터. 포털에 올라서면 다음 맵으로 넘어갑니다.

메인 광장

05_tour_plaza.jpg

모두가 만나는 곳입니다. 바닥을 누르거나 방향키로 걷고, Shift를 누르면 달립니다. 같은 맵에 있는 사람은 실시간으로 보이고, 채팅을 치면 머리 위에 말풍선이 뜹니다. 이모티콘과 인사·춤 같은 동작도 같은 맵 사람들에게 바로 보입니다.

광장에는 건물이 세 개 있습니다.

  • 공연장 — 큰 화면을 모두가 같은 시각에 맞춰 함께 봅니다.
  • 회의방 — 비밀번호를 건 회의실을 만들 수 있고, 안에서 음성으로 대화하고 화면을 공유합니다.

06_tour_meeting.jpg

  • 사격연습장 — 혼자도 되고, 한 사람이 더 들어오면 둘이 45초 동안 점수를 겨룹니다.

07_tour_shooting.jpg

카페 맵

08_tour_cafe.jpg

분수 정원과 유리 온실 카페가 있는 낮 맵입니다.

  • 커피 주문 — 계산대에서 음료를 주문해 1분 동안 들고 다닙니다.
  • 바리스타 도전 — 60초 동안 손님 주문대로 음료를 만듭니다.

09_tour_barista.jpg

  • 소원 동전 — 분수에 동전을 던져 넣으면 소원을 적을 수 있고, 비둘기가 그 소원을 하늘로 가져갑니다.

10_tour_wish.jpg

  • 분수 리듬쇼 — 떨어지는 구슬이 고리에 들어갈 때 버튼을 누르는 40초짜리 게임입니다.

놀이터

11_tour_playground.jpg

  • 그네 멀리 날기 — 그네를 굴러 날아간 다음 공중에서 2단, 3단 점프
  • 트램펄린 하늘 점프 — 매트에 닿는 순간 눌러서 더 높이
  • 무궁화 꽃이 피었습니다 — 로봇 다섯과 함께, 술래가 돌아볼 때 움직이면 탈락

12_tour_swing.jpg

점수가 남는 놀이는 모두 순위표가 있습니다.


3. "Higgsfield를 썼다"는 건 무슨 뜻일까

광장의 건물과 캐릭터는 Higgsfield로 만들었습니다. 요즘 "Higgsfield로 만들었다"는 말을 자주 듣는데, 정확히 무슨 뜻일까요?

13_hf_models.jpg

Higgsfield는 그림, 영상, 소리, 3D를 만드는 여러 회사의 AI 모델을 한곳에 모아 둔 서비스입니다. 3D 모델 목록만 봐도 Tripo, Meshy, Tencent(Hunyuan3D), Meta(SAM 3)처럼 만든 회사가 따로 적혀 있습니다. (위 화면은 Claude Code에서 Higgsfield MCP로 받아 온 목록입니다.)

그래서 Higgsfield를 썼다 = 여러 AI 모델의 API를 단계별로 이어 붙여 썼다는 뜻입니다.

건물과 소품: GPT Image → Tripo

14_hf_assets.jpg

먼저 GPT Image로 건물 그림을 한 장 만들고,

15_hf_tripo.jpg

그 그림을 Tripo의 Image to 3D에 넣으면 3D 모델 파일(.glb)이 나옵니다. 사격장, 공연장, 회의방, 분수, 벤치, 나무까지 건물과 소품은 모두 이렇게 만들었습니다. (실제로 공연장 모델 파일을 열어 보면 만든 곳에 tripo3d.ai가 적혀 있습니다.)

캐릭터: GPT Image → Meshy

캐릭터는 달라야 했습니다. 걷고 뛰고 앉으려면 3D 모양만이 아니라 뼈대(리깅)와 동작이 필요합니다.

16_hf_meshy.jpg

Higgsfield에서 뼈대와 동작까지 한 번에 만들어 주는 건 Meshy입니다. 그래서 캐릭터는 Meshy로, 건물은 크레딧이 덜 드는 Tripo로 나눠 만들었습니다. 달리기·점프·손 흔들기·춤 같은 동작은 Meshy의 리깅 기능으로 하나씩 더 받았습니다.

17_hf_pipeline.jpg

1단계 2단계 결과
건물 · 소품 GPT Image (그림) Tripo (Image to 3D) .glb
캐릭터 GPT Image (그림) Meshy (3D + 뼈대 + 동작) .glb

일마다 맞는 모델을 골라 이어 붙이는 것, 이것이 Higgsfield를 쓴다는 의미입니다.

반대로, 놀이터는 코드로만

18_playground_compare.jpg

놀이터의 배경과 놀이기구는 AI 모델 없이 전부 코드로 만든 도형입니다. AI로 만든 광장과 품질을 비교해 보려고 일부러 그렇게 만들었습니다. 나란히 놓고 보면 차이가 보입니다.

  • 광장(AI 3D 모델): 질감과 디테일이 살아 있다
  • 놀이터(코드 도형): 둥글둥글, 단순한 모양

(놀이터를 돌아다니는 로봇 캐릭터는 AI 모델입니다.)

이렇게 만든 모델 파일을 브라우저 화면에 불러와 그리는 것이 바로 Three.js입니다.


4. 어떻게 돌아가나 — Three.js와 Colyseus

이런 걸 AI에게 만들어 달라고 하면, 제가 해 보니 대부분 Three.js + Colyseus 조합으로 만들어 줍니다. 둘이 무슨 일을 나눠 하는지만 알아 두면 됩니다.

19_threejs_colyseus.jpg

맡는 일 어디서
Three.js 화면 담당 — 광장과 캐릭터를 3D로 그린다 내 브라우저
Colyseus 서버 담당 — 방(room)을 만들고, 사람들의 상태(state)를 맞춘다 서버

바닥을 클릭하면 무슨 일이 일어날까

20_click.jpg

  1. 내 화면은 "여기로 가고 싶다"는 메시지만 서버에 보냅니다. 내 위치를 직접 바꾸지 않습니다.
  2. 서버가 갈 수 있는 길인지 따져서 위치를 계산하고, 방의 상태에 적습니다.

21_state_doc.jpg

Colyseus 공식 문서도 분명히 적어 둡니다.

"Only the server can directly mutate the state." — 상태를 직접 바꿀 수 있는 건 서버뿐

  1. 서버는 1초에 20번, 바뀐 부분만 골라서 방 안의 모든 사람에게 보냅니다. (Colyseus Room의 patchRate 기본값이 50ms = 1초에 20번이고, 문서에 따르면 바뀐 속성만 보냅니다.)

22_two_windows.jpg

  1. 그러면 각자의 Three.js가 받은 위치대로 캐릭터를 그립니다. 그래서 위 화면처럼 서로 다른 두 브라우저에 같은 장면이 보입니다.

점수도 서버가 정한다

23_shooting_score.jpg

사격연습장 점수도 같은 원리입니다. 화면은 "몇 번 표적을 맞혔다"만 보내고, 점수는 서버가 정합니다. 화면에서 점수를 고쳐 보내는 꼼수를 막기 위해서입니다.

24_ranking.jpg

순위표 같은 기록은 따로 API 서버가 데이터베이스에 저장합니다. Colyseus는 지금 이 순간의 상태만 맡습니다.


5. 사람이 몰리면 — 분산 처리

사실 지금 팔복메타는 트래픽 분산 처리가 안 된, 서버 하나짜리 작은 서비스입니다. 그럼 여러분의 메타버스가 혹시 잘돼서 사람이 몰리면 어떻게 해야 할까요?

25_crowd.jpg

방법 자체는 단순합니다. 서버 프로그램(프로세스)을 여러 개 띄워서 나눠 받는 것입니다.

그런데 문제가 생깁니다

26_cannot_meet.jpg

Colyseus의 방은 자기를 만든 프로그램 안에만 있습니다. 다른 프로그램은 그 방이 있는지조차 모릅니다.

A가 서버 ①의 메인 광장에 있을 때 B가 서버 ②에 붙으면, ②는 광장이 있는지 모르니 joinOrCreate(있으면 들어가고 없으면 새로 만든다)로 광장을 따로 하나 더 만듭니다. 같은 광장에 들어가려던 두 사람이 서로 다른 방에 있게 되고, 만날 수가 없습니다.

Colyseus 공식 문서의 답: Redis

27_redis_doc.jpg

"Redis is required for scaling." — 확장하려면 Redis가 필요하다

Redis가 맡는 일은 두 가지입니다.

① RedisDriver = 모든 방의 목록

28_redis_driver.jpg

방 목록이 Redis 한 곳에 모여서, 어느 프로그램이든 빈 방을 찾을 수 있습니다. 서버 ③도 "메인 광장은 서버 ①에 있다"를 알게 됩니다.

② RedisPresence = 프로그램끼리 대화

29_redis_presence.jpg

프로그램들이 Redis를 통해 서로 메시지를 주고받습니다(pub/sub). "이 방에 자리 하나 맡아 줘", "방을 하나 만들어 줘" 같은 식입니다. 공식 문서는 Presence를 "프로세스 사이 통신(IPC)을 맡는 API"라고 설명합니다.

설정은 이렇게 두 줄이 핵심입니다 (Colyseus 0.18 공식 문서 예시).

import { defineServer } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";

const server = defineServer({
  presence: new RedisPresence(),   // 프로그램끼리 대화
  driver: new RedisDriver(),       // 방 목록
});

접속은 두 단계

30_two_step.jpg

  1. 자리 예약 — 아무 프로그램에나 요청해도 됩니다. Presence와 Driver 덕분에 그 프로그램이 방이 어디 있는지 찾아 자리를 맡아 줍니다.
  2. 직접 연결 — 받은 예약 정보로 그 방이 있는 프로그램에 직접 웹소켓을 연결합니다.

이제 B도 A가 있는 서버 ①의 메인 광장에 들어가 둘이 만납니다.

프로그램마다 주소를 따로

31_ports.jpg

직접 찾아갈 수 있도록, 프로그램마다 공개 주소(publicAddress)를 따로 줍니다. 공식 문서 예시는 포트 번호를 하나씩 올려 2567, 2568 … 이렇게 나눕니다.

publicAddress: `backend.yourdomain.com/${Number(process.env.PORT) + Number(process.env.NODE_APP_INSTANCE)}`,

맨 앞에 nginx, 프로그램 여러 개는 PM2 (fork 모드)

32_pm2_fork.jpg

  • 맨 앞에는 nginx 같은 로드밸런서를 두어 처음 들어오는 사람을 나눠 보냅니다.
  • 프로그램 여러 개는 PM2로 띄웁니다. 이때 문서에 따로 적혀 있습니다 — cluster 모드가 아니라 fork 모드로.
// ecosystem.config.js (공식 문서 예시 일부)
module.exports = {
  apps: [{
    port: 2567,
    name: "colyseus",
    script: "build/index.js",
    instances: os.cpus().length,
    exec_mode: 'fork',   // IMPORTANT: DO NOT use 'cluster' mode.
  }]
}

PM2가 NODE_APP_INSTANCE를 포트에 더해 주기 때문에, 첫 번째 프로그램은 2567, 두 번째는 2568 … 로 뜹니다.

한 장으로 정리

33_final.jpg

서버는 여러 개로 늘리고, 그 서버들이 함께 봐야 하는 것은 Redis 한 곳에 모은다. 이것이 분산 처리의 기본 원리입니다.

같은 원리로, 서버 메모리에만 들고 있던 "모두가 함께 봐야 하는 값"(예: 전체 접속자 수 같은 공용 숫자)도 서버를 여러 개로 나누면 각자 따로 세게 되니, 이런 값도 Redis로 옮겨야 한다는 점을 같이 기억해 두면 좋습니다.


6. 세 줄 정리

34_summary.jpg

  1. Three.js는 내 브라우저에서 3D를 그리고, Colyseus는 서버에서 방과 상태를 맡습니다.
  2. 화면은 하고 싶은 것만 보내고, 서버가 정한 상태를 1초에 20번 모두에게 나눠 줍니다.
  3. 사람이 많아지면 서버 프로그램을 여러 개 띄우고, Redis로 방 목록을 함께 보며 서로 대화하게 합니다.

이상입니다. 감사합니다. 끝 👏


참고

※ "AI에게 맡기면 대부분 Three.js + Colyseus로 만들어 준다"는 제 경험입니다.
※ 지금 팔복메타는 분산 처리 없이 서버 하나로 돌아갑니다. 5장은 Colyseus 공식 문서의 방법을 정리한 것입니다.

유튜브에서 보기

댓글 0

아직 댓글이 없습니다.