WebGL: 브라우저 스크립트와 상호작용
WebGL의 커서 잠금 및 전체화면 모드(Cursor locking and full-screen mode in WebGL)

WebGL 템플릿 사용

When you build a WebGL project, Unity embeds the player in an HTML page so that it can be played in the browser. The default page is a simple white page with a loading bar on a grey canvas. Alternatively, you can select a minimal template (with only the necessary boilerplate code to run the WebGL content) in the Player settings (menu: Edit > Project Settings, then select the Player category).

The built-in HTML pages are fine for testing and demonstrating a minimal Player, but for production purposes, it is often good to see the Player hosted in the page where it will eventually be deployed. For example, if the Unity content interacts with other elements in the page via the external call interface then it must be tested with a page that provides those interacting elements. Unity allows you to supply your own pages to host the Player by using WebGL templates.

WebGL 템플릿의 구조

Assets 폴더에 “WebGLTemplates”라는 폴더를 생성하여 커스텀 템플릿을 프로젝트에 추가합니다. 템플릿 자체는 이 폴더 안에 있는 하위 폴더입니다. 각 템플릿 폴더에는 index.html 파일이 페이지에 필요한 이미지나 스타일시트와 같은 기타 모든 리소스와 함께 포함되어 있습니다.

Once created, the template appears among the options on the Player settings. The name of the template is the same as its folder. Optionally, the folder can contain a file named thumbnail.png, which should have dimensions of 128x128 pixels. The thumbnail image is displayed in the inspector to hint at what the finished page will look like.

HTML 파일에는 최소한 다음과 같은 요소가 포함되어야 합니다.

  • Unity WebGL 로더 스크립트 태그: <script src="%UNITY_WEBGL_LOADER_URL%"></script>

  • 게임 인스턴스화 스크립트: <script> var gameInstance = UnityLoader.instantiate("gameContainer", "%UNITY_WEBGL_BUILD_URL%");</script>

  • <div> 태그. 이 태그의 id가 인스턴스화 함수에 사용됩니다. 이 div의 콘텐츠가 게임 인스턴스로 대체됩니다.

UnityLoader.instantiate(container, url, override)

UnityLoader.instantiate는 콘텐츠의 새 인스턴스 생성을 담당합니다.

  • container 는 DOM 요소(일반적으로 <div> 요소)이거나 DOM 요소의 id일 수 있습니다. DOM 요소를 제공하면 게임이 즉시 인스턴스화됩니다. DOM 요소의 id를 제공하면 전체 문서가 파싱된 후에 게임이 인스턴스화됩니다. 따라서 UnityLoader.instantiate() 호출 시에 아직 생성되지 않은 DOM 요소의 id를 제공할 수 있습니다.

  • url 은 빌드에 대한 정보가 포함된 json 파일의 주소를 지정합니다. 빌드 시간에 자동으로 확인될 %UNITY_WEBGL_BUILD_URL% 변수를 사용할 수 있습니다.

  • override 는 게임 인스턴스의 기본 프로퍼티를 오버라이드하는 데 사용할 수 있는 옵션 파라미터입니다. 예를 들어 compatibilityCheck, onProgresspopup 함수는 게임 인스턴스의 프로퍼티이므로 오버라이드할 수 있습니다. Module도 게임 인스턴스의 프로퍼티이므로 Module의 프로퍼티를 인스턴스화 시에 오버라이드할 수도 있습니다. 다음 예제를 한번 살펴보십시오.

UnityLoader.instantiate("MyContainer", "%UNITY_WEBGL_BUILD_URL%", {
  compatibilityCheck: function (gameInstance, onsuccess, onerror) {
    if (!UnityLoader.SystemInfo.hasWebGL) {
      gameInstance.popup("Your browser does not support WebGL",
        [{text: "OK", callback: onerror}]);
    } else if (UnityLoader.SystemInfo.mobile) {
      gameInstance.popup("Please note that Unity WebGL is not currently supported on mobiles. Press OK if you wish to continue anyway.",
        [{text: "OK", callback: onsuccess}]);
    } else if (["Edge", "Firefox", "Chrome", "Safari"].indexOf(UnityLoader.SystemInfo.browser) == -1) {
      gameInstance.popup("Please note that your browser is not currently supported for this Unity WebGL content. Press OK if you wish to continue anyway.",
        [{text: "OK", callback: onsuccess}]);
    } else {
      onsuccess();
    }
  },
  onProgress: MyProgressFunction,
  Module: {
    onRuntimeInitialized: MyInitializationCallbackFunction,
  },
});

템플릿 태그

빌드 프로세스 동안 Unity는 페이지 텍스트에서 특수 태그 문자열을 찾아 에디터에서 제공한 값으로 바꿉니다. 여기에는 이름, 화면상의 크기, 플레이어에 대한 기타 유용한 정보가 포함됩니다.

Tags are delimited by percent signs (%) in the page source. For example, if the product name is defined as MyPlayer in the Player settings:

<title>%UNITY_WEB_NAME%</title>

템플릿 인덱스 파일에 있는 위 구문은

