There has been bit of confusion regarding HTML5 builds so I wanted to write a post explaining few things.
1. I cannot build HTML5.
Is the SDK setup correctly?
- Unreal build system expects sdk to be setup correctly before It will decide to build HTML5 Target dlls for the editor and/or the real HTML5. The build system depends on the existence of env var EMSCRIPTEN correctly pointing to the root of your SDK - the location of emcc.
- OS X note : for the Editor (a GUI app) to get hold of EMSCRIPTEN env var correctly, you will have to jump through a hoop to get everything working (http://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x)
- It is helpful to play around with SDK and possibly compile and run a hello world program to have some familiarity with SDK. Read emscripten Documentation on correctly configuring emscripten sdk - i.e .emscripten configuration file.
Emscripten compiler crashes.
- Emscripten tool chain is fairly new and there are few issues. Make sure you are on the latest emscripten release and if it still persists - please let us know. Unreal build system does emscripten version sanity check - you can set the SDK version in UEBuildHTML5.cs, ExpectedSDKVersion.
Editor builds on Win64 and OSX supports building and packaging HTML5. and when Linux editor build is stable, on Linux too.
**
2. The generated .js files are huge. **
- Build the Shipping version.
- Look for UEBuildConfiguration.bCompileForSize - This enables building with -Oz. ( http://kripken.github.io/emscripten-site/docs/optimizing/Optimizing-Code.html)
Okay, my builds are STILL huge.
-At this point, you need to start removing code and features which you are not using. E.g For tappy chicken builds we remove vehicle physics etc - Look in UE4Game.Target.cs SetupGlobalEnvironment.
Not good enough, I think I want even smaller .js files.
-Big javscript files are generally minified and hosted in a compressed format. The browser downloads the compressed javascript and automatically decompresses locally behind the scene.
-Set up your webserver to serve compressed javascript and compress your generated .js files using gzip. javascript is all text and compresses well. (TappyChicen demo engine .js is < 8MB compressed)
The generated .js files are already minified.
**
3. How do I see it in action? **
Multiple workflows are supported ( parity with other platforms )
- Editor Package.
- Editor Launch.
- Unreal Front end.
- Cook on the fly.
**
4. Do I need a Web server? **
Firefox allows file system XHRs but for every other browser - HTML5 files need to be hosted behind a web server. A quick way of starting a webserver is "python -m SimpleHTTPServer 8000".
Editor Launch On Device feature starts a web server behind the scenes, starts the selected web browser and points it to the desired location. For cook on the fly, the HTTP protocol is supported for the cook on the fly server.
With more HTML5 features in pipeline, we are moving towards an "always need a web server" senario.
**5. My Game doesn’t run. **
It possibly needs more memory to run.
for HTML5 builds, we need to pre-allocate a contiguous chunk of memory which the game needs over its lifetime. Setting this number is done via different paths - Engine HTML5Engine.ini has a HeapSize setting which is currently set to 1024 mb. Game HTML5Engine.ini can override it e.g. TappyChicken does it HTML5Engine.ini (256MB)
Further more, there's code in Game.template.html which clamps the memory usage to 512 MB if we are running in a 32 bit browser. Our experiments show 512MB seems to be the safest, largest amount of memory 32 bit firefox stable can provide to js code running inside the browser. Module.TOTAL_MEMORY is the final variable which is set.
Chrome has been tricky to work with as its memory usage is almost twice when compared to firefox. we are in conversation with Chrome guys and hopefully things will be resolved soon. That being said - optimized builds of small games like TappyChicken do work in Chrome (~256MB).
64 bit browsers (firefox 64 bit nightly on Win64, stable versions of firefox and safari on linux and mac) provide a much looser memory constraint and can provide more than .5 GB to the game.
The advised workflow is here is to run an optimized build of your game in a 64 bit browser and figure out the high watermark for memory usage and use that number in your game HTML5Engine.ini - if it's huge ( >512 MB ) you are possibly out of luck when using a standard 32 bit browser. (memory profiler: https://groups.google.com/forum/#!topic/emscripten-discuss/HtAzVposlX4)
The following equivalence probably makes sense -
64 bit browsers - Dev kits.
32 bit browsers - Shipping consoles.
Chrome already has a 64 bit distribution, we expect mozilla to follow suite on Win64. 32 bit browsers will slowly go away on win64 but not very soon.
When testing make sure you have the latest versions - if the problems still persist, collect information from the browser console and not just the unreal engine console and let us know!
**6. I don’t see my browser in the devices list. **
HTML5Engine.ini contains the list of browsers, please edit and restart editor - The requested browser should pop up in the devices list.
**
7. Rendering Feature X doesn’t work. **
HTML5 builds uses the Mobile OpenGL ES 2 rendering code path and use WebGL internally and should be at feature parity with Android/IOS as a thumb rule. If its not then its a bug. A quick mobile preview of your game
should give you an idea of what it will look like.
**8. Everything is Shiny.
**
The browser probably doesn’t support texture_lod (WebGL EXT_shader_texture_lod Khronos Ratified Extension Specification) extension.
**9. What do you actively test the build on? **
Templates, Tappy Chicken, StrategyGame.
**10. I did Launch from editor but the the game didn’t show up - It errors out “cannot connect to 127.0.0.1” and the editor says Launch Completed. **
The browser decided to update itself. Try launching again. Make sure no other instance of the browser is already running.
**11. Why is everything packaged and preloaded even before the game starts ticking? **
We are working on getting Streaming etc for working for HTML5.
**12. Destructibles don’t seem to work. **
Possibly at a later time / Not sure.
**13. Is ICU supported? **
Yes! we missed it for 4.5 - but its now in master.
14. Does Physics work?
Yes.
**15. Is Game Networking supported? **
No. This is one of the biggest missing feature and its on our radar.
**16. Template X doesn’t work. **
They should all work atleast on firefox 32 bit- Including the new Adv Vehicle template. Please let us know if it doesn't.
**17. Browser X on OS Y doesn’t work. **
Read 5. Talk to us.
**18. FPS controls don’t work correctly. **
They should with 4.5
**19. I want feature X! **
Yes - we are actively seeking feedback from the users so that we can prioritize. we working towards making HTML5 as a very viable platform. Stay tuned!