This article is under heavy construction and heavy rewrites.
Introduction
This page uses a pretty crude project as a demo for various examples. The source is available here – and the raw WebGL demo is available here.
Emscripten & Transcompilations
What’s a transpiler? It’s a compiler that compiles source code into the source code of another programming language instead of into an executable program (like a compiler would).
There’s a lot of compiler and transpiler technology going on here. The linchpin in all this is Emscripten. Emscripten is a transpiler that can take C/C++ code and compile it into Javascript or WebAssembly (more on that later). It’s also used by Unreal engine for their web build technologies. The same goes for other companies and products. Some don’t even use a second code path for their web builds; they code everything into C/C++ and use Emscripten to generate their web applications.
While Unity lives in the .NET environment and is commonly programmed in C#, there is a technology they use when building called IL2CPP that takes the compiled intermediate language of .NET and transpiles it to C++ code.
So let’s break down this chain of complexities:
- A developer codes their C# scripts for the Unity game engine.
- The developer tells the Unity editor to build a WebGL version of their app.
- The editor builds a .NET version that’s made up of a .NET bytecode called IL.
- That bytecode is sent through the IL2CPP transpiler and converted into C++ code. This includes not only your scripts but standard Unity game engine code.
- That C++ code is sent through Emscripten and turned into WebAssembly code.
- The WebAssembly code is compressed into a file that you host on a web server.
We have languages into languages into languages, transpilers into transpilers. It’s as simple as that! Simple, simple, simple #NotSoSimple.
TODO: Link in equivalent Systems article
Running A Build
TODO: Reference embedding post
Anatomy
TODO: Add in anatomy post
GZip Compression
TODO: Link in GZip post
WebAssembly
TODO: Link in WebAssembly
Post-Build Editing
TODO: Link in post build article
Runtime Classes
There are a few high-level Javascript classes tied a Unity WebGL builds that can be accessed.
unityLoader
gameInstance
gameInstance.Module
Cookbook
Now that all the basics are covered, I’m just going to list some things that people might find useful. To avoid cramming too many examples into one page and to avoid flooding this page with too much explanation text, each topic exists in its own post. If anything is missing a post link, then it’s post hasn’t been published yet.
Embedding the WebGL app.
[Blog post]
The basics of how to embed a Unity WebGL app into your web page. What are the constraints? What are the pitfalls?
Embedding multiple apps.
[Blog post]
Viewing Debug.Log messages in Unity WebGL apps.
[Blog post]
Notes on how to view Debug.Log() messages in your app without any special tools or libraries except your desktop browser.
Delaying loading an app with a placeholder image.
[Blog post]
Don’t want to load and run the app until the user confirms they want it to run by interacting with it?
Accessing and Manipulating the Canvas DOM Element
[Blog post]
What if we want to do typical DOM and style manipulations to the DOM node hosting the app?
Throttling the application.
[Blog post]
What if there are certain times we know the app isn’t used by the user and want to throttle it to avoid using up excess processor utilization?
Suspending the application.
[Blog post]
What if there are certain times we know the app isn’t used by the user and completely suspend it to avoid using any processor utilization?
Browser and App Communication
[Blog post]
Notes on making the WebGL app and its containing website communicate and react to each other.
Network Communication
[Blog post]
Notes on internet networking options for the WebGL app.
Uploading a Text File to WebGL app
[Blog post]
How to make a Unity WebGL app receive a file uploaded from a user.
Downloading a Text File from WebGL app
[Blog post]
How to make a Unity WebGL app provide files that a user can download from their browser.
Transferring Binary Files Between the Computer’s File System, Web Browser, and Unity WebGL app
[Blog post]
Information on how to upload binary files to the application.
URL Arguments
[Blog post]
Notes on letting a Unity WebGL app know about the page URL it’s in. This includes extracting query strings.
Microphone Support In WebGL Applications
[Blog post]
Adding microphone functionality to Unity WebGL apps.
FMUBMAQ
The section we’ve all been waiting for, the frequently made up by me asked questions! or Feemub-mack for short.
How can we be sure the undocumented Javascript calls used in the cookbook will be around in the future?
Wut? Who said anything about that (said the guy making up his own questions to himself)? The only guarantee you have is that if it works right now, and if you don’t change it, it will continue to function as it has been. Beyond that, I literally cannot guarantee anything of the sort.