Skip to content

Update dev-client-winrt.rst #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arves100 merged 4 commits into from
Aug 26, 2025
Merged

Update dev-client-winrt.rst #19

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b55f685
DRAFT: Update dev-client-winrt.rst
Seltraeh Jul 29, 2025
b95d9be
Update dev-client-winrt.rst
Seltraeh Aug 12, 2025
74e5248
Update dev-client-winrt.rst
Seltraeh Aug 12, 2025
21a8222
Update dev-client-winrt.rst
Seltraeh Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 126 additions & 115 deletions source/pages/Tutorial/dev-client-winrt.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,193 +1,204 @@
Setting Up a Development Game Client (Windows 8.1+)
=======================================================

Requirements
------------
.. _dev-client-winrt:

* Visual Studio or Visual Studio Build Tools installed on your system
* `Microsoft Visual C++ Runtime Package 12.0 for x86 <https://github.com/M1k3G0/Win10_LTSC_VP9_Installer/blob/master/Microsoft.VCLibs.120.00_12.0.21005.1_x86__8wekyb3d8bbwe.appx>`_
* A copy of the Brave Frontier package (APPX) for Windows (`Share Drive link <https://drive.google.com/file/d/1NB64gzQOe-QQx9fY0mkoZiCSfe3WlTYi/view?usp=sharing>`_)
* Developer Mode enabled on your system
* Development game server setup and running (see `Setting Up a Development Game Server <dev-server.html>`_)
.. role:: raw-html(raw)
:format: html

.. warning::

If Developer Mode is not installed or enabled in Windows, the proxy will not function, and you will not see the command prompt.
Setting Up a Development Game Client (Windows 8.1+)
====================================================

Cloning the Repository
----------------------
.. contents::
:local:

To clone the offline-proxy repository, run the following command:
Introduction
-------------

::
This tutorial guides you through setting up a development game client for Brave Frontier on Windows 8.1 and later, enabling offline play via a local proxy server. It assumes you have Visual Studio 2022 installed with the Desktop development with C++ workload and the Windows 10 SDK. The process involves cloning the repository, building the proxy, generating certificates, modifying the game client, and enabling loopback for local testing.

git clone --depth=1 https://github.com/decompfrontier/offline-proxy
.. note::
If you are brand new to development, follow the exact folder structure shown in this tutorial (e.g., creating a folder named BF under your user profile directory). This will make storage and following along easier. You are free to use any folder structure you are comfortable with, but adjust paths in commands accordingly.

Building the Proxy
------------------
Requirements
-------------

.. warning::
If Developer Mode is not installed or enabled in Windows, the proxy will not function, and you will not see the command prompt.

The client *only* supports 32-bit platforms. Ensure you use the MINGW32 (i686-w64-mingw32) toolchain.
- Windows 8.1 or later
- Visual Studio 2022 with Desktop development with C++ workload and Windows 10 SDK
- Microsoft Visual C++ Runtime Package 12.0 for x86 (from https://github.com/M1k3G0/Win10_LTSC_VP9_Installer/blob/master/Microsoft.VCLibs.120.00_12.0.21005.1_x86__8wekyb3d8bbwe.appx)
- Git for Windows
- Administrator privileges

Using CMake, configure the proxy with one of the following options:
Cloning the Repository
-----------------------

* For Visual Studio as your compiler: ``cmake --preset debug-vs``
* For MSYS/MinGW as your compiler: ``cmake --preset debug-mingw``
To clone the offline-proxy repository, open PowerShell and run the following command:

After compilation, navigate to your CMake build directory. Inside the ``bin`` folder, you should find a ``libcurl.dll`` file. Keep track of this file, as it will be required later in the tutorial.
.. code-block:: console

Generating UWP Development Certificates
---------------------------------------

.. warning::
cd $env:USERPROFILE\BF
git clone --depth=1 https://github.com/decompfrontier/offline-proxy
cd $env:USERPROFILE\BF\offline-proxy

It is recommended to remove these certificates when they are no longer needed to prevent them from compromising system trust.
.. note::
The `$env:USERPROFILE` variable automatically points to your user directory (e.g., `C:\Users\YourUsername`). Adjust the path if you use a different structure.

.. important::
Building the Proxy
-------------------

All commands in this section must be executed in PowerShell. Ensure you are using PowerShell, or the system will not recognize the required applications.
.. warning::
The client only supports 32-bit platforms. Ensure the build targets Win32.

.. note::
First, configure the project to generate the necessary solution file (`.sln`):

If you have previously generated a PFX certificate for deploying applications to the Windows Store or have already completed this section, skip ahead to the "Modifying Brave Frontier APPX" section.
.. code-block:: console

.. hint::
cmake --preset debug-vs

This section provides a simplified process adapted from `this MSDN page <https://learn.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing>`_.
This command uses the Visual Studio preset to set up the project for a Debug build, creating the `.sln` file. If you encounter issues (e.g., "CMakePresets.json not found"), ensure your Visual Studio environment is correctly installed, or proceed manually with `cmake -G "Visual Studio 17 2022" -A Win32`.

To install custom Windows Store apps, you must first generate a development certificate. Run the following command in PowerShell to create a certificate:
Build the proxy using the following steps:

::
.. code-block:: console

New-SelfSignedCertificate -Type Custom -Subject "CN=<Name>" -KeyUsage DigitalSignature -FriendlyName "Your friendly name goes here" -CertStoreLocation "Cert:\CurrentUser\My" -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}")
cmake --build . --config Debug

