diff --git a/articles/tutorials/advanced/MobileDeployment/01_getting_started/index.md b/articles/tutorials/advanced/MobileDeployment/01_getting_started/index.md new file mode 100644 index 00000000..bf0ae67c --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/01_getting_started/index.md @@ -0,0 +1,73 @@ +--- +title: "Chapter 01: Setting Up MonoGame for Android and iOS Development" +description: "Get started with MonoGame mobile development by setting up your development environment, tools, and SDKs for Android and iOS platforms." +--- + +# Getting Started and Overview + +This tutorial extends the [Dungeon Slime](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d) tutorial to mobile platforms. If you have not completed the desktop tutorial yet, we recommend finishing it first as we will be building directly on that foundation. + +## What You Will Learn + +By the end of this mobile tutorial series, you will have: +- Ported the **Dungeon Slime** game to run on Android and iOS +- Implemented touch controls to replace mouse and keyboard input +- Set up cross-platform project architecture for code sharing +- Learned debugging techniques for mobile development +- Published your game to both Google Play and the App Store +- Created automated deployment workflows + +# Development Requirements + +## Android Development + +**Platform Support:** Android development can be accomplished on either Windows PC or Mac. + +> [!NOTE] +> ARM64 variants of Windows do not run the Android simulator very well. +> + +**Required Tools:** +- **Android Device Manager** - Used to set up simulators (accessible through Visual Studio) +- **Android SDK Manager** - Used to install the SDK platforms + +These tools are available by installing the Android Workload using the [MonoGame Getting Started Instructions](../../../../getting_started/platforms.md). + +**Additional Notes:** For Windows users, ensure **Hyper-V** is enabled for better emulator performance. On Mac, Android Studio can be used alongside Rider for advanced emulator configurations. + +For more information visit about getting started with Android development: + +- [Getting Started with Android Development](https://learn.microsoft.com/en-us/dotnet/android/getting-started/installation/) +- [Getting Started with Maui Development](https://learn.microsoft.com/en-us/dotnet/maui/get-started/installation) + +To release your game to the **Google Play Store**, you will need to sign up for a developer account at [Google Play Signup](https://play.google.com/console/signup). You will need to accept the Developer Distribution Agreement and pay a registration fee. + +More information about the registration process can be found here [Registration process](https://support.google.com/googleplay/android-developer/answer/6112435). + +## iOS Development + +**Platform Requirement:** For iOS development you will require a Mac, whether you develop entirely on one or use the **Pair to Mac** option with Windows Visual Studio. + +Since **Visual Studio for Mac** has been deprecated, [JetBrains Rider](https://www.jetbrains.com/rider/) or [VS Code](https://code.visualstudio.com/) can be used to develop for iOS. There is a non-commercial licence available of Rider. + +For information about Pairing between Visual Studio and Mac, learn more [here](https://learn.microsoft.com/en-us/dotnet/maui/ios/pair-to-mac). + +**Additional Requirements:** +- **Xcode** - Required for iOS development and deployment +- **Apple Developer Account** - Required for physical device deployment and App Store publishing ([enrollment link](https://developer.apple.com/programs/enroll/)) + +# Modern .NET Project Features + +This tutorial utilizes modern .NET project management features to streamline cross-platform development: + +## Central Package Management + +We will be using [Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management) to maintain consistent package versions across all platform projects. This ensures your shared code library and platform-specific projects use identical dependency versions. + +## SLNX Solution Format + +The sample projects use the new [SLNX solution format](https://devblogs.microsoft.com/dotnet/introducing-slnx-support-dotnet-cli/) for improved cross-platform development experience and better integration with modern .NET tooling. + +# Next Steps + +In the next chapter, we will convert the existing Windows-only Dungeon Slime game project to support iOS and Android platforms. diff --git a/articles/tutorials/advanced/MobileDeployment/02_crossplatform/images/crossplatform_projects.png b/articles/tutorials/advanced/MobileDeployment/02_crossplatform/images/crossplatform_projects.png new file mode 100644 index 00000000..494b6114 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/02_crossplatform/images/crossplatform_projects.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/02_crossplatform/index.md b/articles/tutorials/advanced/MobileDeployment/02_crossplatform/index.md new file mode 100644 index 00000000..f3053fca --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/02_crossplatform/index.md @@ -0,0 +1,101 @@ +--- +title: "Chapter 02: Setting Up Cross-Platform Projects" +description: "Learn how to convert a Windows-only MonoGame project to support iOS and Android platforms, creating a unified codebase for multi-platform deployment." +--- + +# What You Will Learn + +In this chapter you will: +- Convert a Windows-only MonoGame project to support multiple platforms +- Understand the project structure for multi-platform games +- Set up shared code architecture for cross-platform development + +# Prerequisites + +- **For iOS Development:** + - An App Store Developer Account + - **Certificates** and **Provisioning Profiles** configured and installed. + - **Mac 15.x (Sequoia) with Xcode 16 installed** - installed through the App Store. +- **For Android Development:** + - Android SDK and tools installed - through the Visual Studio Installer or through Jetbrains Rider. + +# Converting the Dungeon Slime Project + +The Dungeon Slime game from the 2D tutorial serves as our practical example for cross-platform conversion. This approach can be applied to any MonoGame project you want to deploy across multiple platforms. + +The key principle is **code sharing** of the game logic between all platform variants - we will extract the game logic into a common library that all platform-specific projects can refer to and use. + +# Cross-Platform Project Structure + +When converted to support multiple platforms, your solution structure will look like this, as shown in the following figure. + +| ![Figure 2-1: Cross Platform Projects](images/crossplatform_projects.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 2-1: Cross Platform Projects** | + +This architecture separates concerns cleanly: +- **Shared game logic** in a common library +- **Platform-specific shells** that handle deployment and platform requirements +- **Consistent naming** for easy project management + +## DungeonSlime.Common - The Shared Library + +The common project contains all your game logic and uses multi-targeting to support different platforms: + +```xml +net8.0;net8.0-ios;net8.0-android +``` + +## Platform-Specific Package References + +Each target framework pulls in the appropriate MonoGame package: + +For **iOS**: +```xml + + + +``` + +For **Android**: + +```xml + + + +``` + +For **Windows**: + +```xml + + + +``` + +## Platform-Specific Projects + +The individual platform projects become lightweight shells that: + +- Reference the _common_ library +- Handle platform-specific initialization +- Manage deployment settings and assets +- Contain minimal platform-specific code + +## Project Structure + +- **DungeonSlime.Windows** - Windows desktop version +- **DungeonSlime.Android** - Android mobile version +- **DungeonSlime.iOS** - iOS mobile version + +The platform projects no longer contain the main Game class - this has been moved to the common library for sharing. + +## Third-Party Library Considerations + +When using external libraries like **Gum**, ensure they support cross-platform development: + +[https://github.com/vchelaru/Gum](https://github.com/vchelaru/Gum) + +```xml + +``` diff --git a/articles/tutorials/advanced/MobileDeployment/03_touch/index.md b/articles/tutorials/advanced/MobileDeployment/03_touch/index.md new file mode 100644 index 00000000..9c8e3c58 --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/03_touch/index.md @@ -0,0 +1,207 @@ +--- +title: "Chapter 03: Touch Gesture Handling" +description: "Learn the fundamentals of touch gesture recognition in MonoGame - registration, detection, and processing." +--- + +Before proceeding with the cross-platform conversion, let us review how to handle touch input in MonoGame. The concepts discussed here apply to any MonoGame project. For our Dungeon Slime demo, touch input is managed by the Gum library, but understanding the fundamentals is still important. + +## Gesture Registration + +Before your application can respond to touch input, you must explicitly register for the gesture types you want to detect. + +This is done during initialization: + +```csharp +protected override void Initialize() +{ + TouchPanel.DisplayWidth = GraphicsDevice.PresentationParameters.BackBufferWidth; + + TouchPanel.DisplayHeight = GraphicsDevice.PresentationParameters.BackBufferHeight; + + TouchPanel.EnabledGestures = GestureType.Tap | + GestureType.DoubleTap | + GestureType.Hold | + GestureType.Flick | + GestureType.FreeDrag | + GestureType.HorizontalDrag | + GestureType.VerticalDrag | + GestureType.Pinch | + GestureType.DragComplete | + GestureType.PinchComplete; + + base.Initialize(); +} +``` + +### Available Gesture Types + +| Gesture Type | Description | Common Use Cases | +|--------------|-------------|------------------| +| `Tap` | Quick touch and release | Button presses, object selection | +| `DoubleTap` | Two quick taps in succession | Zoom to fit, special actions | +| `Hold` | Touch and hold for extended time | Context menus, charged actions | +| `Flick` | Quick swipe motion | Throwing objects, page navigation | +| `FreeDrag` | Continuous dragging motion | Moving objects, drawing | +| `HorizontalDrag` | Dragging constrained to horizontal | Sliders, horizontal scrolling | +| `VerticalDrag` | Dragging constrained to vertical | Vertical scrolling, pull-to-refresh | +| `Pinch` | Two-finger pinch/spread motion | Zoom in/out, scaling | +| `DragComplete` | End of any drag operation | Finalize object placement | +| `PinchComplete` | End of pinch operation | Finalize zoom level | + +> [!NOTE] +> Only register for gestures you actually need. Each enabled gesture type has a small performance cost. + +## Gesture Detection Loop + +Touch gestures are processed using a polling approach in your `Update` method. Use `TouchPanel.IsGestureAvailable` to check if gestures are waiting to be processed: + +```csharp +protected override void Update(GameTime gameTime) +{ + // Process all available gestures each frame + while (TouchPanel.IsGestureAvailable) + { + GestureSample gesture = TouchPanel.ReadGesture(); + ProcessGesture(gesture); + } + + base.Update(gameTime); +} +``` + +### Why Use a Loop? + +Multiple gestures can occur between frames, especially during complex touch interactions. The `while` loop ensures you process all queued gestures rather than missing any: + +- **Single `if` statement** - Might miss gestures if multiple occur +- **`while` loop** - Processes all queued gestures until none remain + +## Reading and Processing Gestures + +Each gesture is read using `TouchPanel.ReadGesture()`, which returns a `GestureSample` containing the gesture details: + +```csharp +void ProcessGesture(GestureSample gesture) +{ + switch (gesture.GestureType) + { + case GestureType.Tap: + HandleTap(gesture.Position); + break; + + case GestureType.Flick: + HandleFlick(gesture.Position, gesture.Delta); + break; + + case GestureType.Pinch: + HandlePinch(gesture.Position, gesture.Position2); + break; + + // Handle other gesture types... + } +} +``` + +### GestureSample Properties + +Each `GestureSample` provides different data depending on the gesture type: + +- **`GestureType`** - The type of gesture detected +- **`Position`** - Primary touch point location (screen coordinates) +- **`Position2`** - Secondary touch point (used for pinch gestures) +- **`Delta`** - Movement vector for drag and flick gestures +- **`Timestamp`** - When the gesture occurred + +### Example: Processing Different Gesture Data + +```csharp +switch (gesture.GestureType) +{ + case GestureType.Tap: + // Use: Position + Vector2 tapLocation = gesture.Position; + break; + + case GestureType.Flick: + // Use: Position (start), Delta (direction/speed) + Vector2 flickStart = gesture.Position; + Vector2 flickDirection = gesture.Delta; + break; + + case GestureType.Pinch: + // Use: Position (finger 1), Position2 (finger 2) + Vector2 finger1 = gesture.Position; + Vector2 finger2 = gesture.Position2; + break; +} +``` + +## Complete Example + +Here is a minimal working example demonstrating all three concepts: + +```csharp +public class TouchGame : Game +{ + protected override void Initialize() + { + // 1. Register for gestures + TouchPanel.EnabledGestures = GestureType.Tap | GestureType.Flick; + base.Initialize(); + } + + protected override void Update(GameTime gameTime) + { + // 2. Check for available gestures + while (TouchPanel.IsGestureAvailable) + { + // 3. Read and process each gesture + GestureSample gesture = TouchPanel.ReadGesture(); + + switch (gesture.GestureType) + { + case GestureType.Tap: + Console.WriteLine($"Tap at {gesture.Position}"); + break; + + case GestureType.Flick: + Console.WriteLine($"Flick from {gesture.Position} with delta {gesture.Delta}"); + break; + } + } + + base.Update(gameTime); + } +} +``` + +## Dungeon Slime Sample + +In the _DungeonSlime_ game, touch input is encapsulated in a new **TouchInfo** class, which internally uses the **TouchPanel** API to detect and process gestures. + +This class abstracts gesture handling and exposes methods like `IsTouchSwipeUp()`, `IsTouchSwipeDown()`, etc., making it easy to check for swipe actions. + +The **TouchInfo** class is then integrated into the **GameController** class, allowing the game logic to respond to touch gestures in a platform-agnostic way. This modular approach keeps input handling clean and maintainable, and ensures that touch support works seamlessly alongside keyboard and gamepad input. + +### Extending Move Functions with Touch Gestures + +To support touch input alongside keyboard and gamepad, extend your movement functions to include checks for swipe gestures. + +For example: + +```csharp +public static bool MoveUp() +{ + return s_keyboard.WasKeyJustPressed(Keys.Up) || + s_keyboard.WasKeyJustPressed(Keys.W) || + s_gamePad.WasButtonJustPressed(Buttons.DPadUp) || + s_gamePad.WasButtonJustPressed(Buttons.LeftThumbstickUp) || + IsTouchSwipeUp(); <=== extended to support touch +} +``` + +This approach ensures your game responds to swipe gestures for movement, providing a consistent experience across touch, keyboard, and gamepad input. + +## Conclusion + +This foundation enables you to respond to touch input across iOS and Android platforms using MonoGame's cross-platform gesture system. diff --git a/articles/tutorials/advanced/MobileDeployment/04_publishing/index.md b/articles/tutorials/advanced/MobileDeployment/04_publishing/index.md new file mode 100644 index 00000000..b85a8810 --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/04_publishing/index.md @@ -0,0 +1,50 @@ +--- +title: "Chapter 04: Publishing to iOS App Store and Google Play Store" +description: "Learn how to publish your MonoGame mobile application to both the iOS App Store and Google Play Store with step-by-step guidance and real-world insights." +--- + +# Starting Publishing + +Before publishing your game to an app store, you need to sign up to the Apple Developer Program or Google Play. + +There is a fee for both of these stores to allow you to publish your game. + +As part of the publishing process, a **bundle identifier** is a unique string, that distinctly identifies a mobile game or app across iOS and Android ecosystems for deployment. + +## Understanding the Bundle Identifier + +The **bundle identifier** is a unique string that identifies your app. It follows a reverse domain name notation, such as `com.companyname.gamename`. + +This identifier is used by Apple and Google to distinguish your app from all others on the stores and on devices. + +- It **must** be unique across all apps and games in the store. + +- The bundle identifier you set in your game project must exactly match the one registered in the stores. + +- Changing the bundle identifier after publishing will create a new app entry, not update the existing app, so carefully choose it. + +**Tip:** Choose a bundle identifier that reflects your organization and app name, and keep it consistent across your project files and provisioning profiles. + +## Why App Signing is Essential + +Signing your app is a mandatory security measure for both the iOS App Store and the Google Play Store. It serves three primary purposes: *authenticity*, *integrity*, and *updates*. + +### Authenticity: Proving It's You + +Signing your app with your private developer key is how you prove that the app came from you and not an imposter. When a user downloads your game, their device checks this digital signature to verify its origin. This builds trust and protects your users from malicious actors distributing fake or harmful versions of your app. + +### Integrity: Ensuring the Code is Unchanged + +The digital signature guarantees that the code has not been altered or corrupted since you signed it. If even a single bit of the application is changed after signing (for example, by a hacker injecting malware), the signature will become invalid. The operating system (iOS or Android) will then refuse to install or run the app, protecting the user's device and data. + +### Updates: Authorizing Future Versions + +The app stores use the signature to verify that updates for your game are coming from the original developer. Only an update signed with the same private key as the original app will be accepted by the store and installed on users' devices. This prevents other developers from hijacking your app by releasing an unauthorised update. This is why it is crucial to keep your signing keys safe! + +## How It Works on Each Platform + +While the core concept is the same, the implementation differs slightly between Apple and Google. + +**iOS App Store**: Apple uses a system involving a Certificate, an App ID (which includes your bundle identifier), and a Provisioning Profile. These components work together to sign your app, ensuring it can be installed on specific devices for testing and submitted to the App Store for public release. The certificate is linked to your Apple Developer account. + +**Google Play Store**: Android uses a keystore, which is a file containing one or more private keys. You use this keystore to sign your app bundle. Google Play also offers a service called "Play App Signing," where Google manages your app signing key for you, adding an extra layer of security. diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive.png new file mode 100644 index 00000000..1a7d8607 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_distribute.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_distribute.png new file mode 100644 index 00000000..30c0c509 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_distribute.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_signing.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_signing.png new file mode 100644 index 00000000..28e0dff4 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_archive_signing.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_import_keystore.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_import_keystore.png new file mode 100644 index 00000000..279791b9 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_import_keystore.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_package_name.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_package_name.png new file mode 100644 index 00000000..82450b98 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_package_name.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_release.png b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_release.png new file mode 100644 index 00000000..2a2da6f3 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/images/android/android_release.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/05_publishing_android/index.md b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/index.md new file mode 100644 index 00000000..041fb30c --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/05_publishing_android/index.md @@ -0,0 +1,141 @@ +--- +title: "Chapter 05: Publishing to Google Play Store" +description: "Learn how to publish your MonoGame mobile application to the Google Play Store with step-by-step guidance." +--- + +# Publishing Overview + +This chapter covers the complete publishing process for both major mobile app stores. You will learn the requirements and workflows for getting your MonoGame app successfully published on Android platforms. + +# Google Play Store Publishing + +## Creating Your Developer Account + +**Register at** [play.google.com/console](https://play.google.com/console) + +## Pre-Publishing Preparation + +Ensure your Android project is properly configured for Google Play submission. + +## Project Properties + +```xml +23 +com.companyname.DungeonSlime.Android +1 +1.0 +``` + +## Activity Configuration + +Verify your main activity is properly configured. Ensuring the orientation of your game - portrait or landscape. + +```csharp +[Activity( + Label = "@string/app_name", + MainLauncher = true, + Icon = "@drawable/icon", + AlwaysRetainTaskState = true, + LaunchMode = LaunchMode.SingleInstance, + ScreenOrientation = ScreenOrientation.SensorLandscape, + ConfigurationChanges = ConfigChanges.Orientation | ConfigChanges.Keyboard | + ConfigChanges.KeyboardHidden | ConfigChanges.ScreenSize +)] +``` + +## Required Assets + +### App Icons + +You will need to create and ensure you have app icons for all density buckets. There are a few online offerings where you can create a single image and it produce the icons. For example, [App Icon Generator](https://www.applicon.com). + +- **mdpi:** 48x48 px +- **hdpi:** 72x72 px +- **xhdpi:** 96x96 px +- **xxhdpi:** 144x144 px +- **xxxhdpi:** 192x192 px + +### Feature Graphic + +- **Size:** 1024 x 500 px +- **Format:** PNG or JPEG +- **Purpose:** Featured in Google Play Store + +### Screenshots + +Required for each supported device type to promote your game and its features. + +- **Phone:** Minimum 320px, maximum 3840px +- **7-inch Tablet:** Same requirements +- **10-inch Tablet:** Same requirements +- **Android TV:** 1920 x 1080 px +- **Wear OS:** 384 x 384 px + +## Signing Configuration + +### Creating a Keystore + +```bash +# Generate new keystore (first time only) +keytool -genkey -v -keystore your-app.keystore -alias your-key-alias -keyalg RSA -keysize 2048 -validity 10000 + +# Verify keystore +keytool -list -v -keystore your-app.keystore +``` + +**Important:** Keep your keystore file secure and backed up. Lost keystores cannot be recovered and prevent app updates. + +## Creating Your Game at Google Play + +1. **Create App** in Google Play Console + +2. **App Details:** + - App Name: Your app's display name + - Default Language: Primary market language + - App or Game: Select "Game" for MonoGame apps + - Free or Paid: Choose pricing model + +3. **Declarations:** + - App Content: Age rating and content + - Target Audience: Age groups + - News App: Usually "No" for games + +## Building Release APK/AAB + +### Android App Bundle (Recommended) + +Google Play prefers AAB format for optimized delivery: + +```bash +# Build AAB using .NET CLI +dotnet publish -f net8.0-android -c Release + +# Or using MSBuild +msbuild YourApp.Android.csproj /p:Configuration=Release /p:AndroidPackageFormat=aab +``` + +### APK Build (Alternative) + +```bash +# Build APK +dotnet publish -f net8.0-android -c Release /p:AndroidPackageFormat=apk +``` + +| ![Figure 4-7: Visual Studio Archive](images/android/android_release.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-7: Visual Studio Archive** | + +### Verification Steps + +Before upload, verify your build: + +```bash +# Check APK contents +aapt dump badging your-app.apk + +# Verify signing +jarsigner -verify -verbose -certs your-app.apk + +# Test installation +adb install your-app.apk +``` diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@2x.png new file mode 100644 index 00000000..0d36c4be Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@3x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@3x.png new file mode 100644 index 00000000..13e81e5b Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon20x20@3x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@2x.png new file mode 100644 index 00000000..826942c9 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@3x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@3x.png new file mode 100644 index 00000000..eef69b7e Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon29x29@3x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@2x.png new file mode 100644 index 00000000..76bf8b6c Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@3x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@3x.png new file mode 100644 index 00000000..09da383e Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon40x40@3x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@2x.png new file mode 100644 index 00000000..2a6eba37 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@3x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@3x.png new file mode 100644 index 00000000..fd8c4a04 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon60x60@3x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon76x76@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon76x76@2x.png new file mode 100644 index 00000000..b3ef476c Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon76x76@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon83.5x83.5@2x.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon83.5x83.5@2x.png new file mode 100644 index 00000000..cb03f365 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appicon83.5x83.5@2x.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appiconItunesArtwork.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appiconItunesArtwork.png new file mode 100644 index 00000000..3f789e7e Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/icons/appiconItunesArtwork.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-assign-testers.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-assign-testers.png new file mode 100644 index 00000000..54072691 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-assign-testers.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-encryption.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-encryption.png new file mode 100644 index 00000000..01fbdcb8 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build-encryption.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build.png new file mode 100644 index 00000000..0cf50e82 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/testflight-build.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload1.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload1.png new file mode 100644 index 00000000..c1fc8432 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload1.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload2.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload2.png new file mode 100644 index 00000000..9e8ebbf9 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter-upload2.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter.png b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter.png new file mode 100644 index 00000000..1de96af6 Binary files /dev/null and b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/images/ios/transporter.png differ diff --git a/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/index.md b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/index.md new file mode 100644 index 00000000..f3b64ab0 --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/06_publishing_ios/index.md @@ -0,0 +1,311 @@ +--- +title: "Chapter 06: Publishing to iOS App Store" +description: "Learn how to publish your MonoGame mobile application to both the iOS App Store with step-by-step guidance." +--- + +# Publishing Overview + +This chapter covers the complete publishing process for both major mobile app stores. You will learn the requirements, workflow for getting your MonoGame app successfully published on iOS platforms. + +# Apple Develoer Program + +## Pre-Publishing Preparation + +Ensure your iOS project is properly configured for App Store submission: + +## Project Properties + +```xml +12.2 +com.companyname.gamename +AppIcon +``` + +## Code Signing for Release + +Two entitlements - one for debug and one for publication. + +```xml + + iPhone Distribution + EntitlementsProduction.plist + +``` + +## Production Entitlements + +Verify your `EntitlementsProduction.plist` has debugging disabled: + +```xml +get-task-allow + +``` + +## Required Assets + +### App Icons + +You will need to create and ensure you have app icons for all density buckets. There are a few online offerings where you can create a single image and it produce the icons. For example, [App Icon Generator](https://www.applicon.com). + +You can place all of your icons in the location `Assets.xcassets/AppIcon.appiconset`. + +- **iPhone**: 40x40, 60x60, 87x87, 120x120, 180x180 +- **iPad**: 40x40, 58x58, 80x80, 152x152, 167x167 +- **App Store**: 1024x1024 + +|Asset|Image| +|-|-| +|40x40|![40x40](images/icons/appicon20x20@2x.png)| +|58x58|![58x58](images/icons/appicon29x29@2x.png)| +|60x60|![60x60](images/icons/appicon20x20@3x.png)| +|80x80|![80x80](images/icons/appicon40x40@2x.png)| +|87x87|![87x87](images/icons/appicon29x29@3x.png)| +|120x120|![120x120](images/icons/appicon40x40@3x.png)| +|120x120|![120x120](images/icons/appicon60x60@2x.png)| +|152x152|![152x152](images/icons/appicon76x76@2x.png)| +|83.5x83.5|![167x167](images/icons/appicon83.5x83.5@2x.png)| +|180x180|![180x180](images/icons/appicon60x60@3x.png)| +|Artwork 1024x1024|![1024x1024](images/icons/appiconItunesArtwork.png)| + +### Info.plist Configuration + +Verify essential properties are set: + +The bundle identifier: + +From the csproj to match the one in the info.plist file too. + +> [!NOTE] +> Change the bundle identifier to match what was set up during the provisioning process. + +IOS CSProj: + +```xml +com.monogame.dungeonslime +``` + +Info.Plist setting: + +```xml +CFBundleIdentifier +com.monogame.dungeonslime +``` + +The game name to appear on the device: + +```xml +CFBundleDisplayName +DungeonSlime +``` + +Versioning of game: + +```xml +CFBundleVersion +11 +CFBundleShortVersionString +1.10 +``` + +Typical settings for a game: + +```xml +UIRequiresFullScreen + +UIStatusBarHidden + +``` + +API descriptions: + +If your game uses any additional API's or API's are pulled in from libraries, then the following descriptions need to be added to define your usage. If you're not using them, then you need to identify the library being added and determine if you need this. + +```xml +NSBluetoothAlwaysUsageDescription +This game uses bluetooth because... + +NSLocationAlwaysAndWhenInUseUsageDescription +This game is location information because... + +NSLocationWhenInUseUsageDescription +This game is location information because... + +NSCalendarsUsageDescription +This game uses calendar information because... + +NSSiriUsageDescription +This game uses Siri because... + +NSMicrophoneUsageDescription +This game uses the microphone because. + +NSContactsUsageDescription +This game uses contacts because... + +NSAppleMusicUsageDescription +This game uses Apple Music because... +``` + +## Asset Compilation Target + +Ensure your iOS project includes the asset compilation target. This is currently required for MonoGame projects to get the AppIcons and assets included in the bundle. + +```xml + + + + +``` + +## Creating Game at App Store Connect + +Once you're ready to publish your game to TestFlight or the AppStore, following these steps: + +1. **Log into App Store Connect** at [appstoreconnect.apple.com](https://appstoreconnect.apple.com) + +2. **Create New App:** + - Platform: **iOS** + - Name: _Your app's marketing name_ + - Primary Language: English (or your primary market) + - Bundle ID: Must match the `BundleIdentifier` of your game. + - SKU: Unique identifier if you were to create a series of games. + +## Screenshots and Media + +### Required Screenshots + +You need screenshots for each of the following devices: + +- **iPhone 6.7"** (iPhone 14 Pro Max): 1290 x 2796 pixels +- **iPhone 6.5"** (iPhone 11 Pro Max): 1242 x 2688 pixels +- **iPhone 5.5"** (iPhone 8 Plus): 1242 x 2208 pixels +- **iPad Pro (6th gen)**: 2048 x 2732 pixels +- **iPad Pro (2nd gen)**: 2048 x 2732 pixels + +### App Preview Videos (Optional) + +Although optional, a video to demo your game will certainly appeal to the audience. + +- Create a 30 seconds video showing features and market your game. +- Try and show actual gameplay and advertise features and any unique play. + +## Building and Uploading using Terminal + +The creation of an IPA file can be achieved using the **Terminal** app. Currently, Rider does __not__ support this part of the process. + +If you are building on MacOS Tahoe, you'll need the following in the csproj: + +```xml + +26.0 + +``` + +Using terminal, navigate to the dungeonslime.iOS folder and run the following steps: + +For game projects that are targeting .NET 8.0 iOS: + +```sh +dotnet clean +rm -rf bin/ obj/ +dotnet publish -c Release -f net8.0-ios -r ios-arm64 -p:ArchiveOnBuild=true +``` + +For game projects that are targeting .NET 9.0 iOS: + +```sh +dotnet clean +rm -rf bin/ obj/ +dotnet publish -c Release -f net9.0-ios -r ios-arm64 -p:ArchiveOnBuild=true +``` + +For game projects that are targeting .NET 10.0 iOS: + +```sh +dotnet clean +rm -rf bin/ obj/ +dotnet publish -c Release -f net10.0-ios -r ios-arm64 -p:ArchiveOnBuild=true +``` + +This will create an IPA file in your publish folder which you can upload to the AppStore. + +Some other options for the project file that have helped make an ipa. + +### **UseInterpreter** setting + +If you encounter an exit code of 134 during (Ahead of Time) AOT compilation during the **dotnet publish** phase, then set this property to **true**. + +e.g. + +```sh +/usr/local/share/dotnet/packs/Microsoft.iOS.Sdk.net9.0_26.0/26.0.9752/targets/Xamarin.Shared.Sdk.targets(1387,3): error : Failed to AOT compile aot-instances.dll, the AOT compiler exited with code 134. +``` + +This setting tells the build system to disable full Ahead-Of-Time (AOT) compilation and instead rely on the Mono Interpreter for the managed C# code. + +Setting the csproj file: + +```xml + + true + +``` + +### End of Life Target warning + +Suppressing the End of Life (EoL) warning can be done with the **CheckEolTargetFramework** setting. + +```sh +error NETSDK1202: The workload 'net8.0-ios' is out of support and will not receive security updates in the future. +``` + +Setting in the csproj file to suppress the warning: + +```xml + + false + +``` + +## Upload Method using Transporter + +You can use the **Transporter** tool to upload your IPA file and that can be found in the **Applications** folder. + +| ![Figure 4-1: Transporter](images/ios/transporter.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-1: Transporter** | + +Step through the upload process for your IPA file. + +| ![Figure 4-2: Transporter Upload Step 1](images/ios/transporter-upload1.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-2: Transporter Upload Step 1** | + +| ![Figure 4-3: Transporter Upload Step 2](images/ios/transporter-upload1.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-3: Transporter Upload Step 2** | + +## After uploading + +The process can take a few moments to happen, but switching to the AppStore to watch the progress and complete the publication of your app. + +| ![Figure 4-4: iOS Builds](images/ios/testflight-build.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-4: iOS Builds** | + +| ![Figure 4-5: Encryption Dialog](images/ios/testflight-build-encryption.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-5 Encryption Dialog** | + +**Tip:** If you want to skip the "Encryption" dialog box altogether and streamline the process and because you do not use encryption in your game, simply add this section to your **info.plist** file. + +```xml +ITSAppUsesNonExemptEncryption + +``` + +Finally, add your testers and test information and they will receive your updated game (via Testflight or Store). + +| ![Figure 4-6: Assign Testers](images/ios/testflight-build-assign-testers.png) | +| :----------------------------------------------------------------------------------------------------------------------------------------: | +| **Figure 4-6: Assign Testers** | diff --git a/articles/tutorials/advanced/MobileDeployment/07_checklist/index.md b/articles/tutorials/advanced/MobileDeployment/07_checklist/index.md new file mode 100644 index 00000000..3178e980 --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/07_checklist/index.md @@ -0,0 +1,53 @@ +--- +title: "Chapter 07: Checklist for publishing to iOS App Store and Google Play Store" +description: "Learn how to publish your MonoGame mobile application to both the iOS App Store and Google Play Store with step-by-step guidance." +--- + +# App Review Submission + +## Pre-Submission Checklist + +- [ ] All required screenshots uploaded +- [ ] App description and metadata complete +- [ ] Privacy policy URL provided (if required) +- [ ] Content rating completed +- [ ] Pricing and availability set +- [ ] Build selected and tested +- [ ] Export compliance information provided + +## Review Information + +## App Review Contact Information + +- First Name, Last Name +- Phone Number +- Email Address + +## Demo Account (If Required) + +If your app requires login: +- Demo Username +- Demo Password +- Additional instructions for reviewers + +## Notes for Review + +Additional information to help reviewers: +- Special instructions +- Feature explanations +- Known limitations + +## Submission Process + +1. **Select Build:** Choose your uploaded build +2. **Review Summary:** Check all information is correct +3. **Submit for Review:** Click "Submit for Review" +4. **Status Tracking:** Monitor in App Store Connect + +## Review Timeline and Common Issues + +## Typical Timeline + +- **Review Time:** 24-48 hours +- **Processing:** Additional time for first-time developers +- **Holiday Delays:** Longer during Apple holidays, so plan accordingly. diff --git a/articles/tutorials/advanced/MobileDeployment/08_conclusion/index.md b/articles/tutorials/advanced/MobileDeployment/08_conclusion/index.md new file mode 100644 index 00000000..9f7ac252 --- /dev/null +++ b/articles/tutorials/advanced/MobileDeployment/08_conclusion/index.md @@ -0,0 +1,32 @@ +--- +title: "Chapter 08: Conclusion" +description: "Learn how to publish your MonoGame mobile application to both the iOS App Store and Google Play Store with step-by-step guidance." +--- + +# Conclusion + +This completes the tutorial to publishing your MonoGame application on both iOS and Android app stores. Following these workflows will help ensure successful publication and ongoing updates to your mobile game. + +## And now for a Recap... + +- [Getting Started with Android Development](https://learn.microsoft.com/en-us/dotnet/android/getting-started/installation/) + +- [Getting Started with Maui Development](https://learn.microsoft.com/en-us/dotnet/maui/get-started/installation) + +- [Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management) + +## App Stores + +- [Google Play Console](https://play.google.com/console) + +- [Apple Connect](https://appstoreconnect.apple.com) + +## Libraries + +- [https://github.com/vchelaru/Gum](https://github.com/vchelaru/Gum) + +## Tools + +- [JetBrains Rider](https://www.jetbrains.com/rider/) +- [VS Code](https://code.visualstudio.com/) +- [App Icon Generator](https://www.applicon.com) diff --git a/articles/tutorials/index.md b/articles/tutorials/index.md index 51525a47..18094248 100644 --- a/articles/tutorials/index.md +++ b/articles/tutorials/index.md @@ -33,14 +33,14 @@ description: Tutorials provided by MonoGame community members.
-
2D Mobile Deployment - coming soon
+
2D Mobile Deployment

An extension tutorial following on from the Beginner 2D above demonstrating how to take a desktop project to Mobile devices.

-

Coming Soon

+

Click to view deploment tutorial