Unity3D官方教程：WebGL

開始WebGL開發

什麼是 Unity WebGL?**

WebGL工程選項允許Unity以JavaScript程式形式釋出使用HTMl5技術和WebGL渲染API、在網頁瀏覽器中執行的Unity內容。為了構建和測試WebGL內容，在“Build Player”視窗中選擇WebGL構建目標，並且點選“Build & Run ”。

技術概覽

為了在WebGL中執行，所有程式碼需要是JavaScript。我們使用 emscripten 編譯器工具鏈來交叉編譯Unity執行時程式碼（用C和C++編寫）到asm.js的JavaScript程式碼。asm.js是一個非常理想的JavaScript子集，允許JavaScript引擎 預編譯asm.js程式碼為極具效能的原生程式碼。
為了轉換.NET 遊戲程式碼（C#和UnityScript指令碼）至JavaScript，我們使用了一個稱為IL2CPP的技術。IL2CPP獲取.NET位元組程式碼並將它轉換為對應的C++原始檔，然後通過使用emscripten，這些原始檔被編譯，最終將使用者的指令碼轉換為JavaScript。

平臺支援

Unity WebGL內容在當前大部分桌面主流瀏覽器都支援，然而不同的瀏覽器，提供的支援程度仍有所差別。移動裝置並不被Unity WebGL支援。
不是所有Unity特性在WebGL工程中都可用，大部分是因為平臺限制的關係，例如：

• 多執行緒不被支援，因為JavaScript沒有執行緒支援技術。這對Unity使用多執行緒來提升執行速度，以及指令碼程式碼和管理dll，都產生了影響。實際上，所有在System.Threading名稱空間中的都不被支援。
• WebGL工程無法在MonoDevelop或Visal Studio中進行除錯。詳細請看“Debugging and trouble shooting WebGL builds”（暫未譯出）。
• 瀏覽器不允許聯網進行IP套接字的直接存取，出於安全方面得考慮。詳細請看“WebGL Networking”（暫未譯出）。
• WebGl圖形API等同於OpenGL ES 2.0，有一些限制，詳細請看：“ WebGL Graphics”（暫未譯出）。
• WebGL工程使用一個自定義、基於Web Audio API的後端，用於音效。這僅支援基本的音訊功能。詳細請看“Using Audio in WebGL”（暫未譯出）。
• WebGL是一個預編譯平臺，所以它不允許使用System.Reflection.Emit的程式碼動態生成。這在所有其它IL2CPP平臺,iOS,以及大部分控制檯都一樣。

WebGL 瀏覽器相容性

Unity WebGL在一定程度上支援所有的桌面主流瀏覽器。然而，不同的瀏覽器之間，支援程度、預期效能並不一樣。請通過以下的表格，對Unity WebGL特性，以及哪些瀏覽器支援它們做一個整體檢視。
注意，Unity WebGL 內容目前在移動裝置上不支援。它或許在高檔裝置仍可以工作，但許多現有的裝置並不足夠強大，且沒有足夠的記憶體空間來很好地支援Unity WebGL內容。出於這個原因，當嘗試在移動裝置的瀏覽器上載入內容時，Unity WebGL會顯示一個警告資訊（如果需要，此功能可以被關閉）。
注意到，這個兼容表針對瀏覽器特定版本才有意義。更高版本會繼續支援，但先前的版本可能會不穩定。

注意

Chrome可能需要大量的記憶體來解析生成的JavaScript程式碼，可能在32位瀏覽器重載入內容時，引起記憶體溢位或崩潰錯誤。檢視“Memory Considerations”（暫未譯出）獲得更多關於記憶體使用的資訊。
Internet Explorer 不支援音效，並且太緩慢而無法像樣地支援大部分Unity WebGL內容。出於這個原因，當在IE中開啟內容時，我們將展示一個關於使用不支援的瀏覽器的警告資訊。在表格中列舉IE只是為了完整性；應當建議IE使用者升級到微軟新的Edge瀏覽器。

構建並執行一個WebGL專案

當你構建一個WebGL專案時，Unity用以下檔案建立了一個資料夾：

• 一個index.html檔案，瀏覽器可以使用它導航讀取到你的內容。
• 一個開發或發行資料夾裝有你生成的工程輸出檔案（是哪個資料夾，依賴於你是否進行開發）
• 一個模板資料資料夾（至少在使用預設模板時會有），裝有載入條和其它模板資源。檢視“WebGL 模板”（暫未譯出）的使用者手冊頁面，來獲取更多資訊。

