Trophy Case for developers

Achievements are a great way to engage players and encourage them to explore your game's content by setting rewarding goals. Designing achievements well and adopting the standard format means your players get a great achievements experience both in your game and in Trophy Case.

Getting started

You can add your game's achievements to Trophy Case by writing a JSON file and optional supporting artwork to the shared directory on Playdate, adopting the standard format.

The standard format for achievements is available as a JSON schema document in the pd-achievements repo on GitHub. The repo also includes a reference implementation library in Lua.

Designing great achievements

Achievements work best when they reflect a thorough exploration of your game's objectives and content. They should be challenging but realistically achievable, and you should carefully consider which achievements you include.

Non-trivial

Unlike other platforms, achievements on Playdate are not required, nor are there minimum requirements for the number of achievements you include. Avoid padding out your achievements list with achievements like opening the game for the first time or completing the required tutorial.

This doesn't mean you shouldn't include achievements that are too easy, but you should strive to make them meaningful.

Inclusive

Players might play your game in many different circumstances. Carefully consider the requirements for unlocking your achievements, especially if they rely on external conditions like time or location. Avoid:

• Achievements that present only a single chance to be unlocked. For example, completing a level flawlessly on your first attempt.
• Achievements that can only be unlocked before a certain date or a specific time period. For example, completing the game before the end of 2025. These achievements cannot be unlocked by players who play your game in the future.

Enduring

Just like the rest of your game, achievements should be designed to last. Carefully consider any achievements that rely on external services or APIs—including Panic services.

The internet is fleeting, and these services will not always be available in the future. When these services go offline, your achievements may become impossible to unlock.

Realistic

Achievements should present opportunities for players to achieve something meaningful within the context of your game. Increasing the difficulty of an achievement by arbitrarily increasing the number of repeated steps required to complete it is unlikely to present a meaningful challenge.

Consider a game that has daily challenges—a gameplay loop that varies algorithmically based on the date and changes every day. An achievement that requires players to complete seven daily challenges is realistic and presents a great opportunity to showcase the feature and encourage meaningful engagement.

Changing the requirements to require completing 365 daily challenges technically makes the achievement more difficult to complete, but it isn't realistically achievable for most players, who will be less likely to attempt it as a result.

In a similar vein, multiple achievements that have the same requirements which vary only in quantity are unlikely to add value to your achievements lineup.

Artwork

Bundles can provide optional supporting artwork for achievements.

For bundles, the card image and icon image have the same requirements as the Catalog wide app banner and app list icon. If you have these assets ready, re-using them can save time and effort.

Individual achievements can also have their own unique icons, which have the same requirements as the bundle icon image. If each of your achievements relates to a distinct visual element in your game, this is a good place to showcase it. Remember that achievement icons are entirely optional—avoid using generic icons just to populate this field.

Handling achievements data

Save your achievements data to the shared directory when exiting your game, even if none were unlocked, so that Trophy Case can display intermediate progress for your achievements and detect when your game was last played.

Copying images to the shared directory can be an expensive operation. Avoid doing it more often than necessary. If you're using a library to manage your achievements, it will likely handle this for you.

Keep your achievements data consistent—no data in your achievements list, except for the progress and unlock date fields, should change within the same build of your game. Trophy Case expects this data to be consistent, and changing it may make certain features like sharing unavailable for your game, or cause it to not appear in Trophy Case.

Adding and changing achievements after release

If you choose to change the contents of your achievements in an updated version of your game, your game is responsible for migrating that data.

If you're adding achievements to your game for the first time, consider adding a one-off migration function that will retroactively unlock and increment achievements based on the player's saved data.

Handling save slots

Like many handheld gaming consoles, Playdate is a single-user system that provides no common way to differentiate between or manage players. Achievements exist as system-wide shared data that isn't partitioned between users. If you choose to implement a save slot system for your game, you should similarly treat achievements as game-wide.

Achievements should be cumulative across all game slots; achievements unlocked in any slot contribute to a shared list. Don't change the progress of achievements your game shares based on the loaded save slot; this means that when another player uses the Playdate, the data you've shared will be for the wrong player until they launch your game again.