godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7720 from Calinou/uwp-non-functional

Browse Source
This commit is contained in:
Max Hilbrunner
2023-07-25 02:05:30 +02:00
committed by Max Hilbrunner
parent 171cf070a9
commit ac12eb06f3
2 changed files with 10 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
contributing/development/compiling/compiling_for_uwp.rst
View File

@@ -3,152 +3,10 @@
Compiling for Universal Windows Platform
========================================
.. highlight:: shell
.. important::
.. seealso::
Compiling UWP export templates is not implemented in Godot 4.
Godot 3 has limited UWP support, but there are many
`known issues <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Auwp>`__.
This page describes how to compile UWP export template binaries from source.
If you're looking to export your project to UWP instead, read :ref:`doc_exporting_for_uwp`.
Requirements
------------
- `Python 3.6+ <https://www.python.org/downloads/windows/>`_.
**Make sure to enable the option to add Python to the ``PATH`` in the installer.**
- `SCons 3.0+ <https://scons.org/pages/download.html>`_ build system. Using the
latest release is recommended, especially for proper support of recent Visual
Studio releases.
- Windows 10 SDK (can be selected in Visual Studio installation).
- `ANGLE source <https://github.com/Microsoft/angle>`__. Use the
``ms_master`` (default) branch. Keep it in a path without spaces to
avoid problems.
.. note:: The ANGLE repo by Microsoft has been discontinued and the
``ms_master`` branch has been cleared out.
As a temporary workaround however, it is still possible to
download an older state of the source code via commit
`c61d048 <https://github.com/microsoft/angle/tree/c61d0488abd9663e0d4d2450db7345baa2c0dfb6>`__.
This page will eventually be updated in the future to reflect
the new build instructions.
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
Compiling
---------
You need to open a proper Visual Studio prompt for the target architecture
you want to build. Check :ref:`doc_compiling_for_windows` to see how these
prompts work.
There are three target architectures for UWP: x86 (32-bits), x64 (64-bits)
and ARM (32-bits). For the latter, you can run ``vcvarsall.bat`` with
``x86_arm`` or ``amd64_arm`` as argument to set the environment.
Set the ``ANGLE_SRC_PATH`` to the directory where you downloaded the ANGLE
source code. The build process will also build ANGLE to produce the
required DLLs for the selected architecture.
Once you're set, run the SCons command similarly to the other platforms::
C:\godot>scons platform=uwp
Creating UWP export templates
-----------------------------
To export using the editor you need to properly build package the templates.
You need all three architectures with ``debug`` and ``release`` templates to
be able to export.
Open the command prompt for one architecture and run SCons twice (once for
each target)::
C:\godot>scons platform=uwp target=template_debug
C:\godot>scons platform=uwp target=template_release
Repeat for the other architectures.
In the end your ``bin`` folder will have the ``.exe`` binaries with a name
like ``godot.uwp.opt.debug.32.x86.exe`` (with variations for each
target/arch).
Copy one of these to ``misc/dist/uwp_template`` inside the Godot source
folder and rename the binary to ``godot.uwp.exe``. From the ANGLE source,
under ``winrt/10/src/Release_%arch%`` (where ``%arch%`` can be ``Win32``,
``x64`` or ``ARM``), get the ``libEGL.dll`` and the ``libGLESv2.dll``,
putting them along with the executable.
Add the files in the ``uwp_template`` folder to a ZIP. Rename the resulting
Zip according to the target/architecture of the template::
uwp_x86_debug.zip
uwp_x86_release.zip
uwp_x64_debug.zip
uwp_x64_release.zip
uwp_arm_debug.zip
uwp_arm_release.zip
Move those templates to the ``[versionstring]\templates`` folder in Godot
settings path, where `versionstring` is the version of Godot you have compiled
the export templates for - e.g. `3.0.alpha` for the alpha version of Godot 3.
If you don't want to replace the templates, you can set the "Custom Package"
property in the export window.
Running UWP apps with Visual Studio
-----------------------------------
If you want to debug the UWP port or simply run your apps without packaging
and signing, you can deploy and launch them using Visual Studio. It might be
the easiest way if you are testing on a device such as a Windows Phone or an
Xbox One.
Within the ANGLE source folder, open ``templates`` and double-click the
``install.bat`` script file. This will install the Visual Studio project
templates for ANGLE apps.
If you have not built Godot yet, open the ``winrt/10/src/angle.sln`` solution
from the ANGLE source and build it to Release/Win32 target. You may also need
to build it for ARM if you plan to run on a device. You can also use MSBuild if
you're comfortable with the command line.
Create a new Windows App project using the "App for OpenGL ES
(Windows Universal)" project template, which can be found under the
``Visual C++/Windows/Universal`` category.
This is a base project with the ANGLE dependencies already set up. However, by
default it picks the debug version of the DLLs which usually have poor
performance. So in the "Binaries" filter, click in each of the DLLs there
and in the "Properties" window and change the relative path from
``Debug_Win32`` to ``Release_Win32`` (or ``Release_ARM`` for devices).
In the same "Binaries" filter, select "Add > Existing Item" and point to the
Godot executable for UWP you have. In the "Properties" window, set "Content"
to ``True`` so it's included in the project.
Right-click the ``Package.appxmanifest`` file and select "Open With... > XML
(Text) Editor". In the ``Package/Applications/Application`` element, replace
the ``Executable`` attribute from ``$targetnametoken$.exe`` to
``godot.uwp.exe`` (or whatever your Godot executable is called). Also change
the ``EntryPoint`` attribute to ``GodotUWP.App``. This will ensure that
the Godot executable is correctly called when the app starts.
Create a folder (*not* a filter) called ``game`` in your Visual Studio project
folder and there you can put either a ``data.pck`` file or your Godot project
files. After that, make sure to include it all with the "Add > Existing Item"
command and set their "Content" property to ``True`` so they're copied to the
app.
To ease the workflow, you can open the "Solution Properties" and in the
"Configuration" section untick the "Build" option for the app. You still have
to build it at least once to generate some needed files, you can do so by
right-clicking the project (*not* the solution) in the "Solution Explorer" and
selecting "Build".
Now you can just run the project and your app should open. You can also use
the "Start Without Debugging" option from the "Debug" menu (or press :kbd:`Ctrl + F5`) to make it
launch faster.
We recommend you use the :ref:`Win32 export <doc_exporting_for_windows>` instead.

