PopStocks

Trade your favorite movie stars, musicians, and more with PopStocks!  You can trade in your profits for cool items or try to corner the market and compete with your friends, it's up to you.  PopStocks is a pop culture trading game for everyone!

Developers:
* Andy Burke
* Geoff Evans
* Marc Hernandez, esq.
* Paul Haile
* Rachel Mark

Sites:
* http://www.pop-stocks.com
* http://blog.pop-stocks.com/

Development Links:
* http://www.facebook.com/developers/apps.php
* * http://apps.facebook.com/popstocks-devel

Docs:
* See folder: docs/

=======================================

Software Requirements:
-----------------------
* Git
* Python
* Google App Engine
* Text Editor of choice


Utilities
-----------------------
* Javascript graphing?
* jQuery
* * ThemeRoller
* * Fancybox
* * 

=======================================

Game Design Principles:
------------------------
* The user should be minimally successful when they click "yes" to everything the Broker suggests 
* Classy, attractive offers, that keep the players in the game
* We make money off you interacting with our virtual world
* If they have to do any work at all, we give them Pops, and vice versa
* Anything and everything we can do client side in java script we must (scalability) 

=======================================

Money Making Model:
--------------------
* Purchase Pops; either directly through PayPal or via facebook credits.
* Classic Ads: The Right Hand Side bar is designated Ad space.
* Lead generation: 
* * Pops Rewards: Awarding the Player X Pops for following a lead; Example: Sign up for this news letter and get 50k pops!
* * Real World Rewards: Get discounts on real world things; Example: Spend 50k Pops and get two free movie tickets from Fandango!

=======================================

Market Design:
---------------

Most Important Things:
# Market orders complete as soon as possible
# Market price fluctuates as a function of demand for a stock
# Rumors effects the market price as soon as possible
# Limit orders are 100% firm and all fill when the market price meets the limit price
# Market orders complete at the expected price

Design #1:
-----------

Monolithic Tick:
    For each stock:
        Adjust market price and search for orders that are want to trade at that price

Design #2:
-----------

Monolithic Tick:
    For each stock:
        Adjust market price based on rumors and randomness
        Move super-user buy and sell (IPO) orders along with market price
    For each stock:
        For each buy order:
            For each sell order:
                If order bids intersect, do trade

Design #3:
-----------

Super User:
* NO SUPER-USER specific code in the market engine
* Sell IPO shares from SU at market price
* Super user never actually buys back any stock *need to playtest this, may be necessary*

Market Price:
* Market price is adjusted only by supply and demand (as a concept)
* Supply and Demand are defined by the number of shares in open orders
    * Buy orders indicate demand (since one must put down escrow to issue a buy order)
    * Sell order indicate supply (since one must own shares to issue a sell order)
* Rumors effect market price through buy and sell orders from the super user
    * These orders are at impossible prices for the engine to fulfill (0, and 0xFFFFFFFF)
    * The amount of effect rumors have on the market is set by the number of shares at these prices
    * In this way rumors could have linear or non-linear effect based on how they stack onto each other
* We potentially adjust the market price:
    * After some amount of trading volume
    * If there are no market orders
    
Limit Orders:

Sell:
* limitPrice <= marketPriceAtCreation
    * stop-loss order to liquidate
* limitPrice >= marketPriceAtCreate
    * profit exit point to liquidate    
Buy:
* limitPrice <= marketPriceAtCreation
    * trigger buy order since cost is low
* limitPrice >= marketPriceAtCreate
    * spending cap to prevent loss of cash (may be unnecessary due to escrow)

Tasks:
* N tasks to fill orders at the current market price
    * Results are committed inside transaction so if orders were cancelled we get graceful failure
    * Orders are either in the task system or killed.  Killed orders are kicked by a cron job looking
        for market price to change, or orders within a windows around market price to be created
    * MatchOrder: searches for other orders to trade with
        * kills orders over threshold commit count
        * performs searches based on db schema properties to find candidates
        * kills orders if there are not matches on the market
        * matched pairs are posted into corresponding CommitOrder queue
    * CommitOrder: commits trade logic
        * mostly a lot of basic math and a *ton* of puts to update db state
        * post failures back into MatchOrder
        * increments commit count

TODO:
Remove PowerTrader code, shelve store items until we think of how to implement it at lower CPU cost