Javascript / WASM File Size in custom builds

[PhoenixIllusion]

This post is not about any request to change any part of the library, just discussing custom builds.

Posting TLDR Conclusion:

• The biggest FileSize issue I see is the emscripten's web_idl_binder glue JS. I may look into a way to modify this emscripten python file for my personal builds, to run against latest JoltPhysicsJS@latest and output the JS Classes into their own JS modules with a top-level await to the root wasm module, so the entire thing Tree-Shakes. This should approximate results close to my own custom builds except stripping unused functions/properties, and the JS bundle-size on minimal-usage builds be reduced
• If you work at it, it is possible to semi-automate a strip of the WASM build down to just what functions you need, analyzed via typescript typing, although in my case the WASM bandwidth the savings is just about 200kB gzipped

---

With all of the additions to the library that have been done, I looked into file size change of the project, with regard to both the JS file (base + glue) and stand-alone WASM file.

Due to server-side support for file compression via GZ, and browser built-in compression support of gz compression-streams, compressed sizes are used for reference on bandwidth.

Currently, with v0.23.0, these both stand at:

• WASM: ~1.97 MB -> gz-compressable to 690 kB
• JS: 1.1 MB -> gz-compressable to 132 kB

Compared with version version v0.10.0

• WASM: 1.6 MB
• JS: 727 kB

As a web-developer, this isn't much growth and not unreasonable compared to most other libraries, or the size of a couple detailed background JPGs. The biggest JS growth appears to purely be method-names, either of classes and functions or repeated usage of the raw emscripten export names. With ServiceWorkers, this is also just a one-time-only download of files.

Since I was going to make custom builds for my projects anyway, for multi-threading at least and possibly bake in additional event-listeners, I looked into if I could minify my builds and see how much smaller it would be.

I looked into the vanilla TypeScript package for its language features, before turning to a transformation and analysis library ts-morph. I loaded up my library directory in the script, and located the typings.ts file for jolt-physics. I then traversed the Jolt module for every class, method, property, return-types, parameter-types, inherited types, and variable. I used project-wide-reference-lookup on each item, flagging every item as 'required' if it existed outside of the typings.ts and logging to a JSON file.

This did break in cases where Key-Value notation was used on a class, or classes were assigned to an interface, then methods invoked on that interface, ex:

interface HasPoints {
  mPoint1: Vec3;
  mPoint2: Vec3;
}

function setPoints( constraint: HasPoints) { ... }

I then loaded up the existing JoltJS.idl file and processed it top-top-bottom, parsing enum's and interfaces and seeing if they were 'required', breaking apart enums and interfaces to only their required fields and outputting to a new IDL file. I ran this through the IDL type-gen code, and tested compiles against it to confirm that all my code still compiled and type-checks were flagging any missing methods or properties.

Once built and validated against library's examples, my totals were:

• WASM: 1.3 MB -> gz-compressable to 500 kB
• JS: 240 kB -> gz-compressable to 35 kB

Conclusion: Quite a bit of overhead and risk in generating new builds, with savings under gzip of ~300k, so I'm not sure its worth it to me yet.
I may look into modifying the existing web_idl_binder.py generated JS file only so it can be tree-shaken, and possibly cut that down by during bundle-time.

Files used for my minify, having several edge cases and the need to add an extra "override" file to add types not originally included:
https://gist.github.com/PhoenixIllusion/68f3796be91fdf26aa667290f6782692

[jrouwe]

Looks like a cool project again! As you say, it seems to be very specific for your setup, so I'm guessing it is going to be hard to generalize this (if it is worth the savings in the first place). I'm guessing that, besides gzipping, there's not much else you can do to minify the package?

[PhoenixIllusion]

The tree shaking setup can be generalized for the JS side if it could be done, but it makes a lot of files, one or more per class.

Feature flags could be used to conditionally compile entire classes and IDL, but I'm not sure which classes would be good candidates.

One potential saving is getting Emscripten to minify the function's raw export names, but I couldn't get that to trigger. With the glue layer, we never use the original names (_emscripten_foo_set_abc style) that is used 2x or 3x in the JS and once in the WASM, so there is a large amount of pure text that could be reduced to an index, like _f+base64 index, since they are only ever used inside the glue library.