.. note::
If the build fails, open ``offline-proxy.sln`` in Visual Studio 2022, set the solution platform to Win32 and configuration to Debug, then build (F7 or, with an "Fn Lock" keyboard, ``Fn`` + ``F7``). After a successful build, locate ``libcurl.dll`` in ``$env:USERPROFILE\BF\offline-proxy\bin\libcurl.dll`` (or search the bin folder).

Replace ``<Name>`` with a name of your choice (e.g., "My BraveFrontier"). Write down this name, as it will be needed later.
Generating UWP Development Certificates
----------------------------------------

Take note of the certificate's **Thumbprint**, as it will be used to export the certificate. Then, run the following commands to export it:
Generate a development certificate to sign the modified client:

::
.. code-block:: powershell

$password = ConvertTo-SecureString -String "<Your Password>" -Force -AsPlainText
Export-PfxCertificate -cert "Cert:\CurrentUser\My\<Certificate Thumbprint>" -FilePath MyKey.pfx -Password $password
$certName = "MyBraveFrontier"
$friendlyName = "Brave Frontier Dev Cert"
New-SelfSignedCertificate -Type Custom -Subject "CN=$certName" -KeyUsage DigitalSignature -FriendlyName "$friendlyName" -CertStoreLocation "Cert:\CurrentUser\My" -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}")

.. note::
The output will show a Thumbprint (e.g., ``ABC123...``). Highlight the first line of the output (starting with "Thumbprint") with your mouse, right-click to copy, then paste it into the next command using right-click paste. Use arrow keys (up/down/left/right) to navigate and edit the ``$thumbprint`` variable. This is a basic CLI skill: right-click pastes copied text, and arrow keys move the cursor without needing the mouse.

- Replace ``<Your Password>`` with a strong password of your choosing.

- Replace ``<Certificate Thumbprint>`` with the Thumbprint from the previous step.
Export the certificate:

You should now have a ``MyKey.pfx`` file. Keep this file safe, as it will be used to sign the modified Brave Frontier client.
.. code-block:: powershell

Installing the Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~
$thumbprint = "ABC123..." # Paste and edit your Thumbprint here using right-click paste and arrow keys
$password = ConvertTo-SecureString -String "YourStrongPassword" -Force -AsPlainText # Change password
Export-PfxCertificate -cert "Cert:\CurrentUser\My\$thumbprint" -FilePath $env:USERPROFILE\BF\MyKey.pfx -Password $password

1. Open the ``MyKey.pfx`` file to launch the Certificate Import Wizard.
2. Select ``Local Machine`` and proceed.
3. When prompted for the certificate store, choose ``Place all certificates in the following store``.
4. Browse and select ``Trusted Root Certification Authorities``.
5. Click ``Finish``, then confirm with ``Yes`` when prompted.
Install the certificate:

.. image::
../../images/dev-client-winrt/certpath_win.png
#. Double-click ``$env:USERPROFILE\BF\MyKey.pfx`` to launch the Certificate Import Wizard.
#. Select ``Local Machine`` and proceed.
#. Choose ``Trusted Root Certification Authorities`` as the store.
#. Click ``Finish``, then confirm with ``Yes``.

