느린 개발자

 

 

 

[WebGL] 웹 브라우저 환경(Nuxt,React) 에서 WebGl 연결 - 1

이전 포스팅에 이어서 WebGL 프로젝트 빌드와 Nuxt 프로젝트 페이지 화면에 띄우는 방법을 설명하겠습니다.

 

 

WebGL 프로젝트 빌드 파일 구성

• Build 폴더 파일 구성
• [ExampleBuild]는 타깃 빌드 폴더의 이름을 나타냅니다.
• 글자색으로 채워진 Build 파일로 웹브라우저에 연결합니다. (나머지 파일은 일단 사용하지 않음)

파일 이름	내용
[ExampleBuild].loader.js	웹 페이지가 Unity 콘텐츠를 로드하는 데 필요한 JavaScript 코드.
[ExampleBuild].framework.js	JavaScript 런타임 및 플러그인.
[ExampleBuild].wasm	WebAssembly 바이너리.
[ExampleBuild].mem	플레이어의 힙 메모리를 초기화하는 바이너리 이미지. Unity는 멀티 스레드 WebAssembly 빌드에 대해서만 이 파일을 생성합니다.
[ExampleBuild].data	에셋 데이터 및 씬.
[ExampleBuild].symbols.json	오류 스택 추적을 디맹글하는 데 필요한 디버그 심볼 이름. 이 파일은 Debug Symbols 옵션(File > Build Settings > Player Settings)을 활성화한 경우에만 릴리스 빌드에 대해 생성됩니다.
[ExampleBuild].jpg	빌드가 로드되는 동안 표시되는 배경 이미지. 이 파일은 플레이어 설정(File > Build Settings > Player Settings > Splash Image)에서 배경 이미지가 제공된 경우에만 생성됩니다. 자세한 내용은 스플래시 화면 페이지를 참조하십시오.

 

 

WebGL 프로젝트 빌드 설정

 

• 빌드 설정
• File - Build Settings에서 WebGL Platform으로 선택합니다.

 

 

• Player Settings
• WebGL 플레이어 설정 창(메뉴:Edit> Project Settings> Player에서 WebGL을 선택한 후Other Settings섹션 확장에서 Optimization 옵션) -  strip Engine Code 체크 

Player 탭

 

Optimization - stript Engine Code

엔진 코드 스트립 (참고)

이 옵션이 선택되어 있으면 Unity는 사용되지 않은 클래스에 대한 코드를 포함시키지 않습니다. 예를 들어, 물리 컴포넌트 또는 함수를 사용하지 않으면 전체 물리 엔진이 빌드에서 제거됩니다. 테스트 용이니 체크해 줍니다. 만약 물리적인 내용이 들어간 함수나 컴포넌트를 사용할 경우 체크 해제해 줍니다.

 

 

 

 

WebGL 프로젝트 압축 빌드 및 서버 설정

• WebGL 플레이어 설정 창(메뉴: Edit > Project Settings > Player에서 WebGL을 선택한 후 Publishing Settings 섹션 확장)에서 압축 타입

Publishing Settings

• Compression Format: Unity가 빌드 단계에서 파일을 압축하는 방식을 결정합니다.
• Decompression Fallback: 브라우저에서 빌드가 실행될 때 Unity가 다운로드된 파일을 처리하는 방식을 결정합니다.
• WebGL용으로 퍼블리시하는 경우 콘텐츠가 시작되기 전에 사용자가 충분한 다운로드 시간을 얻을 수 있게, 빌드 크기를 작게 유지하는 것이 중요합니다. 에셋 크기를 줄일 수 있는 방법은  빌드 파일 크기 축소  링크로 확인하시면 됩니다.

 

