Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

웹 내보내기를 위한 사용자 정의 HTML 페이지

웹 내보내기 템플릿은 추가 사용자 정의 없이 프로젝트를 시작할 수 있는 기본 HTML 페이지를 제공하지만 사용자 정의 HTML 페이지를 생성하는 것이 도움이 될 수 있습니다. 게임 자체는 아직 외부에서 쉽게 직접 제어할 수 없지만 이러한 페이지를 통해 엔진의 초기화 프로세스를 사용자 정의할 수 있습니다.

기본 페이지를 사용자 정의하는 것이 유용한 일부 사용 사례는 다음과 같습니다.

  • 페이지가 아닌 다른 디렉터리에서 파일 로드

  • .pck 파일 대신 .zip 파일을 메인 팩으로 로드합니다.

  • 메인 팩 파일과 다른 디렉터리에서 엔진을 로드합니다.

  • 전체 화면 모드에서 게임을 시작할 수 있도록 클릭하여 플레이 버튼을 추가합니다.

  • 엔진이 시작되기 전에 일부 추가 파일을 로드하여 가능한 한 빨리 프로젝트 파일 시스템에서 사용할 수 있도록 합니다.

  • 사용자 정의 명령줄 인수 전달(예: -s - MainLoop 스크립트를 시작합니다.

기본 HTML 페이지는 `/misc/dist/html/full-size.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/full-size.html>`__의 Godot 엔진 저장소에서 사용할 수 있지만 다음 템플릿을 훨씬 더 간단한 예로 사용할 수 있습니다.

<!DOCTYPE html>
<html>
    <head>
        <title>My Template</title>
        <meta charset="UTF-8">
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="$GODOT_URL"></script>
        <script>
            var engine = new Engine($GODOT_CONFIG);
            engine.startGame();
        </script>
    </body>
</html>

설정

위의 예에서 볼 수 있듯이 이는 대부분 일반 HTML 문서이며, 내보내는 동안 교체해야 하는 몇 가지 자리 표시자, html <canvas> 요소 및 Engine() 클래스를 호출하는 몇 가지 간단한 JavaScript 코드가 있습니다.

필수 자리표시자는 다음과 같습니다:

  • $GODOT_URL: 엔진을 시작하는 데 필요한 Engine() 클래스를 제공하고 HTML에 ``<script>``로 포함되어야 하는 기본 JavaScript 파일의 이름입니다. 이름은 내보내기 프로세스 중에 *내보내기 경로*에서 생성됩니다.

  • $GODOT_CONFIG: 내보내기 옵션을 포함하고 나중에 재정의할 수 있는 JavaScript 개체입니다. 재정의 전체 목록은 :js:attr:`EngineConfig`를 참조하세요.

다음 선택적 자리 표시자는 사용자 정의 HTML 템플릿에서 몇 가지 추가 기능을 활성화합니다.

  • $GODOT_PROJECT_NAME: **프로젝트 설정 > 애플리케이션 > 구성**의 Name 설정에 정의된 프로젝트 이름입니다. 템플릿에서 ``<title>``로 사용하는 것이 좋습니다.

  • $GODOT_HEAD_INCLUDE: <head> 태그 끝 부분 바로 앞에 HTML 문서에 포함할 사용자 정의 문자열입니다. Html / Head include 섹션 아래의 내보내기 옵션에서 사용자 정의됩니다. 생성한 HTML 페이지를 완전히 제어하는 동안 이 변수는 Godot 편집기에서 HTML head 요소의 일부를 구성하는 데 유용할 수 있습니다. 다양한 웹 내보내기 사전 설정용.

  • $GODOT_SPLASH: **프로젝트 설정 > 애플리케이션 > 부트 스플래시**의 Image 설정에 정의된 대로 부트 스플래시로 사용되는 이미지의 경로입니다.

  • $GODOT_SPLASH_COLOR **프로젝트 설정 > Application > Boot Splash**의 BG Color 설정에 정의된 스플래시 화면 배경색은 16진수 색상 코드로 변환됩니다.

  • $GODOT_SPLASH_CLASSES: 이 자리 표시자는 시작 화면에 영향을 미치는 설정 이름과 해당 값의 문자열을 제공합니다. 이 문자열은 CSS 클래스 이름 집합으로 사용되며, 이를 통해 스플래시 프로젝트 설정에 따라 스플래시 이미지 스타일을 지정할 수 있습니다. **프로젝트 설정 > Application > Boot Splash**의 다음 설정이 제공되며, 설정의 부울 값에 따라 아래 표시된 클래스 이름으로 표시됩니다.

사용자 정의 페이지가 준비되면 Html / Custom Html Shell 섹션 아래의 내보내기 옵션에서 선택할 수 있습니다.

../../../_images/html5_export_options.png

프로젝트 설정하기

게임을 시작하려면 엔진을 초기화하는 스크립트(제어 코드)를 작성해야 합니다. 이 프로세스는 세 단계로 구성되지만 여기에 표시된 것처럼 사용자 정의가 필요한 정도에 따라 대부분을 건너뛸 수 있습니다.

사용 가능한 전체 메소드 및 옵션 목록은 :ref:`HTML5 쉘 클래스 참조 <doc_html5_shell_classref>`를 참조하세요.

먼저 엔진을 로드한 다음 초기화해야 하며, 그 후에 최종적으로 프로젝트를 시작할 수 있습니다. 이러한 모든 단계를 수동으로 효과적으로 제어할 수 있습니다. 그러나 가장 간단한 경우에는 내보낸 구성을 사용하여 Engine() 클래스의 인스턴스를 만든 다음 선택적으로 EngineConfig 매개 변수를 재정의하는 engine.startGame 메서드를 호출하기만 하면 됩니다.

const engine = new Engine($GODOT_CONFIG);
engine.startGame({
    /* optional override configuration, eg. */
    // unloadAfterInit: false,
    // canvasResizePolicy: 0,
    // ...
});

이 코드 조각은 게임을 시작하기 전에 엔진을 자동으로 로드하고 초기화합니다. 엔진을 로드하기 위해 주어진 구성을 사용합니다. engine.startGame 메서드는 비동기식이며 ``Promise``를 반환합니다. 이를 통해 제어 코드는 실행을 차단하거나 폴링에 의존하지 않고 게임이 올바르게 로드되었는지 추적할 수 있습니다.

프로젝트에서 시작 인수 및 종속성 파일에 대한 특별한 제어가 필요한 경우 engine.start 메서드를 대신 사용할 수 있습니다. 이 방법은 pck 파일을 자동으로 사전 로드하지 않으므로 engine.preloadFile 방법을 통해 해당 파일(및 기타 추가 파일)을 수동으로 사전 로드하는 것이 좋습니다.

선택적으로 :js:meth:`engine.init <Engine.prototype.init>`를 수동으로 수행하여 모듈 초기화 후 엔진이 시작되기 전에 특정 작업을 수행할 수도 있습니다.

이 프로세스는 좀 더 복잡하지만 엔진 시동 프로세스를 완벽하게 제어할 수 있습니다.

const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
    // Load and init the engine
    engine.init(myWasm),
    // And the pck concurrently
    engine.preloadFile(myPck),
]).then(() => {
    // Now start the engine.
    return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
    console.log('Engine has started!');
});