Modifying Brave Frontier APPX
-----------------------------
.. warning::
Remove these certificates when you are done with Brave Frontier development to prevent compromising system trust. Removing the certificate after installing the patched BraveFrontier APPX is a safety step and will prevent launching the patched APPX if it relies on ongoing verification.

.. important::
All commands must be executed in PowerShell with administrator privileges.

All commands in this section must be executed in a Developer Command Prompt for Visual Studio. Ensure you use this environment, or the required tools will not be recognized.

To unpack the game client, run the following command:
Obtaining the APPX File
------------------------

::
Download the unmodified Brave Frontier APPX file from the provided link:

makeappx unpack /p gumi.BraveFrontier_2.19.6.0_x86__tdae4wqex79w6.appx /d BraveFrontierAppxClient
- URL: https://drive.google.com/file/d/1NB64gzQOe-QQx9fY0mkoZiCSfe3WlTYi/view?usp=sharing
- Save as: ``$env:USERPROFILE\BF\BraveFrontier_2.19.6.0_x86.appx`` (right-click link > Save As).

A new folder named ``BraveFrontierAppxClient`` will be created, containing the extracted game client files for modification.

1. Copy the ``libcurl.dll`` file from the "`Building the Proxy <https://github.com/decompfrontier/offline-proxy>`_" section and place it in the root of the ``BraveFrontierAppxClient`` directory. When prompted to replace the original file, select ``Yes``.
2. Delete the following files from the ``BraveFrontierAppxClient`` directory:
.. note::
Verify the file size (~100MB) to ensure integrity. This file is not publicly hosted elsewhere; direct downloads are rare and often risky (e.g., APKs from APKPure/BlueStacks). If issues arise, extract from an installed app: ``Get-AppxPackage *BraveFrontier* | Export-AppxPackage -Path $env:USERPROFILE\BF\BraveFrontier.appx``.

- ``AppxMetadata``
Modifying Brave Frontier APPX
------------------------------

- ``AppxSignature.p7x``
Unpack and modify the APPX file using Developer PowerShell for Visual Studio 2022:

- ``AppxBlockMap.xml``
.. code-block:: console

- ``ApplicationInsights.config``
makeappx unpack /p $env:USERPROFILE\BF\BraveFrontier_2.19.6.0_x86.appx /d $env:USERPROFILE\BF\BraveFrontierAppxClient

3. Open ``AppxManifest.xml`` in a text editor (e.g., Notepad++) and locate this line:
.. note::
Launch "Developer PowerShell for Visual Studio 2022" from the Start menu to ensure SDK access.

::
Copy the proxy library:

<Identity Name="gumi.BraveFrontier" Publisher="CN=5AA816A3-ED94-4AA2-A2B4-3ADDA1FABFB6" Version="2.19.6.0" ProcessorArchitecture="x86" />
.. code-block:: console

Replace ``CN=5AA816A3-ED94-4AA2-A2B4-3ADDA1FABFB6`` with ``CN=<Name>``, where ``<Name>`` matches the name used during certificate generation (e.g., "My BraveFrontier"). This ensures the application installs correctly.
Copy-Item $env:USERPROFILE\BF\offline-proxy\bin\libcurl.dll $env:USERPROFILE\BF\BraveFrontierAppxClient -Force

4. (Optional) Modify the ``Properties`` tag to customize the app’s display details, such as:
Delete unnecessary files:

::
.. code-block:: console

<Properties>
<DisplayName>Brave Frontier</DisplayName>
<PublisherDisplayName>株式会社gumi</PublisherDisplayName>
<Logo>Assets\StoreLogo.png</Logo>
</Properties>
Remove-Item $env:USERPROFILE\BF\BraveFrontierAppxClient\AppxMetadata -Recurse -Force
Remove-Item $env:USERPROFILE\BF\BraveFrontierAppxClient\AppxSignature.p7x, $env:USERPROFILE\BF\BraveFrontierAppxClient\AppxBlockMap.xml, $env:USERPROFILE\BF\BraveFrontierAppxClient\ApplicationInsights.config -Force

5. (Optional) To change the app’s name in the Windows Start menu, edit this tag:
Edit the manifest:

