Editing Getting Started with CLOT

[[CLOT]] is a framework that allows players to create their own automated ladders or tournaments.  This page walks you through how to get started making your own.

== How it works ==

Fundamentally, CLOT is source code that powers a website.  The website primarilly serves the following functions:
* Allows players to join and leave the CLOT
* Creates games between players who have signed up to the CLOT
* Determines and displays the state of the tournament or ladder (shows player's ladder ranks or draws a tournament bracket, for example)

The framework provided is only a skeleton that provides a very simple implementation of a ladder.  It simply matches up players randomly, and gives out ranks based on who won the most games.  It's expected you will modify this to implement your own system.

== Google App Engine ==

The framework provided is set up to work under Google App Engine (GAE).  GAE is a great choice for the following reasons:

* All of the website components (database, logging, e-mail, cache, indexes, etc.) are all integrated into one package making setup and sharing of code easy.
* GAE takes care of deployment and scaling for you, making the site practically maintenance-free.
* It's free!  As long as traffic doesn't get out of hand (which it shouldn't for a CLOT website), GAE doesn't charge anything.

If you don't want to use GAE, you can always port CLOT to your preferred hosting environment.

== Installation == 

This section shows you how to set up a CLOT website on your own computer so you can start developing your own.

# Download and install Python 2  (http://www.python.org/download/)
# Download and install Google App Engine SDK for Python  (https://developers.google.com/appengine/downloads)
# Download CLOT from https://github.com/FizzerWL/CLOT (click the Zip button at the top and then extract it to a directory)
# Run the Google App Engine Launcher
# Select File -> Add Existing Application
# Enter the name of the directory you extracted CLOT to
# Select the app and click Run.  Wait a moment as it starts.
# Click Browse to launch the website in your local browser.

That's it!  You're up and running.  Now you can play around with the website, crack open the code, and figure out how it all works.

== Using Test Mode ==

If you look in api.py, there’s a line that says TestMode = False. By changing this to True, you’ll enable test mode which allows you to test your app offline using fake data.

In test mode, the app won’t hit warzone.com APIs at all, and instead when the code tries to call an API, it will return fake data. This is useful while building your app since you can easily simulate players signing up and see how games get created with them. You can do things like simulate 500 players signing up to your tournament, which would be very time consuming to do by hand.

There's also a page, at '''/test''' that helps invoke your code. This page is only accessible while TestMode is True.  To access it, just visit /test/<lotid>.  The easiest way to get there is to visit a lot in your browser, and change your browser's url from '''/lot/1234567''' to '''/test/1234567'''.

When you’ve got everything working perfectly, all you have to do is set TestMode back to False and release!

== Setting up Authentication ==

The CLOT framework uses the [[CLOT Authentication]] system to ensure that players are who they say they are.  By using this system, it ensures that players can only join or leave the CLOT themselves and can't, say, remove other people from a ladder.

To set this up, it requires two additional configuration changes.

# While logged into your main Warzone account, visit https://www.warzone.com/CLOT/Config.  In the CLOT Redirect URL field, insert a path to your CLOT's '''login''' page.  For example, http://clot-test.appspot.com/login
# At the bottom of this same page, the site will tell you your CLOT Authentication URL.   At the end of this URL is a number (the "p" parameter) that identifies your invite token.  You need to insert this number into your python code in two places: join.py and leave.py.

== Understanding the Code ==

The most important file of the starter code is '''clot.py'''.  This contains two key functions: '''createGames''' and '''setRanks'''.

'''createGames''' is called periodically to check for new games that need to be created.  The sample provided just retrieves all players in the database, figures out who isn't currently in a game, and creates Strategic 1v1s randomly between them.  You should replace this function with your own logic that determines what game settings and player configurations should be used.

'''setRanks''' is also called periodically to update each player's rank.  The sample provided just counts how many wins each player has had and then gives players ranks based on their number of wins.  This is the simplest ladder ranking algorithm, but you can plug your own in.  If you're making a tournament, you might not need this function at all.

There's a '''templates''' subdirectory that defines all of the html that powers the website.  '''base.html''' defines the overall look and feel of the site.  It's a good idea to edit the <title> element here to give your site its own name.

There's a '''static''' subdirectory that defines files that never change.  Here you can place things like images you want to host.  You'll probably want to adjust the stylesheet here to give your site its own look and feel.

Another file to check out is '''urls.py'''.  This defines how web addresses map to the different Python files.  If you want to add a new page, this is where you'll do it.

'''cron.py''' is called every 6 hours.  This is what calls createGames and setRanks, but it also does some other maintenance as it checks for games that have recently finished.

== Development Tips ==

* In the Google App Engine Launcher, there's a button named SDK Console.  Under the SDK Console, you'll see the Datastore Viewer which lets you view and manipulate what's stored in the CLOT database.
* In the Google App Engine Launcher, there's a button named Logs.  Click this to open up a window that shows information about what the app is doing.  You can write to this log in the app by calling logging.info()
* test.py gives you a blank function that you can test code out in.  You can activate it by hitting the "/test" page in your browser.