- Update documentation for emscripten 3.1.34

- Move troubleshooting to separate document
- Add known issues section, including blue tint issue

README.md

@@ -14,13 +14,18 @@ Some other changes were also made to try and make a better out of the box experi
 - **Build compression of assets (to .gz files) is enabled by default**. You can still disable this if you prefer.
 - **All required scripts/assets (e.g. Bootstrap) are included in built project** (no more third party JS/font downloads).
 - **Web browser IndexedDB usage is enabled by default** to prevent having to download all the assets on each page refresh. You can still turn this off if you prefer the user to download the data every time.
-- **Uses single-threaded by default** as it seems to work better at the moment (tried this after seeing [@ufna](https://github.com/ufna/UE-HTML5)'s decision). Multi-threaded is still available but currently only works properly when packing for Development (will be looking into this issue).
+- **Uses single-threaded by default** as it seems to work better at the moment (tried this after seeing [@ufna](https://github.com/ufna/UE-HTML5)'s decision).
 - **Web socket networking plugin is enabled by default** should you wish to use multiplayer in HTML5.
 - Added [**optional experimental support for websocket SSL**](Features/Feature-WebSocketSSL.md). This allows multiplayer to work when serving the HTML5 client via HTTPS. This feature is disabled by default.
 - Added an [**optional way to pass command line options to the HTML5 application**](Features/Feature-CommandLine.md) e.g. to select different maps etc. This feature is disabled by default.
+- Added support for using [DecompressionStream](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) to attempt decompression of assets when they are not served with appropriate HTTP header. This gives more flexibility when hosting your application in environments where you don't/can't control the HTTP headers. This fallback is only supported in Chrome-based browsers.
 
 Live Example: [**AdhocCombat** (https://adhoccombat.com)](https://adhoccombat.com) - work in progress
 
+Known Issues:
+- In ES3 branch, reflections appear incorrect / have a blue tint. Using a gray texture reflection cubemap can somewhat mitigate this issue. See relevant [troubleshooting section](TROUBLESHOOTING.md).
+- In both ES2 and ES3 branch, HTML5 multithreading only works for Development builds (Test/Shipping has graphical corruption / black screen). Single-threaded is now the default and should be used to avoid this issue.
+
 ## Git Repository / Branches
 
 **To access the links below you need to link your Epic Games account to GitHub - see your [Epic Games Account](https://www.epicgames.com/account/connected) - if you do not do this you will see 404 error.**
@@ -29,19 +34,18 @@ Live Example: [**AdhocCombat** (https://adhoccombat.com)](https://adhoccombat.co
 
 https://github.com/SpeculativeCoder/UnrealEngine/tree/4.27-html5-es3
 
-This is **UnrealEngine 4.27.2** with HTML5 platform support using **ES3** shaders and **emscripten 3.1.32**.
+This is **UnrealEngine 4.27.2** with HTML5 platform support using **ES3** shaders and **emscripten 3.1.34**.
 
-If you want to take a look at the full code here is a [diff](https://github.com/EpicGames/UnrealEngine/compare/4.27.2-release...SpeculativeCoder:4.27-html5-es3) of this branch against the pristine UE 4.27.2 release (you can see the changes are all _new_ files in the Platforms/HTML5 folder). An alternative way to view the changes is to take UE 4.27.2 _along with_ @nickshin's last community supported UE4.24 HTML5 plugin code and compare this against the ES3 branch above - see this [diff](https://github.com/SpeculativeCoder/UnrealEngine/compare/4.27.2-release_with_4.24.3-html5-1.39.18_plugin..4.27-html5-es3). This shows the actual differences in the plugin code which were needed to get 4.27.2 working (along with the other changes) rather than all new files.
+If you want to take a look at the full code here is a [diff](https://github.com/EpicGames/UnrealEngine/compare/4.27.2-release...SpeculativeCoder:4.27-html5-es3) of this branch against the pristine UE 4.27.2 release (you can see the changes are all _new_ files in the Platforms/HTML5 folder). An alternative way to view the changes is to take UE 4.27.2 _along with_ @nickshin's last community supported UE4.24 HTML5 plugin code and compare this against the ES3 branch above - see this [diff](https://github.com/SpeculativeCoder/UnrealEngine/compare/4.27.2-release_with_4.24.3-html5-1.39.18_plugin..4.27-html5-es3). This shows the actual differences in the plugin code which were needed to get 4.27.2 working rather than all new files.
 
 ### 4.24 HTML5 ES2
 
 https://github.com/SpeculativeCoder/UnrealEngine/tree/4.24-html5-es2
 
-This is **UnrealEngine 4.24.3** with HTML5 platform support using **ES2** shaders and **emscripten 3.1.32** 
+This is **UnrealEngine 4.24.3** with HTML5 platform support using **ES2** shaders and **emscripten 3.1.34** 
 
 This may be useful as a fallback if you still need to use 4.24 or ES2 but want the other changes above - it also works as a reference of changes versus @nickshin's UE4.24 HTML5 plugin branch - see this [diff](https://github.com/UnrealEngineHTML5/UnrealEngine/compare/4.24.3-html5-1.39.18..SpeculativeCoder:4.24-html5-es2) for the comparison.
 
-
 ## Requirements
 
 - Git for Windows
@@ -99,7 +103,7 @@ Now you can build all the programs. CTRL-Click the following projects to select
 
 Now **Right Click -> Build Selection**
 
-This will take a long time. UE4 will be built last and takes the longest.
+This will take a long time. UE4 will be built last and takes the longest. If you see any failures at the end, try again at least once in case there was any ordering issue etc.
 
 ## Usage
 
@@ -117,91 +121,13 @@ Select the .html file. You should see the running game.
 
 ## Troubleshooting
 
-### When opening UE4.sln in Visual Studio you see "Target framework not supported" for each .NET program
-
-For each of these you should be able to accept the default of "Update the target" to the newer version of .NET which seems to work fine.
-
-### When packaging HTML5 you see: **error CS1519: Invalid token '(' in class, struct, or interface member declaration**
-
-If you see this when trying to package for HTML5 then in Visual Studio CTRL-Click these:
-- AutomationTool
-- AutomationToolLauncher
-- HTML5LaunchHelper
-- UnrealBuildTool
-
-Then do **Right Click -> Rebuild Selection** to force rebuild the .NET programs. Seems to fix the issue.
-
-### When running game you see in browser console an error with: "Assertion failed" regarding multisampled textures
-
-Try disabling Mobile MSAA (in Project Rendering options).
-
-### When running game you see in browser console an error with: "Assertion failed" relating to a compression method and "file needs to be forced to use zlib compression"
-
-This can happen if you have PAK file compression format set to **Oodle**. This HTML5 plugin requires you to use **Zlib** compression. You can change this as follows:
-
-Project Settings -> Packaging -> Pak File Compression Format(s): Change this from **Oodle** to **Zlib** 
-
-NOTE: This is an advanced setting so you need to click the down arrow to unhide the setting.
-
-Once you have done this you can package the project again as HTML5 and see if the issue is fixed. You may need to to clear the IndexedDB and/or browser cache so you get the newly generated PAK file.
-
-### When compiling, you see: "Detected compiler newer than Visual Studio XXX, please update min version checking"
-
-XXX is just whatever version of Visual Studio the branch was last successfully tested with. This can appear if you are using an even more recent version of Visual Studio (i.e. 2022 latest versions). It is just a warning and shouldn't cause any issues as VS2022 seems to be able to build the engine fine.
-
-### When packaging HTML5 you see: "WARNING: Library XXX as not resolvable to a file when used in Module 'XXX'"
-
-The XXX is usually PhysX. This seems to occur when HTML5Setup.sh randomly fails to properly build PhysX (or some other third party library) with an error like ```mingw32-make.exe[2]: write error: stdout``` but doesn't actually stop the ./HTML5Setup.sh build so it is easy to miss and you will only notice when then trying to package for HTML5.
-
-If you get this issue try running ./HTMLSetup.sh again.
-
-NOTE: In the latest versions of the above branches the third party libraries are built using only a single thread (-j 1) to hopefully avoid this problem happening as much.
-
-### When running HTML5Setup.sh you see: "fatal: not a git repository (or any of the parent directories): .git"
-
-The HTML5Setup.sh script in the above branches used to do a git checkout/restore to ensure the engine files were in a clean state before applying a patch, hence it didn't work if you downloaded a ZIP. However, I changed the HTML5Setup.sh to no longer require a git repository so if you have an older version of the code just do a new clone or ZIP download and you shouldn't run into this problem any more.
-
-### When running HTML5Setup.sh you see: "zlib-1.2.8.tar.gz: Cannot open: No such file or directory"
-
-This happens if you run HTML5Setup.sh without first having run the ./Setup.bat stage. Running ./Setup.bat to ensure all the dependencies Unreal needs are downloaded (including this zlib tar) should avoid this error.
-
-### When running HMTL5Setup.sh you see: "Python" (and/or things simply stop after seeing "Resolving deltas: 100% (XXX/XXX), done." and nothing more happens)
-
-Even if you have Python properly installed, Windows may have some [App installer python.exe and python3.exe](https://stackoverflow.com/questions/57485491/python-python3-executes-in-command-prompt-but-does-not-run-correctly) that could possibly be interfering with Python usage.
-
-### When running the game you only see a blank white page with buttons at the top and/or in the console log you see: "Uncaught SyntaxError: illegal character U+001F" and/or you see error/warning message: "Downloaded a compressed file XXX without the necessary HTTP response header "Content-Encoding: gzip""
-
-If you are using compressed packaging for HTML5 (which is the default), you need to ensure the files ending in `.gz' (i.e. the compressed files) are served with the following HTTP header:
-
-    Content-Encoding: gzip
-
-This signals to the web browser that it needs to decompress the file before trying to use it.
-
-The way the header can be set depends on how you are hosting the files. It will differ per solution - check the documentation for your web hosting solution. 
-
-However, if you need to temporarily work around this, you can disable compressed packaging:
-
-Project Settings -> HTML5 -> Packaging -> Compress files during packaging: Set to **false**
-
-Most of the increase in size due to turning off this compression will be in the size of the Unreal binary code which will no longer be compressed. The PAK data file actually has its own compression (which should be turned on by default) handled by Unreal so depending on how big your project the increase may or may not be a significant versus the overall size. 
-
-Also some web hosting solutions may _automatically_ do all the gzip compression of .css / .js assets on the fly (and set appropriate headers too) so in those cases you may be better off not using compressed packaging.
-
-### Why is the download so big? Can I reduce the size of the generated application?
-
-By default, Unreal includes all assets used by _any_ map in the project. So if you have enabled starter content, or some Marketplace assets, these may have maps in them that are dragging in a lot of assets you didn't actually intend to use.
-
-You should set the maps which will be included the packaging via this setting (make sure it has only the maps you make use of):
-
-Project Settings -> Packaging -> List of maps to include in packaged build
-
-This is an advanced setting so you may need to click the down arrow to show it.
+See [TROUBLESHOOTING](TROUBLESHOOTING.md) for troubleshooting / workarounds.
 
 ## Issues / Discussions
 
-If you need to raise any technical issues / discussions regarding this fork and the code changes you can use [Issues](https://github.com/SpeculativeCoder/UnrealEngine/issues) / [Discussions](https://github.com/SpeculativeCoder/UnrealEngine/discussions) (as above, you need your GitHub linked to your Epic Games account to use these).
+If you need to raise any technical issues / discussions regarding this fork and the code changes you can use [Issues](https://github.com/SpeculativeCoder/UnrealEngine/issues) / [Discussions](https://github.com/SpeculativeCoder/UnrealEngine/discussions) (you need your GitHub linked to your Epic Games account to see these or you will see 404 error).
 
-If interested in a more in-depth discussion of the development / code etc. there are some notes in a [COMMENTARY](https://github.com/SpeculativeCoder/UnrealEngine/wiki/COMMENTARY) wiki page which I will aim to add to over time.
+If interested in a more in-depth discussion of the development / code etc. there are some notes in a [COMMENTARY](https://github.com/SpeculativeCoder/UnrealEngine/wiki/COMMENTARY) wiki page which I will aim to add to over time (you need your GitHub linked to your Epic Games account to see this or you will see 404 error).
 
 Also there could be some general HTML5 plugin discussion in Unreal Slackers Discord https://unrealslackers.org/ in the **#web** channel (but note this channel is for general discussion of Unreal on the web, including the <a href="https://docs.unrealengine.com/5.1/en-US/pixel-streaming-in-unreal-engine/">Pixel Streaming</a> technology).