開發/發行 資料夾包含了以下檔案（“MyProject”檔名稱代表你專案的名稱）。（注意，如果你生成一個發行版工程，這個資料夾裡的檔案會誒壓縮並有一個.gz的字尾。檢視下面分發尺寸的註釋。）

• MyProject.js這個JavaScript 檔案包含了你播放器的程式碼。
• MyProject.mem檔案包含了一個初始化你播放器堆記憶體的二進位制影象。
• MyProject.data檔案包含了資源資料和場景。
• UnityLoader.js檔案包含了需要用於在網頁中載入Unity內容的程式碼。

你可以通過用大部分瀏覽器開啟index.html檔案，直接檢視你的WebGL 播放器。然而，出於安全的原因，Chrome在從本地檔案URL中開啟的指令碼上做了限制，所以這個技術在Chrome中無法使用。為了繞過Chrome的限制，使用Unity的Build&Run命令（File->Build&Run）；這個檔案就暫時在一個本地網頁伺服器中，並且是從一個本地宿主URL中開啟。或者，可以用 –disable-web-security 命令列選項來執行Chrome，這允許Chrome從本地檔案的URL載入內容。
在一些伺服器上，使用者需要生成可讀取的.mem和.data檔案，因為伺服器需要提供這些檔案給使用者。

構建播放器選項

（選單：File->Build Settings…）進入WebGL選項對話方塊。在對話方塊中，從平臺列表中選擇WebGL，然後選擇播放器選項…

開發工程

當你選中Development Build 勾選框，Unity生成一個開發工程，有事件探查器支援喝一個開發控制檯來檢視錯誤。另外，開發工程不壓縮內容（即，內容不是最小化的）；維持在在可以人工閱讀的JavaScript形式，保留了函式名，這樣使用者得到有用的錯誤追蹤棧。注意，這意味著開發工程會非常大，太大而無法釋出。

使用預構建引擎

這個選項僅在使用者勾選了開發工程時出現。在工程選項對話方塊中使用“Use pre-build Engine”選項來在開發期間加速構建迭代時間。當此選項被啟用時，Unity僅重構建”manager code”，動態連結到預編譯Unity引擎，這樣專案的重構建大概會快30%至40%。注意，這種構建型別僅適合於開發目的，因為總是產生”unstripped”引擎程式碼。此外，由於動態連結，這種工程的型別比普通型別的執行上更慢。

自動連線探查器

此選項僅當用戶勾選了開發工程時可用。勾選自動連線探查器選項，讓使用者探查Unity WebGL內容。對於WebGL，它不可能連線到事件探查器來執行工程像在其它平臺上那樣，所以使用者需要使用這個選項來連線內容到編輯器。這是因為事件探查器連線通過使用WebGL的WebSockets被掌控，單一個網頁瀏覽器僅允許內容的向外連線。

播放器設定

WebGL在播放器設定的檢視器視窗（選單：Edit->Project Settings ->Player）中，有一些另外的選項。

其它選項 Other Settings

精簡引擎程式碼

開啟 Other Settings 來選擇 Strip Engine Code選項。這個選項預設被選中，來允許程式碼為WebGL所精簡。隨著這個選項被選中，Unity不包括任何你不使用的類的程式碼。例如，如果你不使用任何物理元件或功能，那麼整個物理引擎會被從你的工程中移除。檢視下方的精簡區來獲得更多細節。

釋出選項

WebGL記憶體大小

開啟Publishing Settings進入WebGL 記憶體大小區域。這裡，你可以指定內容應為它的堆分配多少記憶體（以MB為單位）。如果這個值太低，使用者會收到“記憶體溢位”錯誤。這意味著要載入的內容喝場景無法完整放入可用的記憶體中。然而如果這個值太高，內容可能無法載入到一些瀏覽器或一些機器裡，因為瀏覽器可能沒有足夠的可用記憶體來分配要求的堆尺寸。這個值被寫到在生成的 .html 檔案裡一個名為TOTAL_MEMORY的變數中，所以如果使用者希望嘗試這個值，可以編輯 .html 檔案來避免重構你的專案。檢視在 WebGL memory usage 中的 User Manual 頁面來獲取更多細節。

