├── 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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
149 |
150 | - and **Solution Configuration** is set to **Development Editor**
151 |
152 | 
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 | 
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 | 
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 | 
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 | 
222 |
223 | - and then select:
224 | - **Menu -> Product -> Build For -> Running**
225 | - or `Command + Shift + R`
226 |
227 | 
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 | 
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 | 
328 |
329 | #### window #2
330 |
331 | - Menu bar -> Edit -> Project Settings ...
332 |
333 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 | 
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 |
--------------------------------------------------------------------------------