Construct can export your project as a Windows desktop app using Microsoft Edge WebView2. This is basically a copy of the Microsoft Edge browser engine that is built in to Windows. Note Microsoft Edge is based on the same Chromium browser engine as is used by Chrome. In other words it's very much like having your project run in Edge or Chrome, but without the user needing to have a specific browser installed on their computer, and without the browser parts showing like the address bar so it looks like a traditional desktop app. It's also a very lightweight export option with minimal file size overhead as it does not need to bundle a browser engine. This tutorial covers how to use this export option.
See also:
Exporting
When exporting, you can choose some options in the Windows Wrapper options dialog. This includes choosing which of the platform architectures you export for, which includes:
- 32-bit (x86): for Windows 32-bit on Intel-compatible systems
- 64-bit (x64): for Windows 64-bit on Intel-compatible systems
- ARM64: for Windows 64-bit on ARM-based systems
The Intel-compatible Windows 64-bit is the most common version of Windows, but you can support more systems by distributing all the platform-specific versions of the app.
Architecture naming
The names of the architecture may look odd, but they are the technical terms used in the software industry.
Although the x64 architecture is 64-bit, the x86 architecture is 32-bit, not 86-bit. The x86 name derives from the Intel 8086 microprocessor, which was actually originally 16-bit. However later chips were 32-bit and replaced the older 16-bit kinds. So "x86" is now widely used to refer to the 32-bit instruction set of Intel-compatible processors. See x86 on Wikipedia for more history.
Try not to confuse x64 with ARM64: both are 64-bit systems, but they are for different chip architectures (Intel-compatible and ARM respectively). ARM is used for some newer devices such as the Surface Pro X.
WebView2 features
Construct is based on browser technology, but WebView2 does not work exactly the same as a browser. Some of the differences of most interest are:
- Lightweight export option that does not need to include a copy of an entire browser engine, relying on the system instead
- WebView2 automatically updates, much like modern browsers, ensuring users get the best performance and latest features
- Permission requests, e.g. for the camera, are automatically approved without prompting the user.
- Some actions which are only allowed after a user input event, such as audio playback and entering fullscreen, can be used unrestricted
- Navigating to a URL, or opening a URL in a new window, will open the system default browser. This could be a different browser entirely, e.g. Firefox.
- The Browser 'Close' action exits the app
- Accessing the browser developer tools can be disabled
- You can use the File System plugin to directly access certain folders on disk - such as to read and write files directly to the user's Documents folder with the picker tag "<documents>". See the File System plugin manual entry for more details on that.
Updating the app icon
For technical reasons it's difficult for Construct to set the app icon from inside the browser. Instead a tool named WindowsIconUpdater.exe is exported with your files. All you need to do is extract all the files in the zip to a local folder, run WindowsIconUpdater.exe, and your executable icons should switch to use the ones in your Construct project.
Distribution
The exported app requires the Microsoft Edge WebView2 runtime to be installed. It's installed by default on Windows 11+. Microsoft announced in June 2022 that it would be installed by default on Windows 10 devices too. On Windows 10 and older, if it is not installed, the app will automatically download and install it, and then should start up successfully. This only needs to be done once per system, and then the WebView2 runtime automatically keeps itself up-to-date, like modern browsers do.
Advanced users can still include a full copy of a browser engine with the app if they choose to. This is referred to as "fixed" mode, whereas using the auto-updating system webview is referred to as "evergreen" mode. See the following section for more details.
If you can, you should also digitally sign your app. This will show that you are its verified publisher, and increases the trust the system has in your app. Without it, users may see warnings that the app is not verified or trusted, and some other security tools may treat it with enhanced caution.
Advanced topics
While the exported app ought to work straight away if distributed to users, these topics may be of interest to advanced users.
Customizing messages
When the user is prompted to install the WebView2 runtime, the app will show some messages, such as "This app requires the Microsoft Edge WebView2 runtime. It will be downloaded and installed for you now." You can customize these messages, such as to translate them, or explain in more detail what your app is doing. These messages can be edited in the "messages" section of the exported package.json file.
Digital signature
The exported app is not digitally signed. This means it may show a warning when run for the first time. Other security tools may also treat it with enhanced caution.
To improve the level of trust the system has in your app, and avoid users seeing such warnings, you should digitally sign the app. This requires obtaining a code-signing certificate and using a Windows tool to sign the app with your certificate. This is a somewhat complex topic out of the scope of this tutorial, but you can start at the Microsoft documentation's Introduction to code signing, which includes the SignTool for signing executables, and search the web for further resources.
Sample signtool command
Once you have obtained a code signing certificate, got signtool.exe from the Windows SDK, and updated the executable icon if you wish to change it, the following PowerShell command illustrates how to sign your app's executable if using a .PFX certificate with a password.
./signtool.exe sign /f "MyCodeSigningCertificate.pfx" /p CERTIFICATE_PASSWORD /fd SHA256 /t http://timestamp.digicert.com /d "My app description" /du https://www.example.com "MyAppExecutable.exe"
Note you should replace "MyCodeSigningCertificate.pfx" with the filename of your code signing certificate, CERTIFICATE_PASSWORD with the password for the given code signing certificate, "My app description" with your own description of your app, https://www.example.com with your own website URL, and "MyAppExecutable.exe" with your app's executable file.
Alternatively some services which provide a code signing certificate may use a different approach, such as a hardware USB key, and installing the certificate to your system. The following kind of command may be needed in this case.
./signtool.exe sign /n "MyCompany" /fd SHA256 /t http://timestamp.digicert.com /d "My app description" /du https://www.example.com "MyAppExecutable.exe"
Note you will need to replace "MyCompany" with the name of the certificate that was installed to your system, as well as the description and URL. When performing this command you may be prompted to enter a password, such as if a hardware USB key was used.
Verifying the digital signature
To check the digital signature has been added to the executable, right-click on the executable file in Windows Explorer and choose Properties. In the dialog that opens there should be a tab that says Digital signatures where you can see an entry in the signature list with your code signing certificate. If the executable is not digitally signed at all, then no Digital signatures tab will appear at all in the Properties dialog.
Creating an installer
If you create an installer for your app, you can also make the installer pre-install the Microsoft Edge WebView2 runtime, so the app will work immediately on the first run and not have to prompt the user to download and install the runtime.
You can find standalone installers for the WebView2 runtime at the Microsoft Edge WebView2 website. You can then configure your installer to also run the WebView2 standalone installer during installation.
Fixed distribution mode
We recommend using the "evergreen" distribution mode, which is the default. This uses a system-provided webview that automatically updates. However it's possible to also ship your own copy of the Microsoft Edge WebView2 runtime with the app (similar to how NW.js works). This substantially increases the file size and will not update the browser engine automatically, so your app will remain on the same version until you release an update with a newer version.
To use fixed distribution mode, follow these steps:
- Edit package.json and change the value by "distribution-mode" (under "settings") from
"evergreen" to "fixed".
- Create a subfolder in the same folder as your executable named
webview2.
- Visit the Microsoft Edge WebView2 website and download a fixed version of the WebView2 runtime (with a specific browser engine version). Make sure you match the same architecture as the app that was exported.
- Extract the downloaded fixed version to the "webview2" subfolder. In the documentation for fixed mode, Microsoft advise to use the command line
expand {path to the package} -F:* {path to the destination folder} or use a third-party tool such as WinRAR. They advise against decompressing through the File Explorer, as it may not generate the correct folder structure.
- Compatibility for Windows 10: as of Fixed version 120+, to support Windows 10 you must run additional commands to change the security configuration. This is not necessary for Windows 11+. The following commands need to be run, where
webview2 is the folder path to the fixed distribution files.
icacls webview2 /grant *S-1-15-2-2:(OI)(CI)(RX)
icacls webview2 /grant *S-1-15-2-1:(OI)(CI)(RX)
This may need to be done for every system that your app is distributed to, so you may need to make an installer and configure it to run these commands for you. For more details see the official Microsoft documentation here.
- Now run the app executable, and it should run successfully with the fixed version you downloaded.
Note in fixed mode, the app will never prompt the user to download and install the Microsoft Edge WebView2 runtime - it always uses the version in the "webview2" subfolder, and will fail to start up if there isn't a fixed version there.
Conclusion
The Windows wrapper export option provides a lightweight option for publishing to Windows, using an auto-updating system webview to power your game. It's a convenient option since it has a low file size and doesn't require setting up web hosting. Remember to distribute copies of your app for each system architecture (x86, x64 and ARM64), and advanced users should consider digitally signing the app.