<title>MyPlayer</title>

…in the host page generated for the build. The complete set of tags is given below:

  • UNITY_WEB_NAME: 플레이어 이름

  • UNITY_WEBGL_LOADER_URL: 빌드 인스턴스화를 수행하는 UnityLoader.js 스크립트의 URL

  • UNITY_WEBGL_BUILD_URL: 빌드에 대해 필요한 정보가 모두 포함된 JSON 파일의 URL

  • UNITY_WIDTH, UNITY_HEIGHT: 플레이어가 화면에 표시되는 너비와 높이(픽셀 단위)

  • UNITY_CUSTOM_SOME_TAG: If you add a tag to the index file in the form UNITY_CUSTOM_XXX, then this tag will appear in the Player settings when your template is selected. For example, if you add &lt;title&gt;Unity Player | %UNITY_CUSTOM_MYTAG%&lt;/title&gt; to the source, the Player settings look like this:

태그 이름 옆의 텍스트 상자에는 빌드 중에 커스텀 태그와 교체될 텍스트가 들어 있습니다.

예제

템플릿 태그의 사용법을 설명하기 위해 여기에서는 Unity가 최소 WebGL 템플릿에 사용하는 HTML 소스가 나와 있습니다.

<!DOCTYPE html>
<html lang="en-us">

  <head>
    <meta charset="utf-8">
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Unity WebGL Player | %UNITY_WEB_NAME%</title>
    <script src="%UNITY_WEBGL_LOADER_URL%"></script>
    <script>
    var gameInstance = UnityLoader.instantiate("gameContainer", "%UNITY_WEBGL_BUILD_URL%");
    </script>
  </head>
  
  <body>
    <div id="gameContainer" style="width: %UNITY_WIDTH%px; height: %UNITY_HEIGHT%px; margin: auto"></div>
  </body>
  
</html>

최소 템플릿과 기본 템플릿은 모두 Unity 설치 폴더에서 찾을 수 있습니다. Windows의 경우 Editor\Data\PlaybackEngines\WebGLSupport\BuildTools\WebGLTemplates이고 Mac의 경우 /PlaybackEngines/WebGLSupport/BuildTools/WebGLTemplates입니다.

진행 표시줄 추가

Unity WebGL 콘텐츠는 로드 시 기본 진행 표시줄을 자동으로 렌더링합니다. 다음과 같이 자체 진행률 함수를 추가 인스턴스화 파라미터로 제공하여 기본 로딩 바를 오버라이드할 수도 있습니다.

var gameInstance = UnityLoader.instantiate("gameContainer", "%UNITY_WEBGL_BUILD_URL%", {onProgress: UnityProgress});

여기에서 UnityProgressgameInstance(진행 표시줄이 속해 있는 게임 인스턴스 식별)와 progress(현재 로딩 진행률에 대한 정보를 제공하는 0.0부터 1.0까지의 값)라는 인수 2개의 함수입니다.

예를 들어 기본 WebGL 템플릿의 진행률 함수는 다음과 같습니다.

var gameInstance = UnityLoader.instantiate("gameContainer", "%UNITY_WEBGL_BUILD_URL%", {onProgress: UnityProgress});

예를 들어 기본 WebGL 템플릿의 진행률 함수는 다음과 같습니다.

function UnityProgress(gameInstance, progress) {
  if (!gameInstance.Module)
    return;
  if (!gameInstance.logo) {
    gameInstance.logo = document.createElement("div");
    gameInstance.logo.className = "logo " + gameInstance.Module.splashScreenStyle;
    gameInstance.container.appendChild(gameInstance.logo);
  }
  if (!gameInstance.progress) {    
    gameInstance.progress = document.createElement("div");
    gameInstance.progress.className = "progress " + gameInstance.Module.splashScreenStyle;
    gameInstance.progress.empty = document.createElement("div");
    gameInstance.progress.empty.className = "empty";
    gameInstance.progress.appendChild(gameInstance.progress.empty);
    gameInstance.progress.full = document.createElement("div");
    gameInstance.progress.full.className = "full";
    gameInstance.progress.appendChild(gameInstance.progress.full);
    gameInstance.container.appendChild(gameInstance.progress);
  }
  gameInstance.progress.full.style.width = (100 * progress) + "%";
  gameInstance.progress.empty.style.width = (100 * (1 - progress)) + "%";
  if (progress == 1)
    gameInstance.logo.style.display = gameInstance.progress.style.display = "none";
}

위 함수를 그대로 사용하거나 사용자 지정 템플릿의 레퍼런스로 사용할 수 있습니다. 진행 표시줄은 JavaScript로 완전히 구현되므로 커스터마이즈하거나 대체하여 원하는 항목을 진행률 표시로 나타낼 수 있습니다.


  • 2017–05–24 편집 리뷰 없이 페이지 수정됨

  • Unity 5.6에서 업데이트됨

WebGL: 브라우저 스크립트와 상호작용
WebGL의 커서 잠금 및 전체화면 모드(Cursor locking and full-screen mode in WebGL)