[Ocs] First draft of Achievements module

[Dan Leinir Turthra Jensen]

Hi people!

  As some of you know already, the Gluon project, in particular the 
GamingFreedom.org site, is basing its social interaction features on OCS. 
Since we are all about gaming, we will obviously be needing some achievement 
system. However, rather than simply jumping at it and creating something 
useful only for games, with Frank Karlitschek's blessing i have spent the last 
couple of days working on a first draft of the specification for an OCS 
extension module for achievements. Please find this draft in the attached txt 
file.
  Now, i would very much like to get to work on this ASAP, and so: If any of 
you out there have an interest in something like this, please get back with 
any comments about the draft specification, and i shall do my best to take it 
into account. Also, if you want to discuss it directly with me, i'm on IRC as 
leinir on the #gluon channel on Freenode.

-- 
..Dan // Leinir..
http://leinir.dk/

                          Co-
                            existence
                          or no
                            existence

                          - Piet Hein
-------------- next part --------------
== Achievements ==

An achievement is a concept first developed for use in video games, whereby a meta-goal existing outside of the normal gameplay is defined as having a value in itself. In the world of online social interaction, these become a way of measuring your own progress through a game in a different way, adding another layer on top of the traditional methods of levels or quests. This module is a generalised system which allows for achievements to be attached to any OCS content item, which means it also becomes useful for other applications. It is left up to the user of this API to choose which those are, but a couple of tricks for designing good achievements follow:

* Consider the distribution of achievements throughout the application and ensure that are positioned deliberately. This will encourage the users to try and reach parts of the application that they might have otherwise not known about.
* Do not take the simple options only, ensure that there are non-obvious achievements to be found in odd corners. Note that while this can assist the users in achieving further knowledge of the application's possibilities, you should not allow this to let you fall into creating applications with obscure work flows.
* Build achievements which can be reached by users of any skill level. This is more important in video games, but it is still useful in other applications.
* In particular in video games, achievements which have been reached can be responded to in various ways. This then allows for the achievement to become more than a simple trophy or medal.

==== list ====

List achievements for a piece of content. Optionally with progress data for a specified user.

* Syntax: /v1/achievemt/list/"contentid"
* HTTP method: GET
* URL argument: contentid - The ID to query on.
* GET argument: userid - Show the progress that the specified user has in each returned achievement. If the user has made no progress in a specific achievement, that achievement will not have a progress field.
* Mandatory fields: "contentid"
* Result: achievements list xml. Each achievement contains the following items:
  * id - The achievement's ID, as unique to the local service
  * contentID - The ID of the content item the achievement is tied to
  * name - A short, human readable name
  * description - A teaser style description
  * explanation - A description normally only visible to those who have succeeded in fulfilling the achievement completely
  * points - The number of points which will be added to the user's score once the achievement is fully completed
  * image - A url pointing to an image symbolising the achievement
  * dependenton - A list of achievement IDs that this achievement is dependent on. The list can be empty.
  * visibility - When to show the achievement to the user. The possible values are:
    * visible - always shown
    * dependents - shown when the dependents are all completed
    * secret - hidden until the user begins to progress on the achievement
  * progress - optional. A floating point value between 0 and 1, with 0 meaning progress has been started, and 1 meaning completed.
* Statuscodes:
  * 100 - success
  * 101 - no such content ID
  * 102 - no such user

Example: GET http://api.opendesktop.org/v1/achievement/list/1234&userid=frank

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <achievements>
      <achievement>
        <id>12</id>
        <contentID>1234</contentID>
        <name>The Great Thing</name>
        <description>Great things are afoot</description>
        <explanation>A great thing which will help you with other things.</explanation>
        <points>15</points>
        <image>http://opendesktop.org/content/achievements/images/12.png</image>
        <dependenton />
        <visibility>visible</visibility>
        <progress>1</progress>
      </achievement>
      <achievement>
        <id>321</id>
        <contentID>1234</contentID>
        <name>The Greater Thing</name>
        <description>Even greater things are afoot</description>
        <explanation>Incredible things have been achieved.</explanation>
        <points>25</points>
        <image>http://opendesktop.org/content/achievements/images/321.png</image>
        <dependenton>
          <achievementid>12</achievementid>
        </dependenton>
        <visibility>dependents</visibility>
      </achievement>
    </achievements>
  </data>
</ocs>

==== listforuser ====

List achievements that a user has progress on. Optionally filtered by a specified content item, so only achievements reached on that piece of content are shown. 

