Web / HTML5 link

Ren’Py支持在Web瀏覽器上運行遊戲。該功能是在某個版本Ren’Py已完全編譯為 WebAssembly，實現了瀏覽器端運行大多數Ren’Py的大部分要求。本頁面解釋了在瀏覽器上運行的一些限制，幫助創作者在設計階段就避免踩坑；同時也解釋了打包Web端程序的方法。

限制 link

與其他運行在Web瀏覽器上的遊戲類似，Ren’Py遊戲也有一些限制。其中一些是瀏覽器內部的沙盒機制導致，另一些則是出於遊戲運行需要下載數據的考量。

具體限制包括：

使用瀏覽器內建影片播放器播放影片檔案。 renpy.movie_cutscene() 可以支持的影片格式，不一定也可以在Web瀏覽器裡播放。
使用瀏覽器支持的音訊格式播放音訊檔案更快。使用Ren’Py內的音訊播放器慢一些，但是能用的格式更多。詳見後續章節。
Web端不支持多執行緒，因此 renpy.invoke_in_thread() 函數和Python模組 threading 不能使用。某些遊戲的性能表現也會下降，在電腦和手機上運行Ren’Py可以在後台預載入，但Web端不行。因此Web端載入圖像時可能會掉幀。
網路功能也不支持。雖然聽起來很讓人震驚，但瀏覽器的沙盒環境不允許Ren’Py發起網路請求。這表示使用socket埠和requests庫在Web瀏覽器上都會報錯。

除此之外，還有一些限制是由伺服器主機造成的。有些主機對單個項目的遊戲大小和文件總數量有限制。例如 itch.io 就有這樣的限制。瀏覽器則有其他限制：超過50MB大小的文件不會被cache快取，因此較大的文件每次執行遊戲都要重新下載。

支持的瀏覽器 link

我們盡力讓Ren’Py能運行在一些主流網頁瀏覽器的近期版本上，比如Chrome、Edge、Firefox和Safari，以及這些瀏覽器的iOS和安卓版本。 Ren’Py也可能在其他瀏覽器上運行，但主要取決於那些瀏覽器對WebAssembly的支持，已經其他的Ren’Py功能要求。

Ren’Py不會使用Web端近期的一些花裡胡哨的功能特性，所以不在乎那些功能是否被禁用。

While we try to keep Ren’Py running, Ren’Py can push the edge of what a browser is capable of, and so it’s possible that changes to the browsers will render them incapable of running games. (譯者註：上一句是吹厲害內容。)

我們會更隨各種瀏覽器更新，盡可能確保瀏覽器能正常運行Ren’Py，但依然存在每次瀏覽器的某次變更後可能要求遊戲更新。

遊戲打包 link

在啟動器使用Web(Beta)選項就能生成Web平台的包了。其中有4個主要選項。

構建網頁應用

選擇該項會生成一個Web平台的包(package)。最終結果是一個包含整個遊戲的 web.zip 文件，以及一個包含遊戲中各資源文件的文件夾。 (實際上不能在文件夾中運行遊戲，需要一個Web伺服器的host服務。)

構建應用並在瀏覽器中打開

選擇該項會生成一個Web平台的包(package)，並使用本地Web瀏覽器打開並測試。你的電腦上會自動運行一個Web服務以裝載遊戲，然後使用瀏覽器接入該Web服務。

這是測試遊戲的常用方式。

在瀏覽器中打開

選擇該項，不經過完整的構建流程，直接嘗試用你電腦的本地Web瀏覽器接入Web服務i

打開構建目錄

選擇該項，會打開構建後包含生成文件的目錄。

上傳遊戲 link

正確構建遊戲後，你需要找個公共Web伺服器並上傳。像 itch.io 之類的平台，你需要上傳 web.zip 文件，該文件包含所有遊戲所有資源。其他平台可能需要上傳web文件夾裡的所有內容。

如果你為自己的遊戲搭建了主機，需要確保自己的Web服務中的 .wasm 文件使用 application/wasm MIME 類型。這樣設置可以更快載入遊戲，並且防止運行時的警告(warning)資訊。

presplash link

Web平台原生使用預設的preslash圖片。若要更換，需要提供一個名為 web-preslash 的圖片，圖片後綴可以是 .jpg、.png 或 .webp。該圖片會替換預設的preslash並顯示。

.webp 格式文件，可以是多幀動畫。

Icon link

If no custom image is given, the default Ren’Py icon is used. 在項目根目錄中放入名為 web-icon.png 的圖片文件，就更改了Web版本的頁面圖示。該圖示文件必須寬高相等，並且解析度不小於512×512像素。