121
tutorials/export/exporting_for_uwp.rst
View File

@@ -1,123 +1,12 @@
:article_outdated: True
.. _doc_exporting_for_uwp:
Exporting for Universal Windows Platform
========================================
.. seealso::
.. important::
This page describes how to export a Godot project to UWP.
If you're looking to compile export template binaries from source instead,
read :ref:`doc_compiling_for_uwp`.
Exporting projects to UWP is not implemented in Godot 4.
Godot 3 has limited UWP support, but there are many
`known issues <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Auwp>`__.
There's no extra requirement to export an ``.appx`` package that can be
installed as a Windows App or submitted to the Windows Store. Exporting UWP
packages also works from any platform, not only from Windows.
However, if you want to install and run the app, you need to sign it with a
trusted signature. Godot supports automatic signing of packages with
external tools.
Also, make sure the Publisher Name you set when exporting the package matches
the name used on the certificate.
Limitations on Xbox One
-----------------------
As described in the `UWP documentation <https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/system-resource-allocation>`__:
- Submitted as an "App"
- available memory is 1GB
- share of 2-4 CPU cores
- shared access of GPU power (45%)
- Submitted as a "Game" (through `Xbox Live Creators Program <https://www.xbox.com/en-US/developers/creators-program>`__)
- available memory is 5GB
- 4 exclusive CPU cores and 2 shared CPU cores
- exclusive access to GPU power (100%)
- Exceeding these memory limitations will cause allocation failures and the application will crash.
Creating a signing certificate
------------------------------
This requires the ``MakeCert.exe`` and ``Pvk2Pfx.exe`` tools, which come with
the Windows SDK. If you use Visual Studio, you can open one of its Developer
Prompts, since it comes with these tools and they can be located in the path.
You can get more detailed instructions from `Microsoft's documentation
<https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx>`__.
First, run ``MakeCert`` to create a private key::
MakeCert /n publisherName /r /h 0 /eku "1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13" /e expirationDate /sv MyKey.pvk MyKey.cer
Where ``publisherName`` matches the Publisher Name of your package and
``expirationDate`` is in the ``mm/dd/yyyy`` format.
Next, create a Personal Information Exchange (.pfx) file using ``Pvk2Pfx.exe``::
Pvk2Pfx /pvk MyKey.pvk /pi pvkPassword /spc MyKey.cer /pfx MyKey.pfx [/po pfxPassword]
If you don't specify a password with ``/po`` argument, the PFX will have the
same password as the private key.
You will also need to trust this certificate in order to be able to install your
app. Open the Command Prompt as Administrator and run the following command::
Certutil -addStore TrustedPeople MyKey.cer
Setting up automatic signing
----------------------------
To setup automatic signing on export you need to go to Editor Settings > Export > Uwp.
From there you need to click on the folder for ``Signtool``, and navigate to
the ``SignTool.exe`` file on your computer.
.. image:: img/UWP_sign_tool.png
After setting that up close the editor settings, go to Project > Export,
and select the UWP preset. Under the ``Signing`` options click on the folder
next to ``Certificate`` and go to the certificate file. Then enter the
pfxPassword in the password field.
.. image:: img/UWP_export_signing.png
Your project will now be automatically signed on export.
If you want to sign an exported app manually run ``SignTool.exe`` and use the
following command.
SignTool sign /fd SHA256 /a /f MyKey.pfx /p pfxPassword package.appx
Installing the package
----------------------
As of the Windows 10 Anniversary Update, you are able to install packages simply by
double clicking the ``.appx`` file from Windows Explorer.
It's also possible to install by using the ``Add-AppxPackage`` PowerShell cmdlet.
.. note:: If you want to update your already installed app, you must
update the version number on the new package or first uninstall
the previous package.
Environment variables
---------------------
You can use the following environment variables to set export options outside of
the editor. During the export process, these override the values that you set in
the export menu.
.. list-table:: UWP export environment variables
:header-rows: 1
* - Export option
- Environment variable
* - Encryption / Encryption Key
- GODOT_SCRIPT_ENCRYPTION_KEY
* - Options / Signing / Certificate
- GODOT_UWP_SIGNING_CERTIFICATE
* - Options / Signing / Password
- GODOT_UWP_SIGNING_PASSWORD
We recommend you use the :ref:`Win32 export <doc_exporting_for_windows>` instead.