[PhoenixIllusion]

The above about export names assumption is incorrect. The Distribution build already minifies the export names, it just does not minify anything added to the Module[_emscripten_bind...] style names. If those are stripped out and not exposed on the Module, then the JS file drops down existing JS file (wasm, non-compat) from 1.1MB to about 600k right now.

I'm not sure on a clean way to do that. It's kind of crude, but I used the --js-transform "node ${CMAKE_CURRENT_SOURCE_DIR}/strip-module.mjs" and a simple script to replaceAll and a RegEx and get rid of those Module level exports to get the above file-sizes.

[LeXXik]

I would like to drop my 50 cents here. I cannot stress enough how important the package size is in web game dev. Every 50 kb is worth saving. Majority of gamers today are accessing the games from potato devices with some crappy network. It takes not-inconsiderable time to download the game. The players simply don't wait. Maybe it comes from the fear that if it takes long to load it will eat their monthly plan (many regions don't have unlimited plans and pay per Mb). Maybe we get used to the fact that websites are insta-loading and web games are expected as well. No matter the reasons, our stats show that at most you have is 3 seconds for the "potential" player to load the game. Every second after that you lose half of your players. By second 10 only your friends will actually see and try the game. Unfortunately, "its only for the first load" is a misconception - there is simply no second load, if it takes too long for the first one. This is the main reason we did multiple IDL variants for Ammo, stripping out features that are not needed for a type of game. When you say 300 kb of saving - its already an amazing number worth going for, not mentioning even potentially larger improvements. I will definitely try it, @PhoenixIllusion, even if a generalized solution will be hard to create. I am totally fine to have an unofficial and brittle one that requires maintenance with every new release, but the size savings are worth it.

[DennisSmolek]

I often wonder that.
In other libraries we scrape and squabble over 50k yet load multiple GLTF models with the smallest being 4mb.

As a percentage of a whole, how big is the physics system? What is an acceptable size?
What is a size to "start" and then be streamed in later.

I don't disagree that 300kb is a lot and might be worth all the extra headaches, but I'm spending less and less time worrying about it.

[LeXXik]

From our internal stats, you are doing great, if your initial load is less than 1.5 Mb. The very first load is the most critical. Once the player is past it and gets into the game, you can do other tricks to pull assets, can be dozens of Mb. For example, there is usually some kind of a Home Screen in the game, where you don't need physics, so it can come after the app starts. However, if physics is needed immediately, then you only have 1.5 - size-of-physics-lib - size-of-webgl-framework Mb.

[PhoenixIllusion]

Technically not just the home screen/initial-menus, but any progress up until "physics takes hold or is required" (transitions, animations, dialogs, etc). Potentially most things up until the user takes over.
(ex: Racer cars - spin the camera around to behind the car, FirstPerson/3rd Person shooter like N64 Golden Eye - spin around to behind the player)
With BabylonJS, I can technically delay the physics engine init as late as I need, post scene creation and animation, though I would need to defer my physics-body registration/binding as well, and dump them all to Jolt all-at-once. That delayed scene behavior was kind of my experience in testing memory allocation/cleaning where I'd been snapshotting everything before/during/after the physics engine init.

In actual practice, that would be playing chicken with it and REALLY need to be sure the physics engine is going to be loaded in those cases or you've just weirded out and risk the experience freezing the game mid-play.

[PhoenixIllusion]

I found that instead of trying to manually transform the generated wasm JS-file, compiling with -s MINIMAL_RUNTIME=1 kind-of works.

I need to confirm it works for every feature we've been using with all potential flags, especially multi-threading, but it does perform the step of stripping exposure of all the _emscripten_bind functions on the Module, as well as removing some of the startup/exit routines.

Extra Stub to add before our glue

function assert(x) {
  if (!x) throw 'failed assert';
}
var runtimeInitialized = false;

