하이브 코딩. 3D 월드 생성 모듈화

※ 하이브 코딩은 AI코딩으로 만든 산출물을 코딩을 공부하면서 내것으로 소화하고 재활용 가능한 모듈로 묶어 자산화하는 방법으로 제가 만든 용어입니다. 실험적 접근이라 어디까지 될지 장담할수 없는 도전 단계인 점 참조 부탁드립니다.

지난 시간에는 안티그래비티 IDE 프로그램을 설치하고 기존 바이브 코딩처럼 3D월드를 간단히 생성하는 부분을 다루었습니다.

https://itadventure.tistory.com/939

문제는 이렇게 바이브 코딩으로 생성한 1회용 코드는 매번 결과가 달라지기 때문에 관리하기 어려운데요,
오늘은 이러한 기능을 기능 단위로 쪼개서 '모듈화'하는 부분을 살펴보겠습니다.
html, 자바스크립트 기초 정도는 숙지하셨다는 걸 전제로 합니다.

# 모듈이란?

모듈이란 기능을 단위로 묶어서 코드 덩어리로 만든 것인데요.
이렇게 만든 모듈은 마치 레고 블록과 같아서 사용법만 알면 언제든 재활용할수 있습니다.

# 기본 세팅

폴더를 새로 만들고 안티그래비티 IDE를 열어 해당 폴더를 열어줍니다.
지난 시간에 만들었던 폴더를 열고 이지 만들어진 index.html 파일을 삭제해주셔도 됩니다.

그리고 하이브 코딩을 위한 간단한 세팅을 잡아 줄텐데요.
GEMINI.md 파일을 만들고 아래 규칙을 입력해 주세요.
그러면 이 규칙을 항상 최우선으로 코딩을 작성해 줍니다.

# 프로젝트 가이드

## 기술 스택
- babylon.js, CDN 사용
- html, jquery

## 파일 구성
- html, css, js 분리
- js 는 기능성 모듈 단위로 분리

# 최신 모델

AI채팅 창애서 모델을 선택하실 수 있는데요.
최신 빨라지고 똑똑한 모델을 선택합니다.
이 글을 쓸때는 Gemini 3.6 Flash 가 최신인데 나중에 바뀔순 있습니다.
Gemini 3.6 Flash(Medium) 정도면 충분합니다.

# 간결한 프롬프트, 작게 구현

이제 프롬프트는 아래와 같이 써줍니다.
앞에서 GEMINI.md 파일에 주요 내용을 적었기 때문에 이 정도면 충분합니다.

3차원 월드를 만들어줘. 우선 바닥만 먼저 구현해줘

어떤 결과가 나왔을까요? 짜잔~

마우스로 클릭해 돌려볼수도 있고, 마우스 휠을 돌려 확대/축소도 할 수 있는 3차원 공간입니다.

사실 AI는 매번 다른 결과를 내기 때문에 여러분은 저와 결과가 다를 겁니다.
저는 이런 결과가 나왔는데요.
용도별로 기능을 아주 세분화해서 코드를 생성해준 것을 볼 수 있습니다.
어휴 꽤나 세분화해주었네요.

이렇게 세분화하면 좋은 점이 있습니다.
기능을 수정할 때 AI가 참조하는 코드량이 줄어들어 토큰 소모도 줄어든다는 점이지요.
그래서 '모듈' 단위로 코드를 분리하는게 좋은 겁니다.
사실 사람 개발자도 이렇게 모듈 단위로 분리된게 좋습니다.

# 각 기능을 물어보기

js폴더에 여러 파일들이 바로 기능별 구분된 모듈들입니다.
이 파일들이 각각 뭐하는 건지, 그리고 사용법은 어떤건지 AI에게 물어보면 됩니다.

각각 구현된 모듈의 용도와 사용법을 정리해줘

그러면 쫙 정리해주는데요.

마음가짐이 중요합니다.
이걸 다 언제 이해하지? 생각하면 '짐'이 되지만 하나만이라도 이해해서 내 껄로 소화한다면
언제든 사용할 수 있는 자산이 되는 셈입니다.

# 그래도 가져갈 선행 지식

3D 가상공간은 필수 요소들이 있습니다.
이런게 '필요하다'는 사실 정도 이해하면 코드 구성을 이해하기 수월한데요.
기본적으로 '땅바닥' 외에도 '빛'과 '카메라'가 있어야 합니다.

'빛'이 없으면 어두컴컴해 볼수가 없기 때문이고,
'카메라'는 마치 영화감독이 영화를 촬영할 때 카메라맨에게 이 방향에서 촬영하라고 하듯이
3D 공간을 촬영할때도 마찬가지로 카메라가 필요하기 때문입니다.

# 시작은 어디?

AI에게 물어봐도 됩니다.

이거 제일 처음 시작하는 부분은 어디지? 간략히 적어줘

가장 처음 시작하는 위치는 

js/app.js
 의 $(document).ready(...) 구문입니다.



index.html
 접속


