Dumping Achievements for an Existing Game

1. Open the game in the emulator (this downloads the existing achievements and code notes from the server).

   • Note the Game ID (or get it from the web site)

2. Select the New Script menu option in RATools, then enter the Game ID and press Search.

   • This will populate the specified file with all of the published (core) achievements for the game.

3. Select one or more achievements to dump (all will be selected initially)

4. On the right side of the window are a list of addresses referenced in the selected achievements.

   • You can give any or all of them names. For each address associated to a name, a helper function will be generated

5. Press the Create button. This will generate a new script.

6. From the File menu, select Save or Save Script As. Enter a filename and hit Save.

7. Select one of the achievements in the left-hand pane.

   • This will show the individual conditions of the achievement and the code notes associated with them.

8. Click on the "Source" link just above the conditions.

   • This will take you to the code that was generated for the achievement.

   achievement(
       title = "Dominated Grass Land", description = "Clear every stage and minigame in World 1", points = 10,
       id = 4217, badge = "04848", published = "12/28/2013 4:49:25 AM", modified = "12/28/2013 5:26:10 AM",
       trigger = bit7(0x007D04) == 1 && bit7(0x007D08) == 1 && bit3(0x007D08) == 1 && bit7(0x007D0A) == 1 && 
                 bit5(0x007D0A) == 1 && bit5(0x007D0C) == 1 && bit0(0x007D04) == 1 && bit0(0x007D08) == 1 && 
                 bit1(0x007D06) == 1 && 
                 byte(0x000727) == 0 && 
                 repeated(20, word(0x007DFC) == 10800) && word(0x007DFC) == 3879 && 
                 byte(0x000079) == 0 && byte(0x000075) == 0 && 
                 never(byte(0x000727) != 0)
   )
   

   The first 9 bit checks are the completion flags. The byte check is the world. The repeated() and word check are to ensure the player spends some time on the end of world screen. The next two bytes are coordinate checks, and the final never resets the repeated() hitcount if the player is completing a world other than the first.

   For demonstration purposes, let's simply remove everything but the world check and level 1 complete check (or whatever you feel like removing from your test achievement):

   achievement(
       title = "Dominated Grass Land", description = "Clear every stage and minigame in World 1", points = 10,
       id = 4217, badge = "04848", published = "12/28/2013 4:49:25 AM", modified = "12/28/2013 5:26:10 AM",
       trigger = bit7(0x007D04) == 1 &&
                 byte(0x000727) == 0 
   )
   

9. The hollow circle next to the achievement in the left pane will change to a half-filled circle. This indicates the generated achievement differs from the server achievement.

   • If you view the achievement, you'll see a side-by-side diff comparing the core implementation to the generated one.
   • The items on the left are were Generated. The items in the right are in Core. You should see a bunch of stuff in Core that isn't in Generated to reflect the requirements we removed.
   • You may see some half-filled circles for other achievements because the compiler eliminated some duplicate conditions or other small optimizations.

10. Right+click on the modified achievement and select Update Local. This will write the generated achievement to the "XXXX-User.txt" file, which the emulator uses for Local Achievement development.

11. In the emulator, refresh the user achievements for the game. You can use the Refresh from Disk button or reload the game from the Recent menu.

    • The achievement should show up as Modified in the achievements list.
    • The other generated achievements will not appear in the Local Achievements list unless you also Update Local for them.

12. Activate the achievement in Local Achievements and test it.

    • With our modifications, it should trigger after completing stage 1-1 (or whatever is appropriate based on the changes you made to your achievement). As this is a locally modified version of the achievement, you won't actually receive the points for completing it.
    • If it is not behaving correctly, you can further modify the script, recompile it, update local, refresh the emulator, and try again. Repeat as many times as necessary.

13. Once you feel the changes are correct, you're ready to commit the changes to the server.

    • NOTE: Do not upload the changes you've made to your test achievement. The achievement was presumably working correctly. The remaining steps are informational, and only apply if you're actually fixing a broken achievement!
    • Unfortunately, RATools does not currently support writing the updated achievement directly to the server.
    • This is actually preferred so we can do another round of testing before committing.