압축	설명
gzip	기본 옵션입니다. Gzip 파일은 Brotli 파일보다 크지만, 빌드 속도가 더 빠르고 모든 브라우저에서 HTTP와 HTTPS를 통해 모두 기본적으로 지원됩니다.
Brotli	Brotli 압축은 최고의 압축 비율을 자랑합니다. Brotli 압축 파일은 gzip보다 작지만 압축하는 데 시간이 더 오래 걸리므로, 릴리스 빌드에서 반복 시간이 늘어납니다. Chrome 및 Firefox는 기본적으로 HTTPS를 통한 Brotli 압축만 지원합니다.
Disabled	압축을 비활성화합니다. 포스트 프로세싱 스크립트에서 자체 압축을 구현하려면 이 옵션을 사용하십시오. 호스팅 서버에서 정적 압축을 사용하려는 경우에도 이 옵션을 사용해야 합니다.

 

현재 저희는 gzip 압축 방식으로 테스트를 진행합니다. 만약에 최적화 고려라면 Brotli 압축 방식으로 진행하시면 됩니다.

 

참고) Brotli 압축방식에서는 Decompression Fallback 설정을 해제해야 하며 ,  배포 서버 Nginx에서 설정이 필요합니다.  자세한 사항은 <서버 설정 코드 참조>

WebGL: 서버 설정 코드 샘플 - Unity 매뉴얼

 

• 설정을 마치고 Build Settings에서 Build를 실행합니다.

 

경로) C:\Users\{개인}\My project/Build 폴더를 확인합니다. (경로는 각자 다를 수 있습니다.)

 

 Decompression Fallback 체크로 인하여 확장자뒤에 unityweb이라는 문구가 붙습니다.

Build 파일

 

---

 

Nuxt 프로젝트 WebGL Build 파일 설정

 

기본적으로 Nuxt 프레임워크를 안다?라는 가정하에 진행하겠습니다.

가장 처음으로 Nuxt 프로젝트를 생성합니다.

Nuxt2로 구성합니다. 아래 표로 버전을 참고해 주세요.

이름	버전
Nuxt	2.15.8
unity-webgl	3.2.0

 

• unity-webgl 이라는 npm 라이브러리 패키지를 사용합니다. 

npm install unity-webgl

 

 

• Static - Build 파일 설정
• Unity에서 빌드한 Webgl 파일을 Nuxt static(정적파일) 폴더에 설정합니다.

Nuxt static 폴더

 

 

Nuxt 프로젝트 WebGL 에디터 컴포넌트 생성

 

• 컴포넌트 안에 EditorViewer라는 컴포넌트를 생성합니다. (폴더 구성과, 이름은 달라도 됩니다.)

Nuxt Components

• unity-webgl을 import 해주고, static 폴더에 이동시켜 둔 Build 파일을 연결합니다.
• 이제 이 컴포넌트를 page index.vue 페이지로 연결합니다.

<template>
  <div id="editor-container">
    <canvas id="canvas" style="width: 1900px; height: 1000px;"></canvas>
  </div>
</template>

<script>
import UnityWebgl from 'unity-webgl';
export default {
  name: "EditorViewer",
  mounted() {
    this.ConfigBuildEditor()
    this.EditorOnLoad()
  },
  data:()=>({
    editor:null,
  }),
  methods:{
    // Static 폴더 Build 파일 연결
    ConfigBuildEditor(){
      this.editor = new UnityWebgl({
        loaderUrl:
          '/Build/app_web.loader.js',
        dataUrl:
          '/Build/app_web.data.unityweb',
        frameworkUrl:
          '/Build/app_web.framework.js.unityweb',
        codeUrl:
          '/Build/app_web.wasm.unityweb',
      })
    },
    // Unity 콘텐츠 화면 로드
    EditorOnLoad(){
      this.editor
        .on('progress', percent =>{
          console.log('Unity Loaded: ', percent)
        })
        .on('created', () => {
         console.log('Unity Instance created: ')
        })
        .on('destroyed', () => console.log('Unity Instance: Destroyed.'))
        .create(document.querySelector('#canvas'))
    },
  }
}
</script>

 