流程化下載 link

Ren’Py支持流程化下載功能特性，可以在項目底層目錄中的 progressive_download.txt 文件中。如果文件不存在，則在首次打包web平台的包是將創建該文件。文件的默認內容如下：

# RenPyWeb progressive download rules - first match applies"
# '+' = progressive download, '-' = keep in game.zip (default)
# See https://www.renpy.org/doc/html/build.html#classifying-and-ignoring-files for matching
#
# +/- type path
- image game/gui/**
+ image game/**
+ music game/audio/**
+ voice game/voice/**

該文件的內容決定了，那些文件要在遊戲開始前下載，那些文件根據遊戲進度下載。 # 符號開頭的那些是注釋。以減號“-”開頭的行，表示要在遊戲開始前下載，通常是一些開場界面就會用到的資源文件。以加號“+”開頭的行，表示會根據實際需要下載。

文件的第二列表示文件類型，以及Ren’Py的處理方式。具體類型包括：

image

圖片文件會生成一個低像素的版本，並在載入時用於代替完整的圖片。在很多情況下，Ren’Py可以預載入圖片並在需要顯示完整圖像時直接載入。所以低像素圖片只會在短時間內沒辦法載入完整圖片時出現。

如果完整圖片始終無法載入，那可能是Web伺服器上有錯誤數據。

music

只有整個音樂文件載入完成後才開始播放。

voice

只有整個語音文件載入完成後才開始播放。

最後一列表示文件所在目錄。

音訊與影片 link

由於瀏覽器總是會阻止廣告播放聲音，音效和音樂文件只有在用戶至少點擊一點遊戲後才開始播放。

Ren’Py有兩種方式播放音訊檔案。第一種是使用瀏覽器內建的webaudio系統，第二種是使用自身的音訊播放系統。 webaudio系統速度更快，但在Safari瀏覽器上，ogg格式的音訊無法播放。

配置項 config.webaudio_required_types 決定使用哪種音訊系統。如果遊戲中只使用mp3文件，可以這樣配置：

define config.webaudio_required_types = [ "audio/mpeg" ]

播放影片時，有兩個相關控制配置項：

config.web_video_base

該項是一個URL連結，與影片檔案名相連後得到完整的影片播放連結地址。可以包括子目錄，比如 “https://share.renpy.org/movies-for-mygame/” 。

如果需要把影片檔案與遊戲本體放在不同伺服器上的話，該配置項就派上用場了。

config.web_video_prompt

iOS系統手機版Safari上運行時，用戶需要點擊後才能播放帶音訊的影片。該配置項是提示用戶點擊的消息。

還有一個與Safari有關的功能特性。Safari不支持一些流行的影片格式，比如webm。首次嘗試播放影片失敗後，會把影片檔案後綴改為 .mp4 並再次嘗試播放。在Safari上的具體情況就是，https://share.renpy.org/oa4_launch.webm 會嘗試播放並由於不支持而失敗，然後認為 https://share.renpy.org/oa4_launch.mp4 文件必定存在併嘗試播放。

Javascript link

Ren’Py可以通過 emscripten 模組中的3個函數運行Javascript。 emscripten模組僅在Web瀏覽器端才會被使用。可以使用 renpy.emscripten 的值測試，根據結果決定在使用前是否還需要引入emscripten模組。

emscripten.run_script(script) link: 運行指定的Javascript腳本。不會有返回值。

emscripten.run_script_int(script) link: 運行指定的Javascript腳本，將運行結果作為一個整型數值返回。

emscripten.run_script_string(script) link: 運行指定的Javascript腳本，將運行結果作為一個字串返回。

編輯 web/index.html 文件可以將Javascript函數添加到遊戲中，並在Ren’Py中調用。注意，該文件會在Ren’Py更新後被自動替換。

也可以在Ren’Py中使用 window.renpy_exc、window.renpy_get 和 window.renpy_set 函數調用Javascript。關於這些函數的說明，可以在 web/renpy-pre.js 中找到。

位元組碼快取 link

在Ren’Py 8.1版本中，載入時間可能比想像得更長，因為Ren’Py需要把Python代碼編譯為位元組碼(bytecode)然後再下載。為了避免載入時間過長的問題，可以使用位元組碼快取：

在瀏覽器中打開遊戲。當載入preslash界面時，按下鍵盤的F12鍵，打開javascript控制台。
在javascript控制台，輸入 downloadBytecode()。然後瀏覽器會下載 bytecode-311.rpyb。
將下載的 bytecode-311.rpyb 文件放在 game/cache 目錄中，然後重新構建遊戲。