js/app.js
 의 $(document).ready() 함수 자동 실행
EngineModule, CameraModule, LightModule, GroundModule 순서로 3D 월드 조립 및 렌더링 시작

'간략히'를 안 적어주면 장황하게 적어주거든요.
근데 장황한 내용도 한번 읽어보면 좋은 내용이긴 합니다.
그 내용들을 소화할 선제 지식이 필요하긴 한데, 그런 것들도 AI에게 하나 하나 물어보면 됩니다.
마치 '가정교사' 처럼 말이지요 :)

# 도식화

글이 한눈에 들어오지 않는다면, 그림을 이용해도 좋습니다.
그림이 더 이해가 쉽긴 하거든요. 아래와 같이 요청하면 그림을 생성해 줍니다.

전체적인 흐름을 한글로 이미지로 생성해줘.

이 때 '한글로' 문구는 꼭 넣어 주셔야 합니다.
보통은 영어로 만들어 주거든요.

이미지를 잘 생성할때도 있지만 안되면 다시 요청하면 됩니다.
아래 도식 화면이 표준 3D웹의 정석입니다. 글보다는 이해하기 쉬우실 겁니다 :)

사실 처음 그림을 보면 왜 이렇게 복잡해? 할수 있는데요.
처음 접하면 '개념'을 몰라서 그렇습니다.
그러니 그냥 여러번 반복해서 보다 보면 익숙해집니다. 
그 익숙함이 쌓이면 코드도 볼 수 있게 되고 그게 바로 내공이 되는 것이지요 :)

# 코드 뜯어보기. index.html 웹페이지

이제 웹페이지 index.html을 보겠습니다. 전체 코드는 본문 아래 수록할께요.
사실 AI 에게 설명해달라고 해도 되지만, AI는 사용자의 '선제 지식'이 어느정도인지 모르기 때문에 좀 복잡하게 설명합니다.
제가 좀 풀어 설명드리면,

1. 바빌론JS CDN 가져오기

강력한 3차원 라이브러리 babylon.js 를 CDN에서 가져다 쓰려면 아래 코드가 있어야 합니다.

<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/materialsLibrary/babylonjs.materials.min.js"></script>

윗줄이 바빌론 CDN을 가져다 쓰는 선언부이고,
그 아랫 부분은 '메터리얼'이라고 해서 물의 표면이나 유용한 여러가지 표면 이미지를 사물 표면에 입히는 자원입니다.

2. 캔버스 정의하기

3D 가상공간은 일반 웹방식으로 작동하지 않습니다.
반드시 캔버스(canvas) 기술을 사용해야 하는데요.
아래 코드가 바로 캔버스를 정의한 부분입니다.

<canvas id="renderCanvas"></canvas>

이 캔버스를 연결해서 사용하는 것이지요.
참고로 이 캔버스는 스타일 시트를 이용해 크기를 조정하는 것도 가능합니다.

3. 스크립트 정의부

아래 코드는 모듈화된 각 스크립트를 사전에 불러오는 부분입니다.

<script src="js/engine.js"></script>
<script src="js/camera.js"></script>
<script src="js/light.js"></script>
<script src="js/ground.js"></script>
<script src="js/app.js"></script>

위에서부터 게임엔진, 카메라, 빛, 땅바닥, 시작 및 통합처리를 담당하는 모듈인데요.
보통 메인으로 app.js 이름을 많이 씁니다.
※ 여기서 꿀팁 하나!app.js는 모든 모듈을 통합 호출하기에 항상 맨 마지막에 위치해야 합니다.
AI를 이용해 기능을 추가하다 보면 새로운 모듈을 app.js 아래 위치하는 경우가 많은데요.

예시)
<script src="js/app.js"></script>
<script src="js/box.js"></script>

이 경우 거의 90%는 작동이 안됩니다.
AI도 이런 에러는 쉽게 잡아 내지 못하는 데요.이 경우 아래처럼 순서를 바로 잡아주어야 정상 작동하는 경우가 많습니다.

수정)
<script src="js/box.js"></script>
<script src="js/app.js"></script>

# 코드 뜯어보기. app.js

오늘은 app.js 까지만 뜯어보기로 합시다.app.js 는 모든 걸 통합 관리하기에 소스코드 전체를 봐야 합니다.
저의 경우 아래와 같이 작성해 주었는데요.

/**
 * 메인 애플리케이션 진입점 (App)
 */
$(document).ready(function () {
    const canvas = document.getElementById("renderCanvas");

    // 1. Engine & Scene 초기화
    const scene = EngineModule.init(canvas);

    // 2. Camera 설정
    const camera = CameraModule.initCamera(scene, canvas);

    // 3. Light 설정
    LightModule.initLights(scene);

    // 4. Ground (3D 월드 바닥) 생성
    GroundModule.createGround(scene, {
        size: 80,
        subdivisions: 2
    });

    // 5. Render Loop 시작
    EngineModule.startRenderLoop();

    console.log("3D World Ground initialized successfully.");
});