• 웹 브라우저 화면
• 유니티 콘텐츠 화면도 잘 보이고, 화면 내부 버튼도 클릭 가능합니다.

 

unity-webgl

 

 

2023.07 추가사항

이름	버전
unity-webgl	3.5.0

unity-webgl 라이브러리 버전이 3.5.0버전으로 업데이트되어 기능 일부가 변경되었습니다.

 

🚀v3.5.0
feat: reload메서드 및 이벤트를 추가합니다
perf: create및 unload방법을 최적화합니다.

🚀v3.4.0
feat: 구성 및 변경 사항을 전역 개체에 추가합니다 bridge.
feat: Unity 애플리케이션 생성에서 소멸까지의 이벤트를 통합합니다.
beforeMount, mounted, beforeUnmount, unmounted 이벤트를 추가합니다.
created, destroyed.이벤트를 제거합니다. 
perf: 내장 이벤트 리스너를 단순화합니다.
perf: 내장 vue 구성 요소를 최적화합니다.
perf: TypeScript 유형을 업데이트합니다.

 

 

<template>
  <div id="editor-container">
    <canvas id="canvas" style="width: 1900px; height: 1000px"></canvas>
  </div>
</template>

<script>
import UnityWebgl from 'unity-webgl'

export default {
  name: 'EditorViewer',
  data: () => ({
    editor: null
  }),
  mounted() {
    this.ConfigBuildEditor()
    this.EditorOnLoad()
  },
  methods: {
    // Static 폴더 Build 파일 연결
    ConfigBuildEditor() {
      const config = {
        loaderUrl: '/Build/app_web.loader.js',
        dataUrl: '/Build/app_web.data.unityweb',
        frameworkUrl: '/Build/app_web.framework.js.unityweb',
        codeUrl: '/Build/app_web.wasm.unityweb'
      }
      const bridge = 'unity' // default __UnityLib__ 추가
      this.editor = new UnityWebgl(config,bridge)  
    },
    // Unity 콘텐츠 화면 로드
    EditorOnLoad() {
      this.editor
        .on('progress', (percent) => {
          console.log('Unity Loaded: ', percent)
        })
        .on('beforeUnmount', (context) => {}) //추가
        .on('mounted', () => { //추가
          console.log('Unity Instance created: ')
        })
        .on('unmounted', () => console.log('Unity Instance: Destroyed.')) //추가
        .on('reload', (context) => {}) //추가
        .on('error', (error) => {}) //추가
        .create(document.querySelector('#canvas'))
    }
  }
}
</script>

 

bridge 옵션은 다음 포스팅 3편에 유니티와 통신할때 유니티에 jslib 스크립트에서 전역객체로 __unitylib__으로  예를들어서  __UnityLib__.showDialog(data); 이런 형식으로 메서드를 연결했는데 __unitylib__ 객체 이름을 변경하는 옵션입니다. 

new Unity params는 아래와 같습니다.
constructor(config: IUnityConfig, bridge?: string);
constructor(canvas: CanvasElement, config: IUnityConfig, bridge?: string);

굳이 구현된것처럼 안하고 순서에 맞게 할당하셔서 진행하셔도 됩니다.

 

---

여기까지 Unity WebGL 빌드로 , Nuxt 프레임워크 환경에서 유니티 콘텐츠 화면 띄우는 것을 해보았습니다.

 

unity-webgl이라는 npm 패키지 라이브러리를 사용하여 간단하게 연결했습니다. 근데 순수 js로도 연결하는 방법이 있으니 Unity webgl 매뉴얼을 확인하시면 구현 가능합니다. 이제 다음 포스팅으로 React에서 연결하는 방법 또는 웹 브라우저 화면에 있는 버튼에서 유니티 콘텐츠 화면 내부를 제어하는 통신(?) 방법을 설명하겠습니다.

 

틀린 부분이나 수정되어야 할부분은 댓글로 남겨주세요. 

 

읽어주셔서 감사합니다.