::
#. Open ``$env:USERPROFILE\BF\BraveFrontierAppxClient\AppxManifest.xml`` in Notepad++.
#. Locate the line: ``<Identity Name="gumi.BraveFrontier" Publisher="CN=5AA816A3-ED94-4AA2-A2B4-3ADDA1FABFB6" ... />``.
#. Replace the Publisher CN with ``CN=MyBraveFrontier``.
#. (Optional) Update ``DisplayName`` to "Brave Frontier Offline" under ``<Properties>``.
#. Save and close.

<m2:VisualElements DisplayName="Brave Frontier"
.. important::
All commands must be executed in Developer PowerShell for Visual Studio 2022.

6. Save and close the file.
Packing and Signing the Modified Client
-----------------------------------------

Next, pack and sign the modified client with these commands:
Pack and sign the modified APPX in Developer PowerShell for Visual Studio 2022:

::
.. code-block:: console

makeappx pack /d BraveFrontierAppxClient /p BraveFrontierPatched.appx
SignTool sign /a /v /fd SHA256 /f MyKey.pfx /p "<Your Password>" BraveFrontierPatched.appx
makeappx pack /d $env:USERPROFILE\BF\BraveFrontierAppxClient /p $env:USERPROFILE\BF\BraveFrontierPatched.appx
SignTool sign /a /v /fd SHA256 /f $env:USERPROFILE\BF\MyKey.pfx /p "YourStrongPassword" $env:USERPROFILE\BF\BraveFrontierPatched.appx

.. note::

Replace ``<Your Password>`` with the password used when exporting the certificate.
Ensure the password matches the one used during certificate export.

Running the Game
----------------
-----------------

Install the newly generated ``BraveFrontierPatched.appx`` file and launch the client. If all steps were followed correctly, a console window should appear alongside the game client, as shown below:
Install the patched client:

.. image::
../../images/dev-client-winrt/bf_appx_patched.png
.. code-block:: powershell

.. warning::
Add-AppxPackage $env:USERPROFILE\BF\BraveFrontierPatched.appx

If no console appears, check the following:

- Ensure the patched ``libcurl.dll`` was correctly installed.
Enable loopback for local server communication:

- Verify you did not use the ``deploy`` preset, as it is not supported in this build.
#. Download the Enable Loopback Utility: https://telerik-fiddler.s3.amazonaws.com/fiddler/addons/enableloopbackutility.exe
#. Run the utility and select "Brave Frontier".
#. Check "Enable loopback" and click "Save Changes".
#. If an error occurs, enable Device Portal in Settings > Update & Security > For developers and disable "Restrict to loopback connections only".

- Confirm Developer Mode is enabled on your Windows PC.
.. image:: ../../images/dev-client-winrt/loopback_win.png
:alt: Loopback Utility Configuration

Connecting to the Server
~~~~~~~~~~~~~~~~~~~~~~~~
Launch the game by searching "Brave Frontier" in the Start menu. A console window should appear alongside the client.

Due to a default limitation in UWP apps, they cannot communicate with localhost, preventing the game from connecting to the server. To resolve this:
.. image:: ../../images/dev-client-winrt/bf_appx_patched.png
:alt: Running the Patched Game Client

1. Download the `Enable Loopback Utility <https://telerik-fiddler.s3.amazonaws.com/fiddler/addons/enableloopbackutility.exe>`_.
2. Run the utility and select the Brave Frontier application.
3. Configure it as shown below, then click ``Save Changes`` and restart the game:
.. warning::
If no console appears, verify the following:

- The patched ``libcurl.dll`` was correctly installed.
- Developer Mode is enabled on your Windows PC.

.. note::
Connecting to the Server
--------------------------

If Loopback Utility reports an error while saving changes, ensure Device Portal is enabled, and the ``Restrict to loopback connections only`` option is disabled under Developer settings.
Run the standalone server (e.g., ``standalone_frontend.exe`` from prior server automation) on ``127.0.0.1:9960``. With the loopback utility configured, the game should connect to the local server and display the login screen.

.. image::
../../images/dev-client-winrt/loopback_win.png
Troubleshooting
----------------

If the game server is running, you should now see the Brave Frontier login screen upon launching the game.
- **Build Fails**: Ensure Visual Studio 2022 C++ workload is installed. Rebuild in VS if needed.
- **Unpack Error**: Verify the APPX path and Developer PowerShell for Visual Studio 2022 usage.
- **Signing Error**: Check certificate installation and password.
- **No Console**: Confirm DLL replacement and Developer Mode.