You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> We are making use of the `PublishAot` option. Using `Aot` has some restrictions which may require changes to your game code. Especially if you are using Reflection.
17
20
18
21
You can then zip the content of the publish folder and distribute the archive as-is.
19
22
20
23
If you are targeting WindowsDX, note that players will need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) to be installed on their machine for audio and gamepads to work properly.
We recommend that you distribute your game as an [application bundle](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html). Application bundles are directories with the following file structure:
32
28
33
29
```text
@@ -37,23 +33,41 @@ YourGame.app (this is your root folder)
37
33
- Content (this is where all your content and XNB's should go)
38
34
- YourGame.icns (this is your app icon, in ICNS format)
39
35
- MacOS
40
-
- amd64 (this is where your game executable for amd64 belongs, place files from the osx-x64/publish directory here)
41
-
- arm64 (this is where your game executable for arm64 belongs, place files from the osx-arm64/publish directory here)
42
-
- YourGame (the entry point script of your app, see bellow for contents)
43
-
- Info.plist (the metadata of your app, see bellow for contents)
36
+
- YourGame (the main executable for your game)
37
+
- Info.plist (the metadata of your app, see below for contents)
> We are making use of the `PublishAot` option. Using `Aot` has some restrictions which may require changes to your game code. Especially if you are using Reflection.
56
+
57
+
Next we need to combine the two binaries into one Universal Binary which will work on both arm64 and x64 machines.
The `Info.plist` file is a standard macOS file containing metadata about your game. Here is an example file with required and recommended values set:
@@ -101,45 +115,94 @@ The `Info.plist` file is a standard macOS file containing metadata about your ga
101
115
</plist>
102
116
```
103
117
104
-
For more information about Info.plist files, see the [documentation](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html).
118
+
> [!NOTE]
119
+
> For more information about `Info.plist` files, see the Apple [documentation](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html).
105
120
106
-
After completing these steps, your .app folder should appear as an executable application on macOS.
121
+
After completing these steps, your `.app` folder should appear as an executable application on macOS.
122
+
However it does need an icon. So we need to create an `.icns` file. We can use online tools to do this or you can use the following:
107
123
108
-
For archiving, we recommend using the .tar.gz format to preserve the execution permissions (you will likely run into permission issues if you use .zip at any point).
> This code is expecting an `Icon.png` file to be in the same directory. This file should be `1024` x `1024` pixels.
141
+
142
+
For archiving, we recommend using the `.tar.gz` format to preserve the execution permissions (you will likely run into permission issues if you use `.zip` at any point).
> We are making use of the `PublishAot` option. Using `Aot` has some restrictions which may require changes to your game code. Especially if you are using Reflection.
115
152
116
153
You can then archive the content of the publish folder and distribute the archive as-is.
117
154
118
-
We recommend using the .tar.gz archiving format to preserve the execution permissions.
155
+
We recommend using the `.tar.gz` archiving format to preserve the execution permissions.
119
156
120
157
---
121
158
122
159
## Special notes about .NET parameters
123
160
124
161
.NET proposes several parameters when publishing apps that may sound helpful, but have many issues when it comes to games (because they were never meant for games in the first place, but for small lightweight applications).
125
162
163
+
### PublishAot
164
+
165
+
This option optimises your game code "Ahead of Time". It allows you to ship your game without the need to JIT (Just In Time compile).
166
+
However, you do need to currently add some additional settings to your `.csproj`.
The `TrimmerRootAssembly` stops the trimmer removing code from these assemblies. This should allow the game to run without
176
+
any issues. However if you are using any Third Party or additional assemblies, you might need to add them to this list or fix your code to be `Aot` compliant.
177
+
It is recommended that you publish using AOT as it simplifies the app bundle.
178
+
179
+
See [Trim self-contained deployments and executables](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) for more information.
180
+
181
+
There are some known areas you need to watchout for:
182
+
183
+
1. Using `XmlSerializer` in your game will probably cause issues. Since it uses reflection it will be difficult for the Trimmer to figure out what needs to be kept.
184
+
It is recommended that, instead of using the `Deserialize` method, you write your own custom deserializer using `XDocument` or `XmlReader`.
185
+
Alternatively you can use the Content Pipeline and create a custom `Processor` and `Reader` to convert the Xml into a binary format that can be loaded via the usual `Content.Load<T>` method.
186
+
2. Dynamically loading assemblies via `Assembly.LoadFile`.
187
+
3. No run-time code generation, for example, System.Reflection.Emit.
188
+
126
189
### ReadyToRun (R2R)
127
190
128
-
[ReadyToRun](https://docs.microsoft.com/en-us/dotnet/core/whats-new/dotnet-core-3-0#readytorun-images) is advertised as improving application startup time, but slightly increasing binary size. We recommend not using it for games, because it produces micro stutters when your game is running.
191
+
[ReadyToRun](https://docs.microsoft.com/en-us/dotnet/core/whats-new/dotnet-core-3-0#readytorun-images) is advertised as improving application startup time, but slightly increasing binary size. We recommend not using it for games because it produces micro stutters when your game is running.
129
192
130
-
Ready2Run code is of low quality and makes the Just-In-Time compiler (JIT) to trigger regularly to promote the code to a higher quality. Whenever the JIT runs, it produces potentially very visible stutters.
193
+
ReadyToRun code is of low quality and makes the Just-In-Time compiler (JIT) trigger regularly to promote the code to a higher quality. Whenever the JIT runs, it produces potentially very visible stutters.
131
194
132
195
Disabling ReadyToRun solves this issue (at the cost of a slightly longer startup time, but typically very negligible).
133
196
134
-
ReadyToRun is disabled by default. You can configure it by setting the `PublishReadyToRun` property in your csproj file.
197
+
ReadyToRun is disabled by default. You can configure it by setting the `PublishReadyToRun` property in your `.csproj` file.
135
198
136
199
MonoGame templates for .NET projects explicitly set this to `false`.
137
200
138
201
### Tiered compilation
139
202
140
203
[Tiered compilation](https://docs.microsoft.com/en-us/dotnet/core/whats-new/dotnet-core-3-0#tiered-compilation) is a companion system to ReadyToRun and works on the same principle to enhance startup time. We suggest disabling it to avoid any stutter while your game is running.
141
204
142
-
Tiered compilation is **enabled by default**. To disable it set the `TieredCompilation` property to `false` in your csproj.
205
+
Tiered compilation is **enabled by default**. To disable it, set the `TieredCompilation` property to `false` in your `.csproj`.
143
206
MonoGame templates for .NET projects explicitly set this to `false`.
description: How to use the latest development NuGet packages to use the cutting edge of MonoGame development in your project.
4
+
---
5
+
6
+
## Overview
7
+
8
+
When the MonoGame develop branch builds, it publishes development NuGet packages to the MonoGame NuGet Feed on GitHub. If you want to test a new feature or just be on the very latest code you can use this Feed to do that.
9
+
10
+
## Adding a NuGet Source
11
+
12
+
1. Create a `NuGet.config` in the root or top level directory of your project.
13
+
14
+
> [!NOTE]
15
+
> NuGet will automatically walk up the directory tree to find `NuGet.config` files.
`Directory.Build.props` is an MSBuild file which will be imported by all projects in your game. It is like a file that contains global variables. In this case the version of MonoGame we want to use.
39
+
40
+
> [!NOTE]
41
+
> To find out the latest version number, you can look at one of the packages at [https://github.com/orgs/MonoGame/packages?repo_name=MonoGame](https://github.com/orgs/MonoGame/packages?repo_name=MonoGame). Or to get the information from the GitHub feed, you can run the following command.
If you try to build now you will get an error. This is because the NuGet feeds on GitHub are not public. You need to be a valid GitHub user to use them.
93
+
94
+
## Authentication
95
+
96
+
You need to create a **Personal Access Token** (PAT) on your GitHub account in order to use the NuGet feed. See the following documentation on how to create your PAT.
> You need to create a "PAT (Classic)" token in order for it to work with the Nuget feed. See [creating-a-personal-access-token-classic](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) for details.
102
+
103
+
Once you have your **PAT**, you can create a new `NuGet.config` file in the directory ABOVE your game project directory.
104
+
To be clear, this file should NOT be in your source tree. It should be outside of any directory which is under source control.
105
+
106
+
```cli
107
+
Projects
108
+
NuGet.config <-- THIS IS WHERE YOU PUT THE FILE.
109
+
MyGame
110
+
.git
111
+
Directory.Build.props
112
+
NuGet.config
113
+
MyGame.DesktopGL
114
+
MyGame.DesktopGL.csproj
115
+
116
+
```
117
+
118
+
> [!IMPORTANT]
119
+
> Do Not... **DO NOT** place a `NuGet.config` file with valid `packageSourceCredentials` in your source control.
120
+
121
+
The contents of the file are as follows, replace `%GITHUB_USER%` with your GitHub username and the `%GITHUB_TOKEN%` with your token.
The really good thing about placing these credentials outside of source control is that they are safe. But also any new projects you create under that folder can also make use of these credentials. So it is a good idea to keep them in one place.
136
+
137
+
> [!NOTE]
138
+
> For more information, you can read [consuming-packages-authenticated-feeds](https://learn.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds#credentials-in-nugetconfig-files).
0 commit comments