Showcase Tips and tricks for using WebGL on desktop and mobile (tested up to 2021.3.11f1)

Hi friends,

Here are some tips and tricks I've used to get great WebGL builds that are fully compatible with mobile devices and work great on desktops too:

• InputField not being supported on mobile: I ended up making an on-screen keyboard in Unity, and it works fine! Don't overthink it. Authoring a jslib that calls the javascript
  Code (JavaScript):

  1. prompt
  works fine too. It has been mentioned elsewhere here a bajillion times.
• InputField apparently not supported anywhere. The underlying issue is that the input fields from UGUI and TextMeshPro both use IMGUI Event, which apparently is broken, disabled or otherwise malfunctioning in Unity 2021 LTS and does not interact correctly with Input System. Set Input Handling to "Both" to resolve the issue. If you are reading this and pay for Unity support, kindly ticket this issue.
• Use flexbox to layout your canvas, and design for a fixed size. I choose 375x635, since that's the iPhone X layout, and my content is in the iPhone SE safe area of 320x568. Then, I use flexbox to position my canvas in the center, and a post-process step to replace the JSON's background color. Grab my modified responsive template here. You can discover responsive design sizes by entering "Responsive Design Mode" in Safari (see https://imgur.com/a/AdrvUNa). Stop using stupid margin or padding or other dumb CSS tricks and get rid of all the crap that's in the default frame. Just do the modern thing. Alternatively, design for a responsive size, and full screen the canvas.
• Use asmdef to control what is Editor versus Player code. This improves your compile speed too.
• Always try to use a link.xml with high code stripping. There's lots of documentation now about how link.xml works, but the overall jist is that the code stripper has a very hard time with static methods and third-party code. Be aggressive, don't just give up and use Medium!
• Disable modules you don't need in the Package Manager window. This will require modifying your external libraries.
  
• Use the Build Report Tool from the asset store to find assets and scripts you aren't expecting to include in your build. For me, the biggest surprise was (1) System.Xml being referenced somewhere, and (2) plugins that pollute their Resources directory instead of using Editor Default Resources.
• Compile for wasm targets and asm.js as a backup. iOS 13.0-13.1.2 do not work with WASM when the build is large, and iOS 12.1 and earlier do not work with Unity's WASM at all. WASM also occasionally breaks on some specific iOS versions. However, Unity now supports it well for Mobile Safari and works with Apple to resolve issues. You can keep targeting both wasm and asm.js to prevent your experience from ever breaking on Mobile Safari.
• Use sprite atlases to fine-tune your 2D asset compression. They're great for controlling which assets need alpha channels and which don't, and which assets can use crunch compression and which can't. You should set each sprite's import settings to correspond to the import settings on the asset, or just use RGBA32 on the individual sprites. Otherwise, the atlas builder will use the compressed version as its input, which is obviously a UX smell but what can we do.
• Test on iOS 15 with WebGL 2.0, because it isn't guaranteed to work. Otherwise, disable auto graphics and specify only WebGL 1.0. It's the only engine supported by Safari for iOS, WebGL 2.0 as Unity implements it doesn't work for the most part. There's no point shipping around shaders or code for a WebGL 2.0 target you don't really need.
• On 2018-2020, use a UnityLoader.js and UnityLoader.min.js that doesn't show a popup on mobile and switches to asm.js for iOS 12.1 and earlier. For 2018, I modified them to fix this. You can copy the files from here into your /Applications/Unity/Hub/Editor/2018.3.13f1/PlaybackEngines/WebGLSupport/BuildTools directory or copy them using a post-processing step. Feel free to use your favorite diff tool to visualize what I changed. My minified version isn't actually minified since it's tricky to minify this code.
• Set Application.targetFramerate to -1. This ensures you use requestAnimationFrame to render your frames as quickly as possible.
• Use asm.js and the Profiler to pin down weird stuff. For example, I discovered that only on iOS, the first call to DateTime.Now took 2275ms! Since you don't have deep profiling, you should familiarize yourself with Profiler.BeginSample and Profiler.EndSample. This is really slow and annoying but it is super informative for finding real issues.
• Native calls do not work in coroutines. They just don't. A native call is one to a function with the [DllImport] attribute. That means if you use e.g. a websocket jslib and try to call a jslib declared method in the coroutine, it will silently fail.
• Enable demangling in your development builds. This gives you more useful stack traces:
  Code (CSharp):

  1. PlayerSettings.SetPropertyString("emscriptenArgs", "-s DEMANGLE_SUPPORT=1 -s ASSERTIONS=1 -s -Werror", BuildTargetGroup.WebGL);
• Use Unity's native JSON. You really shouldn't be using JsonFX/Newtonsoft/JsonObject, it will massively balloon your code size due to the compilation of generic specializations.
• Use WebAudio yourself, and activate it on a click. I use this for looping music. Contemporary browsers require you to `.play()` audio in a click. Set the handler using html `onclick="playAudio()"`, otherwise the canvas will eat the clicks.
• Don't be stupid with third party code. Asset store stuff is good because it works but it can be incredibly poorly written, accidentally referencing stuff like System.Xml, System.Data or System.Runtime and tank everything.
• Don't be stupid with fonts. If you only need a single size and a single character set, configure it. If you can use Unity's UGUI instead of TextMesh Pro, do it. But overall, avoid showing too much text in your game, since that's what HTML is good for!
• Test on iOS devices. I know this scene is really big on Windows + Android but you gotta actually buy an iOS device and try it with your mobile site. You simply cannot reproduce the issues experienced by the ordinary user with the iOS Simulator that ships with XCode.
• Don't use DateTime. There are weird interactions with locale support and Unity player. Use NodaTime for time.
• Test for the appropriate Chrome build to test Android devices. My recommendation is Chrome 44, likely the oldest version of Chrome you'll have to deal with in the real world that can actually play WebGL games distributed this way. I had to use a polyfill for `enumerateDevices` and fix the worker code in the 2018.3 loader to get it to work on this platform. Google how to download old Chromium builds. This platform doesn't support WASM.
• Use a CDN, like CloudFront. You should definitely never serve directly from S3 or object buckets like that, because it'll be way too slow over LTE.
• Use brotli compression. It's so much better than GZip. If you plan to use CloudFront with an S3 origin, make sure to set the .unityweb file's Content-Encoding to br, and use an https (with http redirect) configuration on your CDN because Chrome only decompresses br natively for you from TLS URIs. Executing this code from your project directory will fix the "Exception: Failed building WebGL player" you have
• Build with hashes. It's imperative you build with hashes for simple setup with your CDN. Otherwise your assets will be perpetually mixed and buggy and you won't really know why.
• For compatibility questions, use caniuse.com. This is helpful for platforms you don't have. Unity3D needs localStorage and WebGL 1.0 in canvas support.
• Addressables is overrated. Since the content is decompressed and decoded on the main thread, your whole game will freeze, a worse experience that simply downloading the original content.
• Assetbundles freeze for a while when loading. Loading is single threaded, so you shouldn't expect to have any interactivity while external files, no matter how slow, are loaded into the Unity player.
• Application.isMobilePlatform works except for iPads. Use this to determine if you are on a mobile phone browser. iPads will not report correctly.
• Use PlayerPrefs to store local data. It uses IndexedDB internally and is well supported across browsers. However like all local browser storage it has interactions with playing from the localhost domain (for local testing) and cannot be read by other domains generally.

The single greatest obstacle is that iOS constantly breaks WASM. Apple simply does not care. So always build asm.js.

A 2017 iPhone X is extremely fast, and supports WASM in 12.2. Its graphics and CPU are significantly faster than a Nintendo Switch and any shipping Android device. I guarantee you can make a great-performing WebGL game in Safari as long as you don't do anything stupid!

 

Great post!

Regarding UnityLoader
I prefer to re-set the method that checks if mobile on the html page script, before calling UnityLoader.Instantiate, instead of editing UnityLoader.js, as I don't want to rewrite the file in every install of new version of the engine

 

This is a fantastic thread! Would have saved me a lot of time!

I have found Brotli compression 4 or 5 to offer the most optimal speed. (using that setting decreased loading time by 27%)

I am not using a CDN and my mobile speeds are really slow, will start using a CDN.

To add a couple of things to the list, indexDB can be quite complex to get working on all browsers, we are moving to web sockets within the month, due to compatibility issues.

I am surprised that Unity disabled asm.js from 2019.1.

Has anyone been able to get streaming instantiation working? Currently stuck on that.

 

Actually I use streaming instantiation since 2017 version, but I use my own loader.

 

I just want to point out that these two things, IndexDB and Web Sockets, are not really related to each other.

There are polyfills for browser storage. But for a web game, you should really be storing the user's data on the server.

Web Sockets work fine everywhere I have tried. I use it for my own multiplayer game. Just don't do native calls inside coroutines, they don't work.

 

Whats with mobile specific Texture compression? Like ETC, PVRTC & ASTC. I know there's one guy here on the forums who found a solution to this (although a rather complicated one). Do you have a good approach for this?

 

Yeah mobile compressed textures are our biggest "wish list item". The latest version of Unity even broke my backdoor way to do it on iOS. Honestly for us I think it's a bigger game changer than threads. At the moment on mobile we just roll with uncompressed textures at half the resolution of desktop (roughly the same memory).

In general I agree with the list except for two things:

1. There's nothing wrong with using WebGL2 on firefox/chrome...not sure what the benefit of turning auto off is
2. asm.js on Safari iOS is WAY SLOWER than wasm on Safari iOS (for us it was like less than 1/3 the performance)...it was essentially unusable

I'd also like to add we finally got around to making all of our asset bundles uncompressed and then compressing them with gzip. It actually makes a huge difference on slow devices. They reduced load time on our ancient android device by over a 1/3. So I recommend taking the time to do that.

 

I don't remember where it was written(a post by chrome or firefox devs), but using WebGL2.0 where you can, should give some performance boost even if you use only WebGL1.0 methods. But I guess that it depends on browser version and other stuff

 

You mentioned it earlier somewhere on forum and I tested it. I was really surprised.
We are using cloudflare cdn with `Content-Type: application/wasm` for both bundles and engine files. Cloudlare uses brotli where possible.
In the end uncompressed + brotli has less size than compressed + gzip - win win.

 

This guide works essentially the same for 2019, you will need to modify your UnityLoader.js differently.

I've updated with my experiences using addressables and dealing with audio.

 

Thank you for a fantastic list (and thread!).

Anyone have any experiences on the memory limit on builds?
an empty unity project runs at around 700mb memory on iOS and a simple game i made easily surpasses 1.1 gb. As i understand it, a recent update to iOS (12.2 i believe) increased the memory limit to around 2gb anyone able to confirm this?

 

Sounds like you're building debug or development builds with no code stripping.

On empty projects I usually use 48MB or less. On my WebGL titles I keep it under 128MB pretty easily. 64MB-128MB is my target.

 

@doctorpangloss Can you share what where the assets that used and/or ways that you found to get rid of the system.xml.dll, and system.data.dll in your builds?
I too have both in my build and even trying to remove third party code wasn't enough to get ridden of them.

Thanks

 

@Uli_Okm Just having import System.Data or System.Xml anywhere in your code is enough to import the libraries.

 

Thanks for the tip! I am still figuring out why they are being added EVEN in a empty project with only a empty scene, maybe Unity changed something in 2019.1...

 

Thank you for the tips! Do you have any tips about fullscreen mode on mobile? I've got one issue with it that I can't solve yet: https://forum.unity.com/threads/upscaling-of-fullscreen-mode-in-mobile-chrome-browser.760466/

 

Because you cannot full screen on iOS Mobile Safari, I would say, you cannot do it at all

 

I don't even try iOS. I will be more then satisfied with Android.
Canvas behavior is very strange, I can't understand the logic behind the canvas scaling. Also, In fullscreen mode I've got very strange canvas size. Something like 731.4 * 411.6.

 

Yes, canvas sizes are very odd in WebGL mobile. I'm more familiar with iOS, the sizes are the "responsive" sizes in "pixels" i.e. points, which are really meant to allow sites that specify pixel sizes to have "roughly" the same physical size across all devices. Nowadays, with 2019, you can set up a HiDPI canvas (better known to CTO Google as "retina") and your canvas sizes will get even MORE confusing.

Personally, because of the changing standards, I would recommend feature detection and physical scaling, whenever possible, to determine your canvas scaling size. Specifically, with the appropriate meta tags in place, place a common element in your host .html page, measure its size in various units, and use that sizing information to determine your scale. This essentially outsources your sizing information to browser defaults or, if you style that element with bootstrap for example, Twitter engineers.

 

Hey Hi, anyone know how to detect closing the tab or browser? I need to clear my playerprefs on that but I couldn't find any solution yet.

 

Code (CSharp):

1. $(document).blur(... unityInstance.sendMessage(...) ...)

my dude, from https://api.jquery.com/blur/ and https://docs.unity3d.com/Manual/webgl-interactingwithbrowserscripting.html

 

Thanks. Let me try and give an update first. Do you know how to close popup window, browser tab from the game instead of redirecting to a blank page?

 

That's more of a general Javascript question. "You can't close any tab via JavaScript. 'This method (window.close) is only allowed to be called for windows that were opened by a script using the window.open method.' In other words, you can only use JavaScript to close a window/tab that was spawned via JavaScript."

 

So, as I understood is, I need to call JS function from the script when player terminates the game. Isn't it?

 

I tried following every step you did but i still cant to get the webgl working on any of my IOS mobile device . I tried with mac book / android phones / windows and etc works fine. but as for IOS mobile device the loading stuck at 90% even if i'm using Safari browser / chrome on Iphone X .. anyone have any updates or solution on this ?

 

Addressables is exactly the same as Asset Bundles. The issue you speak of is solved by leaving the bundles uncompressed, then doing a gzip/brotli compression after they're built. Then on your content server, set the headers as gzip/br and when it's downloaded through addressables or assetbundles, the browser will automatically decompress them using whatever system resources it wants (off the main thread I think). Plus, once it's decompressed, it will be stored in the indexedDB in an uncompressed state, thus improving your load times from cache (no need to decompresss).

 

Try select "asm.js" as a linker target for the build.

 

I guess it's relevant here
https://gist.github.com/De-Panther/f08cb4902bd21ee403d579a12510be2c

 

Hi @doctorpangloss
im aiming to build webgl for recent ios devices , do you still see that necessary to compile for asm.js ? my project with brotli compression format is about 250 MB, do you consider that as a large build ?( i havent had chance to upload it yet )
and as figures in https://caniuse.com/#feat=wasm , seems that wasm is now fully supported on all devices.

 

If that's the size of your build with everything in it, that's huge! My entire project is about 190 MB, but most of that is assetbundles. The code is 3.6 MB and built-in assets are 2.0 MB. We just dynamically load our bundles as they are needed so that the initial load time is low.

iOS sucks! They "officially" support wasm, but that doesn't mean it always works. iOS 12 worked with wasm, 13.0 and 13.1 broke wasm, and they "fixed" it with 13.2, but it still doesn't load 100% of the time. I noticed a failure rate of ~10% when I was testing (not sure if it has gotten better since then, haven't tested in a while). Asm seems to work 100% of the time, but is so slow, it's unusable. What's worse, with iOS 13, they started lying in the browser what device it is on iPads, so you can't tell if it's an iPad or a Mac to tell it to load wasm or asm.

 

Thanks for your respond @ProtoTerminator

huge to load or huge for ram? i assumed that in worst case it would occupy something like 2GB of ram, besides my projects are kinda light for cpu, mainly consist of textures

 

I have been trying to make my webgl build work on ios mobile devices too, and it is really frustrating. Even on identical devices (say, 3 identical iPad Air 2), one will work and two got stuck at 90%. Sometimes it will depend on network speed, when I tried the ipads and iphones using the shop's network, none will load. But if I connect them to my phone's hotspot, all can load the app without any problem....

The build works great on desktop browsers and Android devices (interestingly, those devices can load fine though they are connected to the previouisly mentioned shop wifi network).

 

this 90% stuck stems from low ram issue, how large is your build ? wasm or asm.js ?
try it on more recent ios devices

 

My app is very small, the whole Build folder is only about 40MB. I am using the latest Unity version, so should be wasm.

I have tried on the latest ios devices (ipad, ipad air, iphone11, etc) and saw similar behavior. It is rather hit or miss. If network situation is good, then there is a higher chance of successfully loading the app. So strange...

 

idont know exactly but as i tested a 40mb wasm build on my iphone6(1gb ram) , it stuck on 90% too.
i would try asm.js tomorrow but , its weird cuz safari officially supports wasm,and i read some unity testing benchmarks on safari three years ago , idk maybe its just doesnt work with ios safari !
just remember that if your gonno build as asm.js you should identify allocated ram too like :

Code (CSharp):

1. PlayerSettings.WebGL.memorySize = 256;

 

Using the latest Unity version, no longer has the option to choose asm/wasm or to set memory size. Have tried on latest iOS models, still some can load and some cannot...

 

its not in UI anymore because its deprecated but you can change it via editor script

Code (CSharp):

1. using UnityEditor;
2. using UnityEngine;
3.  
4. [InitializeOnLoad]
5. class asm
6. {
7.     static asm()
8.     {
9.         PlayerSettings.WebGL.linkerTarget = WebGLLinkerTarget.Asm;
10.         PlayerSettings.WebGL.memorySize = 512;
11.     }
12. }
13.  

just put this script under Assets/Editor/
btw just keep that in mind that amount of ram which is gonno be occupied by your app isn't defined by the build size actually ,it may differs so much based on your content , you could track it by Unity profiler under ram section/total ram allocated
as i own an iphone6 i can't recommend my statistics to you ,but ill post here when i'm done to have a comprehensive
data to be comparable.
Just for everyone who may read this post in future i'm gonno post the memory allocation limit on ios devices :

device: (crash amount/total amount/percentage of total)

• iPad1: 127MB/256MB/49%
• iPad2: 275MB/512MB/53%
• iPad3: 645MB/1024MB/62%
• iPad4: 585MB/1024MB/57% (iOS 8.1)
• iPad Mini 1st Generation: 297MB/512MB/58%
• iPad Mini retina: 696MB/1024MB/68% (iOS 7.1)
• iPad Air: 697MB/1024MB/68%
• iPad Air 2: 1383MB/2048MB/68% (iOS 10.2.1)
• iPad Pro 9.7": 1395MB/1971MB/71% (iOS 10.0.2 (14A456))
• iPad Pro 10.5”: 3057/4000/76% (iOS 11 beta4)
• iPad Pro 12.9” (2015): 3058/3999/76% (iOS 11.2.1)
• iPad Pro 12.9” (2017): 3057/3974/77% (iOS 11 beta4)
• iPad Pro 11.0” (2018): 2858/3769/76% (iOS 12.1)
• iPad Pro 12.9” (2018, 1TB): 4598/5650/81% (iOS 12.1)
• iPad 10.2: 1844/2998/62% (iOS 13.2.3)
• iPod touch 4th gen: 130MB/256MB/51% (iOS 6.1.1)
• iPod touch 5th gen: 286MB/512MB/56% (iOS 7.0)
• iPhone4: 325MB/512MB/63%
• iPhone4s: 286MB/512MB/56%
• iPhone5: 645MB/1024MB/62%
• iPhone5s: 646MB/1024MB/63%
• iPhone6: 645MB/1024MB/62% (iOS 8.x)
• iPhone6+: 645MB/1024MB/62% (iOS 8.x)
• iPhone6s: 1396MB/2048MB/68% (iOS 9.2)
• iPhone6s+: 1392MB/2048MB/68% (iOS 10.2.1)
• iPhoneSE: 1395MB/2048MB/69% (iOS 9.3)
• iPhone7: 1395/2048MB/68% (iOS 10.2)
• iPhone7+: 2040MB/3072MB/66% (iOS 10.2.1)
• iPhone8: 1364/1990MB/70% (iOS 12.1)
• iPhone X: 1392/2785/50% (iOS 11.2.1)
• iPhone XS: 2040/3754/54% (iOS 12.1)
• iPhone XS Max: 2039/3735/55% (iOS 12.1)
• iPhone XR: 1792/2813/63% (iOS 12.1)
• iPhone 11: 2068/3844/54% (iOS 13.1.3)
• iPhone 11 Pro Max: 2067/3740/55% (iOS 13.2.3)

you could find the ongoing post here :
https://stackoverflow.com/questions/5887248/ios-app-maximum-memory-budget/15200855#15200855

* please post your experiences with mentioning your ios device model/ios version/build size/build format here to help others

 

Seems not that related to the project size. When it can't load, it can't load and will stuck at 90%. Even for the latest model like the iPhone 11 Pro.

 

may you do the same thing as i did in the post below with newest ios device you have and share the results
(just add few more maps to test the limit)
https://forum.unity.com/threads/issue-with-too-much-ram-occupation-on-ios-devices.881920/
for me it run with 3 4k maps.and stuck on 4.

 

First...thanks a lot for all the Infos...really strong and helpful stuff...
Unfortunately....this is seemingly not correct.

I deploy to IPads with iOS 13.3, 13.4, 13.5...it always responds with Application.isMobilePlatform = false (maybe because it's not a Phone, but a Tablet?)

Anyway...so far, i haven't found any solution to determine, whether i am running on iPad or Mac...because all the SystemInfo-Callbacks return crap as well (OS returns as MacOS, deviceType returns as Safari)

Any other recommendations to that?

 

https://stackoverflow.com/questions/57776001/how-to-detect-ipad-pro-as-ipad-using-javascript
Which will also refer to https://stackoverflow.com/questions/56578799/tell-ipados-from-macos-on-the-web

 

That's unfortunate. My recommendation is to check the nav agent, which should indicate if it is an iPad.

 

That's where Apple started lying about their device. I've come to the conclusion that we shouldn't try to hack around Apple's lies ourselves, and if something isn't working properly because of that, place the blame fully on Apple. Tell users to use a different browser that doesn't lie, like Chrome, or tell them to change their device settings for Safari if they want the correct behavior.

 

Maybe use the screen dimensions then. If it's exactly an iPad's dimensions, it's an iPad.

There are platform detector scripts you can use, which is what I would do.

 

Hi,
I want to compile my project for both asm.js and wasm targets. Please, anybody has the C sharp code and which files or scripts I have to edit to make it work? I am using 2019.2.6f1 version.
And finally, do I have to set up something on the webserver side where my WebGL app is hosted?
Thanks

 

Has anyone managed to get the Video Player working in WebGL on Mobile? Using Chrome for Android. Works on Chrome desktop (Windows) but not Android.

 

Never had a problem with it.
Just make sure that the file format and the codec of the video are supported on the device browser.

 

Could you upload a working example to github please? Can't get it to work on MOBILE no matter what.

 

Create a project with a Video Player component
https://docs.unity3d.com/Manual/class-VideoPlayer.html
And instead of selecting a video in your project, set the source as URL, and add there a URL (not a local file) to a video with supported format, like MP4 (you'll want H.264 format just to be sure https://caniuse.com/#search=mp4 )
An example for such video
https://threejs.org/examples/textures/sintel.mp4

 

How do I communicate with the browser on iOS? Regular calls to jslibs outside of coroutines do work, right?