Difference between revisions of "Compo4AllSDK"

From Pandora Wiki
Jump to: navigation, search
(Compo4All API Guide)
 
(→‎Getting the execution info)
 
(9 intermediate revisions by the same user not shown)
Line 14: Line 14:
 
Sending a HTTP GET request to [http://skeezix.wallednetworks.com:13001/curgamelist_1 /curgamelist_1] will return you a list of games, and details of those games
 
Sending a HTTP GET request to [http://skeezix.wallednetworks.com:13001/curgamelist_1 /curgamelist_1] will return you a list of games, and details of those games
  
 +
The JSON response will be an array of dictionairies (one dictionairy per game.)
 +
 +
The dictionaries will include at least the following fields for each game:
 +
  - gamename -> the 'short name' of the game; for MAME, it is the driver name ('dkong') and not generally for display; it is a unique-id (unique within C4A)
 +
  - longname -> the readable display name ('Donkey Kong')
 +
  - status -> current status options include:
 +
    - available -> show in frontends, available for scoring etc
 +
    - active -> show in frontends (and highlight or in their own tab?), is actively in the ROT tournament or highlight right now (but is otherwise same as available)
 +
    - wip -> do not show in frontend; available for scoring and functionality identical to 'active', but for developers to test their code prior to finalization
 +
  - genre -> the 'type' of game (at a high level); current values are..
 +
    - platform
 +
    - maze
 +
    - runngun
 +
    - shmup
 +
    - strategy
 +
    - ... we can add more - to be determined
 +
  - field -> the 'kind' of game it is, the platform; current values are
 +
    - arcade -> implies c4a-mame will be used
 +
    - indie -> means standalone; it will contact c4a, but not be part of c4a-mame
 +
    - TBD
  
 
=== Getting the Score Board ===
 
=== Getting the Score Board ===
Line 19: Line 39:
 
Requesting [http://skeezix.wallednetworks.com:13001/json_1/bublbobl /json_1/(gamename)] will return you scoreboard details
 
Requesting [http://skeezix.wallednetworks.com:13001/json_1/bublbobl /json_1/(gamename)] will return you scoreboard details
  
 +
  - You can also pull a simple HTML (ASCII) dump: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/
 +
  - Getting previous months can use backdating for both JSON and ASCII pulls; for example: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/201304/
 +
 +
The scoreboard is an array of dictionairies, one dict per score entry.
 +
 +
The dictionairies will include at least:
 +
  - shortname -> the player's shortname (initials)
 +
  - longname -> the player's long name (display name)
 +
  - hi -> the actual score number (for single-score style of games); TBD for time-attack, and other kinds of games
 +
  - time -> the epoch time the event occured
 +
 +
=== Getting the execution info ===
 +
 +
The execinfo request will get you some details so you can actually run the application needed for a given game. The url form is:
 +
 +
Example: skeezix.wallednetworks.com:13001/execinfo_1/microbes/pandora
 +
 +
Example return:
 +
  - command_line_add": ""
 +
  - "file_dependancies_hint": "",
 +
  - "last_known_filename_hint": "microbes1.0rel2-1.pnd"
 +
  - "pnd_unique_id": "microbes.wb.mainapp"
 +
  - "type": "standalone"
 +
  - "last_known_appdata_hint": "microbes"
 +
 +
File dependancies could be things like "roms/dkong.zip" for a MAME dependancy, say.
 +
 +
Command line add could be: "--c4a --game foo" or whatever the application needs to tell it we're running from a c4a frontend.
 +
 +
The actual invocation could be done a number of ways, such as by using pnd_run or pnd_run.sh directly; you can use libpnd (built into the firmware) for all the heavy lifting .. it has utility functions for most everything you need.
 +
 +
Some quick off-memory pseudocode follows-- though its so close it would nearly compile:
 +
 +
<code>
 +
Now, libpnd gives you everything you need to run stuff, but you have to call a few functions.. its not all rolled into one.
 +
 +
Why?
 +
 +
Because it lets you be efficient; your steps are usually..
 +
i) Ask it to find pnd_run.sh <- you can skip it, and use the firmware path if you want
 +
ii) Ask it for a path set from config <- you can skip it, hardcode it if you like: the fw conf is:
 +
/media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps
 +
- you feed that to the discovery function
 +
iii) Ask it to run a discovery (return all apps within a path set)
 +
--> keep this value; it returns a 'box', a linked list, save it so that you don't have to re-discover for every run; discover once, and then you are run-instantly next run
 +
iv) for loop over the result list, looking for unique-id match
 +
v) ask libpnd to run the entry you found (just pass the box pointer into the run function)
 +
 +
Its pretty easy for me anyway :) All you need is steps 3-5.
 +
 +
If I roll you a utility 'run the damned pnd' function, it'll be doing all that stuff every time... pretty inefficient.
 +
 +
The code would be like this:
 +
 +
Given char *my_unique_id that you know from the server.
 +
 +
#include "pnd_pxml.h"
 +
