 Since 2015, Conquest! has sent alerts using email. This has worked fine for years but when I first created a UI client for mobile devices, I've wanted to add push notifications. When I looked at this a few years ago, notification services cost money and the integration seemed complex.
But recently I was chatting with ChatGPT and asked about adding notifications to Conquest!. It told me about Firebase and its available free messaging service and after sharing some code samples, we were off to the races. Part 1: Firebase Project Creating a new account and project inside Firebase was easy. I created a service account, ensuring that I downloaded the service account JSON file when prompted as you can't retrieve it again later. The service account information is used to request the access token to send notifications (more on that below). Next I added my iOS and Android applications to my Firebase project and downloaded two additional configuration files, which are required for integration with Unity. Part 2: Server The Conquest! server is the brains of the entire game. In order to send notifications to clients, the server must get an OAUTH2 access token, which expires every hour, from Firebase. The game server is written in C which is great for performance but as ChatGPT said "It’s doable but not fun. C wasn’t made for working with JSON + Base64 + JWT + RS256 + HTTPS, so expect manual plumbing." After reviewing the pseudocode ChatGPT provided, I decided to go with the alternative suggestion, creating a Python script that the C server would call to receive the access token. import google.auth from google.oauth2 import service_account import google.auth.transport.requests import sys # The OAuth 2.0 scope required to send FCM messages SCOPES = ["https://www.googleapis.com/auth/firebase.messaging"] def get_access_token(service_account_file): credentials = service_account.Credentials.from_service_account_file( service_account_file, scopes=SCOPES ) auth_req = google.auth.transport.requests.Request() credentials.refresh(auth_req) return credentials.token if len(sys.argv) < 2: print("Usage: fcm_token.py <path_to_service_account_json>") sys.exit(1) service_account_file = sys.argv[1] token = get_access_token(service_account_file) print(token) This required installing the "google-auth" Python module on both my development and production servers. Now I had the token but I still had to construct the JSON messages. Fortunately, I switched from XML to JSON last year so the server was already using the JSON-C library. I also recently switched from using mailx to send emails to using curl. Both of these changes helped with the development of the new notification system. The server keeps the access token in memory and checks its age to see if its greater than 55 minutes old. If so, it requests a new one by opening a pipe and invoking the Python script above. Next it constructs the notification request using JSON-C and then sends it to Firebase using curl. When a client connects to the server and provides its token, this is stored in a device structure. Part 3: Unity3d The first item to do was install the Firebase SDK into Unity. Since the notifications are coming from the server and the client isn't receiving them directly, I only needed to import FirebaseMessaging.unitypackage. I placed the the application configuration files downloaded from Firebase in Assets/StreamingAssets (Android) and the root Assets folder (iOS). Next I had to add some code in my application to initialize Firebase and receive the client token. I needed to send this token to the server so it knew where to send the notifications. When I first ran the code in the Unity editor I received this error: Database URL not set in the Firebase config. After some back and forth with ChatGPT, it was determined that the URL had to be included in the Android and iOS configuration files i.e., "databaseURL": "https://your-project-id.firebaseio.com" After correcting that error, I was able to run the code in the Editor but not actually test the notifications. Part 4: iOS Naturally, building for iOS was the most complex. From the Apple developer portal, I had to create a new p8 Key used for push notifications and add that to my Firebase project. My development box runs Windows, so after Unity was done I transferred to a Mac. Unity doesn't include all the framework files required to build in XCode (why?!?). In order to add those, I needed to install "CocoaPods". Installing this the first time didn't work (of course) because most Macs ship with an old version of Ruby. In order to update it, I had to use Homebrew, which also wasn't installed. So first I had to install Homebrew and then update Ruby (and adjust my PATH environment variable to use the new versions and tools). Finally, I could install CocoaPods. All of this was done so I could execute "pod install" from the Mac inside the Unity project folder to add all the framework files Firebase required. I opened the xcworkspace file that pod created in XCode. Certain key capabilities cannot be set inside Unity, so I had to add "Background Tasks" (Remote notifications) and "Push Notifications" to the project. Once all of that was done, I was finally able to build the iOS client. Whew! Part 5: Android By contrast, building for Android was much easier. In the Build Settings I had to ensure Custom Main Gradle Template and Custom Launcher Gradle Template were selected. I had to edit the mainTemplate.gradle and replace "**PACKAGING**" with "**PACKAGING_OPTIONS**" and add "**BUILT_IN_EXTRAS**" and "**EXTERNAL_SOURCES**" at the bottom. The Android build completed on Windows but when I first tested no notification showed up. This is because by default Android suppresses notifications if the app is open. Once my tester closed the Conquest! application, the notification worked! There is a workaround to show notifications when the application is open but I decided to leave it as is for now. Conclusion Working with ChatGPT during this process was invaluable. I could have done this with Google searches but it would have taken far more time as I tried to piecemeal solutions from across the Internet. ChatGPT isn't perfect, however, and there were a few times where it led me down an incorrect path. But overall, it is a great tool and I finally have push notifications working for Conquest!. Huzzah!
0 Comments
When Conquest! was solely a text based game, it made sense to send players all the proper names for all the objects in the game (e.g., troop names, ship configurations, magical items, etc.). For example, when sending kingdom details, the server would send something like this:
{ "Id": "4174", "Body": [ "168 Move", "34 Grove", "4357845 Gold", "180" ] } The "Move", "Gold", and "Grove" text descriptions are fine for a text client but they were being discarded by the GUI! This meant lots of unnecessary data being sent to the client. I decided to finally address this situation, similar to the effort last year for troops and reports (you can read the blurb here). Some of the information, for example the names of magical items, still needs to be visible in the client. If it isn't sent every update, how should the client get this information? I thought of three options:
I ended up going with option three and adding three additional JSON files to the client: magical components, magical items, and ships. These files are retrieved when they don't exist or when the server instructs the client to update them. In this way I get the best outcome: data is sent once and only updated when required. This conversion ended up breaking all previous clients, since I didn't build in a way for the server to send the data the old clients needed. The game was still playable, but items and ships couldn't be viewed or utilized (not a great experience). Live and learn I suppose. Until next time! Greetings conquerors, it's time for the 2024 recap. This year focused mainly on "tech debt", with the two largest efforts being the communication protocol switch and text message overhauls.
Switching from XML to JSON reduced the payload sizes by 10-30%. This helps with client performance on slower connections (see separate blog post for further details). Additionally, I recently removed the troop name (e.g., soldier, archer, knight, etc.) and mode (i.e., infantry, cavalry, flight) from the battle and spy reports. Sending this text was wholly unnecessary and further reduced the payload size for those reports. Imagine 8 armies (4 per side) with 8 troops each plus the casualties for each side; that is 80 instances per battle report where the troop name and mode were being sent. Yikes! Conquest! has ~3000 pieces of text, which include button labels, tips, help, email notifications, and success/error messages. This text was developed over years and varied wildly in tone and grammar. Also, there were many duplicate messages. This year I focused on standardization and the removal of duplicates by creating server-side helper functions for common messages (e.g., cannot use an item or skill, capturing or destroying goods, etc.). These functions are called across the game as needed and provide a more consistent experience for players. Here is the complete list of changes. Server
Classes
NPCs
UI
Misc.
Since Conquest! was converted to the C language circa 1998, it has used an XML format to exchange information. This worked fine for years but I recently became concerned with the payload sizes, as the amount of data the server needed to send the client has increased. Additionally, I was not using any advanced XML capabilities (e.g., meta data support) that would warrant its continued use. I started looking at JSON and became convinced after seeing payload sizes reduced by 10-30%. For example, here are examples of common commands and sizes (in bytes).
None of the player or world data is stored client-side, so each action a player takes requires updates from the server. Over time, these will add up to huge savings and should improve the end user experience. Additionally, I wanted to ensure backwards compatibility with existing XML based clients, so the server had to support both formats until I force a client update. I'm using the client version number to determine which to try first.
Part of the challenge was finding existing libraries for both C (server) and Unity3D (client) to handle JSON parsing.
For the server, I decided on json-c. The library itself is great but I found the documentation on the GitHub repository lacking. It wasn't until I found this tutorial that it all finally clicked. This tutorial covers everything from installation to memory management. Another good reference was the header file documentation.
Now that the server was covered, I turned to the client. I installed the Newtonsoft Json package (available for free) and followed the guide here. Serializing and Deserializing the response back from the server took some time to get working. I ended up having to break down the JSON object by object and add them back in one at a time to locate my errors. I found this site very helpful when creating my initial classes.
As part of this conversion, I also moved from using Unity's PlayerPrefs to a JSON configuration file. Over time, the amount of data I was storing in PlayerPrefs had gotten large and I needed to represent more complex structures. I was able to use Newtonsoft for both the responses from the server and management of the configuration file. I even wrote a conversion function to silently upgrade client from PlayerPrefs to the new settings file.
It was a lot of work over several days, but I'm pleased with the results.
UPDATE: After some consideration, I ended up switching from Newtonsoft to the standard JSON utility included in Unity. I didn't need the advanced capabilities of Newtonsoft and the default utility works fine. One item which did cause me problems is that all classes and subclasses need to be identified with [System.Serializable] for the default utility to work properly.
Here is the summary of enhancements made to Conquest! in 2023.
One important item left off is finally utilizing Application.persistentDataPath to store the ~3,000 messages utilized throughout the game. In the past, if I wanted to update messages I would have to re-deploy the entire client. Now the client is pulling the messages down when the server tells it to. This has been a tremendous benefit to me and the players as I can quickly fix spelling or grammatical errors (or even add new error messages). There are Unity packages which allow for dynamic translations but when I implemented the UI circa 2016, I didn't know about them. And when I did learn of them, I was concerned about performance. In hindsight, I may have taken a closer look at those packages vs doing all the translations myself. Major Enhancements
Alliances
Classes
Events
UI
Minor Enhancements Artifacts
Heroes
Misc.
When Conquest! was first developed in 1993, it used a very simple model to exchange data between the server and players. A player would send a command and the server would reply with an appropriate response. If a player needed additional information, they would issue another command to retrieve it. This worked well for a text-based UI.
When the UI was developed in 2016, essentially the same model was used. However, it quickly became apparent that additional information was needed to update the UI. Therefore, after a player issued a command and the server sent the initial response, the client would send additional commands to the server to retrieve the rest of the information. For example, consider this sequence:
In January of 2021, I switch from a pull to a push model. With this model the server would decide what information to send after processing a command. The above example now looks like this:
I have updated the pull model to use a centralized function to examine the player structures after a command is executed to dynamically determine the data required to send to the client. In this way, I do not have to worry about a command missing something (or sending too much data). The correct data is sent automatically each time. After a recent deployment, a player named TaxE contacted me with an unusual bug: none of the cities were showing on the travel maps! This renders Conquest! virtually unplayable. During the course of troubleshooting with TaxE, we discovered that this problem affected not just his Android device but his laptop too. Switching from Wifi to Cellular did not have any effect. I was stumped until I began brainstorming with long time player, Elric.
Until recently, Conquest! used integers to represent cities on a map in a 10x10 grid. These coordinates are sent from the server to clients as strings, where they are transformed to numbers and used to render the cities. During a refresh of the maps, I realized I needed greater precision for positioning so I switched from integers to floating points. Naturally, I changed my code: int.TryParse(Input, out Number) became float.TryParse(Input, out Number) When talking with Elric, he asked where TaxE was located. Turns out, TaxE was outside the US where a comma is typically used as a decimal separator vs a period in the US. Using the original float.TryParse(), clients outside the US were transforming city coordinates such as 3.7 to 37, rendering the cities far out of bounds of my 10x10 grid! A quick Google search revealed the solution: float.TryParse(Input, System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out Number); By forcing TryParse() to utilize InvariantCulture, which by default uses a period as a decimal separator, the numbers are now being transformed correctly. A huge thanks to both Elric and TaxE for helping work through this one!
A reoccurring suggestion has been to have names in chat/world events selectable, so players could quickly select others without resorting to cut/paste on Windows or trying to remember on other platforms. This seemingly innocuous suggestion lead to a project which took 5 days to complete!
When the Unity version of Conquest! started in 2015, it used all standard Text, Input, and Dropdown fields. These standard fields ship with Unity and are easy to use. Unfortunately, they do not support some simple and some advanced use cases e.g. underlining or embedding links in text. The latter functionality is what I really needed to make clickable player names work. Google and I turned up some workarounds to get links working in standard Text objects (maybe?) but it quickly became apparent what I really needed to do was convert to using TextMeshPro. I decided early on that I as going all-in on TextMeshPro and this required converting all buttons, dropdowns, input, and text fields to use the new objects. Fortunately, I recently converted many panels and popup windows to prefabs, which meant I only had to modify them once for them to be fixed everywhere. The first thing to do was add TextMeshPro to my project, an easy task accomplished via Windows > Package Manager. Adding <link> tags to text is also easy but responding to those links was more challenging. I found these two sites to be the most helpful in getting everything configured: www.youtube.com/watch?v=lyZuCnARNSw&ab_channel=JasonWeimann www.feelouttheform.net/unity3d-links-textmeshpro/ Here are the namespace and object names as a reference:
Assigning the new script to my text objects was simple but I had two major problems. First, I had inadvertently unchecked "Raycast Target" on the text object, which naturally prevented the IPointerClickHandler event from being triggered. The second was invoking the function I wanted from a different class (it wasn't opening a standard URL, which I could have accomplished with Application.OpenURL()). What I had to do was create an instance of the object which contained the function: public class MyClass : MonoBehavior { public static MyClass Instance; void Awake() { Instance = this; } public void MyFunction() { DoStuff(); } }
And then invoke the function using this notation: MyClass.Instance.MyFunction(). There are probably better ways to organize a project to allow this, but this is what worked for me. Now, player names are finally clickable! And underlining text is pretty neat too. =)
On October 12th, Conquest! launched on the Steam platform. Like other hosting sites, Steam has its share of idiosyncrasies but once those were worked out I was able to launch successfully. The guide that helped me the most was here: The Simple Guide to Steamworks API in Unity: Uploading Builds | by George Dutton | Finite Guild | Medium
Note that when the Steam platform first created the project for Conquest! it failed to create the default packages. After spending a day attempting to debug this myself (thinking it was a problem with the build or configuration) I opened a support ticket and learned this sometimes happen. Support created the default packages and everything starting working. Adding Conquest! on Steam has seen the biggest increase in the player base ever (including when it was originally on IRC). Conquest! is still difficult to learn and the UI has some usability "quirks" so the overall retention rate is small but I would strongly recommend getting any game listed there. I also went back and updated my submissions to Itch.io and Game Jolt. I'm not sure how much of an impact these platforms have but every little bit helps. I tried to submit to Gog.com but in their automated email back to me, they indicated an automatic pass on free games. So I'll keep looking for other platforms to list Conquest! on. Since its inception in 1993, Conquest! has only been available in the English language. Based on some reviews of Conquest!, adding additional languages seemed like a good idea. Fortunately, a design decision made circa 1995 made the process much easier.
Before the change, all game messages were hard coded within the server. This meant that every time a new message was added or an existing one was changed, the game had to be redeployed and the server restarted. At that time I decided that I would assign all messages with a numeric code and send that to the clients, which would interpret how to display the message (e.g. instead of sending "You must be a Paladin to use this skill." the server sends "35Paladin"). Originally, this was meant to cut down on the network traffic and facilitate creating graphical clients (which didn't materialize until 2016!). However, it had the nice side effect of allowing translations to other languages. This week I completed translations of Conquest! to French, German, and Spanish. It took about a week to translate the ~2000 different messages using Google Translate. When the graphical client was created in 2016, once again all of the help, prompts, and field labels were hard-coded in English. In addition to the messages from the server, all of these had to be pulled out and translated. I did look for a way to perform dynamic translations but I didn't locate a way to do this and I was wary about build an external dependency, especially given the dynamic nature of the game. Now that the plumbing is in place, creating files for additional languages requires just the translation effort (which is still a huge amount of work!). Some items (e.g. level titles, troop names, etc.) cannot be translated at this time. I'm eyeing a translation to Italian in the future but for now I'm going to take a small break (its actually mentally taxing to work on translations). |
AuthorJames has been working on Conquest! since 1993. Archives
May 2025
Categories |
RSS Feed