├── Platforms └── HTML5 │ ├── GettingStarted │ ├── HTML5GettingStarted.md │ └── Images │ │ ├── HTML5_Compression_Enabled.png │ │ ├── HTML5_Disable_MobileMSAA.png │ │ ├── HTML5_Disable_PAK_File.png │ │ ├── HTML5_PackageProject.png │ │ ├── HTML5_ReadMeHelp.png │ │ ├── HTML5_Select_Web_Browser.png │ │ ├── HTML5_StartWebServer.png │ │ ├── HTML5_UE4_ThirdPerson_In_Browser.png │ │ ├── HTML5_WebServer.png │ │ ├── LaunchNightly.png │ │ └── localhostinfo.png │ ├── HTML5.md │ ├── HTML5SDKRequirements │ └── HTML5SDKRequirements.md │ ├── HowTo │ ├── Images │ │ ├── archive_cpp_tp.png │ │ ├── create_BP_FP.apng │ │ ├── editor_build_configuration.jpg │ │ ├── editor_device_profile.png │ │ ├── editor_launcher.png │ │ ├── editor_output_log.png │ │ ├── editor_package_project.jpg │ │ ├── editor_play_in_editor_es2.jpg │ │ ├── editor_plugins_websocket.png │ │ ├── editor_project_launcher.png │ │ ├── editor_project_settings.jpg │ │ ├── editor_supported_platforms_html5.png │ │ ├── frontend_custom_profile.png │ │ ├── frontend_launch_profile.png │ │ ├── frontend_profiles.png │ │ ├── frontend_project_launcher.png │ │ ├── launcher_location_create.png │ │ ├── launcher_shootergame.png │ │ ├── shootergame_host.png │ │ ├── shootergame_join.png │ │ ├── shootergame_match.png │ │ ├── vs_build_ue4_editor.jpg │ │ ├── vs_config_dev_editor.jpg │ │ ├── vs_platform_win64.jpg │ │ ├── vs_solution_explorer.jpg │ │ ├── xc_build_running.png │ │ ├── xc_project_targets.png │ │ └── xc_ue4_target.png │ ├── README.0.building.UE4.Editor.md │ ├── README.1.emscripten.UE4.HTML5.md │ ├── README.2.advanced.UE4.HTML5.md │ ├── README.3.debugging.UE4.HTML5.md │ ├── README.4.faq.UE4.HTML5.md │ └── README.md │ └── Images │ ├── ActionRPG-resize514x289.jpg │ └── HTML5Development_topic.png └── README.md /Platforms/HTML5/GettingStarted/HTML5GettingStarted.md: -------------------------------------------------------------------------------- 1 | # Note: this page has been archived 2 | 3 | And left here for reference purposes. 4 | 5 | The latest detailed instructions on packaging Unreal Engine for HTML5 are all 6 | placed in the [HowTo](../HowTo/README.md) section. 7 | 8 | 9 | * * * 10 | * * * 11 | 12 | # Developing HTML5 Projects 13 | 14 | Setting up UE4 for HTML5 development. 15 | 16 | 17 | ## HTML5 SDK Setup 18 | 19 | The Unreal Engine 4 (UE4) HTML5 implementation utilizes the [Emscripten](https://github.com/emscripten-core/emscripten) toolchain (originally from [Mozilla](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Emscripten)) to cross-compile UE4's C++ code into WebAssembly (WASM). The Community-supported HTML5 platform extension will require this and addtional tools to be manually downloaded, installed and setup before being able to create HTML5 projects. 20 | 21 | 22 | * * * 23 | ## HTML5 Supported Web Browser 24 | 25 | ### 64-bit Browser 26 | 27 | Running UE4 HTML5 is highly recommended with a **64-bit** version web browser. You can find 64-bit versions of the Google Chrome and Firefox web browsers using the following links 28 | 29 | * [Google Chrome 64 Bit](https://www.google.com/chrome/beta/) 30 | 31 | * [Firefox 64 Bit](https://www.mozilla.org/en-US/firefox/all/) 32 | 33 | 34 | ### Multi-thread Support 35 | 36 | Multi-threaded support is available for UE4 HTML5. 37 | 38 | Some browsers may still need special flags enabled to be allowed to run in multi-threaded mode. 39 | 40 | * In **Chrome**: launch with the following flags: 41 | * `--js-flags=--experimental-wasm-threads --enable-features=WebAssembly,SharedArrayBuffer` 42 | * Alternately, these can be enabled and disabled in `chrome://flags/#enable-webassembly-threads` as "WebAssembly threads support" 43 | 44 | * In **Firefox**, **SharedArrayBuffer** can be enabled in `about:config` by setting the `javascript.options.shared_memory preference to true`. 45 | 46 | 47 | * * * 48 | ## UE4 Editor 49 | 50 | ### HTML5 Required Project Setup 51 | 52 | In order to get your UE4 powered HTML5 project working correctly you will need to disable MSAA from the [Project Settings](https://docs.unrealengine.com/en-US/Engine/UI/ProjectSettings). This can be done by going to **Project Settings** > **Rendering** > **Mobile** and then setting the **Mobile MSAA** option to **No MSAA**. 53 | 54 | ![](Images/HTML5_Disable_MobileMSAA.png) 55 | 56 | 57 | ### HTML5 Build Type 58 | 59 | When creating a build of your HTML5 project, you have the option of creating a **Development Build** or a **Shipping Build**. The type of build that you create for your project depends on what you are trying to accomplish. 60 | 61 | ### HTML5 Development Builds: 62 | 63 | * Development builds are used when you are testing or debugging your project before you want to release it. 64 | 65 | * Development builds will only generate uncompressed files. 66 | 67 | * Development builds should only be used with local testing and are not meant to be deployed to a website. 68 | 69 | > You can find more information about building your project for Development in the [HowTo](../HowTo/README.md) pages. 70 | 71 | 72 | ### HTML5 Shipping Builds: 73 | 74 | * Shipping builds are used when you are ready to release your project to end users. 75 | 76 | * Shipping builds can generate either compressed (for smaller download size) or uncompressed files. 77 | * However, smashing your texture sizes has yield the best results for download size savings. 78 | * See [Textures for Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/Textures/index.html), section **Per-Device Texture LOD**, and **especially step #4** for more details on how to do this. 79 | * For HTML5, try setting Max LOD Size to 256 and go up from there to ensure quality and download size are acceptable. 80 | 81 | > You can find more information about building your project for Shipping in the [HowTo](../HowTo/README.md) pages. 82 | 83 | 84 | ### Compression and PakFiles 85 | 86 | **NOTE: compression option is not needed anymore since switching to WASM. Left here for reference.** 87 | * (Use uncompressed builds for the best results on being able to server your project from most web host providers.) 88 | 89 | You can enable or disable compressing files for shipping HTML5 builds by doing the following: 90 | 91 | 1. Go to **Project Settings** > **Platforms** > **HTML5** > **Packaging** and then make sure to enable **Compress files during shipping packaging**. 92 | 93 | ![](Images/HTML5_Compression_Enabled.png) 94 | 95 | 1. It is also recommended that you **disable** the **Use Pak File** option by going to **Project Settings** > **Packaging** > **Packaging** and disable the **Use Pak File** option by clicking on the box next to its name. 96 | 97 | ![](Images/HTML5_Disable_PAK_File.png) 98 | 99 | **AGAIN: compression option is not needed anymore since switching to WASM. Left here for reference.** 100 | * (Use uncompressed builds for the best results on being able to server your project from most web host providers.) 101 | 102 | 103 | * * * 104 | ## Launching HTML5 Projects (i.e. from Editor) 105 | 106 | Once you have installed one of the compatible web browsers you can then test one of your HTML5 project. You can do this by: 107 | * going to the **Main Tool Bar** 108 | * next to the **Launch** button 109 | * click on the **Advanced Options** (drop-down-arrow) 110 | 111 | Then, in the **Devices** menu: 112 | * select the browser you wish to use by clicking on it 113 | 114 | ![](Images/HTML5_Select_Web_Browser.png) 115 | 116 | 117 | * * * 118 | ## Packaging HTML5 Projects (for your web server) 119 | 120 | To create a packaged HTML5 project that can be deployed to the web, you will need to do the following. 121 | 122 | 1. First, go to **File** > **Package Project** and select **HTML5** from the list. 123 | 124 | ![](Images/HTML5_PackageProject.png "HTML5_PackageProject.png") 125 | 126 | 1. Select a folder for the project to be saved and then click **Select Folder** to start the packaging process. 127 | 128 | 129 | * * * 130 | ## Testing Locally 131 | 132 | ### UE4's test web server 133 | 134 | Once the project has finished being packaged: 135 | * open the folder the project was packaged to 136 | 137 | ![](Images/HTML5_StartWebServer.png "HTML5_StartWebServer.png") 138 | 139 | * run the program **HTML5LaunchHelper.exe** (on windows) or **RunMacHTML5LaunchHelper.command** (on Mac) 140 | * this starts a web sever which is configured to serve compressed files on localhost 141 | * NOTE: this is **NOT** a production quality server 142 | * if necessary, add -ServerPort=XXXX to the command line to change the serving port 143 | * default port is 8000 144 | 145 | You can see the progress of this server in the command line window that is displayed when the **HTML5LaunchHelper.exe** program is run. 146 | 147 | ![](Images/HTML5_WebServer.png "HTML5_WebServer.png") 148 | 149 | 150 | Finally, open up your 64-bit web browser of choice and input the following URL: 151 | * `http://localhost:8000/[ProjectName].html` 152 | * This will load your UE4 HTML5 project in the web browser like in the image below (please ignore the URL seen here, this is from when **Launcher** is used (see [above](#launching-html5-projects))). 153 | 154 | ![](Images/HTML5_UE4_ThirdPerson_In_Browser.png "HTML5_UE4_ThirdPerson_In_Browser.png") 155 | 156 | > Again, the URL that you input is based off of your project name. With the above project called **ThirdPerson** the address that should be input would be `http://localhost:8000/ThirdPerson.html` 157 | 158 | 159 | ### Python web server 160 | 161 | You may use python's built in web server, e.g.: 162 | * (from the command prompt, to where the the [project].html file is located) 163 | 164 | > `python -m SimpleHTTPServer 8000` 165 | 166 | 167 | ### Apache/NGINX/other web server(s) 168 | 169 | OSX and Linux normally have Apache installed. NGINX can also be used as well. 170 | 171 | * You can use these (or any of your other favrites) for testing -- which may have the closest behavior to most web host providers. 172 | * If you are reading this section, we assume you have a deep understanding of web server technology. This is not for beginners. 173 | 174 | 175 | 176 | * * * 177 | ## HTML5 File Types 178 | 179 | When building your UE4 project for development or deployment with HTML5 you have the option to use compressed or uncompressed files. The following chart breaks down what files are required for uncompressed builds and what information these files contain. 180 | 181 | 182 | ### Files Required for Non-Compressed Files Deployment 183 | The following files are created when a non-compressed build is created. 184 | 185 | |File Type|Description| 186 | | --- | --- | 187 | | **[project].html** | Main project Landing page (see template code). | 188 | | **[project].UE4.js** | Main project Javascript code (see template code). | 189 | | **[project].css** | Main project CSS code (see template code). | 190 | | **[project].wasm** | Main game code (generated). | 191 | | **[project].js** | Main game code (WASM) Javascript driver (generated). | 192 | | **[project].data** | Game content (generated). | 193 | | **[project].data.js** | Game content Javascript driver (generated). | 194 | | **Utility.js** | Utility (open source) Javascript code. | 195 | | **.htaccess** | Distributed configuration file | 196 | 197 | > Note: template code can be found in `Engine/Platforms/HTML5/Build/TemplateFiles` 198 | 199 | 200 | ### Files Required for Compressed Files Deployment 201 | 202 | **AGAIN: compression option is not needed anymore since switching to WASM. Left here for reference.** 203 | * (Use uncompressed builds for the best results on being able to server your project from most web host providers.) 204 | 205 | The following files are created when a compressed build is crated. 206 | 207 | |File Type|Description| 208 | | --- | --- | 209 | | **[project].UE4.jsgz** | Compressed main project Javascript code. | 210 | | **[project].wasmgz** | Compressed main game code. | 211 | | **[project].jsgz** | Compressed main game (WASM) Javascript code. | 212 | | **[project].datagz** | Compressed game content. | 213 | | **[project].data.jsgz** | Compressed game content Javascript driver. | 214 | | **Utility.jsgz** | Compressed utility (open source) Javascript code. | 215 | 216 | > When using the compressed version of the files you will also need to make sure to include the uncompressed version of the **.htaccess** file and the **.html** file. 217 | 218 | If you are an advanced web server administrator: 219 | * Using compression helps improve download times. 220 | * Using pre-compressed files may help your web server from compressing the files dynamically everytime the time your project is loaded on to a browser. 221 | * NOTE: Being able to serve pre-compressed files will require configuring your web server to properly serve the UE4 compressed file extention type. 222 | * These settings are placed in the .htaccess file 223 | * This file will work on most Apache web servers (that have the AllowOveride option set to (e.g.) All). 224 | * AGAIN, if you are reading this section, we assume you have a deep understanding of web server technology. 225 | * This is not for beginners. 226 | 227 | **AGAIN: compression option is not needed anymore since switching to WASM. Left here for reference.** 228 | * (Use uncompressed builds for the best results on being able to server your project from most web host providers.) 229 | 230 | 231 | ### Files not needed for Deployment 232 | The following files are created when both a compressed and uncompressed version of the project is created. However these files are only needed when your project is under development or being tested. 233 | 234 | |File Name|Description| 235 | | --- | --- | 236 | | **HTML5LaunchHelper.exe** | Used to create a local web server to view your project locally on Windows based PC's. | 237 | | **RunMacHTML5LaunchHelper.command** | Used to create a local web server (via HTML5LaunchHelper) to view your project locally on Mac. | 238 | | **Readme.txt** | Contains additional information about deploying UE4 project for HTML5. | 239 | 240 | 241 | ### Files no longer generated 242 | The following files used to be created when using older emscripten toolchain. 243 | 244 | |File Name|Description| 245 | | --- | --- | 246 | | **[project].symbols** | Symbols (optional: used with debugging). | 247 | | **[project].mem** | Pre-allocated memory file. | 248 | 249 | 250 | * * * 251 | 252 | -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_Compression_Enabled.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_Compression_Enabled.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_Disable_MobileMSAA.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_Disable_MobileMSAA.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_Disable_PAK_File.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_Disable_PAK_File.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_PackageProject.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_PackageProject.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_ReadMeHelp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_ReadMeHelp.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_Select_Web_Browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_Select_Web_Browser.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_StartWebServer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_StartWebServer.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_UE4_ThirdPerson_In_Browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_UE4_ThirdPerson_In_Browser.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/HTML5_WebServer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/HTML5_WebServer.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/LaunchNightly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/LaunchNightly.png -------------------------------------------------------------------------------- /Platforms/HTML5/GettingStarted/Images/localhostinfo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/GettingStarted/Images/localhostinfo.png -------------------------------------------------------------------------------- /Platforms/HTML5/HTML5.md: -------------------------------------------------------------------------------- 1 | # UE4 HTML5 Platform Extension 2 | 3 | HTML5 platform support has been migrated to GitHub as a community-supported Platform Extension and no longer officially supported by Epic in upcoming releases. 4 | 5 | HTML5 uses the [Emscripten Toolchain](https://emscripten.org/docs/introducing_emscripten/about_emscripten.html#emscripten-toolchain) from [Mozilla](https://www.mozilla.org/en-US/) to cross-compile C++ into Javascript. 6 | 7 | * * * 8 | * [Getting Started with UE4 for HTML5](./GettingStarted/HTML5GettingStarted.md) 9 | 10 | * [HTML5 Development Requirements](./HTML5SDKRequirements/HTML5SDKRequirements.md) 11 | 12 | * * * 13 | ## Content Development 14 | 15 | When building content aimed at the HTML5 platform, you can use the guidelines for creating mobile-oriented content as many of the restrictions for mobile development are applicable to HTML5 development. 16 | 17 | * [Materials for Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/Materials) 18 | 19 | * [Textures for Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/Textures) 20 | 21 | * [Lighting for Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/Lighting) 22 | 23 | * [Meshes for Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/Meshes) 24 | 25 | * [Post Process Effects on Mobile Platforms](https://docs.unrealengine.com/en-US/Platforms/Mobile/PostProcessEffects) 26 | 27 | * [Performance Guidelines for Mobile Devices](https://docs.unrealengine.com/en-US/Platforms/Mobile/Performance) 28 | 29 | * [Mobile Performance Tips and Tricks](https://docs.unrealengine.com/en-US/Platforms/Mobile/Performance/TipsAndTricks) 30 | 31 | * [Mobile Previewer](https://docs.unrealengine.com/en-US/Platforms/Mobile/Previewer) 32 | 33 | * [Mobile Packaging Wizard](https://docs.unrealengine.com/en-US/Platforms/Mobile/MobilePackagingWizard) 34 | 35 | * * * 36 | ## Samples 37 | 38 | ![ActionRPG.jpg](Images/ActionRPG-resize514x289.jpg "ActionRPG.jpg") 39 | 40 | The following link will allow you to play an HTML5 version of Action RPG right in your web browser. 41 | 42 | [Action RPG in HTML5](https://epiclearningresources.000webhostapp.com/ActionRPG/ActionRPG-HTML5-Shipping.html) 43 | 44 | * * * 45 | 46 | -------------------------------------------------------------------------------- /Platforms/HTML5/HTML5SDKRequirements/HTML5SDKRequirements.md: -------------------------------------------------------------------------------- 1 | # HTML5 Development Requirements 2 | 3 | In this page you'll find hardware and software development kit (SDK) requirements needed to start developing for the [HTML5](../HTML5.md) platform. 4 | 5 | - You can find the currently supported SDK version(s) in the `HTML5SDKInfo.cs` file. You can find it in your `Engine/Platforms/HTML5/Source/Programs/UnrealBuildTool/` folder. 6 | 7 | * * * 8 | 9 | ## Unreal Engine 4.24 10 | 11 | | Hardware Requirements || 12 | | --- | --- | 13 | | **Recommended Desktop Hardware** | See [Hardware and Software Specifications](https://docs.unrealengine.com/en-US/GettingStarted/RecommendedSpecifications). | 14 | 15 | | Software Requirements || 16 | | --- | --- | 17 | | **SDK Version** | Emscripten 1.39.0 | 18 | | **Supported Web Browsers** | [Google Chrome 64-bit](https://www.google.com/chrome/beta/), [Firefox 64-bit](https://www.mozilla.org/en-US/firefox/all/) | 19 | 20 | ### Special: HTML5's Unreal Engine 4.24.3 21 | 22 | Note: Epic LOCKS down toolchains on all `major.minor` updates. 23 | They do not allow SDK version numbers to change during `major.minor.patch` updates. 24 | 25 | But, since HTML5 is community driven and emscription DOES NOT lock down the version numbers 26 | of TOOLS used (i.e. can be incremented at will -- again, this is the tools used -- not to 27 | be confused with emscripten itself), there are periods of time when upgrading the toolchain 28 | will become possible. In this case, for UE 4.24.3, emscripten 1.39.18 is possible. 29 | 30 | | Software Requirements || 31 | | --- | --- | 32 | | **SDK Version** | Emscripten 1.39.18 | 33 | 34 | 35 | ## Unreal Engine 4.23 36 | 37 | | Hardware Requirements || 38 | | --- | --- | 39 | | **Recommended Desktop Hardware** | See [Hardware and Software Specifications](https://docs.unrealengine.com/en-US/GettingStarted/RecommendedSpecifications). | 40 | 41 | | Software Requirements || 42 | | --- | --- | 43 | | **SDK Version** | Emscripten 1.38.31 | 44 | | **Supported Web Browsers** | [Google Chrome 64-bit](https://www.google.com/chrome/beta/), [Firefox 64-bit](https://www.mozilla.org/en-US/firefox/all/) |:wa 45 | 46 | 47 | ## Unreal Engine 4.22 48 | 49 | | Hardware Requirements || 50 | | --- | --- | 51 | | **Recommended Desktop Hardware** | See [Hardware and Software Specifications](https://docs.unrealengine.com/en-US/GettingStarted/RecommendedSpecifications). | 52 | 53 | | Software Requirements || 54 | | --- | --- | 55 | | **SDK Version** | Emscripten 1.38.20 | 56 | | **Supported Web Browsers** | [Google Chrome 64-bit](https://www.google.com/chrome/beta/), [Firefox 64-bit](https://www.mozilla.org/en-US/firefox/all/) | 57 | 58 | 59 | ## Unreal Engine 4.21 60 | 61 | | Hardware Requirements || 62 | | --- | --- | 63 | | **Recommended Desktop Hardware** | See [Hardware and Software Specifications](https://docs.unrealengine.com/en-US/GettingStarted/RecommendedSpecifications). | 64 | 65 | | Software Requirements || 66 | | --- | --- | 67 | | **SDK Version** | Emscripten 1.37.19 | 68 | | **Supported Web Browsers** | [Google Chrome 64-bit](https://www.google.com/chrome/beta/), [Firefox 64-bit](https://www.mozilla.org/en-US/firefox/all/) | 69 | 70 | 71 | ## Unreal Engine 4.20 72 | 73 | | Hardware Requirements || 74 | | --- | --- | 75 | | **Recommended Desktop Hardware** | See [Hardware and Software Specifications](https://docs.unrealengine.com/en-US/GettingStarted/RecommendedSpecifications). | 76 | 77 | | Software Requirements || 78 | | --- | --- | 79 | | **SDK Version** | Emscripten 1.37.19 | 80 | | **Supported Web Browsers** | [Google Chrome 64-bit](https://www.google.com/chrome/beta/), [Firefox 64-bit](https://www.mozilla.org/en-US/firefox/all/) | 81 | 82 | 83 | * * * 84 | 85 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/archive_cpp_tp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/archive_cpp_tp.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/create_BP_FP.apng: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/create_BP_FP.apng -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_build_configuration.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_build_configuration.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_device_profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_device_profile.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_launcher.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_launcher.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_output_log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_output_log.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_package_project.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_package_project.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_play_in_editor_es2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_play_in_editor_es2.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_plugins_websocket.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_plugins_websocket.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_project_launcher.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_project_launcher.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_project_settings.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_project_settings.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/editor_supported_platforms_html5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/editor_supported_platforms_html5.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/frontend_custom_profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/frontend_custom_profile.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/frontend_launch_profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/frontend_launch_profile.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/frontend_profiles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/frontend_profiles.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/frontend_project_launcher.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/frontend_project_launcher.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/launcher_location_create.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/launcher_location_create.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/launcher_shootergame.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/launcher_shootergame.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/shootergame_host.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/shootergame_host.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/shootergame_join.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/shootergame_join.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/shootergame_match.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/shootergame_match.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/vs_build_ue4_editor.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/vs_build_ue4_editor.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/vs_config_dev_editor.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/vs_config_dev_editor.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/vs_platform_win64.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/vs_platform_win64.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/vs_solution_explorer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/vs_solution_explorer.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/xc_build_running.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/xc_build_running.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/xc_project_targets.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/xc_project_targets.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/Images/xc_ue4_target.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/HowTo/Images/xc_ue4_target.png -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.0.building.UE4.Editor.md: -------------------------------------------------------------------------------- 1 | # Building UE4 Editor 2 | 3 | this page will show you how to: 4 | - get required tools for you development environment 5 | - [clone Unreal Engine](#get-source-files) with the `HTML5 platform extension` branch 6 | - [build Unreal Engine Editor](#compiling-ue4editor) 7 | - [package BluePrint project](#package-a-sample-blueprint-project) (a small example, for your current desktop "target") 8 | - [package C++ project](#package-a-sample-c-cpp-project) (for practice) 9 | 10 | including the different ways Unreal Engine does packaging: 11 | - [Package Project](#build-the-sample-blueprint-project) 12 | - [Project Launcher](#project-launcher) 13 | - [UnrealFrontEnd](#project-launcher-interface) 14 | - Editor's [Launcher](#the-editors-launcher) 15 | 16 | * * * 17 | * * * 18 | ## Development Environment Requirements 19 | 20 | please ensure you have the following tools downloaded and installed: 21 | 22 | - [Git](https://git-scm.com/downloads) 23 | - Windows Note: 24 | - accept the default selected components 25 | - if you wish, change the editor preference (to your favorite) 26 | - personally, i `use Git from Git Bash only` (but, if you forsee yourself 27 | using `git` from the **CommandPrompt** or **PowerShell**, then use the 28 | `recommended` option) 29 | - accept all defaults (including `use MinTTY`) for the rest of the install 30 | - [Python](https://www.python.org/downloads/) 3.x or above 31 | - WARNING: Python 2.x is now "End of Life" 32 | - [CMake](https://cmake.org/download/) 3.12 or above 33 | - Windows Note: 34 | - make sure to choose the option to add cmake to the `PATH` (local user or all users) 35 | - you will most likely need to log out and log back in to have this `PATH` updated 36 | 37 | and, ensure you have the respective compiler tools for your desktop: 38 | 39 | - Windows 40 | - [Visual Studio 2017](https://visualstudio.microsoft.com/vs/community/) 41 | 42 | - Mac 43 | - [XCode 11](https://apps.apple.com/us/app/xcode/id497799835?mt=12) 44 | 45 | - Linux 46 | - build-essential 47 | 48 | 49 | * * * 50 | ## Get Source Files 51 | 52 | clone Unreal Engine (in this case, a fork of UE4 release 4.24.3 that has already 53 | been branched with the HTML5 files populated in the `Unreal Engine platforms 54 | extension` path). 55 | 56 | in this example, clone to a folder named `ue4-4.24.3-html5` 57 | 58 | ``` 59 | git clone -b 4.24.3-html5-1.39.18 --single-branch https://github.com/UnrealEngineHTML5/UnrealEngine ue4-4.24.3-html5 60 | ``` 61 | 62 | remember, HTML5 is no longer an officially supported platform at Epic Games -- hence the `UnrealEngineHTML5` github account. 63 | 64 | * * * 65 | ## Generate Project/Make Files 66 | 67 | NOTE: due to the special branch that already has HTML5 platform files populated, 68 | we are going to squeeze in calling `HTML5Setup.sh` here. 69 | 70 | we will do an indepth explaination (and go over some troubleshooting tips) of 71 | [HTML5Setup.sh](README.1.emscripten.UE4.HTML5.md#html5setupsh-build-script) 72 | in the next HowTo. 73 | 74 | HEADS UP: the first time running this may take a while: 75 | - `Setup.bat/Setup.command/Setup.sh` may take up to 20 minutes 76 | - `HTML5Setup.sh` may take up to an hour or so 77 | - `GenerateProjectFiles.bat/GenerateProjectFiles.command/GenerateProjectFiles.sh` may take up to 5 minutes 78 | 79 | 80 | ### on Windows 81 | 82 | ``` 83 | # open git-bash 84 | # or, you can use "File Explorer" and right click on the 85 | # "ue4-4.24.3-html5" folder and select "Git Bash Here" 86 | cd ue4-4.24.3-html5 87 | ./Setup.bat 88 | 89 | cd Engine/Platforms/HTML5 90 | ./HTML5Setup.sh 91 | cd - 92 | 93 | ./GenerateProjectFiles.bat 94 | # open the generated visual studio solution (UE4.sln) 95 | ``` 96 | 97 | 98 | ### on Mac 99 | 100 | ``` 101 | # open a terminal to 102 | cd ue4-4.24.3-html5 103 | ./Setup.command 104 | 105 | cd Engine/Platforms/HTML5 106 | ./HTML5Setup.sh 107 | cd - 108 | 109 | ./GenerateProjectFiles.command 110 | # open the generated xcode project (UE4.xcworkspace) 111 | ``` 112 | 113 | 114 | ### on Linux 115 | 116 | ``` 117 | # open a terminal to 118 | cd ue4-4.24.3-html5 119 | ./Setup.sh 120 | 121 | cd Engine/Platforms/HTML5 122 | ./HTML5Setup.sh 123 | cd - 124 | 125 | ./GenerateProjectFiles.sh 126 | ``` 127 | 128 | ### a note on (ENGINE) Setup.bat (Setup.command and Setup.sh) 129 | 130 | this only needs to be run ONCE on your desktop. it doesn't hurt if it is run 131 | more than once (which might need to be done on newer Unreal Engine versions). 132 | 133 | but, this is just a tip to save re-build times (or when trying to figure out 134 | why your development environment is not working). 135 | 136 | 137 | * * * 138 | * * * 139 | ## Compiling Support Programs 140 | 141 | ### on Windows 142 | 143 | after the visual studio solution is opened, i like to "manually rebuild" these support programs in the following order: 144 | 145 | - in visual studio: 146 | - ensure **Solution Platform** is set to **Win64** 147 | 148 | ![](Images/vs_platform_win64.jpg) 149 | 150 | - and **Solution Configuration** is set to **Development Editor** 151 | 152 | ![](Images/vs_config_dev_editor.jpg) 153 | 154 | - in **Solution Explorer-> Solution -> Programs**, `right click select` and `build` the following (again, in this order): 155 | - AutomationTool 156 | - AutomationToolLauncher 157 | - UnrealBuildTool 158 | - UnrealHeaderTool 159 | - HTML5LaunchHelper 160 | - this needs to be **MANUALLY** added in to the visual studio solution: 161 | - `Engine/Platforms/HTML5/Source/Programs/HTML5/HTML5LaunchHelper/HTML5LaunchHelper.csproj` 162 | - `UBT` is not adding this automatically during `GenerateProjectFiles.bat` for some reason... 163 | - ShaderCompileWorker 164 | - UnrealLightmass 165 | - UnrealPak 166 | - UnrealFileServer 167 | - UnrealFrontend (i normally like to build this particular one **after** building UE4Editor -- next section below...) 168 | 169 | ![](Images/vs_solution_explorer.jpg) 170 | 171 | 172 | ### on Mac 173 | 174 | - open the XCode project and build the following (again, in this order): 175 | - UnrealHeaderTool 176 | - ShaderCompileWorker 177 | - UnrealLightmass 178 | - UnrealPak 179 | - UnrealFileServer 180 | - UnrealFrontend (i normally like to build this particular one **after** building UE4 -- next section below...) 181 | 182 | ![](Images/xc_project_targets.png) 183 | 184 | - select the target and then select: 185 | - **Menu -> Product -> Build For -> Running** 186 | - or `Command + Shift + R` 187 | 188 | > see building [UE4 on Mac](#on-mac-2) below for screenshot example 189 | 190 | 191 | > NOTE: on Mac and Linux, HTML5LaunchHelper is automatically built when HTML5 is packaged 192 | 193 | 194 | ### on Linux 195 | 196 | - from the same command prompt where `./GenerateProjectFiles.sh` was run above: 197 | - `make StandardSet` 198 | - note, this will also build UE4Editor 199 | - this will all take a while to complete... 200 | - goto Happy Hour 201 | 202 | > NOTE: on Mac and Linux, HTML5LaunchHelper is automatically built when HTML5 is packaged 203 | 204 | * * * 205 | ## Compiling UE4Editor 206 | 207 | ### on Windows 208 | 209 | - `right click select` and `build` **Solution Explorer-> Solution -> Engine -> UE4** 210 | 211 | ![](Images/vs_build_ue4_editor.jpg) 212 | 213 | - this may take a while to complete (especially on the first build) 214 | - goto Lunch 215 | 216 | 217 | ### on Mac 218 | 219 | - select `UE4` 220 | 221 | ![](Images/xc_ue4_target.png) 222 | 223 | - and then select: 224 | - **Menu -> Product -> Build For -> Running** 225 | - or `Command + Shift + R` 226 | 227 | ![](Images/xc_build_running.png) 228 | 229 | 230 | - this may take a while to complete (especially on the first build) 231 | - goto Farmers Market Cafe 232 | 233 | 234 | ### on Linux 235 | 236 | - while this was already built above, use the following when making changes to UE4Editor: 237 | - `make UE4Editor` 238 | 239 | > NOTE: when kernel version has been upgraded, UE4Editor needs to be rebuilt clean: 240 | - run: `make UE4Editor ARGS=-clean` 241 | - and then `make StandardSet` (or `make UE4Editor`) 242 | 243 | 244 | * * * 245 | * * * 246 | ## Run UE4Editor 247 | 248 | when the build completes, fire up the Editor: 249 | - note: i like to see the `stdout` prints (to know that the Editor is still running) 250 | - using `-log` parameter to view this 251 | 252 | ### on Windows 253 | 254 | ...\Engine\Binaries\Win64\UE4Editor.exe -log 255 | 256 | ### on Mac 257 | 258 | open .../Engine/Binaries/Mac/UE4Editor.app --args -log 259 | 260 | - if you happen to see the `Epic Games Launcher` asking you to install it or 261 | "running", go ahead and install it (copy to `Applications` folder) and then 262 | finish up by closing it. 263 | - we will revisit this in the [advanced example](README.2.advanced.UE4.HTML5.md#epic-games-launcher) HowTo 264 | 265 | 266 | ### on Linux 267 | 268 | .../Engine/Binaries/Linux/UE4Editor -log 269 | 270 | 271 | * * * 272 | 273 | > if you see the **shaders building** -- let it run to completion -- this is usually a one time build. 274 | 275 | 276 | * * * 277 | * * * 278 | ## Package a Sample BluePrint Project 279 | 280 | in Unreal parlance, "packaging" means: 281 | - building the executable 282 | - preparing (called "cooking") all graphic, audio assets and other data files 283 | - and bundling everything together for the targeted platform 284 | 285 | 286 | ### Ensure Build Environment Is Working 287 | 288 | #### ( Creating a Sample Blueprint Project ) 289 | 290 | let us start by creating a simple UE4 project targeted for your current desktop 291 | computer. this will check your build environment to see if it is working before 292 | moving on to other platforms. 293 | 294 | after opening UE4Editor (from [Run UE4Editor](#run-ue4editor) above): 295 | 296 | - in the **Unreal Project Browser** 297 | 298 | - in **Select or Create a New Project** 299 | - click on `Games`, then **Next** 300 | 301 | - in **Select Template** 302 | - select (for example) `First Person`, then **Next** 303 | 304 | - in **Project Settings** 305 | - keep (for example) `Blueprint`, `Maximum Quality`, `Raytracing Disabled` and `Desktop/Console` 306 | - do change to `No Starter Content` (want to keep this project small for testing purposes) 307 | - select your `Folder` path and make up a project `Name` 308 | - e.g. let's call this project `BP_FP` (for blueprint first person) 309 | 310 | - finally, click **Create Project** button 311 | 312 | ![](Images/create_BP_FP.apng) 313 | 314 | 315 | * * * 316 | ### Readying UE4Editor 317 | 318 | when the Editor restarts, I like to have the following windows opened: 319 | 320 | #### window #1 321 | 322 | - Menu bar -> Window -> Developer Tools -> **Output Log** 323 | - you can tear the `output log` tab out of the box (for example) to another screen 324 | - the `output log` is where all prints are dumped 325 | - a must have when BugHunting packaging errors 326 | 327 | ![](Images/editor_output_log.png) 328 | 329 | #### window #2 330 | 331 | - Menu bar -> Edit -> Project Settings ... 332 | 333 | ![](Images/editor_project_settings.jpg) 334 | 335 | - click around (and look around) the **Project Settings** categories and options for EVERYTHING (including the kitchen sink) 336 | - nothing needs to be changed here for now 337 | - just be aware this is where a lot of customization settings are found 338 | 339 | 340 | * * * 341 | ### Build the Sample BluePrint Project 342 | 343 | set the build type: 344 | 345 | - Menu bar -> File -> **Package Project** -> Build Configuration 346 | - select `Development` (we are going to use the **game console** to **exit** the game below) 347 | - but, you can select `Shipping` when deploying for release 348 | 349 | ![](Images/editor_build_configuration.jpg) 350 | 351 | finally, package for your desktop: 352 | 353 | - Menu bar -> File -> Package Project -> **Windows** or **Mac** or **Linux** (choose your desktop platform of choice) 354 | - select the folder where the final files will be **archived** to 355 | - **e.g.** on Windows: `D:\Builds\BP_FP\` 356 | - **e.g.** on Mac or Linux: `/ue4/Builds/BP_FP/` 357 | 358 | - this is going to take a while to complete... especially if it's the first time building shaders too 359 | - go out for coffee 360 | 361 | 362 | * * * 363 | ## Test Sample BluePrint Project 364 | 365 | ### on Windows via File Explorer 366 | 367 | - open `File Explorer` to the location where files were **archived** to 368 | - e.g. `D:\Builds\BP_FP\WindowsNoEditor` 369 | - double click on `BP_FP.exe` 370 | 371 | 372 | ### on Mac via Finder 373 | 374 | - open `Finder` to the location where files were **archived** to 375 | - e.g. `/ue4/Builds/BP_FP/MacNoEditor` 376 | - double click on `BP_FP.app` 377 | 378 | 379 | ### on Linux via File Manager 380 | 381 | - open `File Manager` to the location where files were **archived** to 382 | - e.g. `/ue4/Builds/BP_FP/LinuxNoEditor` 383 | - double click on `BP_FP.sh` 384 | 385 | 386 | ### To Exit Game 387 | 388 | - press `~` key 389 | - type `exit` in the **console** 390 | - hit enter/return key to quit game 391 | 392 | 393 | * * * 394 | * * * 395 | ## Package a Sample C++ (cpp) Project 396 | 397 | for practice, let us try doing all of this again. except this time, we are 398 | going to use a C++ template project and use other packaging tools available 399 | with Unreal Engine. 400 | 401 | 402 | ### Creating Sample C++ (cpp) Project 403 | 404 | - [start up the Editor](#run-ue4editor) again if it is shutdown 405 | - in the **Unreal Project Browser** 406 | - in **Select or Create a New Project** 407 | - click on `Games`, then **Next** 408 | 409 | - or, if your Editor is still running, you can select: 410 | - Menu bar -> File -> **New Project...** 411 | - in **Select Template Category** 412 | - click on `Games`, then **Next** 413 | 414 | this time, we are gong to try a different project called: **Third Person** 415 | 416 | - in **Select Template** 417 | - select (for example) `Third Person`, then **Next** 418 | - in **Project Settings** 419 | - change "Blueprint" to `C++` 420 | - keep `Maximum Quality`, `Raytracing Disabled` and `Desktop/Console` 421 | - change to `No Starter Content` (want to keep this project small for testing purposes) 422 | - select your project `Folder` path and make up a project `Name` 423 | - e.g. let's call this project `CPP_TP` (for c++ third person) 424 | 425 | > NOTE: we are going to use `CPP_TP` for the rest of this HowTo 426 | 427 | close down the Editor -- we will restart it after building some (third person) 428 | binary files that the Editor will load-in upon re-running it. 429 | 430 | 431 | ### Compile Sample C++ (cpp) "Editor" Files 432 | 433 | (this is **an additional step** that needs to be done differently from the BluePrint only project.) 434 | 435 | with the new C++ project created from the steps just above: 436 | 437 | #### on Windows 438 | 439 | - visual studio might be automatically started up 440 | - otherwise, double click on the **UE4.sln** to start visual studio up 441 | 442 | - `right click select` and `build` **Solution Explorer-> Solution -> Games -> CPP_TP** 443 | - this will build the **project's Editor files** 444 | - note: this is not the same thing as the **project's runtime files** 445 | - we will do this later back in the Editor 446 | 447 | #### on Mac 448 | 449 | - double click on `UE4.xcworkspace` 450 | 451 | #### on Linux 452 | 453 | ```bash 454 | # remember, the project `Folder` (and project `Name`) was set 455 | # during the last step in "Creating Sample C++ (cpp) Project" 456 | cd CPP_TP 457 | make CPP_TP CPP_TPEditor 458 | ``` 459 | 460 | * * * 461 | ### Build Sample C++ (cpp) Project 462 | 463 | restart the Editor with the project name appended 464 | - note the use of `CPP_TP` here 465 | 466 | ##### on Windows 467 | 468 | ...\Engine\Binaries\Win64\UE4Editor.exe CPP_TP -log 469 | 470 | ##### on Mac 471 | 472 | open .../Engine/Binaries/Mac/UE4Editor.app --args CPP_TP -log 473 | 474 | ##### on Linux 475 | 476 | .../Engine/Binaries/Linux/UE4Editor CPP_TP -log 477 | 478 | 479 | > TIP: put the command in a shortcut (or alias, script, etc.) 480 | 481 | 482 | #### Plugins 483 | 484 | for this example, to get you familiar with the **Plugins** features - open the 485 | **Plugins** window and let's enable one item (we will see a more indepth explaination 486 | on using this plugin in the [advanced example](README.2.advanced.UE4.HTML5.md#special-note-enable-websocket-networking-plugin)). 487 | - Menu bar -> Edit -> Plugins ... 488 | 489 | when the **Plugins** window open, in the `Search` box type **websocket**, 490 | or you can find it in: 491 | 492 | - Built-in -> Misc 493 | - **Experimental WebSocket Networking Plugin** 494 | 495 | ensure that it is enabled (if the Editor asks you to restart, do so). 496 | 497 | ![](Images/editor_plugins_websocket.png) 498 | 499 | 500 | #### BEFORE: 501 | 502 | Back in the Editor, we used the steps in [BluePrint example](#build-the-sample-blueprint-project) 503 | to package from the Editor. 504 | 505 | but now, let's try and use the other packaging tools available with Unreal Engine: 506 | - **Project Launcher** and 507 | - **UnrealFrontend** (think of this as a smaller version of `Editor` that **ONLY** does **packaging**) 508 | > NOTE: you should build from Editor **at least once** before using UnrealFrontend. 509 | the Editor will [setup configurations](#window-2) that are not done outside of Editor. 510 | 511 | 512 | #### Project Launcher 513 | 514 | from the `Editor`, open: 515 | - Menu bar -> Window -> **Project Launcher** 516 | 517 | ![](Images/editor_project_launcher.png) 518 | 519 | > to be continued in the [Project Launcher Interface](#project-launcher-interface) below. 520 | 521 | 522 | #### UnrealFrontEnd 523 | 524 | when, **UnrealFrontEnd** is used, it ALSO has the **Project Launcher** tab -- and 525 | this is the **same** one we see from when opened from `Editor`. 526 | 527 | to run **UnrealFrontEnd**: 528 | 529 | ##### on Windows 530 | 531 | ...\Engine\Binaries\Win64\UnrealFrontend.exe 532 | 533 | ##### on Mac 534 | 535 | open .../Engine/Binaries/Mac/UnrealFrontend.app 536 | 537 | ##### on Linux 538 | 539 | .../Engine/Binaries/Linux/UnrealFrontend 540 | 541 | 542 | #### Project Launcher Interface 543 | 544 | ![](Images/frontend_project_launcher.png) 545 | 546 | here, we've: 547 | - set the **Project** to `CPP_TP` (1) 548 | - enabled the `Advanced` button (2) 549 | - set **Data Build** (which is the cooking type) to `By the book` (3) 550 | 551 | to build the desktop game (4): 552 | - on Windows, you will see `WindowsNoEditor` 553 | - on Mac, you will see `MacNoEditor` 554 | - on Linux, you will see `LinuxNoEditor` 555 | 556 | click on the `Launch` button (5). 557 | 558 | note: this will automatically run the game. remember to exit the game by: 559 | - press `~` key 560 | - type `exit` in the **console** 561 | - hit enter/return key to quit game 562 | 563 | we will revisit this interface to build with `Custom Launch Profiles` in the 564 | next HowTo page. 565 | 566 | 567 | * * * 568 | ### Test Sample C++ (cpp) Project 569 | 570 | #### The Editor's Launcher 571 | 572 | there is (yet) another way to test your project. artists and designers generally 573 | like to use this option when testing their work. 574 | 575 | - from the Editor's **Main Tool Bar** 576 | - next to the **Launch** button 577 | - click on the **Advanced Options** (drop-down-arrow) 578 | 579 | then, in the `Devices` menu: 580 | - select the desktop you are using 581 | 582 | ![](Images/editor_launcher.png) 583 | 584 | this will basically go through the same motion as **UnrealFrontEnd** did. 585 | - the game will automatically run when build completes 586 | - note: using this option (depending on the target platform) will perform what is known as cook-on-the-fly 587 | - the assets will be baked on a need-to-use basis 588 | - it doesn't go through the whole cook process, nor does it pak them 589 | - the assets are kept "loose" 590 | - this helps with faster art testing (i.e. quicker turn-around times) 591 | 592 | 593 | #### Play In Editor 594 | 595 | then, there is PIE (play-in-editor) which is the fast of all iteration types -- but, 596 | these are usually better suited for level designers. 597 | 598 | ![](Images/editor_play_in_editor_es2.jpg) 599 | 600 | * * * 601 | 602 | Next, [Emscripten and UE4](README.1.emscripten.UE4.HTML5.md) 603 | 604 | * * * 605 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.1.emscripten.UE4.HTML5.md: -------------------------------------------------------------------------------- 1 | # Emscripten and UE4 2 | 3 | this page will show you how to: 4 | 5 | - run [HTML5Setup.sh](#html5setupsh-build-script) build script -- which will automatically: 6 | - fetch `EMSDK` (which will be used to install the `Emscripten Toolchain`) 7 | - build all of the UE4 Thirdparty libraries used for HTML5 8 | - [package a UE4 sample project for HTML5](#package-a-sample-blueprint-project-for-html5) 9 | - play a [UE4 multi-player game with HTML5](#ue4-multi-player-testing-with-html5) 10 | - [upgrade the emscripten toolchain](#upgrading-emscripten-toolchain) 11 | - and show which UE4 `C#` files are essential (to add/modify emscripten commands used) during HTML5 packaging 12 | 13 | 14 | * * * 15 | ## First Things First 16 | 17 | back in [Get Source File](README.0.building.UE4.Editor.md#get-source-files), a clone of a 18 | special branch based on Release-4.24.3 was used (which was put in (e.g.) `.../ue4-4.24.3-html5` 19 | and will be used in this HowTo page) -- with the HTML5 platform files already populated. 20 | 21 | - NOTE: this is the last snapshot for HTML5 that is now "no longer supported" by Epic Games 22 | - HTML5 has been moved (out) as a `Platform Extension` to be community-driven at this point 23 | - but, work as gone in to help provide a working "staring point" 24 | (especially as the last **ES2** (WebGL1) render target) for this new (platform extensions) mechanism 25 | - these pages and files are the results of that work 26 | 27 | 28 | DO NOT IMMEDIATELY TRY TO UPGRADE ANYTHING IF THIS IS YOUR FIRST TIME HERE !!! 29 | 30 | that said, if you want to work off of a newer version of Unreal Engine, 31 | extra information is placed in: 32 | - [UE4 HTML5 F.A.Q.](README.4.faq.UE4.HTML5.md#trying-to-get-latest-unreal-engine-working-with-html5-platform-extensions) 33 | - along with addtional steps to take to put HTML5 back into the repository tree 34 | 35 | - NOTE: this is **NOT** the same thing as upgrading the emscripten toolchain 36 | - upgrading emscripten is a lot more straight-forward than upgrading Unreal Engine 37 | - upgrading the emscripten toolchain will be shown at the end of this page 38 | - upgrading Unreal Engine, again, is put in the FAQ section (see just above) 39 | 40 | AGAIN, DO NOT IMMEDIATELY TRY TO UPGRADE ANYTHING IF THIS IS YOUR FIRST TIME HERE !!! 41 | 42 | 43 | moving on... 44 | 45 | 46 | * * * 47 | * * * 48 | ## HTML5Setup.sh Build Script 49 | 50 | > NOTE: if you are continuing from the previous [HowTo](README.0.building.UE4.Editor.md#generate-projectmake-files) 51 | and have already run `HTML5Setup.sh`, you can skip down to the next section: 52 | [Package a Sample BluePrint Project For HTML5](#package-a-sample-blueprint-project-for-html5) 53 | 54 | > but, if you want to understand what `HTML5Setup.sh` does, please continue reading on. 55 | 56 | 57 | in order to package Unreal Engine for HTML5, we need to perform a number of steps 58 | to get the UE4 Editor able to package for HTML5. 59 | - NOTE: this only needs to be done **once** (per local repo) 60 | 61 | all of these steps are all gathered in the (e.g.) `.../ue4-4.24.3-html5/Engine/Platforms/HTML5/HTML5Setup.sh` 62 | build scripts. 63 | 64 | 65 | ### on Windows 66 | 67 | open `git-bash` 68 | - this was installed as part of the 69 | [Development Environment Requirements](README.0.building.UE4.Editor.md#development-environment-requirements) section 70 | - change the directory to where your UE4 was cloned to 71 | - e.g. `cd ue4-4.24.3-html5` 72 | - or, you can use **File Explorer** and right click on the **ue4-4.24.3-html5** folder and select `Git Bash Here` 73 | 74 | 75 | ### on Mac and Linux 76 | 77 | open the Terminal 78 | 79 | - change directory to the location where UE4 was cloned to (as we have seen 80 | in the [Generate Project/Make Files](README.0.building.UE4.Editor.md#generate-projectmake-files) section) 81 | - e.g. `cd ue4-4.24.3-html5` 82 | 83 | 84 | ### Fetch EMSDK and Build ThirdPary Libraries for HTML5 85 | 86 | in `git-bash` (for windows) or in the `terminal` (for mac or linux), do the 87 | following (yes, these commands will work the same on all 3 OS): 88 | 89 | ```bash 90 | # remember, we are now in the ue4-4.24.3-html5 folder 91 | cd Engine/Platforms/HTML5 92 | ./HTML5Setup.sh 93 | ``` 94 | 95 | this will take a while to complete (again, this is only a **one-time** setup): 96 | - emsdk is a small and quick clone 97 | - but, emscripten will take roughly 10 minutes or so 98 | > emscripten will also get **patched** that have been found to be needed with building for UE4 99 | (more about this in the [upgrading emscripten](#upgrading-emscripten-toolchain) section below) 100 | - finally, building the thirdparty libraries will take an hour or two 101 | > please see the FAQ about why [emscripten ports](README.4.faq.UE4.HTML5.md#emscripten-ports) is not used in UE4 102 | 103 | 104 | ### Troubleshooting HTML5Setup.sh 105 | 106 | if you see errors when running the script early on, please see the 107 | UE4 HTML5 [Troubleshooting emsdk issues](README.4.faq.UE4.HTML5.md#troubleshooting-emsdk-issues) F.A.Q. 108 | 109 | if you see errors fairly long into the run, please ensure you have plenty of hard drive space. 110 | - how much hard drive space? 111 | - because you will also be building UE4 Editor (giant), UE4 tools (small), and some projects (can be giant) 112 | - look to have more than 150GB of free hard drive space 113 | 114 | 115 | * * * 116 | * * * 117 | ## Package a Sample BluePrint Project For HTML5 118 | 119 | these should now start to now look more familiar to you. 120 | 121 | restart the Editor with the project name appended: 122 | - note the use of `BP_FP` here (that was created in [Creating a Sample Blueprint Project](README.0.building.UE4.Editor.md#-creating-a-sample-blueprint-project-)) 123 | 124 | #### on Windows 125 | 126 | ...\Engine\Binaries\Win64\UE4Editor.exe BP_FP -log 127 | 128 | #### on Mac 129 | 130 | open .../Engine/Binaries/Mac/UE4Editor.app --args BP_FP -log 131 | 132 | #### on Linux 133 | 134 | .../Engine/Binaries/Linux/UE4Editor BP_FP -log 135 | 136 | > TIP: put the command in a shortcut (or alias, script, etc.) 137 | 138 | 139 | ### Readying UE4Editor 140 | 141 | let's go over this part [again](README.0.building.UE4.Editor.md#window-2) now that we are looking at HTML5: 142 | 143 | #### window #2 144 | 145 | - Menu bar -> Edit -> Project Settings ... 146 | - click around (and look around) the **Project Settings** categories and options for EVERYTHING (including the kitchen sink) 147 | 148 | - (**NEW**) here's a list I always click on **and** look at before each and every packaging (for all platforms): 149 | - Project -> Maps & Modes 150 | - **Default Maps** -> Game Default Map 151 | - Project -> Packaging 152 | - Packaging -> **Use Pak File** 153 | - I normally **UN**check this to help the asset builds (i.e. "cooking") go a little faster 154 | (by not having to build this additional step) -- emscripten has it's own assets bundler 155 | mechanism (see [Emscripten Packaging Files](https://emscripten.org/docs/porting/files/packaging_files.html) 156 | for more information about this) 157 | - if you're looking for compression: please see the [smash texture size](README.2.advanced.UE4.HTML5.md#smash-texture-sizes) 158 | for the most effective way to crush your download size 159 | - Project -> **Full Rebuild** 160 | - just make a note this exists here 161 | - Engine -> Rendering 162 | - Mobile 163 | - note: the HTML5 render path uses the same one writen for mobile, that's why it's good to check-in here every now and then 164 | - again, ue4 HTML5 is currently rendering with ES2 (WebGL1) -- but, note that in 4.25 ue4 will 165 | [drop support for ES2](README.4.faq.UE4.HTML5.md#warning-this-is-not-for-the-faint-of-heart) 166 | - see [Content Development](../HTML5.md#content-development) and 167 | [Mobile MSAA](../GettingStarted/HTML5GettingStarted.md#html5-required-project-setup) 168 | just in case you are see rendering issues on your projects 169 | - Platforms -> HTML5 170 | - Emscripten -> **Multithreading support** 171 | - for 4.24 (as well as 4.24.3) -- this MUST be enabled (there's a (animation curve) crash bug in single threaded mode 172 | that is slated to be fixed in 4.25) 173 | 174 | 175 | ### Build the Sample BluePrint Project 176 | 177 | set the build type: 178 | - Menu bar -> File -> **Package Project** -> Build Configuration 179 | - select `Development` (we are going to use the **game console** to **open a connection** to the game server below) 180 | 181 | finally, package for HTML5: 182 | - Menu bar -> File -> Package Project -> **HTML5** 183 | - select the folder where the final files will be **archived** to 184 | - e.g. on Windows: `D:\Builds\BP_FP\` 185 | - e.g. on Mac or Linux: `/ue4/Builds/BP_FP/` 186 | 187 | - this is going to take while to complete... (more about this in the [upgrading emscripten](#upgrading-emscripten-toolchain) section below) 188 | - go take a nap 189 | 190 | note: if you run into any problems here, take a look at the [FAQ](README.4.faq.UE4.HTML5.md) 191 | to see if there are any common issues that you might be hitting. 192 | 193 | 194 | * * * 195 | ## Test Sample BluePrint Project for HTML5 196 | 197 | ### on Windows via File Explorer 198 | 199 | - open `File Explorer` to the location where files were **archived** to 200 | - e.g. `D:\Builds\BP_FP\HTML5` 201 | - double click on `HTML5LaunchHelper.exe` 202 | 203 | 204 | ### on Mac via Finder 205 | 206 | - open `Finder` to the location where files were **archived** to 207 | - e.g. `/ue4/Builds/BP_FP/HTML5` 208 | - double click on `HTML5LaunchHelper.command` 209 | 210 | 211 | ### on Windows, Mac or Linux via command line 212 | 213 | in `git-bash` (for windows) or in the `terminal` (for mac or linux), you can 214 | use python's built in web server to host the files quick and easy. 215 | 216 | #### on Windows 217 | 218 | ```bash 219 | # remember, this is an "example" path (see "archive to" notes just above) 220 | cd /D/Builds/BP_FP/HTML5 221 | python -m http.server 8000 222 | #python2 -m SimpleHTTPServer 8000 223 | ``` 224 | 225 | #### on Mac or Linux 226 | 227 | ```bash 228 | # remember, this is an "example" path (see "archive to" notes just above) 229 | cd /ue4/Builds/BP_FP/HTML5 230 | python -m http.server 8000 231 | #python2 -m SimpleHTTPServer 8000 232 | ``` 233 | 234 | 235 | * * * 236 | ## Chrome or Firefox (64-bit version recommended) 237 | 238 | - open browser to http://localhost:8000/ 239 | - click on the relevant HTML file ( e.g. http://localhost:8000/BP_FP.html ) 240 | 241 | 242 | in general -- i use both chrome and firefox when testing. note: they both will 243 | periodically "get broken" for some reason or another -- but, they usually get 244 | fixed in the next revision or two. 245 | 246 | i normally have these browsers installed on ALL of my desktops (windows, mac and linux): 247 | - Chrome (stable) 248 | - Canary (chrome "unstable" i.e. alpha) 249 | - Firefox (stable) 250 | - Firefox Nightly ("unstable i.e. alpha) 251 | 252 | those browsers above are the **BEST** at testing UnrealEngine projects in them. 253 | 254 | 255 | #### Note: on Windows 256 | 257 | - DO NOT USE EDGE 258 | - while it is now powered by chromium, it is not quite ready for webgl (yet). 259 | - see [caniuse webgl](https://caniuse.com/#search=webgl) for details 260 | 261 | 262 | #### Note: on Mac 263 | 264 | - DO NOT USE SAFARI 265 | - this browser has horrid support for WebGL(2) 266 | - see [caniuse webgl](https://caniuse.com/#search=webgl) for details 267 | 268 | 269 | ### other issues: 270 | 271 | common run time in browser problems have been put into the [Browser F.A.Q.](README.4.faq.UE4.HTML5.md#browser) 272 | 273 | 274 | * * * 275 | * * * 276 | ## UE4 Multi-player Testing With HTML5 277 | 278 | let's try something fun here. in the last HowTo page, we were introduced to 279 | the [UnrealFrontEnd](README.0.building.UE4.Editor.md#project-launcher-interface) 280 | or UFE for short. 281 | - we will use this to create a (Desktop) Server, Desktop Client and HTML5 Client 282 | - again, because we are using a special branch here, much of the heavy work has already been done 283 | - an indepth "what was done" will be explained in the next HowTo: 284 | [Advanced Example of Building a UE4 HTML5 Project](README.2.advanced.UE4.HTML5.md) 285 | - however, we still need to add some code to the generated template (c++) project. 286 | > note: while it is possible to do the same for generated blueprint project, there 287 | are a number of additional steps required that are beyond the scope of this doc. 288 | see [xxx this F.A.Q.](README.4.faq.UE4.HTML5.md#xxx) if you are interested in knowing how. 289 | 290 | 291 | ### Client and Server C# files 292 | 293 | let us add the additional required files to the project to allow us to create the 294 | server and client (desktop) executables. 295 | 296 | open your file explorer (windows), finder (mac) to the `CPP_TP/Source` folder. 297 | - make a copy of the `CPP_TP.Target.cs` twice and rename them: 298 | - `CPP_TPClient.Target.cs` 299 | - `CPP_TPServer.Target.cs` 300 | 301 | in each of those files a slight modification is needed to tell the build what targets 302 | are wanted. here are both files in their entirety: 303 | 304 | - `CPP_TPClient.Target.cs` 305 | ```cs 306 | using UnrealBuildTool; 307 | using System.Collections.Generic; 308 | public class CPP_TPClientTarget : TargetRules 309 | { 310 | public CPP_TPClientTarget(TargetInfo Target) : base(Target) 311 | { 312 | Type = TargetType.Client; 313 | DefaultBuildSettings = BuildSettingsVersion.V2; 314 | ExtraModuleNames.Add("CPP_TP"); 315 | } 316 | } 317 | ``` 318 | > note the use of **Client** in this file 319 | 320 | 321 | - `CPP_TPServer.Target.cs` 322 | ```cs 323 | using UnrealBuildTool; 324 | using System.Collections.Generic; 325 | public class CPP_TPServerTarget : TargetRules 326 | { 327 | public CPP_TPServerTarget(TargetInfo Target) : base(Target) 328 | { 329 | Type = TargetType.Server; 330 | DefaultBuildSettings = BuildSettingsVersion.V2; 331 | ExtraModuleNames.Add("CPP_TP"); 332 | } 333 | } 334 | ``` 335 | > note the use of **Server** in this file 336 | 337 | 338 | * * * 339 | 340 | let us continue with creating a `Custom Launch Profile` in the UFE to demonstrate 341 | creating a multi-player project. 342 | 343 | run **UnrealFrontEnd**: 344 | 345 | ##### on Windows 346 | 347 | ...\Engine\Binaries\Win64\UnrealFrontend.exe 348 | 349 | ##### on Mac 350 | 351 | open .../Engine/Binaries/Mac/UnrealFrontend.app 352 | 353 | ##### on Linux 354 | 355 | .../Engine/Binaries/Linux/UnrealFrontend 356 | 357 | click on the **Custom Launch Profiles** `Add` (plus-button): 358 | 359 | ![](Images/frontend_profiles.png) 360 | 361 | to set up a multi-player session, we are going to build the desktop server and 362 | desktop client (as our base line test system). at the same time, we will also 363 | build the HTML5 client. 364 | - select **Project** to `CPP_TP` 365 | - select **Build Configuration** 366 | - select `Development` (we are going to use the **game console** (via the **tilda** (`~`) key) 367 | to **open a connection** to the game server below) 368 | - but, you can select `Shipping` when deploying for release (just note: **game console** will NOT be available in `Shipping` builds) 369 | - select **Cook** to `By the book` 370 | - select **Cooked Plaforms** for: 371 | - on Windows: `WindowsClient` and `WindowsServer` 372 | - on Mac: `MacClient` and `MacServer` 373 | - on Linux: `LinuxClient` and `LinuxServer` 374 | - AND HTML5 375 | 376 | NOTE: the following "client" variants are all essentially the same (for the respective platforms): 377 | - `Windows & WindowsNoEditor` and `WindowsClient` 378 | - `Mac & MacNoEditor` and `MacClient` 379 | - `Linux & LinuxNoEditor` and `LinuxClient` 380 | 381 | > in this example, if you clicked on ALL 3 of these "client" variants, the `Client` variant is ONLY built. 382 | 383 | - select **Package** to `Package & store locally` 384 | - in **Archive**, check the box `on` 385 | - and set the archive path: 386 | - e.g. on Windows: `D:\Builds\CPP_TP\` 387 | - e.g. on Mac or Linux: `/ue4/Builds/CPP_TP/` 388 | - select **Deploy** to `Do not deploy` 389 | 390 | ![](Images/frontend_custom_profile.png) 391 | 392 | now, press the `Back` button (upper right) which will automatically save this new profile 393 | - note: if you wanted to change the name of the profile, edit the profile again 394 | by clicking on the **Edit** (wrench and screwdriver) button, double click on 395 | `New Profile` and type a name for this profile 396 | - you can also give this profile a small description by double clicking on the 397 | `Enter a description here.` and type what ever you want for this profile 398 | 399 | back in the **Project Launcher** click on the `Launch` button for your profile 400 | to begin packaging everything. 401 | 402 | ![](Images/frontend_launch_profile.png) 403 | 404 | after the build is done (which may take a while to complete) in your **archive** 405 | folder, you should see something like this: 406 | 407 | ![](Images/archive_cpp_tp.png) 408 | 409 | 410 | ### Launch the Server 411 | 412 | here, we will be using the more advanced way to run the project from the command line. 413 | 414 | - first, tell the server to host with the map: **ThirdPersonExampleMap** 415 | 416 | - as before, i like to see the `stdout` prints -- to know that the game is still running 417 | - using `-log` parameter to view this 418 | 419 | 420 | #### on Windows via CommandPrompt: 421 | 422 | - open `CommandPrompt` to the location where the Server files were **archived** to 423 | - e.g. `cd ...\CPP_TP\WindowsServer` 424 | - run executable 425 | - `CPP_TPServer.exe ThirdPersonExampleMap -log` 426 | 427 | #### on Mac via Terminal: 428 | 429 | - open `terminal` to the location where files were **archived** to 430 | - e.g. `cd .../CPP_TP/MacServer` 431 | - run executable 432 | - `open ./CPP_TPServer.app --args ThirdPersonExampleMap -log` 433 | 434 | #### on Linux via Terminal: 435 | 436 | - open `terminal` to the location where files were **archived** to 437 | - e.g. `cd .../CPP_TP/LinuxServer` 438 | - run executable 439 | - `./CPP_TPServer.sh ThirdPersonExampleMap -log` 440 | 441 | > TIP: put the command in a shortcut (or alias, script, etc.) 442 | 443 | 444 | ### Launch the Desktop Client 445 | 446 | to run multiple instances of the project at once (this networking project is a 447 | perfect example), this time we will launch the game in `windowed` mode from the 448 | 449 | - run the game in a windowed size screen (i.e. not full screen) 450 | - using `-windowed -resx=800 -resy=600` parameter to do this 451 | 452 | - again, i like to see the `stdout` prints -- to know that the game is still running 453 | - using `-log` parameter to view this 454 | 455 | #### on Windows via CommandPrompt: 456 | 457 | - open `CommandPrompt` to the location where the Server files were **archived** to 458 | - e.g. `cd ...\CPP_TP\Windowslient` 459 | - run executable 460 | - `CPP_TPClient.exe -windowed -resx=800 -resy=600 -log` 461 | 462 | #### on Mac via Terminal: 463 | 464 | - open `terminal` to the location where files were **archived** to 465 | - e.g. `cd .../CPP_TP/MacClient` 466 | - run executable 467 | - `open ./CPP_TPClient.app --args -windowed -resx=800 -resy=600 -log` 468 | 469 | #### on Linux via Terminal: 470 | 471 | - open `terminal` to the location where files were **archived** to 472 | - e.g. `cd .../CPP_TP/LinuxClient` 473 | - run executable 474 | - `./CPP_TPClient.sh -windowed -resx=800 -resy=600 -log` 475 | 476 | > TIP: put the command in a shortcut (or alias, script, etc.) 477 | 478 | 479 | ### Launch the HTML5 Client 480 | 481 | using almost the same steps from [test sample blueprint project for HTML5](#on-windows-mac-or-linux-via-command-line) above: 482 | 483 | #### on Windows, Mac or Linux via command line 484 | 485 | in `git-bash` (for windows) or in the `terminal` (for mac or linux), you can 486 | use python's built in web server to host the files quick and easy. 487 | 488 | ```bash 489 | # remember, this is an "example" path (see "archive to" notes just above) 490 | cd .../CPP_TP/HTML5 491 | python -m http.server 8000 492 | #python2 -m SimpleHTTPServer 8000 493 | ``` 494 | 495 | and using almost the same steps from [chrome or firefox](#chrome-or-firefox-64-bit-version-recommended) above: 496 | 497 | - open browser to http://localhost:8000/ 498 | - click on the relevant HTML file ( e.g. http://localhost:8000/CPP_TP.html ) 499 | 500 | 501 | ### Finally... 502 | 503 | in the desktop client AND HTML5 browser: 504 | - open the `game console` command line, by pressing the **tilda** key (`~`) 505 | - type: `open 127.0.0.1` 506 | - here, we are telling the `client` to open a connection to the `server` 507 | (hosted at 127.0.0.1 -- a.k.a. `localhost`) 508 | 509 | you should see the game reload, and as more clients join the server - the more 510 | players you will see in there! 511 | 512 | 513 | > again, we will do an [Advanced Example of Building a UE4 HTML5 Project](README.2.advanced.UE4.HTML5.md) 514 | multi-player example in the next HowTo. 515 | 516 | 517 | * * * 518 | * * * 519 | ## Upgrading Emscripten Toolchain 520 | 521 | this may only be of interest to anyone who wishes to keep this community-supported 522 | project going. 523 | 524 | this section will go over what [HTML5Setup.sh](#html5setupsh-build-script) does in detail. 525 | - we will perform an `emscripten toolchain` upgrade when explaining this 526 | - some reasons for upgrading the emscripten toolchain include: 527 | - bug fixes 528 | - new features 529 | - link times have vastly improved with emscripten "upstream" (clang 10) 530 | - but, at the time of this writting, thirdparty libraries built with emscripten "upstream" will crash at runtime 531 | - thus, emscripten "fastcomp" (clang 6) is still used when building thirdparty libraries 532 | - this will get fixed someday and the `HTML5Setup.sh` build script will be updated to make use of that when the time comes 533 | 534 | 535 | ### EMSDK 536 | 537 | `HTML5Setup.sh` will aways pull a fresh copy of emsdk into its own folder 538 | - i.e. i never `git pull` on my local emsdk weeks/months down the line 539 | - i do this to ensure there are no extra files from older versions getting accidentally left around 540 | - in other words, we do not wish to pollute new versions with old stuff 541 | - also, having multiple versions in their own folders allows us to quickly change between toolchain versions for testing purposes 542 | 543 | > note: when building emscripten from source (i.e. not the precompiled 544 | SDK - e.g. `incoming` branch) -- then yes, i would `git pull` -- but, 545 | this is usually (again) in a separate WIP folder... 546 | 547 | 548 | ### Upgrade Emscripten Version 549 | 550 | let's start the upgrade. 551 | - edit `HTML5Setup.sh` file 552 | - look for the `EMVAR` variable (very near the top of the file) 553 | - it is currently set to `1.39.0` 554 | - let's change this to `1.39.4` (or `latest` if you're bleeding edge) 555 | - save the file and exit your text editor 556 | 557 | re-run HTML5Setup.sh using pretty much the same steps from 558 | [Fetch EMSDK and Build ThirdPary Libraries for HTML5](#fetch-emsdk-and-build-thirdpary-libraries-for-html5) 559 | above. 560 | 561 | in `git-bash` (for windows) or in the `terminal` (for mac or linux): 562 | 563 | ```bash 564 | # remember, we are now in the ue4-4.24.3-html5 folder 565 | cd Engine/Platforms/HTML5 566 | ./HTML5Setup.sh 567 | ``` 568 | 569 | again, this may take an hour or so to complete. 570 | 571 | - but, this is also where most compiler issues arise 572 | - some due to new compiler warnings (set to be treated as errors) 573 | - others due to deprecated compiler options 574 | - and so on 575 | 576 | - take a look at [this FAQ](README.4.faq.UE4.HTML5.md#common-compiler-issues-when-upgrading-emscripten-toolchain) to see tips on how to fix this 577 | 578 | 579 | ### HTML5Setup.sh Deep Dive 580 | 581 | follow along this explaination by opening a page to 582 | [HTML5Setup.sh](https://github.com/UnrealEngineHTML5/UnrealEngine/blob/4.24.3-html5-1.39.18/Engine/Platforms/HTML5/HTML5Setup.sh) 583 | file. 584 | - again: if you see a `404 This is not the web page you are looking for` error 585 | - `Remember to link your Epic Games Account to your GitHub account.` See [HERE](../../../README.md) for more details. 586 | 587 | 588 | #### UnrealBuildTool HTML5 Injection 589 | 590 | because HTML5 is (think of it as) a "new" platform, UnrealBuildTool (UBT) needs 591 | to be told about this. This is done by injecting the HTML5 c# paths into UBT. 592 | 593 | ```c 594 | patch_UBT_HTML5() 595 | ``` 596 | 597 | 598 | #### Patching UE4 Code 599 | 600 | Unreal Engine code is edited and checked in by Epic Games developers and 601 | is eventually propagated to the github repositories. this was a tiny fix 602 | that didn't make the lock down window. 603 | 604 | see [this F.A.Q.](README.4.faq.UE4.HTML5.md#tobool63i--icmp-slt-i176) 605 | for details. 606 | 607 | ```c 608 | patch_UE4_code() 609 | ``` 610 | 611 | 612 | #### Patching emscripten 613 | 614 | changes to emscripten were necessary to keep Unreal Engine HTML5 developement 615 | stable and productive. most of the edits were deemed specific to Unreal Engine 616 | (i.e. not fit for the general public). sometimes, fixes are no longer needed 617 | and gets removed (or commented out for future reference). but, some edits are 618 | brought to the attention of the toolchain maintainers and may get pushed. and 619 | other times, we get them lost in the busy iterations only to be revisited at a 620 | later time. 621 | 622 | edits are wrapped between `EPIC EDIT` (to help me find these to re-apply them 623 | in future version). these included things like: 624 | - verbose logging on timing data 625 | - changes from `warning` to `info` log types (reducing false-positive alerts on Epic's CIS reports) 626 | - hacks to "fix" c# and python issues on windows 627 | - needed code changes (that helps make ue4 run in the browser) 628 | 629 | > WARNING: do NOT just change the patch folder name (version) when upgrading your 630 | emscripten toolchain. you MUST **manually inspect** the files to see if the 631 | **EPIC EDIT** changes (still) makes sense in the (new) file they are to be put in. 632 | 633 | > ALSO (just in case this is not obvious) -- if you just change the patch folder 634 | name (i.e. version) -- you are going to STOMP on the newer file with older ones. 635 | this may/will cause problems when the newer emscripten toolchain has been updated 636 | but is running with (copied over) older files. 637 | 638 | 639 | ```c 640 | patch_emscripten() 641 | ``` 642 | 643 | 644 | #### Fetch and Build 645 | 646 | this part was already described [above](#fetch-emsdk-and-build-thirdpary-libraries-for-html5) 647 | 648 | 649 | * * * 650 | ## Updating UE4 C# Scripts 651 | 652 | the following files are used by Unreal's build system (specifically with the 653 | emscripten toolchain) when packaging for HTML5: 654 | 655 | ##### Engine/Platforms/HTML5/Source/Programs/UnrealBuildTool/HTML5SDKInfo.cs 656 | - the only things of interest here are the string variables listed at the top of the HTML5SDKInfo class 657 | - `SDKVersion` -- for this demo, change this to `1.39.4` (or `latest` if bleeding edge) 658 | - `NODE_VER` 659 | - `PYTHON_VER` -- (used on windows only) 660 | 661 | 662 | ##### Engine/Platforms/HTML5/Source/Programs/UnrealBuildTool/HTML5ToolChain.cs 663 | - this is where everything is put on (1) setting up and (2) run emscripten 664 | - THE functions that builds the emscripten command line options: 665 | - `GetSharedArguments_Global()` - used in both compilation and linking 666 | - `GetCLArguments_CPP()` - used in compilation only 667 | - `GetLinkArguments()` - used in linking only 668 | 669 | > this file will sometimes need updating (e.g. new or deprecated compiler options) 670 | 671 | > again, take a look at [this FAQ](README.4.faq.UE4.HTML5.md#common-compiler-issues-when-upgrading-emscripten-toolchain) 672 | to see if there are any common issues that you might be hitting 673 | 674 | 675 | ##### Engine/Platforms/HTML5/Source/Programs/AutomationTool/HTML5Platform.Automation.cs 676 | - the top half of this C# file is where the files built are selected and archived 677 | (as we have seen in [Build the Sample BluePrint Project](#build-the-sample-blueprint-project) above) 678 | - this is where emscripten sometimes changes the files: 679 | - generated that needs to be added to the **archive** process 680 | - or no longer generates and need to be removed from the **archive** process 681 | - the rest of the file are used for UE4's Editor options that the HTML5 packaging supports 682 | 683 | 684 | ### a note on windows 685 | 686 | after editing the AutomationTool and UnrealBuildTool files, these support 687 | programs will need to be rebuilt. on Mac and Linux, they are always rebuilt 688 | at the start of any packaging process. 689 | 690 | windows needs some help. 691 | 692 | > NOTE: it seems that latest Editor will rebuild the C# (AutomationTool) project automatically when packaging (for example) HTML5. 693 | 694 | > BUT: UnrealBuildTool still needs to be manually built on windows !!! 695 | 696 | - **so**, every-now-and-then ... **this sometimes needs manual intervention:** 697 | - in the **Solution Explorer -> Solution -> Programs**, `Build` (the following support programs): 698 | - AutomationTool 699 | - UnrealBuildTool 700 | 701 | 702 | * * * 703 | ## Test Upgraded Toolchain 704 | 705 | be sure to package a "**SANITY CHECK"** build: 706 | - no engine changes, just the build toolchain (emscripten) changes only 707 | 708 | in this example, do the exact same steps done above: 709 | - [Build the Sample BluePrint Project](#build-the-sample-blueprint-project) 710 | - [Test Sample BluePrint Project for HTML5](#test-sample-blueprint-project-for-html5) 711 | - [Chrome or Firefox (64-bit version recommended)](#chrome-or-firefox-(64-bit-version-recommended)) 712 | 713 | 714 | * * * 715 | * * * 716 | 717 | Next, [Advanced Example of Building a UE4 HTML5 Project](README.2.advanced.UE4.HTML5.md) 718 | 719 | * * * 720 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.2.advanced.UE4.HTML5.md: -------------------------------------------------------------------------------- 1 | # Advanced Example of Building a UE4 HTML5 Project 2 | 3 | this page will show you how to: 4 | 5 | - [obtain a sample UE4 game project](#download-shootergame-sample-project) via the Epic Games Launcher 6 | - [configure multiplayer project to use websockets](#configuring-ue4-projects-with-websocket-networking) 7 | - [play a multiplayer game session with desktop client host and HTML5 client](#test-html5-client-with-desktop-shootergame-host) 8 | - [smash texture sizes]() 9 | - [view modes in editor]() 10 | 11 | 12 | * * * 13 | ## Epic Games Launcher 14 | 15 | normally, game developers (who do not have much or any programming experience) 16 | can download the **Epic Games Launcher** to get the Unreal Engine Editor and to 17 | start making games with it. 18 | 19 | you can also download a number of sample projects from the "Learn" that's 20 | available via the **Launcher**. 21 | 22 | we will use one of Epic Games sample projects from the Launcher's **Learning** 23 | center to continue with this advanced demo. 24 | 25 | 26 | ### Downloading the **Epic Games Launcher** 27 | 28 | to obtain the **Launcher**, download it from: 29 | 30 | - https://www.epicgames.com/store/en-US/download 31 | - Windows and Mac 32 | - https://lutris.net/games/epic-games-store/ 33 | - Linux (requires Wine) 34 | 35 | after opening up the **Launcher**, you will be required to **Sign In** in order 36 | to use it. use **your** Epic Games account credentials you've used when linking 37 | your GitHub account (we saw how to do this [HERE](../../../README.md)). 38 | 39 | 40 | ### Download ShooterGame sample project 41 | 42 | to download the **ShooterGame** project: 43 | - open **Epic Games Launcher** application 44 | - goto the **Learn** tab 45 | - scroll down to the **Games** section 46 | - click on **ShooterGame** to view the project 47 | 48 | ![](Images/launcher_shootergame.png) 49 | 50 | - click on Free 51 | - click on Create Project 52 | - pick the path to download the project to 53 | - in this example, i have put ShooterGame in the same folder where **Engine** 54 | is -- i.e. `.../ue4-4.24.3-html5/ShooterGame`. it doesn't have to be there. 55 | but, for this demo, you can put it there to follow along these instructions. 56 | - select the engine version: 4.24 57 | - click on Create 58 | 59 | ![](Images/launcher_location_create.png) 60 | 61 | 62 | * * * 63 | ### ALERT: on Mac and Linux 64 | 65 | at the time of this writing, we need to patch one file in the ShooterGame project. 66 | (by the time you read this, this may have been fixed. but, just in case it is still 67 | broken on mac and linux, you will need this fix.) 68 | 69 | - edit the following file: `.../ShooterGame/Source/ShooterGame/ShooterGame.Build.cs` 70 | - add the `"RHI"` module to the `PrivateDependencyModuleNames` array 71 | - it should look something like this: 72 | 73 | ```cs 74 | . . . 75 | PrivateDependencyModuleNames.AddRange( 76 | new string[] { 77 | "RHI", // ADD ME! 78 | "InputCore", 79 | . . . 80 | 81 | ``` 82 | 83 | 84 | * * * 85 | ## Build ShooterGame "Editor" 86 | 87 | when ever starting a new project that contains source codes, i usually run the 88 | `GenerateProjectFiles` command (that we saw in [Generate Project/Make Files](README.0.building.UE4.Editor.md#generate-projectmake-files)). 89 | 90 | this may have been done for you automatically when using the **Epic Games Launcher**. 91 | 92 | but, it's good practice to do this when ever you start playing playing with 93 | **new** projects that contain source codes. and this example is a good one 94 | to start with. 95 | 96 | #### on Windows via CommandPrompt 97 | 98 | - open `CommandPrompt` to ue4-4.24.3-html5 99 | - e.g. `cd ...\ue4-4.24.3-html5` 100 | - re-generate the visual studio solution file 101 | - `GenerateProjectFiles.bat` 102 | - open the generated visual studio solution (UE4.sln) 103 | - in **Solution Explorer-> Solution -> Games**, `right click select` and `build` **ShooterGame** 104 | 105 | #### on Mac via Terminal 106 | 107 | - open `terminal` to ue4-4.24.3-html5 108 | - e.g. `cd .../ue4-4.24.3-html5` 109 | - re-generate the xcode project file 110 | - `GenerateProjectFiles.command` 111 | - open the generated xcode project (UE4.xcworkspace) 112 | - select target **ShooterGame** 113 | - and then select: 114 | - **Menu -> Product -> Build For -> Running** 115 | - or `Command + Shift + R` 116 | 117 | #### on Linux via Terminal 118 | 119 | - open `terminal` to ue4-4.24.3-html5 120 | - e.g. `cd .../ue4-4.24.3-html5` 121 | - re-generate the Makefiles 122 | - `GenerateProjectFiles.sh` 123 | - and then: 124 | - `make ShooterGame ShooterGameEditor` 125 | 126 | 127 | * * * 128 | ## Open ShooterGame in UE4Editor 129 | 130 | when the build completes, fire up the Editor: 131 | - note: i like to see the `stdout` prints (to know that the Editor is still running) 132 | - using `-log` parameter to view this 133 | 134 | ### on Windows 135 | 136 | ...\Engine\Binaries\Win64\UE4Editor.exe ShooterGame -log 137 | 138 | ### on Mac 139 | 140 | open .../Engine/Binaries/Mac/UE4Editor.app --args ShooterGame -log 141 | 142 | ### on Linux 143 | 144 | .../Engine/Binaries/Linux/UE4Editor ShooterGame -log 145 | 146 | > TIP: put the command in a shortcut (or alias, script, etc.) for future use! 147 | 148 | 149 | * * * 150 | #### SPECIAL NOTE: Enable WebSocket Networking Plugin 151 | 152 | we saw how to do this back in the first HowTo: 153 | - [enable websocket networking plugin](README.0.building.UE4.Editor.md#plugins) 154 | 155 | ![](Images/editor_plugins_websocket.png) 156 | 157 | 158 | * * * 159 | ## ShooterGame for Desktop 160 | 161 | just like [Starting with UE4 Editor](README.0.building.UE4.Editor.md), we will 162 | first build for the Desktop to ensure the project (still) "works" before trying 163 | other platforms. 164 | - it is much easier to debug or trying to diagnose any problems on the "Native Platform" first (i.e. the desktop) 165 | 166 | ShooterGame is a fully fleshed out project that can host network games. 167 | 168 | - usually, a server is used to host these game sessions 169 | - Unreal Engine make these and are known as "UE4 Dedicated Servers" 170 | - an example of this was done in the previous HowTo: [UE4 Multi-player Testing With HTML5](README.1.emscripten.UE4.HTML5.md#ue4-multi-player-testing-with-html5) 171 | 172 | - another way to host game sessions is to have the running application **open a 173 | listening port** and perform the same functionality as a Dedicated Server 174 | (many console games do this) 175 | - we will be doing an example of this here 176 | 177 | finally, the HTML5 client will need to connect to a **listening host**. 178 | > NOTE: UE4 HTML5 will NEVER be able to "host" a game (it can join them, but never host). 179 | 180 | for the purpose of this demo, we are going to use the "desktop game client" to 181 | open a listening port to host a session. 182 | - the HTML5 client will connect to this to play a networked game 183 | 184 | 185 | ### Configuring UE4 Projects with WebSocket Networking 186 | 187 | in the previous previous HowTo, it was mentioned that the clone of a special 188 | branch based on Release-4.24.3 was made with the HTML5 platform files already 189 | populated. this includes **config.ini** files. 190 | 191 | in this HowTo, we will go through the steps to make UE4 networking projects work 192 | on the HTML5 platform in detail. 193 | 194 | normally, all desktop and most console platforms will be using what is known as 195 | the Unreal Engine **IpNetwork** NetDriver for network communications. 196 | 197 | - this needs to be change to use the **WebSocketNetwok NetDriver** ([1](#netdriverdefinitions-1)) 198 | - add the **WebSocketNetworking.WebSocketNetDriver** ([2](#add-websocketnetdriver-settings-2)) 199 | settings to the Engine 200 | - and finally, **disable Packet Handler Components not supported with websocket** ([3](#disable-packethandler-components-3)) 201 | - one such example is the **SteamAuthComponentModuleInterface** 202 | 203 | 204 | we will now go over each of these (1-3) steps one by one. 205 | 206 | 207 | #### NetDriverDefinitions (1) 208 | 209 | in the following files: 210 | - Engine/Config/BaseEngine.ini 211 | - ShooterGame/Config/Windows/WindowsEngine.ini 212 | - ShooterGame/Config/Mac/MacEngine.ini 213 | - ShooterGame/Config/Linux/LinuxEngine.ini 214 | 215 | **disable** all existing NetDriverDefinitions 216 | - by placing a `;` (semicolon) at the start of each line 217 | - this is known as **commenting out** a line (which "disables" or "hides" them from being used) 218 | 219 | in **BaseEngine.ini**, it would look like this: 220 | 221 | ```ini 222 | ;NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/OnlineSubsystemUtils.IpNetDriver",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver") 223 | ;+NetDriverDefinitions=(DefName="DemoNetDriver",DriverClassName="/Script/Engine.DemoNetDriver",DriverClassNameFallback="/Script/Engine.DemoNetDriver") 224 | ``` 225 | 226 | next, **add** the WebSocket NetDriver - like this: 227 | 228 | ```ini 229 | ;NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/OnlineSubsystemUtils.IpNetDriver",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver") 230 | ;+NetDriverDefinitions=(DefName="DemoNetDriver",DriverClassName="/Script/Engine.DemoNetDriver",DriverClassNameFallback="/Script/Engine.DemoNetDriver") 231 | NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/WebSocketNetworking.WebSocketNetDriver",DriverClassNameFallback="/Script/WebSocketNetworking.WebSocketNetDriver") 232 | ``` 233 | 234 | **remember** to also do this in WindowsEngine.ini, MacEngine.ini or LinuxEngine.ini 235 | (depending on the system you are using - or do it on all of them if you are not sure). 236 | 237 | > note: **BaseEngine.ini** has been done for you (if you're using the special branch) 238 | 239 | > repeat: **ShooterGame/Config/{Windows,Mac,Linux}/{Windows,Mac,Linux}Engine.ini** 240 | will **NEED TO BE EDITED** with these changes mentioned above. 241 | 242 | 243 | #### Add WebSocketNetDriver Settings (2) 244 | 245 | at the end of **BaseEngine.ini** (and only this file), add the 246 | **WebSocketNetworking.WebSocketNetDriver** settings at the end of the file: 247 | 248 | ```ini 249 | [/Script/WebSocketNetworking.WebSocketNetDriver] 250 | AllowPeerConnections=False 251 | AllowPeerVoice=False 252 | ConnectionTimeout=60.0 253 | InitialConnectTimeout=120.0 254 | RecentlyDisconnectedTrackingTime=180 255 | AckTimeout=10.0 256 | KeepAliveTime=20.2 257 | MaxClientRate=15000 258 | MaxInternetClientRate=10000 259 | RelevantTimeout=5.0 260 | SpawnPrioritySeconds=1.0 261 | ServerTravelPause=4.0 262 | NetServerMaxTickRate=30 263 | LanServerMaxTickRate=35 264 | WebSocketPort=8889 265 | NetConnectionClassName="/Script/WebSocketNetworking.WebSocketConnection" 266 | MaxPortCountToTry=512 267 | ``` 268 | 269 | > again, this has been done for you if you're using the special branch 270 | 271 | 272 | #### Disable PacketHandler Components (3) 273 | 274 | in the following files: 275 | - Engine/Config/BaseEngine.ini 276 | - note: as of this writting, this is **not** seen in BaseEngine.ini -- but, 277 | it is mentioned here just in case you see this in the future... 278 | - ShooterGame/Config/Windows/WindowsEngine.ini 279 | - ShooterGame/Config/Mac/MacEngine.ini 280 | - ShooterGame/Config/Linux/LinuxEngine.ini 281 | 282 | find any **PacketHandler** Components sections, and disabling them by commenting them out. 283 | 284 | for example, in **ShooterGame/Config/Windows/WindowsEngine.ini** -- this should look like this: 285 | 286 | ```ini 287 | ;[GameNetDriver PacketHandlerProfileConfig] 288 | ;+Components=OnlineSubsystemSteam.SteamAuthComponentModuleInterface 289 | ; 290 | ;[PendingNetDriver PacketHandlerProfileConfig] 291 | ;+Components=OnlineSubsystemSteam.SteamAuthComponentModuleInterface 292 | ``` 293 | 294 | > note the `;` (semicolon) at the start of the line indicating this line is disabled (commented out) 295 | 296 | 297 | * * * 298 | ### Package ShooterGame for Desktop 299 | 300 | using the same steps outlined in [Build Sample Project](README.0.building.UE4.Editor.md#build-sample-project) 301 | 302 | set the build type: 303 | - Menu bar -> File -> **Package Project** -> Build Configuration 304 | - select `Development` (i.e. keep the build type the same for all platforms) 305 | 306 | finally, package for your desktop 307 | - Menu bar -> File -> Package Project -> **Windows/Mac/Linux** (etc.) 308 | - select the folder where the final files will be **archived** to 309 | 310 | > NOTE: on linux, you may need to enable it as a supported platform - see (HTML5) 311 | screenshot below to find where to enable it 312 | 313 | 314 | ### Package ShooterGame for HTML5 315 | 316 | ##### SPECIAL NOTE: enable the HTML5 as a supported platform 317 | 318 | ![](Images/editor_supported_platforms_html5.png) 319 | 320 | 321 | now, using the same steps outlined in [Build Sample Project](README.0.building.UE4.Editor.md#build-sample-project) 322 | 323 | set the build type: 324 | - Menu bar -> File -> **Package Project** -> Build Configuration 325 | - select `Development` (i.e. keep the build type the same for all platforms) 326 | 327 | finally, package for HTML5 328 | - Menu bar -> File -> Package Project -> **HTML5** 329 | - select the folder where the final files will be **archived** to 330 | 331 | 332 | * * * 333 | ### Test Desktop ShooterGame Client 334 | 335 | as we have seen in the previous HowTo's [multi-player testing](README.1.emscripten.UE4.HTML5.md#launch-the-desktop-client), 336 | we will run this project in `windowed` mode from the command line. 337 | 338 | - run the game in a windowed size screen (i.e. not full screen) 339 | - using `-windowed -resx=800 -resy=600` parameter to do this 340 | 341 | - again, i like to see the `stdout` prints -- to know that the game is still running 342 | - using `-log` parameter to view this 343 | 344 | 345 | #### on Windows via CommandPrompt 346 | 347 | - open `CommandPrompt` to the location where files were **archived** to 348 | - e.g. `cd ...\ShooterGame\WindowsNoEditor` 349 | - run executable 350 | - `ShooterGame.exe -windowed -resx=800 -resy=600 -log` 351 | 352 | #### on Mac via Terminal 353 | 354 | - open `terminal` to the location where files were **archived** to 355 | - e.g. `cd .../ShooterGame/MacNoEditor` 356 | - run executable 357 | - `open ./ShooterGame.app --args -windowed -resx=800 -resy=600 -log` 358 | 359 | #### on Linux via Terminal 360 | 361 | - open `terminal` to the location where files were **archived** to 362 | - e.g. `cd .../ShooterGame/LinuxNoEditor` 363 | - run executable 364 | - `./ShooterGame.sh -windowed -resx=800 -resy=600 -log` 365 | 366 | 367 | > TIP: put the command in a shortcut (or alias, script, etc.) for future use! 368 | 369 | 370 | ### Another Desktop Client 371 | 372 | for the purpose of this demo, open another client in windowed mode. 373 | 374 | then, in the **first** game window, select: 375 | - in **MAIN MENU -> HOST** 376 | - set **NUMBER OF BOTS** to 0 (zero) 377 | - click on **FREE FOR ALL** 378 | 379 | ![](Images/shootergame_host.png) 380 | 381 | 382 | now, in the **second** game window, select: 383 | - in **MAIN MENU -> JOIN** (may have to click on **JOIN** twice) 384 | - click on **SERVER** 385 | - wait for your server to show up in the list, and then double click on it 386 | 387 | ![](Images/shootergame_join.png) 388 | 389 | you should now see the two game clients in the same match. 390 | 391 | 392 | * * * 393 | ### Test HTML5 Client with Desktop ShooterGame Host 394 | 395 | now, let's get the HTML5 client in the same match. 396 | 397 | using the same steps from [launch the HTML5 client](README.1.emscripten.UE4.HTML5.md#launch-the-html5-client) 398 | from the previous HowTo's multi-player testing example. 399 | 400 | 401 | #### on Windows, Mac or Linux via command line 402 | 403 | in `git-bash` (for windows) or in the `terminal` (for mac or linux), you can 404 | use python's built in web server to host the files quick and easy. 405 | 406 | ```bash 407 | # remember, this is an "example" path (see "archive to" notes just above) 408 | cd .../ShooterGame/HTML5 409 | python -m http.server 8000 410 | #python2 -m SimpleHTTPServer 8000 411 | ``` 412 | 413 | and using almost the same steps from [chrome or firefox](#chrome-or-firefox-64-bit-version-recommended) above: 414 | 415 | - open browser to http://localhost:8000/ 416 | - click on the relevant HTML file ( e.g. http://localhost:8000/ShooterGame.html ) 417 | 418 | - join the desktop match: 419 | - NOTE: due to the way **ShooterGame** was designed, the **JOIN** mechanism will NOT WORK with the browser 420 | - SO, we are going to use the `game console` command line we've seen in 421 | [testing muti-player on HTML5](README.1.emscripten.UE4.HTML5.md#finally) 422 | in the last HowTo 423 | - open the `game console` command line, by pressing the **tilda** key (`~`) 424 | - type: `open 127.0.0.1` 425 | 426 | you should see something like this: 427 | 428 | ![](Images/shootergame_match.png) 429 | 430 | 431 | > NOTE: if the desktop game match ended, just start a new match. you might have 432 | to restart the whole server and client executable(s) -- so use multiple command 433 | prompts/terminals and use the `up` arrow to re-run the same command (or use 434 | the handy shortcut, alias, script, as recommended). 435 | 436 | 437 | * * * 438 | * * * 439 | ## smash texture sizes 440 | 441 | let us take a look at a common issue with web browser games. data size downloads 442 | are quite sensitive to many users. keeping them small while trying to keep up 443 | visual quality up is a delicate balance. 444 | 445 | for the purpose of this HowTo, we are going to reduce the texture sizes for 446 | EVERYTHING for HTML5. 447 | 448 | - Menu bar -> Window -> Developer Tools -> **Device Profiles** 449 | - in the Device Profiles -> **Existing Device Profiles** window 450 | - select the `HTML5 ...` (3 small "dots") 451 | - or the HTML5 `Texture LODGroup` (wrench icon) 452 | - this will bring up the **HTML5 Device Profile** settings window 453 | - set **ALL** `Max LOD Size` to 256 (to start) 454 | 455 | ![](Images/editor_device_profile.png) 456 | 457 | - here, we see the `World` limit set to `256` 458 | - do the same for ALL the other categories 459 | 460 | doing this will greatly reduce the `.data` file size 461 | 462 | - repackage and notice the difference in the `data` file size 463 | 464 | 465 | * * * 466 | * * * 467 | ## view modes in editor 468 | 469 | back in the [first HowTo: PIE](README.0.building.UE4.Editor.md#play-in-editor) 470 | was mentioned. here's a link that will explain this feature in better details: 471 | 472 | - https://docs.unrealengine.com/en-US/Platforms/Mobile/Previewer/index.html 473 | 474 | NOTE: for HTML5, set the Editor's previewer to the following to see (as close 475 | as possible) for the following equivalent HTML5 rendering format: 476 | - ES2: WebGL1 477 | - ES3: WebGL2 478 | - ES3.1: WebGL2 + WebGPU (someday...) 479 | 480 | 481 | * * * 482 | * * * 483 | 484 | Next, [Debugging UE4 HTML5](README.3.debugging.UE4.HTML5.md) 485 | 486 | * * * 487 | 488 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.3.debugging.UE4.HTML5.md: -------------------------------------------------------------------------------- 1 | # Debugging UE4 HTML5 2 | 3 | while most browsers have a pretty nice debugger for "web page" development -- it is essentially un-usable when building UE4 for the web browser. 4 | 5 | - before, builds compiled to "javascript assembly" (ASMjs) -- and, there was no way to put in breakpoints when the JS was smashed into one line 6 | - yes, some have a code beautifier button -- but, the debuggers would choke when trying to keep the (back then) giant 100+MB of code in the scroll window 7 | - and now, with "web assembly" (WASM) -- there doesn't seem to be any UE4 code visible (just the JS plumbing code for the WASM driver) 8 | 9 | so, I mostly just print stuff to the console window for debugging. 10 | 11 | > TIP: build for your Desktop platform and debug as much as you can there. 12 | it will be so much easier than trying to do the same thing for HTML5. 13 | 14 | 15 | * * * 16 | ## How To Dump The Stack And Print From Cpp 17 | 18 | at the top of any UE4 cpp file -- put the following at the **end** of the `#includes`: 19 | ```cpp 20 | #ifdef __EMSCRIPTEN__ 21 | #include 22 | #include 23 | #else 24 | #define EM_ASM(x) 25 | #define EM_ASM_(...) 26 | #define EM_ASM_ARGS(...) 27 | #endif 28 | ``` 29 | 30 | and use the `EM_ASM*` where ever you see fit. the `#else` allows you to just put the `EM_ASM*` calls in anywhere 31 | without having to `#ifdef __EMSCRIPTEN__` the `EM_ASM*` calls (e.g. just in case you rebuild the editor). 32 | 33 | 34 | so for example, in `Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp`, 35 | put the `#include` and`#define` stuff (*EM_ASM code*) up near the top of the 36 | file -- and then, in the following function: 37 | 38 | ```cpp 39 | void FDebug::LogAssertFailedMessageImpl(const ANSICHAR* Expr, const ANSICHAR* File, int32 Line, const TCHAR* Fmt, ...) 40 | { 41 | EM_ASM({ console.log( jsStackTrace() ); }); 42 | . . . 43 | ``` 44 | 45 | here, I added a call to the `jsStackTrace()` function to dump the call stack when ever UE4 crashes. 46 | 47 | 48 | I sometimes put `jsStackTrace()` when ever I need to figure what's going on. 49 | 50 | * * * 51 | ### My `EM_ASM*` snippets: 52 | 53 | `EM_ASM({ console.log("NICKNICK: msg here"); });` 54 | - no variables -- just output to console.log 55 | 56 | `EM_ASM_({ console.log("NICKNICK: msg here:" + $0); }, bSucceeded);` 57 | - simple variables 58 | 59 | `EM_ASM_ARGS({ var str = UTF8ToString($0,$1); console.log("NICKNICK: msg here [" + str + "]"); }, TCHAR_TO_ANSI(*some_FString), some_FString.len());` 60 | - string variables -- most of UE4's strings are the `FString` object. 61 | these needs to be wrapped in the `TCHAR_TO_ANSI()` macro in order to make them printable in the console.log 62 | 63 | these 3 `EM_ASM*` snippets above, are pretty much my most used ones -- including finding some goofy compilier bugs... 64 | 65 | the following are not used as much, but you may encounter a need for them in UE4's code: 66 | 67 | ``` 68 | emscripten_log(EM_LOG_CONSOLE, TCHAR_TO_ANSI(some_TCHAR)); 69 | EM_ASM_ARGS({ var str = UTF8ToString($0,$1); console.log("NICKNICK: msg here [" + str + "]"); }, TCHAR_TO_ANSI(some_TCHAR), strlen(TCHAR_TO_ANSI(some_TCHAR))); 70 | EM_ASM_ARGS({ var str = UTF16ToString($0,$1); console.log("NICKNICK: msg here [" + str + "]"); }, some_TCHAR, wcslen(some_TCHAR)); 71 | ``` 72 | - using the TCHAR variables here 73 | 74 | **Note**: UE4 has a logger (that prints to stdout -- which then gets printed to console.log) 75 | - but, these `UE_LOG()` needs setup (typed via macros) and turned on (via configuration settings) 76 | - so I just use the `EM_ASM*` functions to make this simple to **use** -- as well as simple to **find and remove** 77 | - however, if you feel there is a valid reason for permanent logging in certain situation (that will be commited), please see: 78 | - https://wiki.unrealengine.com/Logs,_Printing_Messages_To_Yourself_During_Runtime 79 | - pay special attention to: **Log Category Macros** and **Config file** 80 | 81 | * * * 82 | ## BugHunting GLSL 83 | 84 | for graphic shaders, I would use a combination of **RenderDoc** and **Spector.js**. 85 | 86 | ### RenderDoc 87 | 88 | RenderDoc has a nice way to view a mesh from the vertex shader before and after calculations. 89 | 90 | i'm going to just defer to the following video on how to configure chrome and use renderdoc: 91 | - https://www.youtube.com/watch?v=T7MPxvX5alA 92 | - here's a shortcut/batch file command i use with this: 93 | - `"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --disable-gpu-sandbox --disable-gpu-watchdog --gpu-startup-dialog --user-data-dir=zzz --no-first-run http://localhost:8000` 94 | 95 | sometimes, i have to look through (in the **Mesh Output** tab) the raw data via the 96 | (right click anywhere in the **VS Input** window) "Export to Bytes" option to see/ensure what the data is and expected. 97 | 98 | the only problem with RenderDoc (in the context of webgl) -- is that the VertexShader disassembly is only available 99 | for the desktop's GPU driver (i.e. ms directx, amd gcn, etc.). in other words, not in "WebGL shader" code. 100 | 101 | ### Spector.js 102 | 103 | this brings us to the in-browser extension called: [**Spector.js**](http://spector.babylonjs.com). 104 | 105 | but first, we need to get UE4 to dump the WebGL shaders during cooks. follow the instructions here: 106 | - https://www.unrealengine.com/en-US/blog/debugging-the-shader-compiling-process 107 | - basically, after cooks, you'll be able to find the generated glsl files at (**for example**): 108 | - `.../Project/Saved/ShaderDebugInfo/GLSL_ES_WEBGL/.../0/Engine/Private/MobileBasePassVertexShader.usf.glsl` 109 | - and the respective UE4 shader file used to build that, is located at: 110 | - `.../Project/Saved/ShaderDebugInfo/GLSL_ES_WEBGL/.../0/MobileBasePassVertexShader.usf` 111 | 112 | - again, you need to repackage in order to recook the assets -- which will then dump the GLSL code. 113 | 114 | now, use Spector.js to capture a session, click through the frames we are interested in, 115 | and (finally) view the shader used for that draw. 116 | 117 | we can scan the dump of WebGL shaders with a snippet of the shader code (from Spector.js) to find 118 | the `*.usf` file (which contains the sources and inlined file paths) to hunt down the broken shader. 119 | - i've found scanning for the block inside of the main() curly braces (of the GLSL code from Spector.js) 120 | is all you'll need to find the respective `*.usf` file. 121 | - here's the perl script (scan.pl) i use to do this: 122 | 123 | ```perl 124 | #!/usr/bin/perl -w 125 | 126 | use strict; 127 | use warnings; 128 | 129 | # the code we are interested in 130 | my @data = (); 131 | while() { # see BELOW for the the DATA block 132 | s/[\r|\n|\s]//g; # strip all whitespace and line ending chars 133 | push @data, qq($_); 134 | } 135 | 136 | # the file we are scanning against... 137 | my $index = 0; 138 | my $limit = @data; 139 | while (<>) { 140 | s/[\r|\n|\s]//g; # strip all whitespace and line ending chars 141 | $index++ if ( qq($data[$index]) eq qq($_)); 142 | 143 | if ( $index >= $limit ) { 144 | print "FOUND"; 145 | last; 146 | } 147 | } 148 | 149 | # the lines inside of the main() curly braces (of the GLSL code from Spector.js) 150 | # (please note, this is a sample and has been truncated for this doc) 151 | __DATA__ 152 | v0.xyz = vu_h[10].xyz; 153 | vec4 v3; 154 | v5.xyz = clamp((cross(clamp((cross(in_ATTRIBUTE2.xyz, in_ATTRIBUTE1)*in_ATTRIBUTE2.www), vec3(0.000000e+00, 0.000000e+00, 0.000000e+00), vec3(1.000000e+00, 1.000000e+00, 1.000000e+00)), in_ATTRIBUTE2.xyz)*in_ATTRIBUTE2.www), vec3(0.000000e+00, 0.000000e+00, 0.000000e+00), vec3(1.000000e+00, 1.000000e+00, 1.000000e+00)); 155 | vec3 v6; 156 | vec3 v7; 157 | v11.xyz = ((in_ATTRIBUTE9.zzz*vu_h[3].xyz)+((in_ATTRIBUTE9.yyy*vu_h[2].xyz)+(in_ATTRIBUTE9.xxx*vu_h[1].xyz))); 158 | ``` 159 | 160 | - and that script is called via this shell script (scan.sh): 161 | 162 | ```bash 163 | #!/bin/sh 164 | find /work/ue4-4.24.3-html5/ShooterGame/Saved/ShaderDebugInfo/GLSL_ES2_WEBGL -name "*.glsl" -print | while read i; do 165 | results=`cat "$i" | ./scan.pl` 166 | if [ "$results" == "FOUND" ]; then 167 | echo $i 168 | fi 169 | done 170 | ``` 171 | 172 | - finally, to kick this all off, just run: `./scan.sh` 173 | - i'm sure these perl and shell scripts could have been combined and written a little more optimally 174 | (instead of having a script call another script) -- but, for me -- this was all **throw-away code**, 175 | quick and dirty utilities... 176 | 177 | * * * 178 | 179 | Next, [UE4 HTML5 F.A.Q](README.4.faq.UE4.HTML5.md) 180 | 181 | * * * 182 | 183 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.4.faq.UE4.HTML5.md: -------------------------------------------------------------------------------- 1 | # F.A.Q. - Frequently Asked Questions 2 | 3 | in this page, you can find information on: 4 | 5 | - Browsers 6 | - [multi-threading](#multi-threading) 7 | - [integer overflow](#integer-overflow--script-error) 8 | - [infinite spinning "Launching engine..."](#infinite-spinning-launching-engine) 9 | - Unreal Engine and HTML5 10 | - [already have UnrealEngine, how to get HTML5 platform extension](#i-already-have-unrealengine-how-do-i-get-the-html5-platform-extension) 11 | - [trying to get latest Unreal Engine working with HTML5 platform extensions](#trying-to-get-latest-unreal-engine-working-with-html5-platform-extensions) 12 | - Troubleshooting UE4 HTML5 builds 13 | - [attempting to package for HTML5 instead brings up the help page](#attempting-to-package-for-html5-instead-brings-up-the-help-page) 14 | - [bit packing brokeness](#bit-packing-brokeness) 15 | - [common compiler issues when upgrading emscripten toolchain](#common-compiler-issues-when-upgrading-emscripten-toolchain) 16 | - Emscripten 17 | - [links](#links) 18 | - [custom edits to emsripten for Unreal Engine](#custom-edits-to-emsripten-for-unreal-engine) 19 | - [troubleshooting emsdk issues](#troubleshooting-emsdk-issues) 20 | - [Unreal Engine HTML5 Files](#unreal-engine-html5-files) 21 | 22 | 23 | * * * 24 | * * * 25 | ## Browsers 26 | 27 | ### multi-threading 28 | 29 | - if you are having problems seeing the game run (**especially on the first time running this**) 30 | - e.g. on firefox - `LinkError: shared memory is disabled` 31 | - e.g. on chrome - `Assertion failed: requested a shared WebAssembly.Memory but the returned buffer is not a SharedArrayBuffer, indicating that while the browser has SharedArrayBuffer it does not have WebAssembly threads support - you may need to set a flag` 32 | 33 | - you will need to configure your browser to allow "multi-threading" support 34 | - for Chrome: set `chrome://flags/#enable-webassembly-threads` as `WebAssembly threads support` 35 | - for Firefox: in `about:config` set `javascript.options.shared_memory` preference to `true` to enable **SharedArrayBuffer** 36 | 37 | - then try reloading the project in your browser 38 | - you may need to restart your browser if you are still having problems 39 | 40 | 41 | ### Integer Overflow / Script error 42 | 43 | open the `console.log` window for your browser (`Control+Shift+I` as in "eye") 44 | 45 | - if you see an error: 46 | - e.g. on firefox - `error: RuntimeError: integer overflow` 47 | - e.g. on chome - `Script error.` 48 | - or (on developement builds) you do **NOT** see `LogHTML5Launch: Display: Starting UE4 ...` 49 | 50 | these are usually indications of the browser not having enough resources to load page. 51 | 52 | - try shutting down "other" applications 53 | - tests have shown that running to many apps in the background have lead to memory fragmentation, 54 | which browsers will have a hard time getting the memory space needed to run 55 | - shut down things like visual studio, the Editor, EVERYTHING -- except your 56 | browser and the "web server" -- this will all help you get the game running 57 | in the browser 58 | - then, reload the project page on the browser 59 | 60 | 61 | if however, you see a lot of logs in the `console.log` window, then BUGHUNT the 62 | game code (logic/functions). please see [Debugging UE4 HTML5](README.3.debugging.UE4.HTML5.md) 63 | for more details. 64 | 65 | 66 | ### Infinite Spinning "Launching engine..." 67 | 68 | chances are, the game has crashed. open the `console.log` window for your 69 | browser (`Control+Shift+I` as in "eye"). and if you see a pile of red errors, 70 | this should show you the crash stack. begin the BUGHUNT! 71 | 72 | 73 | * * * 74 | * * * 75 | ## Unreal Engine and HTML5 76 | 77 | * * * 78 | ### i already have UnrealEngine, how do i get the HTML5 platform extension 79 | 80 | ```bash 81 | git fetch https://github.com/UnrealEngineHTML5/UnrealEngine 4.24.3-html5-1.39.18 82 | git checkout 4.24.3-html5-1.39.18 83 | ``` 84 | 85 | 86 | * * * 87 | ### trying to get latest Unreal Engine working with HTML5 platform extensions 88 | 89 | ##### i.e. putting HTML5 platform files back in with latest Unreal Engine. 90 | 91 | ##### WARNING: this is not for the faint of heart. 92 | 93 | > NOTE: Unreal Engine as of 4.24, is the last `ES2` supported rendering feature level 94 | 95 | > this will cause headaches, as the HTML5 rendering code and shader compiler will need 96 | to be either changed to **only** support `ES3` (WebGL2) and above -- or pull in a 97 | lot of `ES2` code into the HTML5 platform extension folder (work is currently trying 98 | to impliment the latter solution so that more "older" OS are supported) 99 | 100 | 101 | #### Engine/Platforms/HTML5/HTML5Setup.sh 102 | 103 | rerun `Engine/Platforms/HTML5/HTML5Setup.sh` build script (see [HERE](README.1.emscripten.UE4.HTML5.md#html5setupsh-build-script) 104 | for a refresher). this will: 105 | - re-setup the emscripten toolchain 106 | - re-build all ThirdParty libraries HTML5 uses (that Epic sometimes edits) 107 | - re-inject the HTML5 platform into UnrealBuildTool 108 | 109 | 110 | #### re-generate Project/Make files 111 | 112 | this should **ALWAYS** be done when ever new code is `pull` down (i.e. your local repository is `fetch` with latest & `merge` in): 113 | 114 | 115 | ##### on Windows 116 | GenerateProjectFiles.bat 117 | 118 | ##### on Mac 119 | GenerateProjectFiles.command 120 | 121 | ##### on Linux 122 | GenerateProjectFiles.sh 123 | 124 | 125 | #### UE4Editor 126 | 127 | with new Unreal Engine code now ready, re-build the Editor: 128 | - [Compiling Support Programs](README.0.building.UE4.Editor.md#compiling-support-programs) 129 | - [Compiling UE4Editor](README.0.building.UE4.Editor.md#compiling-ue4editor) 130 | 131 | 132 | #### Packaging 133 | 134 | make sure your existing development platform isn't broken. try to: 135 | [Package a Sample BluePrint Project](README.0.building.UE4.Editor.md#package-a-sample-blueprint-project) first. 136 | 137 | and then finally, try to: [package a UE4 sample project for HTML5](README.1.emscripten.UE4.HTML5.md#package-a-sample-blueprint-project-for-html5) 138 | 139 | 140 | * * * 141 | * * * 142 | ## Troubleshooting UE4 HTML5 builds 143 | 144 | the following are tips and suggestions to try out when your HTML5 builds goes wrong. 145 | 146 | 147 | * * * 148 | ### attempting to package for HTML5 instead brings up the help page 149 | 150 | if you are seeing the [XXX Developing HTML5 project](https://docs.unrealengine.com/en-us/Platforms/HTML5/GettingStarted) 151 | help page after clicking on **Menu Bar -> File -> Package Project -> HTML5** 152 | - chances are that there is a mismatched `emscripten toolchain version` value(s) 153 | - this is normally seen when developers try to upgrade their emscripten toolchain and forget to update those values in `HTML5SDKInfo.cs` 154 | - please see [Updating UE4 C# scripts](README.1.emscripten.UE4.HTML5.md#updating-ue4-c-scripts) 155 | for more details on what to check for and how to fix this 156 | 157 | > note: do not forget to recompile all [ThirdParty libraries](README.1.emscripten.UE4.HTML5.md#fetch-emsdk-and-build-thirdpary-libraries-for-html5) with your changed toolchain versions. 158 | 159 | 160 | * * * 161 | ### bit packing brokeness 162 | 163 | ##### tobool63.i = icmp slt i176 164 | 165 | the crux of this issue is best explained from this stackoverflow post: 166 | - [C++ bitfield packing with bools](https://stackoverflow.com/questions/308364/c-bitfield-packing-with-bools) 167 | 168 | in UE4, there are some mixed bitfield types that seems to explode the data structure size that emscripten doesn't like 169 | - this may be fixed in "upstream" (i.e. clang10) 170 | - but, UE4 can only be build with "fastcomp" (i.e. clang6) 171 | - this was mentioned in [Emscripten and UE4 README](README.1.emscripten.UE4.HTML5.md#upgrading-emscripten-toolchain) -- Upgrading Emscripten Toolchain section 172 | 173 | to hunt down the offending `struct`, you need to disassemble the bitcode (`.bc`) file and scan for the error the build spits out during link. 174 | - for example, during HTML5 packaging, you might see `error: tobool63.i = icmp slt i176` in the build log 175 | - to get an idea of what function this might be coming from -- we scan the disassembled file (`.ll`) for that error 176 | - using `grep`, we dump 1000 lines before (`-B 1000`) and a few lines after (`-A 20`) 177 | - inspect that smaller chunk of disassembled lines to try and narrow the file we need to look for 178 | 179 | in this example, `Engine/Source/Runtime/Engine/Classes/Engine/Scene.h` contained a mix of `uint8 :1` and `uint32 :1` data types. 180 | emscripten ("fastcomp") didn't like this -- but, changing them all to bool fixed this link time error. 181 | 182 | ```bash 183 | Engine/Binaries/HTML5$ llvm-dis-6.0 UE4Game.bc 184 | Engine/Binaries/HTML5$ egrep -B 1000 -A 20 "tobool63.i = icmp slt i176" UE4Game.ll > minidump.txt 185 | . . . 186 | Engine/Source/Runtime/Engine/Classes/Engine$ mv Scene.h Scene.h.save 187 | Engine/Source/Runtime/Engine/Classes/Engine$ cat Scene.h.save | perl -0p -e "s/uint\d+\s+(.+)\s?:\s?1;/bool \1;/g" > Scene.h 188 | ``` 189 | 190 | ##### PLATFORM_USE_SHOWFLAGS_ALWAYS_BITFIELD 191 | 192 | in `Engine/Source/Runtime/Engine/Public/ShowFlags.h`, this also had a similar bit packing problem. 193 | but, all of the data types were the same here. and yet, something was causing the game to render a black screen if the data type wasn't set as just `bool` for some reason. 194 | 195 | it could have been due to using a `char` size value in `memset()` -- when the data type was originally `uint32 :1` -- but, 196 | setting everything to `bool` here, caused the playstation to render its screen black... so this was `#if` guarded on platforms 197 | in a case by case basis (yes, only HTML5 was the only one that needed this "fix"). 198 | 199 | 200 | * * * 201 | ### Common Compiler Issues When Upgrading Emscripten Toolchain 202 | 203 | TODO: FINISH ME... 204 | 205 | 206 | * * * 207 | * * * 208 | ## Emscripten 209 | 210 | to learn more about what powers Unreal Engine for the web browsers, please see: 211 | 212 | ### Links 213 | - https://github.com/emscripten-core/emsdk 214 | - https://github.com/emscripten-core/emscripten 215 | - https://emscripten.org/docs/building_from_source/toolchain_what_is_needed.html 216 | 217 | 218 | ### Custom Edits to Emscripten for Unreal Engine 219 | 220 | the detailed are found in the [patching emscripten](README.1.emscripten.UE4.HTML5.md#patching-emscripten) section. 221 | 222 | 223 | * * * 224 | ### Troubleshooting emsdk issues 225 | 226 | this is run during `HTML5Setup.sh` - if you see errors like the following: 227 | 228 | 229 | ##### python SSL/TSL 230 | 231 | ```bash 232 | Warning: Possibly SSL/TLS issue. Update or install Python SSL root certificates... 233 | ``` 234 | 235 | update your system's [Python](https://www.python.org/downloads/) version. 236 | 237 | 238 | ##### "tools cannot be activated since it is not installed" 239 | 240 | ```bash 241 | Warning: The SDK/tool 'node-X.Y.Z-64bit' cannot be activated since it is not installed! Skipping this tool... 242 | Warning: The SDK/tool 'python-X.Y.Z.a-64bit' cannot be activated since it is not installed! Skipping this tool... 243 | Warning: The SDK/tool 'java-X.Y-64bit' cannot be activated since it is not installed! Skipping this tool... 244 | ... 245 | ``` 246 | 247 | you might have missied the first error when running the `HTML5Setup.sh` script the first time. 248 | 249 | in other words, running the `HTML5Setup.sh` script (the first time) shows that 250 | `./emsdk install ` has failed for some reason. 251 | 252 | and now, when trying to run `HTML5Setup.sh` again - it tried to proceed to 253 | `./emsdk activate ` and it is saying that these tools are missing. 254 | - to show the first error again (for bug reporting purposes): 255 | - DELETE you local copy of `Engine/Platforms/HTML5/Build/emsdk/*` 256 | - rerun `HTML5Setup.sh` again 257 | - carefully look at the build output and see if this error has been reported before 258 | - be sure to also see if this has been reported in https://github.com/emscripten-core/emscripten/issues 259 | 260 | 261 | * * * 262 | * * * 263 | ## Unreal Engine HTML5 Files 264 | 265 | 266 | #### Custom HTML TemplatesFiles 267 | you can change HTML and CSS template files to make them stick every re-packaing 268 | - for all projects: 269 | - `.../Engine/Platforms/HTML5/Build/TemplateFiles/*` 270 | - however, we recommend developers putting their custom template file changes in the project's own folder 271 | - copy `TempateFiles/*` 272 | - i.e. the same one "for all projects" (just above) 273 | - to `...//Build/HTML5/` 274 | 275 | 276 | #### Build Folders 277 | 278 | before the final copy to the **archive** folder, they are staged at: 279 | 280 | - for **blueprint projects** 281 | - `.../Engine/Binaries/HTML5/` 282 | - for **C++ projects** (e.g. project is named `CPP_TP`) 283 | - `.../CPP_TP/Saved/StagedBuilds/WindowsNoEditor/` 284 | - `.../CPP_TP/Saved/StagedBuilds/MacNoEditor/` 285 | - `.../CPP_TP/Saved/StagedBuilds/LinuxNoEditor/` 286 | 287 | do not edit anything in those folders, they will be stompped on after every packaging. 288 | - i.e. treat this folder as READ ONLY 289 | 290 | 291 | #### Engine/Intermediate/Build/HTML5/EmscriptenCache 292 | - every time you upgrade/change your toolchain version (or switch between them or make a local modification 293 | to `.../emsdk/emscripten//system/...` you will need to delete the respective *.bc file or the 294 | whole folder to ensure your changes are recompiled 295 | 296 | 297 | #### emscripten ports 298 | - while a lot of the UE4 Thirdparty libs (used with HTML5 builds) are also available as escripten ports: 299 | - there are a number of custom UE4 changes that are required to make the engine functional for HTML5 300 | - for now, we recommend using the UE4 versions until this is revisited in the future 301 | - NOTE: when using ports, remember to "turn off" UE4's version 302 | - e.g. if you wish to use emscripten's version of SDL2 -- you will need to disable UE4's version: 303 | - edit: **.../Engine/Thirdparty/SDL2/SDL2.Build.cs** 304 | - delete/comment out the HTML5 section and save the file 305 | - this change will be automatically picked up at packaging time 306 | 307 | 308 | #### Engine/Platforms/HTML5/Build/BatchFiles/Build_All_HTML5_libs.rc 309 | - this **_used_** to setup my shell environment when I need to 310 | _rebuild the thirdparty libraries_ for HTML5 (**from the ~OSX or Linux~ commandline**) 311 | - currently, I now use: `source .../emsdk/emsdk-/emsdk_set_env.sh` 312 | - **_now_**, this file has notes reminding me of the changes needed to the emscripten toolchain for UE4 purposes 313 | - ~please see the file if you're curious (especially the "**upgrading emsdk - REMEMBER TO DO THE FOLLOWING**" section)~ 314 | - no longer needed - these are now [patched](README.1.emscripten.UE4.HTML5.md#patching-emscripten) in automatically 315 | 316 | 317 | #### Engine/Platforms/HTML5/Build/BatchFiles/Build_All_HTML5_libs.sh 318 | - after pulling down a new version of emscripten, we **have to rebuild** the (UE4's) thirdparty libs used with HTML5 319 | - i.e. **new toolchain --> new binaries** 320 | - this shell script spells out which libs need to be rebuilt for HTML5 321 | - scan the additional scripts called from this file for more details 322 | - every now and then, the Makefiles, CMake files, or something needs to change 323 | (new compiler warnings, depricated features, compiler/toolchain support level, etc.) 324 | - I like to build the thirdparty libs **one at a time** and even **one optimization level** at a time 325 | - YMMV, play with the (sh) scripts -- it's spelled out like a normal cookbook set of CLI instructions 326 | - **this(these) script(s) DOES NOT NEED to know about UE4's build environment** 327 | - ~that said, **it is recommended to build the thirdparty libs from OSX or Linux** (see the companion 328 | file **Build_All_HTML5_libs.rc** -- just mentioned above -- under the **WINDOWS NOTES** section for details on why)~ 329 | - no longer needed - everything is now powered by CMake 330 | 331 | - when these errors happen, you will need to hunt them down 332 | - all of the CMake files used here are found in `Engine/Platforms/HTML5/Build/BatchFiles/ThirdParty/...` 333 | - editing `Engine/Platforms/HTML5/Build/BatchFiles/Build_All_HTML5_libs.sh` and 334 | commenting out all libs except for the troubled one will be of help 335 | 336 | -------------------------------------------------------------------------------- /Platforms/HTML5/HowTo/README.md: -------------------------------------------------------------------------------- 1 | # Unreal Engine HTML5 Platform Extension 2 | 3 | `Remember to link your Epic Games Account to your GitHub account.` 4 | See [HERE](../../../README.md) for more details. 5 | 6 | * * * 7 | The following are detailed instructions for packaging HTML5 projects with Unreal Engine. 8 | 9 | - [Starting with UE4 Editor](README.0.building.UE4.Editor.md) 10 | - Developement Environment Requirements 11 | - Get Source Files 12 | - Compiling UE4 Editor 13 | - Package sample project 14 | 15 | - [Emscripten and UE4](README.1.emscripten.UE4.HTML5.md) -- >> **the** UE4 HTML5 **crash course** << 16 | - EMSDK 17 | - Emscripten toolchain and Building UE4 Thirdparty libraries for HTML5 18 | - UE4 C# scripts 19 | - Package The Project For HTML5 20 | - Test The HTML5 Packaged Project 21 | 22 | - [Advanced Example of Building a UE4 HTML5 Project](README.2.advanced.UE4.HTML5.md) 23 | - Package a Multiplayer Project For HTML5 24 | 25 | - [Debugging UE4 HTML5](README.3.debugging.UE4.HTML5.md) 26 | - How To Dump The Stack And Print From Cpp 27 | - BugHunting GLSL 28 | 29 | - [UE4 HTML5 F.A.Q](README.4.faq.UE4.HTML5.md) 30 | - Frequently Asked Questions 31 | 32 | * * * 33 | 34 | -------------------------------------------------------------------------------- /Platforms/HTML5/Images/ActionRPG-resize514x289.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/Images/ActionRPG-resize514x289.jpg -------------------------------------------------------------------------------- /Platforms/HTML5/Images/HTML5Development_topic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UnrealEngineHTML5/Documentation/48b669b5a0101cd961027eda7120051bf538b8f7/Platforms/HTML5/Images/HTML5Development_topic.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Documentation 2 | 3 | This is the documentation for the Community-supported HTML5 Platform Extension for Unreal Engine 4. 4 | 5 | - [Detailed "HowTo" Build UE4 for HTML5](Platforms/HTML5/HowTo/README.md) 6 | - latest documentation 7 | 8 | - [Unreal Engine 4 HTML5 Platform Documentation](Platforms/HTML5/HTML5.md) 9 | - older, but may have addtional information that might be useful 10 | 11 | * * * 12 | 13 | After **linking your [Epic Games Account](https://www.epicgames.com/account/connected) to your GitHub account**, 14 | you can find the HTML5 Platform Extenion repository [HERE](https://github.com/UnrealEngineHTML5/UnrealEngine/tree/4.24.3-html5-1.39.18/Engine/Platforms/HTML5). 15 | 16 | - NOTE: if you still see a `404 This is not the web page you are looking for` error 17 | - Double check you have linked your Epic Games and GitHub accounts [#12](https://github.com/UnrealEngineHTML5/Documentation/issues/12#issuecomment-597729773) 18 | - Double check you have accepted email confirmation link [#12](https://github.com/UnrealEngineHTML5/Documentation/issues/12#issuecomment-609103355) [#25](https://github.com/UnrealEngineHTML5/Documentation/issues/25#issuecomment-629591561) 19 | - Double check you are logged in to (the correct) GitHub (account) [#7](https://github.com/UnrealEngineHTML5/Documentation/issues/7#issuecomment-585855847) 20 | - You **MUST** be able to see [EpicGames/UnrealEngine](https://github.com/EpicGames/UnrealEngine) **before** you can see the HTML5 fork 21 | [#7](https://github.com/UnrealEngineHTML5/Documentation/issues/7#issuecomment-585850444) 22 | [#8](https://github.com/UnrealEngineHTML5/Documentation/issues/8#issuecomment-587092613) 23 | [#12](https://github.com/UnrealEngineHTML5/Documentation/issues/12#issuecomment-632891334) 24 | [#25](https://github.com/UnrealEngineHTML5/Documentation/issues/25#issuecomment-632911377) 25 | - You **MAY** Have to wait for a bit (usually less than 24 hours) before access is granted 26 | [#7](https://github.com/UnrealEngineHTML5/Documentation/issues/7#issuecomment-585872314) 27 | [#35](https://github.com/UnrealEngineHTML5/Documentation/issues/35#issuecomment-636389033) 28 | - Please see all [**Open and Closed** HTML5 404 issues](https://github.com/UnrealEngineHTML5/Documentation/labels/404) for more tips 29 | 30 | * * * 31 | 32 | --------------------------------------------------------------------------------