Skip to content

Commit

Permalink
Remove Stadia docs, demote macOS to Appendix page, promote NativeAOT …
Browse files Browse the repository at this point in the history 
…to page A
  • Loading branch information
@flibitijibibo
flibitijibibo committed Dec 30, 2024
1 parent 6be8c50 commit e582fb2
Show file tree
Hide file tree
Showing 5 changed files with 26 additions and 203 deletions.
174 changes: 1 addition & 173 deletions docs/3:-Distributing-FNA-Games.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,6 @@ OS: glibc 2.28+, 64-bit only
Graphics (Minimum): OpenGL 3.0+ support (2.1 with ARB extensions acceptable)
Graphics (Recommended): Vulkan support
macOS:
OS: 10.9 Mavericks and newer
Graphics (Minimum): OpenGL 3.0+ support (2.1 with ARB extensions acceptable)
Graphics (Recommended): Metal support
Other: SDL_GameController devices fully supported
```

Expand Down Expand Up @@ -120,180 +115,13 @@ A good publicly-available example of this layout is the PC version of [I MAED A

***

### macOS
Download the latest version of MonoKickstart:

https://github.com/flibitijibibo/MonoKickstart

You only need the latest revision; it is actually _not_ recommended to download using Git, as the repository is mostly binary blobs, so the download time will be much longer.

In the precompiled/ folder you will notice the following:

* `kick.bin.osx`, `kick.bin.x86_64`, `monoconfig`, `monomachineconfig`
* For macOS, you care about all of these except `kick.bin.x86_64`
* Lots and lots of DLL files.
* If you don't know which ones you need, just use them all.

What follows is really convoluted and annoying, because that's the Apple Way:

You'll start by making a series of seemingly-arbitrary folders that will look something like this:

```
flibitGame.app/
Contents/
MacOS/
Resources/
```

Next, you will put `kick.bin.osx` into the `MacOS/` folder and rename it to the name of your main EXE. For example, for `flibitGame.exe` you will name it `flibitGame`, no extension. Next to that you will put the `osx/` folder (NOT ITS CONTENTS) from the [fnalibs.tar.bz2 package](1:-Setting-Up-FNA.md#step-2-download-native-libraries). The `vulkan/` folder from fnalibs.tar.bz2 will go in the `Resources/` folder. Any other native libraries you have will also go in the `osx/` folder (for example, if you're using Steamworks.NET, you would put libsteam_api.dylib in the `osx/` folder). Lastly, if you're shipping on Steam, you will put your `steam_appid.txt` file in `Resources/`.

So now your bundle should look like this:

```
flibitGame.app/
Contents/
MacOS/
flibitGame
osx/
Resources/
vulkan/
steam_appid.txt
```

Now, onto the `Resources/` folder. You will put `monoconfig`, `monomachineconfig`, and the DLL files into this folder.

Those DLL files, config files, and `kick.bin.osx` are actually a highly compacted Mono runtime that will be executing the C# assemblies, just as .NET would on Windows. The upside is, there are no system dependencies - the whole runtime is in this one folder, and all the native dependencies are in the lib folder. Convenient!

However, note that not every single DLL in the C# standard library exists in this folder. Libs like System.Web.Services are not provided by default to save disk space, but if you need these you can just grab these from any Mono runtime and we'll recognize it. These libs are typically found in the lib/mono/4.x/ folder (the precompiled folder uses 4.5).

Finally, you will put _your whole game_ into the `Resources/` folder. After that, the bundle should look like this:

```
flibitGame.app/
Contents/
MacOS/
flibitGame
osx/
steam_appid.txt
Resources/
vulkan/
monoconfig
monomachineconfig
mscorlib.dll, System.dll, blah blah
flibitGame.exe
Content/
etc...
```

At this point, we're now ready for the Mac-specific data. No, seriously, we haven't even gotten to that part yet.

First, you will need to put a `.icns` file in the `Resources/` folder. An icns file can be generated with any image using this website:

https://cloudconvert.com/png-to-icns

It is _strongly_ recommended that you use an image that is at least 512x512 in size. For certification, Apple actually requires a 4096x4096 image for your icon!

The very last file that will be made before your bundle is done is an `Info.plist` file, which will go in the `Contents/` folder. Here's an example Info.plist file:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>
<key>CFBundleExecutable</key>
<string>EscapeGoat2</string>
<key>CFBundleIconFile</key>
<string>EscapeGoat2</string>
<key>CFBundleIdentifier</key>
<string>com.magicaltimebean.Bastille2</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<string>Escape Goat 2</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<key>CFBundleSignature</key>
<string>GOAT</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>LSApplicationCategoryType</key>
<string>public.app-category.games</string>
<key>LSMinimumSystemVersion</key>
<string>10.9</string>
<key>NSHumanReadableCopyright</key>
<string>Copyright © 2014 MagicalTimeBean. All rights reserved.</string>
<key>NSPrincipalClass</key>
<string>NSApplication</string>
<key>NSHighResolutionCapable</key>
<string>True</string>
</dict>
</plist>
```