1. 스크립트의 시작

우리는 jQuery 를 사용했기 때문에 이 부분을 보시면 됩니다.

$(document).ready(function () {

   :
   
});

그냥 이 부분은 페이지가 로딩되고 맨 처음 시작되는 부분이다~ 라고 외워두시면 세상 편하거든요.
jQuery는 이 부분이 극단적으로 이해하기가 쉽습니다. ㅎㅎ
이 코드 안에 아래 코드들이 차례대로 실행됩니다.

2. 캔버스 연결

이제 웹페이지에 있는 캔버스를 연결해야 사용할 수 있습니다.
그게 바로 아래 코드입니다. 

const canvas = document.getElementById("renderCanvas");

canvas 변수에 연결해놓고 주물럭 주물럭 하는 거지요.
이렇게 변수에 연결해 놓으면 무엇보다 속도가 빠릅니다.

3. 3D엔진 초기화

아래 코드는 3D엔진을 초기화하는 부분인데요.

const scene = EngineModule.init(canvas);

이 캔버스는 사실 3D전용이 아닙니다.
2D게임을 만들수도 있는게 바로 캔버스인데요.
바빌론JS에서 '이건 내가 3D용으로 쓰겠다'고 하면 3D용으로 바뀌는 겁니다.EngineModule 은 engine.js에 들어 있는데요.
정확한 코드는 이해하지 않아도 상관없습니다.
일단은 이렇게 쓴다는 사용법만 이해하면 되는 것이지요.

4. 카메라 설정

카메라를 설정하는 코드입니다. camera.js 에 연결되어 있습니다.

const camera = CameraModule.initCamera(scene, canvas);

3D 가상 공간이 2D웹브라우저와 가장 큰 차이는 보는 시점이 현실 세계와 같다는 건데요.
2D웹 브라우저는 항상 좌측상단에서 시작해서 X, Y죄표에 그림이나 텍스트를 위치합니다.
하지만 3D 공간은 내가 바라보는 방향의 사물을 봅니다. 입체적으로요. 마치 현실과 같죠.

그래서 3D 게임을 해보신 분들이라면 이 개념이 이해가 쉬운데요.
고개를 돌리면 그쪽 방향의 사물들이 보이는 방식인데. 그 눈이 되는 지점이 바로 '카메라'입니다.
마우스로 화면을 돌려보는 것도 여기서 처리합니다.이렇게 카메라를 정의하고 회전 액션을 하면 다른 방향의 사물이 보이는 방식입니다.
카메라는 3D의 기본 개념 중 하나입니다.

4. 빛 설정

빛 설정 코드는 아래와 같습니다. light.js 에 연결되어 있습니다.

LightModule.initLights(scene);

3D공간의 사물들이 보이려면 반드시 빛이 있어야 합니다. ( 예외는 있습니다만.. )
이 부분을 정의하는 것이지요.

5. 땅바닥

아래 코드는 땅바닥입니다. ground.js 에 연결되어 있는데요.

// 4. Ground (3D 월드 바닥) 생성
GroundModule.createGround(scene, {
    size: 80,
    subdivisions: 2
});

꽤 잘 만들었네요.
최소한의 파라미터, 측 땅바닥의 '크기'와 '면의 분할' 정도만을 전달하는 구조라서
크기만을 변경할 때는 ground.js 코드를 볼 필요가 없습니다.

6. 루프

마지막으로 루프 처리 부분입니다. engine.js에 연결되어 있습니다.

EngineModule.startRenderLoop();

3D 공간에서는 사물의 움직임이나 회전, 마우스로 카메라를 돌려보는 동작 조차도 액션 후에는 화면이 바뀌어야 하거든요. 근데 다시 화면을 그려주는 '랜더링'이란걸 해주지 않으면 안 바뀝니다.
그걸 처리하는 부분이라 보시면 됩니다.
한번만 콜하면 Babylon.js 가 앞으로 자동으로 계속 랜더링해 줍니다.# 총 정리전체 과정은 아래와 같습니다.=> 시작 index.html 웹페이지
=> 여러 스크립트를 불러오고 app.js 의 '도큐먼트 레디!' 자동 실행 : $(document).ready(function () { ... });
=> 캔버스 연결
=> 3D엔진 초기화
=> 카메라, 빛 세팅
=> 땅바닥 만들기
=> 자동 랜더링을 위한 랜더링 시작 호출

처음에는 조금 복잡하게 느껴질 수 있지만 익숙해지면 금방 친해집니다.

# 전체 코드(Git)

아래 GIT에 방문하시면 위 전체 코드를 확인하실수 있습니다.

https://github.com/goodsdrlee-del/babylonjs1.git

GitHub - goodsdrlee-del/babylonjs1: 하이브 코딩으로 만든 바빌론JS 예제

AI코딩을 다루지만 이 게시글은 생성된 코드, 이미지를 제외하곤 순수 '사람 크레이글'입니다 :)