엔진을 수동으로 로드하려면 Engine.load() 정적 메서드를 호출해야 합니다. 이 방법은 정적이므로 동일한 ``wasm``를 공유하는 경우 여러 엔진 인스턴스가 생성될 수 있습니다.

참고

엔진은 초기화된 후 즉시 언로드되므로 기본적으로 여러 인스턴스를 생성할 수 없습니다. 이러한 일이 발생하지 않도록 하려면 unloadAfterInit 재정의 옵션을 참조하세요. 이후에도 Engine.unload() 정적 메서드를 호출하여 엔진을 수동으로 언로드할 수 있습니다. 엔진을 언로드하면 인스턴스가 초기화된 후 더 이상 필요하지 않은 파일을 언로드하여 브라우저 메모리를 확보할 수 있습니다.

빌드 커스터마이징하기

웹 환경에서는 게임이 의도한 대로 작동하도록 보장하기 위해 여러 가지 방법을 사용할 수 있습니다.

특정 버전의 WebGL을 대상으로 하거나 WebGL을 사용할 수 있는지 확인하려는 경우 Engine.isWebGLAvailable() 메서드를 호출할 수 있습니다. 선택적으로 WebGL의 특정 주요 버전을 테스트할 수 있는 인수를 사용합니다.

웹 환경에는 실제 실행 파일이 존재하지 않기 때문에 엔진은 로드된 엔진 파일의 기본 이름으로 구성된 가상 파일 이름만 저장합니다. 이 값은 OS.get_executable_path() 메서드의 출력에 영향을 미치고 자동으로 시작되는 기본 팩의 이름을 정의합니다. executable 재정의 옵션을 사용하여 이 값을 재정의할 수 있습니다.

프레젠테이션 사용자 정의

여러 구성 옵션을 사용하여 페이지에서 게임의 모양과 동작을 추가로 사용자 정의할 수 있습니다.

기본적으로 페이지의 첫 번째 캔버스 요소가 렌더링에 사용됩니다. 다른 캔버스 요소를 사용하려면 canvas 재정의 옵션을 사용할 수 있습니다. DOM 요소 자체에 대한 참조가 필요합니다.

const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });

엔진이 캔버스 크기를 조정하는 방식은 canvasResizePolicy 재정의 옵션을 통해 구성할 수 있습니다.

게임을 로드하는 데 시간이 좀 걸리는 경우 진행 상황을 추적하는 사용자 정의 로딩 UI를 표시하는 것이 유용할 수 있습니다. 이는 엔진이 새 바이트를 로드할 때 정기적으로 호출되는 콜백 함수를 설정할 수 있는 onProgress 콜백 옵션을 사용하여 달성할 수 있습니다.

function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });

어떤 경우에는 ``total``가 ``0``일 수 있다는 점에 유의하세요. 즉, 계산할 수 없습니다.

게임이 여러 언어를 지원하는 경우 유효한 언어 코드 문자열이 있는 경우 locale 재정의 옵션을 사용하여 특정 로케일을 강제 적용할 수 있습니다. 사용자가 선호할 수 있는 언어를 결정하려면 서버 측 논리를 사용하는 것이 좋습니다. 이런 방식으로 언어 코드는 Accept-Language HTTP 헤더에서 가져오거나 GeoIP 서비스에 의해 결정될 수 있습니다.

디버깅

내보낸 프로젝트를 디버깅하려면 엔진에서 생성된 표준 출력 및 오류 스트림을 읽는 것이 유용할 수 있습니다. 이는 편집기 콘솔 창에 표시된 출력과 유사합니다. 기본적으로 표준 console.log 및 ``console.warn``는 각각 출력 및 오류 스트림에 사용됩니다. 이 동작은 메시지를 처리하는 자체 기능을 설정하여 사용자 정의할 수 있습니다.

출력 스트림에 대한 콜백 기능을 설정하려면 onPrint 재정의 옵션을 사용하고, 오류 스트림에 대한 콜백 기능을 설정하려면 onPrintError 재정의 옵션을 사용하세요.

function print(text) {
    console.log(text);
}
function printError(text) {
    console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });

엔진 출력을 처리할 때 완제품으로 출력하는 것은 바람직하지 않을 수 있다는 점을 염두에 두시기 바랍니다.