#include "pnd_utility.h"
 +
#include "pnd_conf.h"
 +
#include "pnd_container.h"
 +
#include "pnd_discovery.h"
 +
#include "pnd_apps.h"
 +
 +
// run a discovery
 +
pnd_box_handle g_active_apps = NULL;
 +
char *searchpath = "/media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps" <- from conf file!
 +
 +
g_active_apps = pnd_disco_search ( searchpath, NULL ); <- keep this value for the life of the frotnend session
 +
 +
if ( ! g_active_apps ) {
 +
printf ( life is hell )
 +
return ( sucks )
 +
}
 +
 +
pnd_disco_t *a = pnd_box_get_head ( g_active_apps );
 +
void *nexta = NULL;
 +
 +
while ( a ) {
 +
nexta = pnd_box_get_next ( a );
 +
 +
if ( strncmp ( a -> unique_id, my_unique_id, strlen ( my_unique_id ) ) == 0 ) {
 +
// found disco-t entry, run it
 +
 +
ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, 0 /* options */, NULL );
 +
if ( ret ) .....
 +
 +
}
 +
 +
a = nexta;
 +
}
 +
 +
..
 +
 +
Thats it :)
 +
 +
Now, the pnd_run.sh path might be wrong, I dont' sleep much :)
 +
 +
....
 +
 +
Now, you want to pass args.. theres some params to pnd_apps_exec_disco() so you can pass it args, I think:
  
 +
pnd_apps_exec_info_t extra;
 +
extra.args = "--game foo"
 +
then pass PND_EXEC_OPTION_INFO into the 'args' bit instead:
 +
 +
ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, PND_EXEC_OPTION_INFO /* options */, &extra );
 +
 +
That should do it, but I'm going from memory. Still, thats pretty damned close pseudo-code... probably compiles ;)
 +
</code>
  
 
== Game Developer ==
 
== Game Developer ==
Line 27: Line 155:
 
The [http://boards.openpandora.org/index.php/topic/12127-release-compo4all-mame-ladderscoreboard-competition-for-classic-arcade-games/page-18#entry237182 Spaghetti Client] can be downloaded from the thread, and you can easily submit scores by starting a process with the following command line (assuming sc is bundled in your working directory)
 
The [http://boards.openpandora.org/index.php/topic/12127-release-compo4all-mame-ladderscoreboard-competition-for-classic-arcade-games/page-18#entry237182 Spaghetti Client] can be downloaded from the thread, and you can easily submit scores by starting a process with the following command line (assuming sc is bundled in your working directory)
  
−
<source lang="bash">./sc MODE OPERATION GAMENAME PLATFORM SCORE</source>
+
The paramater's vary by module;
 +
 
 +
An example for the 'scoreonly' simple module is:
 +
<source lang="bash">./sc MODULE OPERATION GAMENAME PLATFORM SCORE</source>
 +
 
 +
Platform: Currently 'pandora' should be specified
  
 
==== SC Modes ====
 
==== SC Modes ====
Line 50: Line 183:
 
! pull
 
! pull
 
! Get data from the server (not implemented)
 
! Get data from the server (not implemented)
 +
|}
 +
 +
==== SC Exec Return Values ====
 +
{| border="1"
 +
|-
 +
! Value
 +
! Description
 +
|-
 +
! 0
 +
! All seemed well
 +
|-
 +
! -1
 +
! General error (such as bad arguments to sc); maybe failure to get RAM; possibly a problem with plugins (scoreonly module submissions.)
 +
|-
 +
! -2
 +
! Could not write file that was pulled; coudl not find player profile
 +
|-
 +
! -3
 +
! For a file dependancy (such as MAEM ./hi file), file could not be found/opened
 
|}
 
|}

Latest revision as of 00:27, 11 May 2013

Compo4All API Guide

Overview

All information from the server is transfered by the HTTP protocol, so you can use libraries such as libcurl to handle all that work. Information is passed using the JSON markup language


Launcher Developer

Getting the Games List

Sending a HTTP GET request to /curgamelist_1 will return you a list of games, and details of those games

The JSON response will be an array of dictionairies (one dictionairy per game.)

The dictionaries will include at least the following fields for each game: 

 - gamename -> the 'short name' of the game; for MAME, it is the driver name ('dkong') and not generally for display; it is a unique-id (unique within C4A)
 - longname -> the readable display name ('Donkey Kong')
 - status -> current status options include:
   - available -> show in frontends, available for scoring etc
   - active -> show in frontends (and highlight or in their own tab?), is actively in the ROT tournament or highlight right now (but is otherwise same as available)
   - wip -> do not show in frontend; available for scoring and functionality identical to 'active', but for developers to test their code prior to finalization
 - genre -> the 'type' of game (at a high level); current values are..
   - platform
   - maze
   - runngun
   - shmup
   - strategy
   - ... we can add more - to be determined
 - field -> the 'kind' of game it is, the platform; current values are
   - arcade -> implies c4a-mame will be used
   - indie -> means standalone; it will contact c4a, but not be part of c4a-mame
   - TBD

