HTML5 개발

Defold는 다른 플랫폼과 마찬가지로 일반 번들링 메뉴를 통해 HTML5 플랫폼용 게임 빌드를 지원합니다. 또한 생성된 게임은 간단한 템플릿 시스템으로 스타일을 지정할 수 있는 일반 HTML 페이지에 임베드됩니다.

game.project 파일에는 HTML5 전용 설정이 들어 있습니다:

힙 크기

Defold의 HTML5 지원은 Emscripten(참고: http://en.wikipedia.org/wiki/Emscripten)을 기반으로 합니다. 간단히 말해 어플리케이션이 동작하는 힙을 위한 샌드박스 메모리를 생성합니다. 기본적으로 엔진은 넉넉한 메모리(256MB)를 할당합니다. 일반적인 게임에는 충분한 양입니다. 최적화 과정에서 더 작은 값을 사용하도록 선택할 수도 있습니다. 이렇게 하려면 다음 단계를 따르세요:

1. heap_size를 원하는 값으로 설정합니다. 메가바이트 단위로 입력해야 합니다.
2. HTML5 번들을 생성합니다(아래 참고).

HTML5 빌드 테스트

테스트하려면 HTML5 빌드에는 HTTP 서버가 필요합니다. Project ▸ Build HTML5를 선택하면 Defold가 서버를 생성합니다.

번들을 테스트하려면 원격 HTTP 서버에 업로드하거나, 예를 들어 번들 폴더에서 Python을 사용해 로컬 서버를 생성하면 됩니다. Python 2:

python -m SimpleHTTPServer

Python 3:

python -m http.server

또는

python3 -m http.server

HTML5 번들 생성

Defold에서 HTML5 컨텐츠를 생성하는 것은 간단하며, 지원되는 다른 모든 플랫폼과 같은 패턴을 따릅니다. 메뉴에서 Project ▸ Bundle... ▸ HTML5 Application...를 선택합니다:

HTML5 번들은 두 가지 WebAssembly 아키텍처를 지원합니다.

• wasm-web - 일반적인 non-threaded WebAssembly 엔진입니다.
• wasm_pthread-web - thread를 사용할 수 있는 WebAssembly 엔진입니다.

둘 중 하나 또는 둘 다 포함할 수 있습니다. 둘 다 포함하면 브라우저와 호스팅 환경이 지원할 때 loader가 wasm_pthread-web을 선택하고, 그렇지 않으면 wasm-web으로 폴백합니다. 표준 타겟 이름은 Bob 매뉴얼을 참고하세요.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Defold HTML5 번들에는 WebAssembly를 지원하는 최신 브라우저가 필요합니다. Internet Explorer 11은 지원되지 않습니다.

Create bundle 버튼을 클릭하면 어플리케이션을 생성할 폴더를 선택하라는 메시지가 표시됩니다. 익스포트 과정이 완료되면 어플리케이션 실행에 필요한 모든 파일을 확인할 수 있습니다.

WebGL 컨텍스트 버전

graphics.webgl_version_hint로 요청할 그래픽 컨텍스트를 선택합니다. 기본값은 WebGL 2입니다. 두 버전을 모두 지원하는 브라우저에서 WebGL 1을 테스트하거나 대상으로 삼으려면 WebGL 1을 요청하세요.

Defold 1.14.1 버전부터 WebGL 1 쉐이더는 기본적으로 제외됩니다. WebGL 1을 직접 요청하거나 WebGL 2에서 대체하도록 허용할 때 모두 Exclude GLES 2.0을 비활성화해야 포함됩니다. WebGL 1을 명시적으로 요청하려면 game.project에서 두 옵션을 모두 설정합니다:

[graphics]
webgl_version_hint = 1

[shader]
exclude_gles_sm100 = 0

픽셀 비율 제한

html5.min_pixel_ratio와 html5.max_pixel_ratio는 CSS 픽셀당 사용할 캔버스 렌더링 픽셀 수를 제어합니다. 캔버스의 CSS 크기는 페이지에서 게임이 보이는 크기를, 렌더링 해상도는 엔진이 그리는 픽셀 수를 결정합니다.

이 제한을 사용하려면 game.project의 Display 섹션에서 High Dpi를 활성화합니다. 그러면 브라우저의 기기 픽셀 비율이 활성화된 경계 안으로 제한됩니다. 두 제한의 기본값은 0이며 해당 경계를 비활성화합니다. 값은 유한한 음이 아닌 수여야 하고, 둘 다 양수이면 최솟값이 최댓값을 넘으면 안 됩니다.

예를 들어 고밀도 디스플레이의 렌더링 해상도를 제한하려면 비율의 상한을 1.5로 설정합니다:

[display]
high_dpi = 1

[html5]
min_pixel_ratio = 0
max_pixel_ratio = 1.5

기기 픽셀 비율이 3인 브라우저에서 800 × 600 CSS 픽셀로 표시되는 캔버스는 이 설정에 따라 1200 × 900 픽셀로 렌더링됩니다. 표시 크기는 그대로입니다. 비율이 1인 브라우저에서는 최댓값이 비율을 높이지 않으므로 같은 캔버스가 여전히 800 × 600 픽셀로 렌더링됩니다.

1 미만의 소수 비율도 지원합니다. 예를 들어 최댓값이 0.75이면 CSS 표시 크기보다 적은 픽셀을 렌더링합니다. 최솟값을 브라우저의 기기 픽셀 비율보다 높이면 슈퍼샘플링을 위해 렌더링 해상도가 높아집니다. 이 제한은 CSS 레이아웃을 유지하면서 네 가지 Scale Mode 옵션 모두에 적용됩니다.

High Dpi를 비활성화하면 제한과 관계없이 비율은 1입니다. HTML5에서 window.get_display_scale()은 High DPI 설정과 제한을 적용한 실제 렌더링 비율을 반환합니다.

다운로드 검증

HTML5 로더는 기본적으로 다운로드한 엔진 및 아카이브 파일의 크기를 확인합니다. 확인에 실패하면 오류를 보고하기 전에 다운로드를 재시도합니다.

• 엔진의 JavaScript 또는 WebAssembly 다운로드에서 발생한 네트워크 오류, 실패한 HTTP 상태 및 크기 불일치에는 html5.retry_count의 재시도 제한을 사용합니다.
• 아카이브 파일 검증은 크기 또는 SHA-1 불일치에 대해 별도의 재시도 제한을 사용합니다. 검증을 재시도할 때마다 파일의 조각들을 다시 다운로드하며, 각 다운로드에는 일반 네트워크 재시도를 사용할 수 있습니다.

두 경우 모두 재시도 사이의 지연 시간은 html5.retry_time 설정으로 제어합니다.

서버, 프록시 또는 CDN이 제공하는 파일을 의도적으로 변경하여 크기가 달라진다면 game.project에서 크기 검증을 비활성화합니다.

[html5]
verify_downloaded_file_size = 0

Verify Downloaded File Size를 비활성화해도 번들에 포함된 SHA-1 검증은 계속 활성화됩니다. HTML5 프로젝트 설정을 참고하세요.

알려진 이슈와 제약사항

• 핫 리로드 - HTML5 빌드에서는 핫 리로드가 동작하지 않습니다. Defold 어플리케이션이 에디터에서 업데이트를 받으려면 자체적인 소형 웹 서버를 실행해야 하는데, HTML5 빌드에서는 이것이 불가능합니다.
• Chrome
  • 느린 디버그 빌드 - HTML5 디버그 빌드에서는 오류를 감지하기 위해 모든 WebGL 그래픽 호출을 검증합니다. Chrome에서 테스트할 때는 이 과정이 매우 느립니다. game.project의 Engine Arguments 필드를 --verify-graphics-calls=false로 설정하면 이를 비활성화할 수 있습니다.
• 게임패드 지원 - HTML5에서 필요한 특별 고려사항과 절차는 Gamepad 문서를 참조하세요.

HTML5 번들 커스터마이징

게임의 HTML5 버전을 생성할 때 Defold는 기본 웹 페이지를 제공합니다. 이 페이지는 게임이 표시되는 방식을 결정하는 스타일과 스크립트 리소스를 참조합니다.

어플리케이션을 익스포트할 때마다 이 컨텐츠는 새로 생성됩니다. 이러한 요소 중 하나를 커스터마이징하려면 프로젝트 설정을 수정해야 합니다. 이렇게 하려면 Defold 에디터에서 game.project를 열고 html5 섹션으로 스크롤합니다:

각 옵션에 대한 자세한 내용은 프로젝트 설정 매뉴얼에서 확인할 수 있습니다.

game.project에서는 Fullscreen 버튼과 Made with Defold 링크를 끌 수 있습니다. Defold는 index.html에 다크 테마와 라이트 테마를 제공합니다. 기본값은 라이트 테마이며, Custom CSS 파일을 변경해 바꿀 수 있습니다. 또한 Scale Mode 필드에서 선택할 수 있는 네 가지 미리 정의된 스케일 모드가 있습니다.

Downscale Fit and Fit

Fit 모드에서는 화면에 원래 비율로 전체 게임 canvas를 표시하도록 canvas 크기가 변경됩니다. Downscale Fit과의 유일한 차이는 웹 페이지의 내부 크기가 원래 게임 canvas보다 작을 때만 크기를 변경하고, 웹 페이지가 원래 게임 canvas보다 클 때는 확대하지 않는다는 점입니다.

Stretch

Stretch 모드에서는 웹 페이지의 내부 크기를 완전히 채우도록 canvas 크기가 변경됩니다.

No Scale

No Scale 모드에서는 캔버스의 CSS 너비와 높이가 game.project의 Display 섹션에 있는 Width와 Height 값과 일치합니다. 렌더링 해상도에는 실제 픽셀 비율이 계속 적용됩니다.

토큰

index.html 파일을 생성할 때는 Mustache 템플릿 언어를 사용합니다. 빌드하거나 번들링할 때 HTML과 CSS 파일은 프로젝트 설정에 따라 달라지는 값을 특정 토큰으로 대체할 수 있는 컴파일러를 거칩니다. 이 토큰은 문자 시퀀스를 이스케이프해야 하는지 여부에 따라 항상 이중 또는 삼중 중괄호({{TOKEN}} 또는 {{{TOKEN}}})로 둘러싸입니다. 프로젝트 설정을 자주 변경하거나 다른 프로젝트에서 컨텐츠를 재사용하려는 경우 이 기능이 유용할 수 있습니다.

모든 game.project 값은 토큰이 될 수 있습니다. 예를 들어 Display 섹션의 Width 값을 사용하려면:

game.project를 텍스트로 열고 사용하려는 필드의 [section_name]과 이름을 확인합니다. 그런 다음 {{section_name.field}} 또는 {{{section_name.field}}} 형식의 토큰으로 사용할 수 있습니다.

예를 들어 HTML 템플릿의 JavaScript에서는 다음과 같이 사용할 수 있습니다:

function doSomething() {
    var x = {{display.width}};
    // ...
}

또한 다음 커스텀 토큰을 사용할 수 있습니다:

DEFOLD_SPLASH_IMAGE

스플래시 이미지 파일 이름을 쓰거나, game.project의 html5.splash_image가 비어 있으면 false를 씁니다.

{{#DEFOLD_SPLASH_IMAGE}}
		background-image: url("{{DEFOLD_SPLASH_IMAGE}}");
{{/DEFOLD_SPLASH_IMAGE}}

exe-name

허용되지 않는 문자를 제거한 프로젝트 이름입니다.

DEFOLD_ARCHIVE_LOCATION_PREFIX

로더가 사용하는 확정된 아카이브 경로 접두어이며, html5.archive_location_prefix를 기준으로 합니다.

DEFOLD_ARCHIVE_LOCATION_SUFFIX

아카이브 URL에 덧붙이는 확정된 접미어이며, html5.archive_location_suffix를 기준으로 합니다.

DEFOLD_HAS_ARCHIVE_ORIGIN

아카이브 접두사가 //cdn.example.com/archive 같은 프로토콜 상대 URL을 포함하여 HTTP 또는 HTTPS 오리진을 지정하면 true입니다. 상대 아카이브 접두사에는 false입니다.

DEFOLD_ARCHIVE_ORIGIN

스킴, 호스트, 선택적 포트를 포함한 아카이브 오리진이며, 오리진이 지정되지 않으면 빈 문자열입니다. 프로토콜 상대 접두사는 프로토콜 상대 오리진을 만듭니다. preconnect 힌트에 사용됩니다.

DEFOLD_HAS_WASM_ENGINE

번들에 wasm-web 또는 wasm_pthread-web WebAssembly 엔진이 포함되어 있으면 true입니다.

DEFOLD_HAS_WASM_PTHREAD_ENGINE

번들에 wasm_pthread-web이 포함되어 있으면 true입니다. 로더가 런타임에 아키텍처를 선택할 때 잘못된 엔진 variant를 미리 로드하지 않도록 사용하는 값입니다.

DEFOLD_CUSTOM_CSS_INLINE

game.project 설정에 지정된 CSS 파일을 인라인으로 삽입하는 위치입니다.

<style>
{{{DEFOLD_CUSTOM_CSS_INLINE}}}
</style>

DEFOLD_SCALE_MODE_IS_DOWNSCALE_FIT

html5.scale_mode가 Downscale Fit이면 이 토큰은 true입니다.

DEFOLD_SCALE_MODE_IS_FIT

html5.scale_mode가 Fit이면 이 토큰은 true입니다.

DEFOLD_SCALE_MODE_IS_NO_SCALE

html5.scale_mode가 No Scale이면 이 토큰은 true입니다.

DEFOLD_SCALE_MODE_IS_STRETCH

html5.scale_mode가 Stretch이면 이 토큰은 true입니다.

DEFOLD_HEAP_SIZE

game.project의 html5.heap_size에 지정된 힙 크기를 바이트로 변환한 값입니다.

DEFOLD_ENGINE_ARGUMENTS

game.project의 html5.engine_arguments에 지정된 엔진 인자이며 , 기호로 구분됩니다.

build-timestamp

현재 빌드 타임스탬프(초)입니다.

추가 파라미터

커스텀 템플릿을 만들면 전역 CUSTOM_PARAMETERS 오브젝트에 값을 할당해 엔진 로더의 파라미터를 변경할 수 있습니다. 내장 템플릿에는 이러한 커스터마이징을 위한 의도적으로 비어 있는 <script id="engine-setup"> 블록이 있습니다.

예:

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.disable_context_menu = false;
        CUSTOM_PARAMETERS.unsupported_webgl_callback = function() {
            console.log("Oh-oh. WebGL not supported...");
        };
    </script>

CUSTOM_PARAMETERS는 다음을 비롯한 필드를 포함할 수 있습니다.

'archive_location_filter':
    Filter function that will run for each archive path.

'unsupported_webgl_callback':
    Function that is called if WebGL is not supported.

'engine_arguments':
    List of arguments (strings) that will be passed to the engine.

'custom_heap_size':
    Number of bytes specifying the memory heap size.

'disable_context_menu':
    Disables the right-click context menu on the canvas element if true.

'retry_time':
    Pause in seconds before retry file loading after error.

'retry_count':
    How many attempts we do when trying to download a file.

'can_not_download_file_callback':
    Function that is called if you can't download file after 'retry_count' attempts.

'resize_window_callback':
    Function that is called when resize/orientationchanges/focus events happened

'start_success':
    Function that is called just before main is called upon successful load.

'update_progress':
    Function that is called as progress is updated. Parameter progress is updated 0-100.

HTML5의 파일 작업

HTML5 빌드는 sys.save(), sys.load(), io.open() 같은 파일 작업을 지원하지만, 내부에서 이러한 작업을 처리하는 방식은 다른 플랫폼과 다릅니다. 브라우저에서 JavaScript가 실행될 때는 실제 파일 시스템 개념이 없으며 보안상의 이유로 로컬 파일 액세스가 차단됩니다. 대신 Emscripten(따라서 Defold)은 브라우저에서 데이터를 영구적으로 저장하는 데 사용되는 브라우저 내 데이터베이스인 IndexedDB를 사용해 브라우저 안에 가상 파일 시스템을 생성합니다. 다른 플랫폼의 파일 시스템 액세스와 다른 중요한 점은 파일에 쓰는 시점과 변경사항이 실제로 데이터베이스에 저장되는 시점 사이에 약간의 지연이 있을 수 있다는 것입니다. 브라우저 개발자 콘솔에서는 보통 IndexedDB의 내용을 검사할 수 있습니다.

HTML5 게임에 인자 전달

게임이 시작되기 전이나 시작되는 동안 게임에 추가 인자를 제공해야 하는 경우가 있습니다. 예를 들면 사용자 id, 세션 토큰, 또는 게임 시작 시 로드할 레벨일 수 있습니다. 이를 수행하는 방법은 여러 가지가 있으며, 그중 일부를 여기서 설명합니다.

엔진 인자

엔진이 설정되고 로드될 때 추가 엔진 인자를 지정할 수 있습니다. 이러한 추가 엔진 인자는 런타임에 sys.get_config_string()을 사용해 가져올 수 있습니다. index.html의 engine-setup 블록에서 인자를 CUSTOM_PARAMETERS.engine_arguments에 직접 할당하세요.

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.engine_arguments = [
            "--config=example.foo1=bar1",
            "--config=example.foo2=bar2"
        ];
    </script>

새 배열을 할당하면 game.project에서 설정한 엔진 인자를 모두 대체합니다. 기존 인자를 유지하면서 새 인자를 추가하려면 대신 CUSTOM_PARAMETERS.engine_arguments.push("--config=example.foo3=bar3")를 사용하세요.

game.project의 HTML5 섹션에 있는 Engine Arguments 필드에 --config=example.foo1=bar1, --config=example.foo2=bar2를 추가할 수도 있습니다. 쉼표로 구분한 값은 생성된 dmloader.js의 CUSTOM_PARAMETERS.engine_arguments에 추가됩니다.

런타임에는 다음과 같이 값을 얻습니다:

local foo1 = sys.get_config_string("example.foo1")
local foo2 = sys.get_config_string("example.foo2")
print(foo1) -- bar1
print(foo2) -- bar2

URL의 쿼리 인자

페이지 URL의 쿼리 파라미터로 인자를 전달하고 런타임에 읽을 수 있습니다:

https://www.mygame.com/index.html?foo1=bar1&foo2=bar2

local url = html5.run("window.location")
print(url)

모든 쿼리 파라미터를 Lua 테이블로 가져오는 전체 헬퍼 함수:

local function get_query_parameters()
    local url = html5.run("window.location")
    -- URL의 쿼리 부분(? 뒤의 부분)을 가져옵니다
    local query = url:match(".*?(.*)")
    if not query then
        return {}
    end

    local params = {}
    -- 모든 키-값 쌍을 순회합니다
    for kvp in query:gmatch("([^&]+)") do
        local key, value = kvp:match("(.+)=(.+)")
        params[key] = value
    end
    return params
end

function init(self)
    local params = get_query_parameters()
    print(params.foo1) -- bar1
end

최적화

HTML5 게임은 보통 저사양 기기와 느린 인터넷 연결에서도 빠르게 로드되고 잘 실행되도록 초기 다운로드 크기, 시작 시간, 메모리 사용량에 엄격한 요구사항이 있습니다. HTML5 게임을 최적화할 때는 다음 영역에 집중하는 것이 좋습니다:

• 메모리 사용량
• 엔진 크기
• 게임 크기

FAQ

Q: Chrome에서 내 HTML5 앱이 스플래시 화면에서 멈추는 이유는 무엇인가요?

A: 경우에 따라 파일 시스템에서 로컬로 브라우저에서 게임을 실행할 수 없습니다. 에디터에서 실행하면 로컬 웹 서버에서 게임이 제공됩니다. 예를 들어 Python에서 SimpleHTTPServer를 사용할 수 있습니다:

$ python -m SimpleHTTPServer [port]

Q: 로드 중에 내 게임이 “Unexpected data size” 오류와 함께 크래시하는 이유는 무엇인가요?

A: 이는 보통 Windows를 사용하면서 빌드를 만들고 Git에 커밋할 때 발생합니다. Git의 line-ending 설정이 잘못되어 있으면 줄 끝 문자가 변경되고 그에 따라 데이터 크기도 변경됩니다. 문제를 해결하려면 다음 지침을 따르세요: https://docs.github.com/en/free-pro-team@latest/github/using-git/configuring-git-to-handle-line-endings