Theory

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.

  • Your accomplishment should primarily focus on the aquisition of a new skill (e.g. I filed my first bug) or the completion of a new experience (e.g. I sent my first email in Thunderbird).

  • Accomplishments should represent a piece of user's activity that is worth rewarding. Accomplishment "Use GNOME shell instead of Unity" does not reward user's activity, but his taste - definitely avoid that sort of trophies.

  • Accomplishments shouldn't cause worthless activity, nor be based upon traffic, nor be based on numerical achievements. For example if one was "Filed 10 bugs" people would just file worthless bugs, instead concentrate on the effect that the trophy would have on the project. Accomplishments should be never based on meaningless traffic, like "Posted 500 Forum Posts".

  • When you write the documentation for your accomplishment, you should always assume the reader has no knowledge of the accomplishment or the software and technologies involved. Use the 'summary' field as an opportunity to explain in detail what the accomplishment is, explain any jargon.

  • Accomplishments are exciting and positive opportunities; the tone and language we use in the documentation should be friendly and encouraging.Accomplishments should either be great fun, or provide entertaining challenges for the user. Who would want to waste his time accomplishing "Be an active commentator on all Ubuntu related blogs"?

  • Accomplishments should be family friendly. Leave out any swear/curse words or naughty language/jokes.

  • Optionally, Accomplishments should nudge people to do things that are good for the community, even if they're not fun. Things that encourage maintenance of things that are out of date or cleaning out old information should be encouraged as they help keep resources relevant.

  • One of the functions of accomplishments is encouraging users to keep learning Ubuntu. Although this rule may not apply if you are creating a set of accomplishments for your game, this is quite important for Ubuntu accomplishments. Think how much might a newcomer learn reading the description of "Became a LoCo member" accomplishment!

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

The following chapter will teach you about details of .accomplishment files.

Accomplishments/Creating/Guide/Theory (last edited 2012-08-06 22:39:50 by rafalcieslak256)