0. 들어가기 앞서

✔️ 해당 포스트는 Three.js r155 버전을 기준으로 작성하였습니다

그동안 2D 웹 인터렉션을 공부하고, 이제 정말 하고 싶었던 3D 웹 인터렉션 구현에 대해 공부하며 Three.js 라는 아주 유명한 자바스크립트 3D 라이브러리를 다뤄보고 있다.

공부를 하다보니, 이전의 공부를 통해 익혀둔 2D 인터렉션과 canvas의 활용 등의 내용이 3D 인터렉션을 위한 배경 지식으로 활용되는 경우가 많다고 느껴졌다. 2D 인터렉션보다도 3D 인터렉션을 빠르게 구현해보고 싶었던 마음이 컸기에 다소 흥미가 떨어지는 때도 있었으나, 이 내용들을 알지 못했다면 현재의 공부에 꽤나 지장이 있었겠다는 생각이 들면서 역시 기초가 중요하다는 것을 다시금 느꼈다.

아무튼, 현재 하고 있는 공부들은 정말 배우고 사용해보고 싶었던 3D에 대한 내용들이다 보니 정말 재밌게 학습을 진행하고 있다. 과거 3D 모델링 경험과 Unreal Engine을 사용해 본 경험이 있어서인지 익숙한 단어와 내용들이 많아 심적으로 부담이 덜하다는 것도 한 몫 하는 것 같다.

그런데, Three.js를 사용하면서 조금 의아하고 불편한 부분이 있었다.
공식 문서를 참고하여 코드를 작성하는데 겪은 불편한 점이다보니, 혹시 나와 같은 불편함을 겪은 개발자분들이 계실까 하며 이번 포스트를 작성하고자 한다.

---

1. 무작정 따라했던 Add-on import

Three.js에서는 3D 모델 주위의 궤도를 돌게끔 카메라를 컨트롤하는 OrbitControls 또는 텍스트를 3D 모델화 하는데 사용하는 TextGeometry 등의 다양한 Add-on들이 있다.

이러한 add-on들을 사용하기 위해서는 당연하게도 아래 공식 문서의 내용처럼 해당 클래스를 Import 해주어야 한다.

공식 문서의 내용대로, 아래와 같은 코드로 import문을 작성하여 클래스를 사용해 보았다.

import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';

그런데.. 생태계가 넓은 라이브러리임에도 불구하고, 임포트한 클래스의 툴팁이 뜨지 않아 매번 어떤 파라미터가 있는지, 각 파라미터의 내용은 무엇인지 등에 대한 내용을 찾기 위해 공식 문서를 들락날락 거리며 어지럽게 코드를 작성해야만 했다.

그동안의 경험대로라면, 클래스의 메서드를 사용하는데 있어서 각 메서드의 파라미터들에 대한 설명들을 툴팁에서 빠르게 확인 할 수 있었는데 이러한 간단한 편의기능조차 지원이 안되는 하드코어한 라이브러리인가 하는 충격에 빠졌었다.

---

2. 클래스 툴팁이 없는게 정상인가?

이후, 코드를 작성하면서 지속적으로 불편함을 느꼈고, 공식 문서를 왔다갔다 하며 매번 어떤 파라미터가 있는지 확인하는 작업이 너무 비효율적으로 느껴져 이를 해결하기 위한 방법이 없을까 라는 고민을 하게 되었다.

2-1. 클래스 모듈 파일이 없다?

이를 해결하기 위해 첫번째로 해당 클래스를 직접 열어보고자 ctrl 키를 누른채로 클래스 이름을 선택해 보았었다.

이후, 해당 경로에 있는 TextGeometry.js 파일이 열리지 않고 위 사진처럼 TextGeometry 라는 변수명으로 import 되었다는 짤막한 안내 툴팁만 나오는 것을 확인했으며, VSC의 오류인가 싶어서 직접 해당 경로를 찾아 들어가고자 node_modules 폴더를 열어보던 중

공식 문서에 나온 내용처럼 three라는 폴더 안에 addons라는 폴더가 없다는 것을 확인하고 잠시 머리가 띵해졌다. 숨김 폴더인가..?

2-2. 관련 내용 구글링