* Syntax: /v1/achievemt/listforuser/"userid"
* HTTP method: GET
* GET argument: userid - The ID to show achievement progress for. Only items which have a progress will be shown.
* URL argument: contentid - A content ID to filter the search by. If defined, only items for this ID will be returned.
* Mandatory fields: "contentid"
* Result: achievements list xml. See achievement/list for description of items.
* Statuscodes:
  * 100 - success
  * 101 - no such user
  * 102 - no such content ID

Example: GET http://api.opendesktop.org/v1/achievement/list/1234&userid=frank

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <achievements>
      <achievement>
        <id>12</id>
        <contentID>1234</contentID>
        <name>The Great Thing</name>
        <description>Great things are afoot</description>
        <explanation>A great thing which will help you with other things.</explanation>
        <points>15</points>
        <image>http://opendesktop.org/content/achievements/images/12.png</image>
        <dependenton />
        <visibility>visible</visibility>
        <progress>1</progress>
      </achievement>
    </achievements>
  </data>
</ocs>

==== add ====

Add a new achievement tied to a piece of content. Only the owner of that content item is allowed to add achievements on it. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

* Syntax: /v1/achievement/add
* HTTP method: POST
* POST argument: contentID
* POST argument: name
* POST argument: description
* POST argument: explanation
* POST argument: points
* POST argument: image - a local file, the badge for the achievement
* POST argument: dependenton - no depencies by default
* POST argument: visibility - by default, the visibility is "visible"
* Mandatory fields: contentID, name, description, explanation, points
* Result: achievement ID xml
* Statuscodes:
  * 100 - success
  * 101 - no such content ID
  * 102 - authorised user is not owner of content item represented by content ID
  * 103 - missing required data field (includes names of fields)

Example: POST http://frank:password@api.opendesktop.org/v1/achievement/add postdata: contentID=1234 name=Something description="A description" explanation="An explanation" points=12 image=@imagefile.png dependenton[0]=12 dependenton[1]=13

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <achievementid>15</achievementid>
  </data>
</ocs>

==== edit ====

Edit an existing achievement. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

* Syntax: /v1/achievement/edit/"achievementid"
* HTTP method: POST
* URL argument: achievementid - The ID of the achievement being edited
* POST argument: name
* POST argument: description
* POST argument: explanation
* POST argument: points
* POST argument: image - a local file, the badge for the achievement
* POST argument: dependenton - no depencies by default
* POST argument: visibility - by default, the visibility is "visible"
* Mandatory fields: achievementid, contentID, name, description, explanation, points
* Result: status xml
* Statuscodes:
  * 100 - success
  * 101 - no such content ID
  * 102 - authorised user is not owner of content item represented by content ID

Example: POST http://frank:password@api.opendesktop.org/v1/achievement/edit/15 postdata: name="Something Else"

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

==== remove ====
Delete an achievement and all progress on it on all users. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

* Syntax: /v1/achievement/remove/"achievementid"
* HTTP method: POST
* URL argument: achievementid - the ID of the achievement to be removed
* Mandatory fields: achievementid
* Result: status xml
* Statuscodes:
  * 100 - success
  * 101 - no such content ID

Example: POST http://frank:password@api.opendesktop.org/v1/achievement/remove/15

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

==== setreached ====

Set the authorised user's progress on a specified achievement. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

* Syntax: /v1/achievement/setreached/"achievementid"/"progress"
* HTTP method: POST
* URL argument: achievementid - the ID of the achievement to set progress for
* URL argument: progress - A floating point value from 0 to 1 inclusive, describing how far along the player is in completing this achievement. You cannot set a progress value lower than the existing progress for this achievement.
* Mandatory fields: achievementid, progress
* Result: status xml
* Statuscodes:
  * 100 - success
  * 101 - no such achievement
  * 102 - progress value attempted to be used, please ensure it is between 0 and 1
  * 103 - dependent achievements not reached

Example: POST http://frank:password@api.opendesktop.org/v1/achievement/setreached/15/0.7

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

==== reset ====

Reset the authorised user's progress on a specified achievement. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

* Syntax: /v1/achievement/reset/"achievementid"
* HTTP method: POST
* URL argument: achievementid - the ID of the achievement to set progress for
* Mandatory fields: achievementid
* Result: status xml
* Statuscodes:
  * 100 - success
  * 101 - no such achievement

Example: POST http://frank:password@api.opendesktop.org/v1/achievement/reset/15

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>