Core - Scoring

The Scoring module (SM) centralizes users’ grading system, providing coin type management, storage for the formulas, a few helper functions to be used in formulas, and detailed history of gained coins.

The coins used in WoUSO are of two types: core and game specific.

An application (a game) define its grading formulas; the SM will register and store these formulas, making them editable by an administrator; when an action finishes, the game asks SM for a formula calculation, with given parameters, and then pushes scores for each user playing the game.

Coins

Core

These types of coin are available globally in the game. God defines their names. Each game can modify the amount of these coins for each user.

Their id are kept simple and suggestive.

Right now, only points core type coin is defined.

Game specific

Each game can define specific types of coin he offers to the user. God can override their names. Only the game defining the coin type can modify the amount for a user.

Their id is prefixed with the owner game, i.e. challenge-stamina.

Examples

Given the core coins:

Id: points
Name: Galbeni

1. Qotd registers one simple formula, giving 3 points for a correct answer:

Name: qotd-ok
Formula: points=3

After an user plays Qotd, it asks SM to calculate the points, with no parameters; then save them for the user:

# self - a Qotd game instance
# 'qotd-ok' - the formula id
core.scoring.score(user1, self, 'qotd-ok')

2. Challenge adds a coin type:

Id: challenge-stamina
Name: Fight Stamina

and registers two formulas, one for won challenge, another for lost:

Name: challenge-lost
Formula: points=-3, challenge-stamina=-100

Name: challenge-won
Formula: points=3 + ({level1} - {level2}) * 0.5, challenge-stamina=50

After playing a challenge:

core.scoring.score(user1, self, 'challenge-lost' external_id=challenge.id)
core.scoring.score(user2, self, 'challenge-won', external_id=challenge.id, level1=user1.level, level2=user2.level)

wouso.core.scoring.models

class wouso.core.scoring.models.Coin(*args, **kwargs)

Different scoring categories.

A special coin is ‘points’ since is used for ladder and levels.

is_core()

A coin is a core coin, if it doesn’t have an owner

class wouso.core.scoring.models.Formula(*args, **kwargs)

Define the way coin amounts are given to the user, based on keyword arguments formulas.

A formula is owned by a game, or by the system (set owner to None)

class wouso.core.scoring.models.History(*args, **kwargs)

Scoring history keeps track of scoring events per user, saving the details from source to amount.

static user_coins(user)

Returns a dictionary of coins and amounts for a specific user.

static user_points(user)

Returns:a list of (game, points) - distribution of points per source

class wouso.core.scoring.models.ScoringModel

Generic loose, fail-proof model with add_if_does_not_exist and get_if_it_isnt_already_an_instance methods

wouso.core.scoring.sm

wouso.core.scoring.sm.calculate(formula, **params)

Calculate formula and return a dictionary of coin and amounts

wouso.core.scoring.sm.check_setup()

Check if the module has been setup

wouso.core.scoring.sm.history_for(user, game, external_id=None, formula=None, coin=None)

Return all history entries for given (user, game) pair.

wouso.core.scoring.sm.score(user, game, formula, external_id=None, percents=100, **params)

Give amount of coin specified by the formula to the player. The amount can be affected by percents/100.

wouso.core.scoring.sm.score_simple(player, coin, amount, game=None, formula=None, external_id=None, percents=100)

Give amount of coin to the player.

wouso.core.scoring.sm.setup_scoring()

Prepare database for Scoring

wouso.core.scoring.sm.sync_all_user_points()

Synchronise points amounts for all players

wouso.core.scoring.sm.sync_user(player)

Synchronise user points with database

wouso.core.scoring.sm.timer(user, game, formula, default=300, **params)

Compute a timer value, or return default

wouso.core.scoring.sm.unset(user, game, formula, external_id=None, **params)

Remove all history records by the external_id, formula and game given to the user

wouso.core.scoring.sm.user_coins(user)

Returns a dictionary with user coins