啟用異常

打開發佈設置來進入 Enable Exceptions（啟用異常） 。啟用異常允許使用者指定在執行時意外的程式碼行為（通常被認為是錯誤）如何被處理。這裡有三個選項：

• None 無：選擇這個如果你不需要任何異常支援。這提供了最佳的效能和最小的構建。使用這個選項，任何異常的丟擲都引起你內容停止。
• Explicitly Thrown Exceptions Only 僅丟擲明確異常（預設）：選擇此項來捕獲，在使用者指令碼中丟擲狀態明確指定的異常。此選項也會讓指令碼中最終的阻塞產生作用。注意，選擇此選項，會讓從使用者指令碼所生成的JavaScript程式碼變得更大及更緩慢，但，除非指令碼是你專案主要的瓶頸，這並不是大問題。
• Full 完整：選擇這個選項來捕獲：
  
  • 在使用者指令碼中丟擲狀態明確指定的異常
  • 空引用
  • 陣列越界讀寫
  • 託管棧跟蹤

Unity通過在程式碼中嵌入檢查，為它們生成這些異常；因此這些選項增大了程式碼尺寸並且降低了效能。僅在需要除錯時，在程式碼中使用這個模式，因為它構建了非常龐大且非常緩慢的工程。
選擇Publishing Settings（釋出設定）來進入Data Caching（資料快取）。選擇此項來開啟播放器資料的自動本地快取。這個選項設定資源在瀏覽器的索引型資料庫中，作為本地的快取而儲存；這樣在內容的後續執行時，資源不會被再次下載。注意，不同的瀏覽器在允許索引型資料庫儲存時，有不同的規則；瀏覽器可能詢問使用者來允許儲存資料，並且工程可能超出被瀏覽器定義的尺寸限制。

發行大小

當向WebGL平臺釋出時，保證工程的大小盡可能低，讓使用者在內容開始前，只經歷可忍受的下載時長。關於降低資源尺寸的通用技巧，請閱讀Reducing the file size of the build。

對於WebGL的專有提示

• 對在紋理匯入器中所有壓縮的紋理，指定Crunch紋理壓縮格式。
• 不要部署開發工程；這些未被壓縮，或不是最小化，所以有很大的檔案尺寸。
• 到播放器設定中（選單：Edit->Project Settings ->Player），開啟Publishing Settings並設定Enable Exceptions為None，如果你不需要在工程中丟擲異常。
• 到播放器設定中（選單：Edit->Project Settings ->Player），開啟Other Settings 並且啟用Strip Engine Code來保證產生高效的工程。
• 當使用第三方dlls時要小心，因為它們可能包含大量的依賴，並且因此明顯增大了生成程式碼的大小。

如果要生成一個發行版工程，Unity根據在WebGL PlayerSetings->Publishing Settings視窗中選擇的Compression Format（壓縮格式），來壓縮工程輸出檔案。

檢視Deploying compressed builds中的文件，來獲取更多這些選項的資訊，以及如何用這些選項來發布工程。

資源包

因為所有資源資料需要在內容之前預先下載，所以你應當考慮從你的主資料檔案中移除資源，放入資源包中。用這種方式，你可以為你的內容建立一個能迅速讀取的，小的載入場景。資源包也有助於資源資料記憶體管理：你可以通過呼叫AssetBundle.Unload，從記憶體中解除安裝你不再需要的資源資料。
一些在WebGL平臺上使用資源包時需要考慮的事情：
當你在資源包中使用在你主工程中沒用到的類型別，Unity會對這些類從工程中精簡掉這些程式碼。當嘗試從資源包中載入資源時，這可能引發錯誤。檢視在下方 Stripping 中的部分，來學習如何修復這個問題。
WebGL不支援多執行緒，但http下載僅在它們結束下載時可用。由於這個原因，當下載完成時，Unity WebGL工程需要在主執行緒中解壓資源資料，阻塞了主執行緒。為了避免這一中斷，對於在WebGL上的資源包，LZMA AssetBundle compression是不可用的。資源包換成用LZ4來壓縮，在解壓縮時非常迅速。如果你需要比LZ4更小的壓縮尺寸，你可以配置你的網頁伺服器對你的資源包使用gzip或者Brotli壓縮（比LZ4壓縮更小）。檢視Deploying compressed builds中的文件來獲取如何進行壓縮的更多資訊。
通過使用瀏覽器的索引型資料庫API，來實現：在WebGL中使用 WWW.LoadFromCacheOrDownload 以支援資源包在使用者的電腦上快取。注意，索引型資料庫可能在某些瀏覽器上支援有限，且這些瀏覽器可能要求使用者提供在磁碟上儲存資料的許可權。檢視 WebGL browser compatibility 中的文件來獲取更多資訊。