var __ATINIT__    = [];
function addOnInit(cb) {
  __ATINIT__.unshift(cb);
}
function callRuntimeCallbacks(callbacks) {
  while (callbacks.length > 0) {
    // Pass the module as the first argument.
    callbacks.shift()(Module);
  }
}
ready = function() {
  updateMemoryViews();
  const heapKey = ['HEAP8','HEAPU8','HEAP16','HEAPU16','HEAP32','HEAPU32','HEAPF32','HEAPF64'];
  const heapVal = [HEAP8,HEAPU8,HEAP16,HEAPU16,HEAP32,HEAPU32,HEAPF32,HEAPF64];
  heapKey.forEach((k,i) => {
    Module[k] = heapVal[i]; 
  });
  Module['_webidl_malloc']=_webidl_malloc;
  Module['_webidl_free']=_webidl_free;
  callRuntimeCallbacks(__ATINIT__);
  readyPromiseResolve(Module);
}

This produces the Distribution wasm-JS uncompressed file size of about 550k vs the existing 1.1MB (or a wasm-compat of 3.2MB compared to 3.7 MB)

Regarding the wasm binary itself,
The built-in emscripten technique replicating what I described in the first post, of profiling the app using typescript, is Emscripten's built-in runtime analysis/profiling. This is not a trivial process.

You would be required to do a special compile and run your application through all your test cases (including create/run/destroy of everything), and store a log-file the special build produces after each test case that flags what functions were called. These profile files are then all combined together during a fresh build to produce 2x WASM files.

1. All functions required for most common execution, with non-functional stubs for all others that just invoke 'load extra WASM file'
2. All other functions

Ideally you don't need to ever load module 2.

https://emscripten.org/docs/optimizing/Module-Splitting.html

[jrouwe]

Is there some way to see which C++ symbols are taking up the most space?

As it happens, I was replacing std::vector with my own Array class and I just integrated that version into JoltPhysics.js. This makes jolt-physics.wasm.wasm 137 KB smaller than it was before and jolt-physics.wasm-compat.js 548 KB smaller (the C++ STL library is known for its bulkiness). I can imagine some of the other STL classes I'm using also add a lot of weight.

[PhoenixIllusion]

I'd looked into this, and https://rustwasm.github.io/twiggy/ is promising for at least breaking down the size of the functions, the call chains, and sizing. twiggy monos <*.wasm> shows some of the ::vector usage, along with some other std template usage.

I'm not sure of a 100% way to keep all the naming conventions in a fully optimized distribution build, but you can get kind-of close building Distribution with the -gseparate-dwarf flag for the project. I'm not sure if it's also required for the static '.a jolt-side as well.

[jrouwe]

That screenshot already suggests another possible saving: Defining JPH_NO_FORCE_INLINE removes some of those big inlined functions (at small performance cost, didn't measure exactly how much), defining this saves another 78K on for jolt-physics.wasm.wasm and 312K for jolt-physics.wasm-compat.js.

[jrouwe]

Running twiggy myself, the biggest functions come from HeightFieldShape, MeshShape and ContactConstraintManager, but you can't really live without them.

Other than that I see some waste coming from std::string, which would be a candidate for replacement with my own implementation.
The ObjectStream serialization system is also something that could be removed fairly easily (it removes a whole bunch of RTTI stuff).

[jrouwe]

Quick test with removing ObjectStream: 55KB of jolt-physics.wasm.wasm goes away (=3%) so it's questionable if this is worth it. See this branch.

I found that instead of trying to manually transform the generated wasm JS-file, compiling with -s MINIMAL_RUNTIME=1 kind-of works.

This seems to be the most promising thing so far...

[jrouwe]

I went ahead and merged the removal of ObjectStream.

[jrouwe]

FYI I made another change that removes C++ RTTI and exception code (unused by Jolt). This reduces the build by another 1%. See: f858ba9

[PhoenixIllusion]

I know one of the biggest reasons for exception and RTTI removal is to enable link-time-opts via -flto , although that can sometimes be a pain to get to fully compile given how much time/RAM/processing it sometimes takes. I'm curious to see if that flag has an impact one way or the other on performance or sizing.