The Dice Championship project is about exploring how a simple voice app - Dice Championship - can be implemented and extended using different frameworks, platforms and services. It was initiated (and published to the Alexa Skill store) by me (Florian Hollandt), but contributions of ideas, implementations and improvements are very welcome. :)

What is this repository about?

This version of Dice Championship implements its leaderboard with Amazon GameOn (via the recently released Skills GameOn SDK).

GameOn offers a wide array of leaderboard-related features, of which this version of 'Dice Championship' uses only the following ones:

• Initializing a player
• Registering the player for a 'tournament' (i.e. the global game leaderboard)
• Registering the player for 'matches' (i.e. iteration of the game loop / dice throws)
• Submitting the player's 'score' (the sum of their dice faces) for the respective match
• Retrieve the ranking data for the player within the tournament, of which Dice Championship utilizes the rank property

Here's how the logic of this implementation differs from the base version, which implements the leaderboard with a DynamoDB table:

	Base version	GameOn version
Player metadata	Custom implementation (generating a player ID)	Provided by GameOn (initializeNewPlayer())
Evaluate only the player's highest score	Custom implementation (Store and compare values)	Provided by GameOn
Determining the player's rank	Custom implementation (DynamoDB scan operation)	Provided by GameOn (getMatchLeaderboardForPlayer())
Development environment for leaderboard	Possible with separate DynamoDB tables	Built-in environment parameter

Setting up the GameOn version

1. Setting up the project folder
   • Clone this repository, run npm install --save and make a copy of .env.example named .env. We'll use environment variables to set up all the required credentials.
     
2. Setting up GameOn
   • This project uses the same basic functions as the SDK documentation's Simple Week-Long Tournament, so you can follow the instructions there for setting up GameOn and your first tournament.
   • Set the end date of the tournament to some point in the distant future to have just one single big open-ended tournament
   • Copy and paste the following credentials into your .env file:
     • GAMEON_PUBLIC_API_KEY: The public API key your received when you registered your new game at GameOn
     • GAMEON_TOURNAMENT_ID: The tournament ID that you received after setting up a new challenge for your registered game (found in the URL of the competition detail page, as seen in the screenshot below)
     • GAMEON_MATCH_ID: The match ID, also found in the competition detail page
     • Each of these keys and IDs are uuids, so they look similar to this: 01234567-0123-0123-0123-01234567abcd.
       
       
3. Creating your Lambda function
   • Setting up a Lambda function isn't required to try out this project (you can just test locally), but it's recommended because it's interesting to see how it behaves in terms of latency, and to have a version that works any time without being restricted to when you're running your Jovo webhook
   • Open the AWS Lambda functions overview in your selected region and hit Create function.
   • Give your Lambda a Node 8.10 runtime (or above) and a basic execution role with write access to Cloudwatch logs.
   • Add 'Alexa Skills Kit' as a trigger for your Lambda function. For now you can disable the restriction to a defined Skill ID.
   • Copy the environment variables from step 2 to the Lambda's environment variable section.
   • Copy the Lambda's ARN into your local .env file, as the value of LAMBDA_ARN_STAGING (more on staging below).
4. Creating the Alexa Skill
   • This is something you could do directly in the Alexa developer console, but here we're using the Jovo CLI because it's super convenient. So be sure to have the Jovo CLI installed and optimally your ASK CLI and AWS CLI profiles set up.
   • Write the name of the ASK CLI profile you plan to use into your local .env file as e.g. ASK_PROFILE='default'.
   • Now execute jovo build -p alexaSkill --stage local --deploy from your command line. This builds the Skill manifest (platforms/alexaSkill/skill.json) and language model (platforms/alexaSkill/models/en-US.json) from the information in the project configuration file (project.js) and the Jovo language model (models/en-US.json), and uses them to set up a new Skill 'Dice Tournament' in your Alexa developer console.
     The result should look like this:
     
     
   • Now copy the Skill ID from the console output and paste it as the value of the SKILL_ID_STAGING variable in your .env file.
   • Execute jovo run --watch from your command line to activate your local endpoint

Congrats, you've already set up the Skill on your machine

You can already test your Skill in the Alexa developer console, or on your device by saying "Alexa, open Dice Tournament"!

The remaining steps are optional, but recommended. Before we proceed to uploading the Skill to Lambda, let's review the staging setup.

6. Reviewing the staging setup
   • This project comes with a setup for three stages, to propagate good practices and let you try out things both locally and on Lambda, because it might behave differently (e.g. in terms of latency)

   Name	Description	Environment + Endpoint	GameOn environment	Skill ID	Invocation name	Skill icon
   local	Local endpoint for rapid development + debugging	${JOVO_WEBHOOK_URL}	development	SKILL_ID_STAGING	dice tournament
   staging	Lambda endpoint for testing on a production-like environment	LAMBDA_ARN_STAGING	development	SKILL_ID_STAGING	dice tournament
   live	Lambda endpoint for fulfillment of the live Skill	LAMBDA_ARN_LIVE	production	SKILL_ID_LIVE	dice championship

7. Uploading your Skill code to Lambda
   • After having reviewed the staging setup, it's clear that uploading your Skill to Lambda is as easy as building and deploying the staging stage of your project.
   • To be able to upload your code to Lambda with the Jovo CLI, make sure your AWS CLI profile is linked to your ASK CLI profile, and has Lambda upload privileges
   • Now all you need to do it execute jovo build -p alexaSkill --stage staging --deploy
   • The result should look like this:
     
     
   • Again, you can now test your Skill in the Alexa developer console just like after step 5, in the same Skill
8. Preparing and deploying the live stage
   • I'll cover this part more briefly than the ones before, because it's more about deployment than about getting this Skill to work
   • First, you need a new Lambda function - Just set one up like in step 4 (with the same role, trigger and environment variables), and copy its ARN as the value of LAMBDA_ARN_LIVE in your .env file
   • To use production settings for your GameOn tournament, all you need is to
   • To set up the new Skill (using the new Lambda endoint, the invocation name 'dice championship', and an expanded version of the manifest including a different Skill icon), execute jovo build -p alexaSkill --stage live --deploy.
   • After the first deployment, copy the new Skill's ID and paste it as the value of SKILL_ID_LIVE in your .env file

Investigating your leaderboard

Before checking your leaderboard, it makes sense to play some sessions so it's already populated. What's the highest score you can roll? 🎰

To see the items of your leaderboard in detail, simply go to your GameOn overview page, find the according game and competition/tournament, and click on the 'Details' link (as seen in the screenshot below). This will take you directly to the leaderboard.

Wrapping it up

I hope you find both this entire project and the individual variants interesting and valuable. Again, if you like this project and want to see it implementing your favorite platform, service or feature, please get in touch or start implementing right away.