Getting the Score Board

Requesting /json_1/(gamename) will return you scoreboard details 

 - You can also pull a simple HTML (ASCII) dump: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/
 - Getting previous months can use backdating for both JSON and ASCII pulls; for example: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/201304/

The scoreboard is an array of dictionairies, one dict per score entry.

The dictionairies will include at least: 

 - shortname -> the player's shortname (initials)
 - longname -> the player's long name (display name)
 - hi -> the actual score number (for single-score style of games); TBD for time-attack, and other kinds of games
 - time -> the epoch time the event occured

Getting the execution info

The execinfo request will get you some details so you can actually run the application needed for a given game. The url form is:

Example: skeezix.wallednetworks.com:13001/execinfo_1/microbes/pandora

Example return: 

 - command_line_add": ""
 - "file_dependancies_hint": "",
 - "last_known_filename_hint": "microbes1.0rel2-1.pnd"
 - "pnd_unique_id": "microbes.wb.mainapp"
 - "type": "standalone"
 - "last_known_appdata_hint": "microbes"

File dependancies could be things like "roms/dkong.zip" for a MAME dependancy, say.

Command line add could be: "--c4a --game foo" or whatever the application needs to tell it we're running from a c4a frontend.

The actual invocation could be done a number of ways, such as by using pnd_run or pnd_run.sh directly; you can use libpnd (built into the firmware) for all the heavy lifting .. it has utility functions for most everything you need.

Some quick off-memory pseudocode follows-- though its so close it would nearly compile:

Now, libpnd gives you everything you need to run stuff, but you have to call a few functions.. its not all rolled into one.

Why?

Because it lets you be efficient; your steps are usually.. i) Ask it to find pnd_run.sh <- you can skip it, and use the firmware path if you want ii) Ask it for a path set from config <- you can skip it, hardcode it if you like: the fw conf is: /media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps - you feed that to the discovery function iii) Ask it to run a discovery (return all apps within a path set) --> keep this value; it returns a 'box', a linked list, save it so that you don't have to re-discover for every run; discover once, and then you are run-instantly next run iv) for loop over the result list, looking for unique-id match v) ask libpnd to run the entry you found (just pass the box pointer into the run function)

Its pretty easy for me anyway :) All you need is steps 3-5.

If I roll you a utility 'run the damned pnd' function, it'll be doing all that stuff every time... pretty inefficient.

The code would be like this:

Given char *my_unique_id that you know from the server.

  1. include "pnd_pxml.h"
  2. include "pnd_utility.h"
  3. include "pnd_conf.h"
  4. include "pnd_container.h"
  5. include "pnd_discovery.h"
  6. include "pnd_apps.h"

// run a discovery pnd_box_handle g_active_apps = NULL; char *searchpath = "/media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps" <- from conf file!

g_active_apps = pnd_disco_search ( searchpath, NULL ); <- keep this value for the life of the frotnend session

if ( ! g_active_apps ) { printf ( life is hell ) return ( sucks ) }

pnd_disco_t *a = pnd_box_get_head ( g_active_apps ); void *nexta = NULL;

while ( a ) { nexta = pnd_box_get_next ( a );

if ( strncmp ( a -> unique_id, my_unique_id, strlen ( my_unique_id ) ) == 0 ) { // found disco-t entry, run it

ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, 0 /* options */, NULL ); if ( ret ) .....

}

a = nexta; }

..

Thats it :)

Now, the pnd_run.sh path might be wrong, I dont' sleep much :)

....

Now, you want to pass args.. theres some params to pnd_apps_exec_disco() so you can pass it args, I think:

pnd_apps_exec_info_t extra; extra.args = "--game foo" then pass PND_EXEC_OPTION_INFO into the 'args' bit instead:

ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, PND_EXEC_OPTION_INFO /* options */, &extra );

That should do it, but I'm going from memory. Still, thats pretty damned close pseudo-code... probably compiles ;)

Game Developer

Spaghetti Client

The Spaghetti Client can be downloaded from the thread, and you can easily submit scores by starting a process with the following command line (assuming sc is bundled in your working directory)

The paramater's vary by module;

An example for the 'scoreonly' simple module is: 

./sc MODULE OPERATION GAMENAME PLATFORM SCORE

Platform: Currently 'pandora' should be specified

SC Modes

Mode Description
so Sends the Score only

SC Operations

Operation Description
push Sending data to the server
pull Get data from the server (not implemented)

SC Exec Return Values

Value Description
0 All seemed well
-1 General error (such as bad arguments to sc); maybe failure to get RAM; possibly a problem with plugins (scoreonly module submissions.)
-2 Could not write file that was pulled; coudl not find player profile
-3 For a file dependancy (such as MAEM ./hi file), file could not be found/opened
Retrieved from "https://pandorawiki.org/index.php?title=Compo4AllSDK&oldid=27139"