Achievements

From OHRRPGCE-Wiki
Jump to navigation Jump to search

Background[edit]

What are achievements?[edit]

Achievements are indicators of a player's progress through the game and/or records of special feats performed. The nature of achievements is highly varied and different games will have different desires. Common types of achievements are:

  • Milestone progress through a game (eg, completed the first level)
  • Accomplishing a difficult task (eg, collecting all types of items)
  • Doing something unusual or funny (eg, finding all ways to die outside of battle)

There are probably other classifications, but in essence they all boil down to flags that, once the relevant condition is met, will be marked on the player's profile. Typically achievements are not tied to a specific playthrough of a game, and earned acheivements remain even if a new game is started. However, the conditions to earn an achievement are typically restricted to a single playthrough. Eg, "defeat 100 goblins" must typically be done in the same save game.

This suggests another use case, which is that achievements may not be a binary "they did the thing or not". Using the "defeat 100 goblins" example, it will require keeping track of how many goblins have been defeated. A game may wish to expose the current progress at intervals ("defeat 100 goblins: 20/100") to motivate the player to continue progresing the achievement.

Finally, achievements tend to have amusing names, typically a play on words related to the subject of the achievement. For example, an achievement for finding all the hidden feathers might be named "Birds of a Feather" or similar.

How do achievements work?[edit]

Based on the information from the previous section, an achievement has three sets of important data:

  • The achievement definitions (name, icon, etc), baked into the game
  • The in-progress data (progress, etc), retained in the save file
  • The completed achievements, stored in the user's profile

Engine support status[edit]

A minimal implementation of achievements were introduced in ichorescent. Achievements work if you don't use Steam

Currently there are no script commands to read or award achievements. You must use tags to progress or award them. There is also no way to see whether an achievement has been awarded!

Initially, achievements are be tied to tags. By default, an achievement will be of type "flag", which means we care about tags being enabled. At their simplest, you might say "if Tag 6 is toggled on, then reward this achievement". Then, you might have a text box that enables Tag 6. As soon as that happens, the game will trigger the achievement.

A more complicated example is that you might have several conditions that must be met for the achievement to trigger. For example, you might need multiple tags enabled at once (eg, "Bob was rescued", "James was exorcised" and "TMC was defeated"). Achievements will let you define multiple tags that all must be enabled at once in order to trigger. Optionally, you may say that the tags "latch", which instead means "all these tags must have been enabled at least once, but not necessarily at the same time".

Getting even more complicated, you might have a condition that can be repeated. Eg, a Tag is enabled and disabled multiple times. Latching won't work, since you need to track each individual enabling. For this, you can switch the achievement to the "count" type. This allows you to define a few other properties, like a target value. The player's value for an achievement can be incremented either with tags or via a scripting command, increment achievement. Once the value reaches the target, then the achievement will trigger.

What about Steam?[edit]

If Steamworks support is enabled, you will be able to associate the Steam ID of each achievement. Then, when achievements are awarded, they will be synced with Steam. This is optional, and if Steamworks support is added to a game at a later time, previously rewarded achievements will be synced on the next game launch.

What about other platforms?[edit]

Similar features on other platforms (Xbox achievements, Playstation trophies, etc) would be nice but are not currently being planned for.

Will the OHRRPGCE have its own Achievement display?[edit]

Likely, yes, in time. Achievements added now will be tracked behind the scenes invisibly, and when the OHR can display its own achievements they will be on full display.

Using achievements[edit]

So, you want to try adding achievements to your game. Here's what you need to know:

Prerequisites[edit]

First and foremost, at the moment there is no UI for achievements in-game yet. That means that unless you are planning to release on Steam or another compatible platform, then players are not going to know they got any achievements. That is not to say you can't add them now, eventually we will add UI. But, we don't know the timeline yet.

Second, the only supported platform is Steam. We are hoping in the future to integrate with other platforms (Epic Games launcher seems likely, maybe some Android stuff? I don't know the landscape there, tbh) but those are down the road. On the bright side, we do support all platforms that Steam does, Windows, MacOS and Linux. You must be a registered Steamworks developer with an App ID to integrate. The process for doing this is beyond the scope of this document, but know that there are contracts and a $100 USD fee.

Setup Guide[edit]

1. Setting up Steamworks[edit]

You need to do two things to get Steamworks to function. First, you need to provide the Steamworks libraries. These are included in the steamworks SDK in the redistributable_bin directory. You must put the appropriate library next to game.exe, per the platform. That means steam_api.dll (32-bit version, not 64-bit) on Windows, libsteam_api.so (32 or 64 bit as appropriate) on Linux and libsteam_api.dylib on MacOS. If the library is missing, then we will not be able to initialize Steamworks.

Make sure Steam is running.

If the library is provided correctly, then in g_debug.txt (press Shift-F8 to open) you should see the text Steam initialized early on. If it can't find the library, it will instead say Running without Steam, unable to load steam_api.dll, or some other error message if something else is wrong (e.g. if Steam isn't running).

The other thing you need to do is create a file, steam_appid.txt, that contains your App ID. Place this next to the executable (e.g. game.exe). If you don't have an app id, you can use a test game's app id, 480, but you must not distribute your game with this ID.

Note: in theory, you are not meant to distribute steam_appid.txt at all, even if it has a real id, but I don't think this is a hard and fast rule.

If everything is working properly, then when you launch Game, you should see the Steam overlay come up, and Steam should show you as playing your game (or Space Wars if you used the test ID 480).

Note: in some circumstances, e.g. on Linux, you have to additionally create a shortcut in Steam to launch game.exe for the overlay to work. We are not really sure why this is, but try it if it is not otherwise working.

2. Creating your achievements[edit]

The Steam ID should match what's set in Steamworks

In Custom, go to Edit General Game Settings -> Achievements and create some achievements. Press F1 to read the help pages.

Optionally, you can add a Steam API to an achievement, and the Steam overlay will display it. If you don't, you won't see anythign when you gain an achievement!

3. Testing[edit]

Once you have inserted the achievement data, you can start testing. If everything is working then as soon as you flip on the tags, then it will give you the achievement.

In-game, you can press F8 to open the Debug Menu and then "Enable achievements debug logging". This will print some messages in g_debug.txt (press Shift-F8 to view) including when achievements are awarded, when any tag that's attached to one is toggled, when loading or saving progress, and other relevant things.

Steam achievements are permanent (by default), so rewarding achievements can be annoying to test. Fortunately, you can ask Game to remove it for you, using a command line parameter:

game --reset_platform_achievements

This will strip all achievements defined in the next loaded game from your Steam profile.

Troubleshooting[edit]

I'm not getting an achievement I was expecting![edit]

First, ensure that Steamworks is loading properly. Do you see notifications when you load game.exe saying "Open the steam overlay", etc? If not, then ensure you have provided the Steamworks binary and set up the steam_appid.txt (see above for details)

If Steamworks is loading, then double check that the expected tags are set. You can do this with the F4 debugging tool in-game. Ensure the IDs of the tags match the ones in the XML, and ensure that if you have more than one that all are set.

Next, make sure you haven't gotten the achivement already. See the Testing section above for details on how to reset Steam achievements

Finally, if all else fails check g_debug.txt. Achievement-related logging is prefixed with "achievement:". If there are any errors, double check that the format of the XML is correct and matches the example provided above.


I have another problem not covered above, or your troubleshooting didn't work[edit]

If all else fails, then please contact TMC or Mike Caron on Discord (ideally in the #engine_dev channel on the Slime Salad discord) or through the mailing list or on the Forums.