<> <> = The Theory Behind Accomplishments = Before we start creating accomplishments, you need to learn a bit about the Accomplishments System. Don't worry, we will not explain how it is all implemented; we just need to cover what an accomplishment actually is, how we check if it has been accomplished, why some accomplishments need to be verified by an external server, and what is being done "behind the scenes". == Accomplishment guidelines == There is a set of tips on how to ensure your accomplishments are of top quality, are useful for the community, and reduce the chances of people gaming the system. We don't want to create accomplishments that people can achieve by repetatively generating pointless content, but instead focus on ''new experiences and skills''. If you want your accomplishments to be included in one of the official accomplishment collections, your accomplishments should follow these guidelines. Make sure your trophy ideas are appropriate. Following criteria will be helpful. <> Keeping the above rules in mind, let's see how the accomplishments are organised from the technical side. == Accomplishment components == Every accomplishment contains two pieces: * An '''.accomplishment''' file. * This file contains information about a particular opportunity and how it is accomplished. This contains some important information that we use to categorize accomplishments, as well as the documentation displayed to users to explain how to accomplish it. * An '''executable script'''. * This is a script used to determine whether the user has accomplished this accomplishment. Currently this has to be a Python script, but we hope to allow other languages to be supported too. How are these to bound to each other? Just ensure to give them the same name, the Accomplishments System will take care of properly matching the accomplishment data and the script. Example: Accomplishment "Report first bug" from the `ubuntu-community-accomplishments` collection contains two files: "'''report-first-bug'''.accomplishment" and "'''report-first-bug'''.py". This shared naming means they are the same accomplishment. This also means that it is important for accomplishments to '''have unique names''' within one accomplishments '''set'''. In the next few chapters we will explore how to create such files. == Global and Local accomplishments == There are two types of accomplishment based on their range. * '''Local''' accomplishments are those that are performed on a user's system. These can be verified only on the user's machine. Examples include "Complete Level 1" or "Change Your Desktop Wallpaper". Such accomplishments are awarded to the user as soon as the Ubuntu Accomplishments System runs it's script, and the script determines the accomplishments has been completed. * Global accomplishments are those that are done outside user's system. These include user's activity in a community, e.g. "Report First Bug" or "Member of a LoCo Team". As these accomplishments are within a social context, they need to be verified and the procedure of accomplishing them is slightly different. After the scripts have been run on user's machine and an accomplishment has been achieved, the Ubuntu Accomplishments System '''asks the validation server''' to confirm that the user has indeed completed that accomplishment. The server runs exactly the same script, and if the user has indeed completed given accomplishment, it sends him a signed trophy file, and only then the user is awarded a trophy. This way the system is more cheat-proof. Fortunately, from the perspective of creating accomplishments, you don't have to do anything special for the verification process: just follow the instructions in this guide. Note that in order to have some global accomplishments working they need to be installed on the validation server. Ask Jono Bacon if you want so. Of course the server has installed the official accomplishments collections, so if you are contributing to one of them, we will take care of setting the server properly. '''Warning''': Local accomplishments are not working in 0.1 release. This has been fixed and will be supported in 0.2, but as for now you need to use daily builds PPA (or source from trunk) if you want to play with local accomplishments. == Extra Information == Some accomplishments require user's credentials to verify their completion. For 'Report First Bug' in Launchpad we obviously need to know the user's Launchpad ID to check whether he or she has indeed reported a bug. The credentials that accomplishments need are called ''extra-information'', be it `launchpad-email`, `forums-login`, `askubuntu-ID` - whatever is needed. * Note that all global accomplishments have to require some extra-information. Only these accomplishments that are verifiable using any sort of credentials may be validated using an external server, for it has no access to the user's system. You do not need to worry about asking the user to type in their credentials, the accomplishments viewer takes care of that automatically. The Accomplishments System provides easy access to all that credentials for your scripts, so if your accomplishments require some extra-information, you just have to specify that in .accomplishment file, and the daemon will pass that information to the script. All extra information is stored in `~/.local/share/accomplishments/trophies/.extrainformation/` directory. It contains files of appropriate name, and 1-line contents. For example, my `~/.local/share/accomplishments/trophies/.extrainformation/launchpad-email` contains `rafalcieslakXYZ@gmail.com`. Not all accomplishments require extra-information. For example, checking high scores in a game can be done by simply reading certain file, no need to use any credentials. == Next == [[Accomplishments/Creating/Guide/AccomplishmentFile|The following chapter]] will teach you about details of .accomplishment files.