With that, the final look of the bundle:

```
flibitGame.app/
Contents/
Info.plist
MacOS/
flibitGame
osx/
Resources/
vulkan/
steam_appid.txt
monoconfig
monomachineconfig
mscorlib.dll, System.dll, blah blah
flibitGame.exe
flibitGame.icns
Content/
etc...
```

Once you've compiled all of this together, you should have a working app bundle! FINALLY! Place your app bundle and any other items you want to include with your game into a folder, then you are ready to upload via [SteamPipe](https://partner.steamgames.com/doc/sdk/uploading), [butler](https://itch.io/docs/butler/), or the [GOG Galaxy builder](https://docs.gog.com/bc-build-game/).

One extra note: If for some reason you want to codesign your app (**this is optional**), you will want to have this in an `entitlements.plist` file when signing:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.automation.apple-events</key>
<true/>
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<true/>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<key>com.apple.security.cs.disable-executable-page-protection</key>
<true/>
<key>com.apple.security.cs.disable-library-validation</key>
<true/>
<key>com.apple.security.device.usb</key>
<true/>
</dict>
</plist>
```

When signing for Steam, the first key should be `false`, otherwise it won't be able to detect when Steam is running.

### .NET Core

The above guide works for .NET Framework and Mono applications, but does not work with .NET 8. The publishing system for modern .NET has completely changed and is described below.

`dotnet publish -r <win-x64/linux-x64/osx-x64> -c Release --self-contained` will produce the executable package, but each platform has different requirements for where the fnalibs must be placed.
`dotnet publish -r <win-x64/linux-x64> -c Release --self-contained` will produce the executable package, but each platform has different requirements for where the fnalibs must be placed.

* **Windows:** Place the x64 fnalibs in the `publish` directory alongside your executable.
* **MacOS:** Place the osx fnalibs in the `publish` directory alongside your executable. Then use `install_name_tool -add_rpath @executable_path <your_app_executable_name>` to force the application to first look in the executable directory for the fnalibs, instead of `/usr/local/lib`.
* **Linux:** Place the lib64 fnalibs in the `publish` directory, in a sub-directory called `netcoredeps`.

#### Single-File Applications
Expand Down
8 changes: 1 addition & 7 deletions docs/appendix/Appendix-E:-NativeAOT-on-PC.md → docs/appendix/Appendix-A:-NativeAOT-on-PC.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Appendix E: NativeAOT on PC
# Appendix A: NativeAOT on PC

FNA now has support for [NativeAOT](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/), a new .NET toolchain which allows you to build your game into an ahead-of-time compiled native executable.

Expand Down Expand Up @@ -71,12 +71,6 @@ Finally, to actually link the fnalibs, follow these platform-specific instructio
* Grab the .lib files from SDL2, FNA3D, FAudio, and Theorafile and place them in your app's .csproj directory.
* Build the application.
* Copy the contents of `fnalibs/x64` into the generated output directory.
* **MacOS:**
* Build SDL2 from source or install the SDL2 development package from a package manager, then use it to build the other libraries from source.
* Copy the resulting \*.dylib files from SDL2, FNA3D, FAudio, and Theorafile into `/usr/local/lib`.
* Build the application.
* Copy the contents of `fnalibs/osx` into the generated output directory.
* Finally, to ensure your application uses the correct search path for SDL2, use `install_name_tool -change /usr/local/lib/libSDL2-2.0.0.dylib @rpath/libSDL2-2.0.0.dylib <my-app-name>`.
* **Linux:**
* NOTE: For maximum compatibility, we recommend you build using a distro with a low glibc version, like Rocky Linux 8.
* Build SDL2 from source or install the SDL2 development package from a package manager, then use it to build FNA3D, FAudio, and Theorafile from source.
Expand Down
6 changes: 5 additions & 1 deletion docs/appendix/Appendix-B:-FNA-on-Consoles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ For all console builds, you should make .NET 8 project files for your game - ins

While the runtimes require a console NDA, there are some things you can do to make your game more robust that just-so-happens to make console support easier, without access to any particular SDK. If you're familiar with consoles, none of these will be surprising:

### NativeAOT

All platforms use NativeAOT as the runtime. If you want a solid head-start, you should read Appendix A. Don't underestimate this step, especially if your game heavily depends on .NET's reflection features!

### Window Size Changes
Even if your window is not resizable, operating systems (including Windows!) may forcibly change the window size for a multitude of reasons, and so the graphics device will reset.

Expand Down Expand Up @@ -121,4 +125,4 @@ While there is no special code needed for Nintendo Switch support (100% of the p

FNA for PlayStation 4 and 5 is now in progress - the first draft of SDL-playstation was recently finished, with FNA3D support coming up next. FAudio and Theorafile are already working on PlayStation targets! For runtimes we are currently using NativeAOT, with Mono as our fallback plan.

If you are a licensee, please get in touch with [Ryan](mailto:[email protected]) for SDL access, then once you have access to that, let us know!
If you are a licensee, please get in touch with [Ryan](mailto:[email protected]) for SDL access, then once you have access to that, let us know!
22 changes: 19 additions & 3 deletions ...pendix/Appendix-A:-FNA-on-iOS-and-tvOS.md → ...dix/Appendix-C:-FNA-on-Apple-Platforms.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Appendix A: FNA on iOS and tvOS
# Appendix C: FNA on Apple Platforms

As of FNA 24.03, FNA supports deploying to iOS and tvOS via the .NET SDK. FNA does not have special branches or configurations for each platform; the public master branch of FNA and the configuration you're already used to is exactly what is used to ship for these targets. The platform code is contained entirely in SDL.
FNA supports deploying to macOS/iOS/tvOS via the .NET SDK. FNA does not have special branches or configurations for each platform; the public master branch of FNA and the configuration you're already used to is exactly what is used to ship for these targets. The platform code is contained entirely in SDL.

## Getting Started

This is the basic guide to getting your game running in iOS/tvOS. Once these steps are followed, your game should be able to boot on real hardware.
This is the basic guide to getting your game running on macOS/iOS/tvOS. Once these steps are followed, your game should be able to boot on real hardware.

### Prerequisites

Expand All @@ -24,6 +24,22 @@ sudo dotnet workload install tvos

The process of building all the fnalibs is normally very tedious, and everybody _loves_ how good Xcode is, so as an alternative to building each project by hand, we have a pair of [build scripts](https://github.com/TheSpydog/fnalibs-ios-builder) that automatically download and build all of the fnalibs at once. If you would like to see the process in detail, take a look at the script sources - they're human-readable!

### Creating/Publishing a macOS Project

A macOS project is essentially the same as any other .NET Core build; the difference is in the publishing process:

`dotnet publish -r <osx-x64> -c Release --self-contained` will produce the executable package. Place the osx version of your fnalibs in the `publish` directory alongside your executable. Then use `install_name_tool -add_rpath @executable_path <your_app_executable_name>` to force the application to first look in the executable directory for the fnalibs, instead of `/usr/local/lib`.

For NativeAOT, the directions in Appendix A largely apply here, with these added steps:

* Build SDL3 from source or install the SDL3 development package from a package manager, then use it to build the other libraries from source.
* Copy the resulting \*.dylib files from SDL3, FNA3D, FAudio, and Theorafile into `/usr/local/lib`.
* Build the application.
* Copy the contents of `fnalibs/osx` into the generated output directory.
* Finally, to ensure your application uses the correct search path for SDL3, use `install_name_tool -change /usr/local/lib/libSDL3.0.dylib @rpath/libSDL3.0.dylib <my-app-name>`.

That about covers macOS - iOS/tvOS are a whole different story:

### Creating an iOS Project

Creating a .NET iOS project is almost identical to the process of [creating a desktop .NET project](https://github.com/FNA-XNA/FNA/wiki/1%3A-Setting-Up-FNA#chapter-5-creating-new-projects).
Expand Down
19 changes: 0 additions & 19 deletions docs/appendix/Appendix-C:-FNA-on-Google-Stadia.md
View file

This file was deleted.

0 comments on commit e582fb2

Please sign in to comment.