Stripping 精簡

Unity 預設會從你的工程中移除所有不被使用的程式碼。可以通過播放器設定檢視器視窗來改變設定。（選單：Edit->Project Settings->Player）：選擇Other Settings 進入Strip Engine Code 精簡程式碼選項。開啟精簡選項會更好。
選擇精簡，Unity對你的專案中任何被使用的UnityObject派生類進行檢查（無論是被指令碼程式碼引用，或是在你場景序列化資料中）。然後，從工程中移除沒有任何類被使用的Unity子系統。這讓你的工程程式碼更少，需要下載與解析的量都更少（所以程式碼執行更快，使用更少的記憶體）。

**程式碼精簡帶來的問題**Issues with code stripping

如果精簡了實際上必須保留的程式碼，可能導致你的專案出問題。當你在執行時，要載入的資源包中原本包含不在主工程中、並已被精簡了的類，就會產生問題。當這發生時，瀏覽器的JavaScript控制檯會出現錯誤資訊（並可能伴隨著更多錯誤）。例如：
無法生成編號為XXX的類
為了排除這些從無，在類編號引用中查詢，以檢視是哪個類在嘗試建立例項。在這種情況下，你可以強制要求Unity在工程中為這個類包含程式碼，要麼通過在你的指令碼或場景中新增一個對該類的引用，或者對你的專案增加一個link.xml檔案。
下面是一個確保碰撞器類（以及物理模組）在專案中得以保留的例子。向名為link.xml的檔案中新增這些XML程式碼，並將此檔案放到你的資原始檔夾中。
<linker>
<assembly fullname="UnityEngine">
<type fullname="UnityEngine.Collider" preserve="all"/>
</assembly>
</linker>
如果你懷疑，精簡引起你工程的問題，你也可以嘗試在測試期間關閉精簡引擎程式碼選項。
Unity不提供檢視哪些模組和類在工程中包含的方便途徑，這途徑可以讓你最優化地精簡專案。然而，為了得到所包含類及模組的概覽，你在生成一個工程後，可以檢視生成的檔案Temp/StagingArea/Data/il2cppOutput/UnityClassRegistration.cpp 。
注意，精簡引擎程式碼選項隻影響Unity引擎程式碼。IL2CPP總是從你管理的dll和指令碼精簡位元組程式碼。當你需要在你的程式碼中，通過反射動態地引用管理的類、而不是通過靜態引用，這會引起問題。如果你需要通過反射存取型別，你也需要設定一個link.xml檔案來保留這些類。檢視iOS Build size optimization 的文件來獲取更多link.xml檔案的資訊。

移動工程輸出檔案

如果你希望改變你輸出檔案相對於index.html檔案的位置，可以通過編輯dataUrl
,codeUrl,以及memUrl區，以及在index.html檔案中的UnityLoader.js指令碼標籤來實現。你可以為這些內容指定在外部伺服器的URL，如果你希望將檔案在一個內容分散式網路（CDN）上主辦，但你需要確保，宿主伺服器已經啟用 跨域資源共享（Cross Origin Resource Sharing, CORS）。檢視 WebGL networking 頁面的指南來獲取更多關於CORS的資訊。

增量工程

你的專案通過IL2CPP生成的C++程式碼時增量編譯的；即，在最新工程中改變的C++程式碼會被再次編譯。沒有改變的原始碼複用為之前工程生成的相同目標檔案。用於增量C++工程的物件檔案儲存在你的Unity專案 Library/il2cpp_cache目錄中。
為了得到一個乾淨的，從零開始都沒有使用增量編譯所生成C++程式碼的工程，刪除 你Unity專案目錄中 Library/il2cpp_cache目錄。注意，如果Unity編輯器版本不同於用於之前WebGL工程的編輯器，Unity會自動生成一個乾淨的，從零開始的工程。