game_template/README.md
The following template will be deprecated soon. Please refer to the new games repo for more genre-specific templates: https://github.com/flutter/games For more information, please refer to flutter.dev/games to see all resources available for flutter game developers.
Old template readme: A starter game in Flutter with all the bells and whistles of a mobile (iOS & Android) game including the following features:
The game compiles and works out of the box. It comes with things like a main menu, a router, a settings screen, and audio. When building a new game, this is likely everything you first need.
When you're ready to enable more advanced integrations, like ads and in-app payments, read the Integrations section below.
To run the app in debug mode:
flutter run
This assumes you have an Android emulator, iOS Simulator, or an attached physical device.
It is often convenient to develop your game as a desktop app.
For example, you can run flutter run -d macOS, and get the same UI
in a desktop window on a Mac. That way, you don't need to use a
simulator/emulator or attach a mobile device. This template supports
desktop development by disabling integrations like AdMob for desktop.
Code is organized in a loose and shallow feature-first fashion.
In lib/src, you'll therefore find directories such as ads, audio
or main_menu. Nothing fancy, but usable.
lib
├── src
│ ├── ads
│ ├── app_lifecycle
│ ├── audio
│ ├── game_internals
│ ├── games_services
│ ├── in_app_purchase
│ ├── level_selection
│ ├── main_menu
│ ├── play_session
│ ├── player_progress
│ ├── settings
│ ├── style
│ └── win_game
├── ...
└── main.dart
The state management approach is intentionally low-level. That way, it's easy to
take this project and run with it, without having to learn new paradigms, or having
to remember to run dart run build_runner watch. You are,
of course, encouraged to use whatever paradigm, helper package or code generation
scheme that you prefer.
To build the app for iOS (and open Xcode when finished):
flutter build ipa && open build/ios/archive/Runner.xcarchive
To build the app for Android (and open the folder with the bundle when finished):
flutter build appbundle && open build/app/outputs/bundle/release
While the template is meant for mobile games, you can also publish
for the web. This might be useful for web-based demos, for example,
or for rapid play-testing. The following command requires installing
peanut.
flutter pub global run peanut \
--web-renderer canvaskit \
--extra-args "--base-href=/name_of_your_github_repo/" \
&& git push origin --set-upstream gh-pages
The last line of the command above automatically pushes your newly built web game to GitHub pages, assuming that you have that set up.
The more advanced integrations are disabled by default. For example, achievements aren't enabled at first because you, the developer, have to set them up (the achievements need to exist in App Store Connect and Google Play Console before they can be used in the code).
This section includes instructions on how to enable any given integration.
Some general notes:
rename tool
(on pub.dev) automates the process.Ads are implemented using the official google_mobile_ads package
and are disabled by default.
// TODO: When ready, uncomment the following lines to enable integrations.
AdsController? adsController;
// if (!kIsWeb && (Platform.isIOS || Platform.isAndroid)) {
// /// Prepare the google_mobile_ads plugin so that the first ad loads
// /// faster. This can be done later or with a delay if startup
// /// experience suffers.
// adsController = AdsController(MobileAds.instance);
// adsController.initialize();
// }
The AdsController code inlib/main.dart is null by default,
so the template gracefully falls back to not showing ads
on desktop.
You can find the code relating to ads in lib/src/ads/.
To enable ads in your game:
Go to AdMob and set up an account. This could take a significant amount of time because you need to provide banking information, sign contracts, and so on.
Create two Apps in AdMob: one for Android and one for iOS.
Get the AdMob App IDs for both the Android app and the iOS app.
You can find these in the App settings section. They look
something like ca-app-pub-1234567890123456~1234567890
(note the tilde between the two numbers).
Open android/app/src/main/AndroidManifest.xml, find the <meta-data>
entry called com.google.android.gms.ads.APPLICATION_ID,
and update the value with the App ID of the Android AdMob app
that you obtained in the previous step.
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ca-app-pub-1234567890123456~1234567890"/>
Open ios/Runner/Info.plist, find the
entry called GADApplicationIdentifier,
and update the value with the App ID of the iOS AdMob app.
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-1234567890123456~0987654321</string>
Back in AdMob, create an Ad unit for each of the AdMob apps.
This asks for the Ad unit's format (Banner, Interstitial, Rewarded).
The template is set up for a Banner ad unit, so select that if you
want to avoid making changes to the code in lib/src/ads.
Get the Ad unit IDs for both the Android app and the iOS app.
You can find these in the Ad units section. They look
something like ca-app-pub-1234567890123456/1234567890
(yes, the format is very similar to App ID; note the slash
between the two numbers).
Open lib/src/ads/ads_controller.dart and update the values
of the Ad unit IDs there.
final adUnitId = defaultTargetPlatform == TargetPlatform.android
? 'ca-app-pub-1234567890123456/1234567890'
: 'ca-app-pub-1234567890123456/0987654321';
Uncomment the code relating to ads in lib/main.dart,
and add the following two imports:
import 'dart:io';
import 'package:google_mobile_ads/google_mobile_ads.dart';
Register your test devices in AdMob's Settings → Test devices section.
The game template defines a sample AdMob app ID and two sample _Ad unit ID_s. These allow you to test your code without getting real IDs from AdMob, but this "feature" is sparsely documented and only meant for hello world projects. The sample IDs won't work for published games.
If you feel lost at any point, a full AdMob for Flutter walk-through is available on Google AdMob's documentation site.
If you want to implement more AdMob formats (such as Interstitial ads),
a good place to start are the examples in
package:google_mobile_ads.
Audio is enabled by default and ready to go. You can modify code
in lib/src/audio/ to your liking.
You can find some music
tracks in assets/music — these are Creative Commons Attribution (CC-BY)
licensed, and are included in this repository with permission. If you decide
to keep these tracks in your game, please don't forget to give credit
to the musician, Mr Smith.
The repository also includes a few sound effect samples in assets/sfx.
These are public domain (CC0) and you will almost surely want to replace
them because they're just recordings of a developer doing silly sounds
with their mouth.
Crashlytics integration is disabled by default.
When enabled, this integration is quite powerful:
To enable Firebase Crashlytics, do the following:
firebase-tools
on your machine.flutterfire CLI
on your machine.pubspec.yaml),
run the following:
flutterfire configure
android and ios are fully
supported by Crashlytics.lib/firebase_options.dart with
the correct code.lib/main.dart and uncomment the lines that relate to Crashlytics.You should now be able to see crashes and errors in console.firebase.google.com. To test, add a button to your project, and throw whatever exception you like when the player presses it.
TextButton(
onPressed: () => throw StateError('whoa!'),
child: Text('Test Crashlytics'),
)
Games Services (like achievements and leaderboards) are implemented by the
games_services package,
and are disabled by default.
To enable games services, first set up Game Center on iOS and Google Play Games Services on Android.
To enable Game Center (GameKit) on iOS:
open ios/Runner.xcodeproj).+ button to add Game Center as a capability.
You can close Xcode now.To enable Play Games Services on Android:
Go to your app in Google Play Console.
Select Play Games Services → Setup and management → Configuration from the navigation menu and follow their instructions.
When done, you can start adding leaderboards and achievements in Play Games Services → Setup and management. Create the exact same set as you did on the iOS side. Make note of IDs.
Go to Play Games Services → Setup and management → Publishing, and click 'Publish'. Don't worry, this doesn't actually publish your game. It only publishes the achievements and leaderboard. Once a leaderboard, for example, is published this way, it cannot be unpublished.
Go to Play Games Services → Setup and management → Configuration → Credentials. Find a button that says 'Get resources'. You get an XML file with the Play Games Services IDs.
<?xml version="1.0" encoding="utf-8"?>
<!--Google Play game services IDs. Save this file as res/values/games-ids.xml in your project.-->
<resources>
<!--app_id-->
<string name="app_id" translatable="false">424242424242</string>
<!--package_name-->
<string name="package_name" translatable="false">dev.flutter.tictactoe</string>
<!--achievement First win-->
<string name="achievement_first_win" translatable="false">sOmEiDsTrInG</string>
<!--leaderboard Highest Score-->
<string name="leaderboard_highest_score" translatable="false">sOmEiDsTrInG</string>
</resources>
Replace the file at android/app/src/main/res/values/games-ids.xml
with the XML you received in the previous step.
Now that you have set up Game Center and Play Games Services, and have your achievement & leaderboard IDs ready, it's finally Dart time.
Open lib/src/games_services/games_services.dart and edit the leaderboard
IDs in the showLeaderboard() function.
// TODO: When ready, change both these leaderboard IDs.
iOSLeaderboardID: "some_id_from_app_store",
androidLeaderboardID: "sOmE_iD_fRoM_gPlAy",
The awardAchievement() function in the same file takes the IDs
as arguments. You can therefore call it from anywhere
in your game like this:
final gamesServicesController = context.read<GamesServicesController?>();
await gamesServicesController?.awardAchievement(
iOS: 'an_achievement_id',
android: 'aNaChIeVeMenTiDfRoMgPlAy',
);
You might want to attach the achievement IDs to levels, enemies,
places, items, and so on. For example, the template has levels
defined in lib/src/level_selection/levels.dart like so:
GameLevel(
number: 1,
difficulty: 5,
achievementIdIOS: 'first_win',
achievementIdAndroid: 'sOmEtHinG',
),
That way, after the player reaches a level, we check if the level
has non-null achievement IDs, and if so, we call awardAchievement()
with those IDs.
Uncomment the code relating to games services in lib/main.dart.
// TODO: When ready, uncomment the following lines.
GamesServicesController? gamesServicesController;
// if (!kIsWeb && (Platform.isIOS || Platform.isAndroid)) {
// gamesServicesController = GamesServicesController()
// // Attempt to log the player in.
// ..initialize();
// }
If at any point you feel lost, there's a How To guide written by the author
of package:games_services. Some of the guide's instructions and screenshots
are slightly outdated (for example, iTunes Connect has been renamed to App Store Connect
after the article was published) but it's still an excellent resource.
In-app purchases are implemented using the official
in_app_purchase package.
The integration is disabled by default.
To enable in-app purchases on Android:
package:in_app_purchase, it signals itself to the
Play Store as a project with in-app purchases.ad_removal).To enable in-app purchases on iOS:
+ button.
Use the same product ID you used on the Android side.Now everything is ready to enable the integration in your Dart code:
Open lib/src/in_app_purchase/ad_removal.dart and change productId
to the product ID you entered in Play Console and App Store Connect.
/// The representation of this product on the stores.
static const productId = 'remove_ads';
AdRemovalPurchase.lib/src/in_app_purchase/in_app_purchase.dart.
By default, the template only supports one in-app purchase.Uncomment the code relating to in-app purchases in lib/main.dart.
// TODO: When ready, uncomment the following lines.
InAppPurchaseController? inAppPurchaseController;
// if (!kIsWeb && (Platform.isIOS || Platform.isAndroid)) {
// inAppPurchaseController = InAppPurchaseController(InAppPurchase.instance)
// // Subscribing to [InAppPurchase.instance.purchaseStream] as soon
// // as possible in order not to miss any updates.
// ..subscribe();
// // Ask the store what the player has bought already.
// inAppPurchaseController.restorePurchases();
// }
If at any point you feel lost, check out the official Adding in-app purchases to your Flutter app codelab.
The settings page is enabled by default, and accessible both from the main menu and the "gear" button in the play session screen.
Settings are saved to local storage using the package:shared_preferences.
To change what preferences are saved and how, edit files in
lib/src/settings/persistence.
abstract class SettingsPersistence {
Future<bool> getMusicOn();
Future<bool> getMuted({required bool defaultValue});
Future<String> getPlayerName();
Future<bool> getSoundsOn();
Future<void> saveMusicOn(bool value);
Future<void> saveMuted(bool value);
Future<void> savePlayerName(String value);
Future<void> saveSoundsOn(bool value);
}
To update the launcher icon, first change the files
assets/icon-adaptive-foreground.png and assets/icon.png.
Then, run the following:
dart run flutter_launcher_icons:main
You can configure
the look of the icon in the flutter_icons: section of pubspec.yaml.
When upgrading to higher versions of Flutter or plugins, you might encounter an error when
building the iOS or macOS app. A good first thing to try is to delete the ios/Podfile.lock
file (or macos/Podfile.lock, respectively), then trying to build again. (You can achieve
a more thorough cleanup by running flutter clean instead.)
If this doesn't help, here are some more methods:
See if everything is still okay with your Flutter and CocoaPods installation
by running flutter doctor. Revisit the macOS
Flutter installation guide
if needed.
Update CocoaPods specs directory:
cd ios
pod repo update
cd ..
(Substitute ios for macos when appropriate.)
Open the project in Xcode, increase the build target, then select Product > Clean Build Folder.
When running the game for the first time, you might see warnings like the following:
Note: Some input files use or override a deprecated API.
or
warning: 'viewState' was deprecated in macOS 11.0: Use -initWithState: instead
These warning come from the various plugins that are used by the template. They are not harmful and can be ignored. The warnings are meant for the plugin authors, not for you, the game developer.