공식 문서의 코드 그대로 Import 해온 add-on 클래스는 정상적으로 동작하는 것을 확인 했음에도 불구하고, 해당 클래스와 관련된 파일이 없다는게 너무나도 이상했다. 엄밀히 말하자면, 해당 파일이 있는 경로가 없다는 것이 너무나 혼란스러웠다.

관련 내용을 구글링 하다보니 곧바로 이 경로가 패턴화 된 것이라는 것을 알게 되었다.

아래 내용은 three.js 라이브러리 모듈 폴더의 package.json 파일의 일부 내용이다.

{
  "name": "three",
  "version": "0.155.0",
  "description": "JavaScript 3D library",
  "type": "module",
  "main": "./build/three.js",
  "module": "./build/three.module.js",
  "exports": {
    ".": {
      "import": "./build/three.module.js",
      "require": "./build/three.cjs"
    },
    "./examples/fonts/*": "./examples/fonts/*",
    "./examples/jsm/*": "./examples/jsm/*",
    // ⬇️ HERE !!!
    "./addons/*": "./examples/jsm/*",
    "./src/*": "./src/*",
    "./nodes": "./examples/jsm/nodes/Nodes.js"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/mrdoob/three.js"
  },

/// ...skip

해당 파일에서 알 수 있듯이, "./addons" 라는 경로는 "./examples/jsm" 와 같다.

즉, 실제 경로는 아래와 같았던 것이다.

import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";

그동안 매핑이 된 경로를 사용하다보니 VSC에서 이를 제대로 인식하지 못했었던 것이라고 생각이 들었다. 나는 직접 원래 경로를 따라 TextGeometry.js 파일을 찾았고, 바로 열어보았다.

---

3. 클래스 툴팁은 있었다.

파일을 열어보니 아스타 기호를 사용하여 장황하게 써둔 여러 툴팁 메시지들이 보였고, 실제 작업 환경에서 확인해 보기 위해 클래스 import 경로를 수정하여 확인해 보았다.

짝짝짝...👏🏻👏🏻👏🏻

내가 기대했던 대로, 바라던 대로 클래스 관련 툴팁이 제대로 출력되는 것을 확인할 수 있었다.

이후 코드를 작성하면서도 파라미터들에 대한 설명 툴팁 또한 출력이 되는 것을 확인할 수 있었으며, 그동안의 방식처럼 공식문서를 여기저기 스크롤 해 가면서 확인하던 비효율적인 작업 방식을 벗어날 수 있었다.

---

4. 마치며

코딩을 하다 보면, "이런게 안될리가 없는데" 혹은 "이런것도 되지 않을까" 하는 것들은 거의 대부분 누군가 구현을 해 두었던 적이 많았다. 아직 부족한 내 수준에서 느끼는 불편함 쯤은 이미 멋진 선배 개발자분들께서 작업을 해두신 덕분이다.

이러한 경험들이 있다보니, 이번 경우에도 "클래스 툴팁이 없는게 말이 안되는데" 라는 고민을 함과 동시에 "당연히 무언가 해결 방법이 있겠지" 라는 확신을 가지고 해결 방법을 찾아낸 경우였던 것 같다.

단순한 import 경로의 차이였지만, 이 사소한 차이로 인해 내가 겪은 사이드 이펙트가 있을 수 있다는 것을 새롭게 알았다.

여담으로, three.js 148 버전부터는 'examples/js' 디렉토리가 삭제되고 'examples/jsm' 디렉토리로 변경된 것을 확인할 수 있었다. ES5에서 ES6로 넘어오면서 기존의 script 태그를 이용하던 방식에서 export와 import 키워드를 사용하는 모듈 방식으로 바뀌었고, 그에 맞추어 클래스들을 모듈화 한 결과가 아닐까 생각이 들었다. 관련 글에 따르면, 이러한 ES6 모듈로의 변경 작업을 통해 three.js를 npm으로 설치하고, 각각의 클래스들을 임포트 할 수 있도록 한 것이라고 한다. Javascript 생태계 변화에 맞추어 업데이트가 된 모습이라고 정리할 수 있겠다.

---

참고

discourse.threejs.org / What is the long term plan for the naming of the examples jsm folder...

discourse.threejs.org / The examples js directory will be removed with r148