Energy

for social games

What is energy?

Oh, you are kidding. You already know what energy is. But, just to make it clear, energy is a concept that is consumable and recoverable in social games. It limits how far players can advance in each session.

_images/variations.gif

Players use energy to perform actions such as farming, housing, or social interactions. Then consumed energy will be recovered after certain amount of time designed by the developer. Recovery is the essence of energy system. It will make players to come back to the game periodically.

Popular social games such as FarmVille , Zoo Invasion or The Sims Social are benefited from the system in high retention rate.

How to use?

Install via PyPI first:

$ easy_install energy

Or check out developement version:

$ git clone git://github.com/sublee/energy.git

The only thing you need to implement energy system is Energy object. Maximum energy and recovery interval have to be set in seconds before use:

from energy import Energy
energy = Energy(max=10, recovery_interval=300)

The example Energy object has 10 of maximum and will recover in every 5 minutes. When a player performs a action that requires energy just call Energy.use() method:

>>> print energy
<Energy 10/10>
>>> energy.use()
>>> print energy
<Energy 9/10 recover in 05:00>

If the player has not enough energy, it throws ValueError:

>>> print energy
<Energy 9/10 recover in 04:12>
>>> energy.use(10)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "energy.py", line 104, in use
    raise ValueError('Not enough energy')
ValueError: Not enough energy

You may want to save Energy object within a specific player’s data in database.

An Energy object is serializable by Pickle. If you have a key-value storage, you can save an Energy object with a player easily. Or, you should prepare some columns for Energy.used and Energy.used_at in your database to save them. Here’s an example of save/load an Energy object:

>>> MAX_ENERGY, ENERGY_RECOVERY_INTERVAL = 10, 300
>>> energy = Energy(MAX_ENERGY, ENERGY_RECOVERY_INTERVAL)
>>> saved_used, saved_used_at = energy.used, energy.used_at
>>> loaded_energy = Energy(MAX_ENERGY, ENERGY_RECOVERY_INTERVAL,
...                        used=saved_used, used_at=saved_used_at)
>>> loaded_energy == energy
True

API

class energy.Energy(max, recovery_interval, recovery_quantity=1, future_tolerance=None, used=0, used_at=None)

A consumable and recoverable stuff in social gamers. Think over reasonable energy parameters for your own game. Energy may decide return period of your players.

Parameters:
  • max – maximum energy
  • recovery_interval (number or timedelta) – an interval in seconds to recover energy
  • recovery_quantity – a quantity of once energy recovery. Defaults to 1.
  • future_tolerance – near seconds to ignore exception when used at the future
  • used – set this when retrieve an energy, otherwise don’t touch
  • used_at (timestamp number or datetime) – set this when retrieve an energy, otherwise don’t touch
Raises TypeError:
 

some argument isn’t valid type
config(max=None, recovery_interval=None, time=None)

Updates max or recovery_interval.

Parameters:
  • max – quantity of maximum energy to be set
  • time – the time when setting the energy. Defaults to the present time in UTC.
current(time=None)

Calculates the current presentative energy. This equivalents to casting to int but can work with specified time.

>>> energy = Energy(10, 300)
>>> energy.use()
>>> energy.current()
9
>>> int(energy)
9
Parameters:time – the time when checking the energy. Defaults to the present time in UTC.
debt(time=None)

Calculates the current energy debt.

>>> energy = Energy(10, 300)
>>> energy.debt()
>>> energy.use(11, force=True)
>>> energy.debt()
1
>>> energy.use(2, force=True)
3
Parameters:time – the time when checking the energy. Defaults to the present time in UTC.
future_tolerance = None

The near seconds to ignore exception when used at the future.

New in version 0.1.3.

max

The maximum energy.

passed(time=None)

Calculates the seconds passed from using the energy first.

Parameters:time – the time when checking the energy. Defaults to the present time in UTC.
Raises ValueError:
 used at the future
recover_fully_in(time=None)

Calculates seconds to be recovered fully. If the energy is full or over the maximum, this returns None.

Parameters:time – the time when checking the energy. Defaults to the present time in UTC.

New in version 0.1.5.

recover_in(time=None)

Calculates seconds to the next energy recovery. If the energy is full or over the maximum, this returns None.

Parameters:time – the time when checking the energy. Defaults to the present time in UTC.
recovered(time=None)

Calculates the recovered energy from the player used energy first.

Parameters:time – the time when checking the energy. Defaults to the present time in UTC.
recovery_interval = None

The interval in seconds to recover energy.

recovery_quantity = None

The quantity of once energy recovery.

reset(time=None)

Makes the energy to be full. Most social games reset energy when the player reaches higher level.

Parameters:time – the time when setting the energy. Defaults to the present time in UTC.
set(quantity, time=None)

Sets the energy to the fixed quantity.

>>> energy = Energy(10, 300)
>>> print energy
<Energy 10/10>
>>> energy.set(3)
>>> print energy
<Energy 3/10 recover in 05:00>

You can also set over the maximum when give bonus energy.

>>> energy.set(15)
>>> print energy
<Energy 15/10>
Parameters:
  • quantity – quantity of energy to be set
  • time – the time when setting the energy. Defaults to the present time in UTC.
use(quantity=1, time=None, force=False)

Consumes the energy.

Parameters:
  • quantity – quantity of energy to be used. Defaults to 1.
  • time – the time when using the energy. Defaults to the present time in UTC.
  • force – force to use energy even if there is not enough energy.
Raises ValueError:
 

not enough energy
used = 0

Quantity of used energy.

used_at = None

A time when using the energy first.

Changelog

Version 0.1.9

Released on June 24th 2014.

Fixes a bug on restored extra energy. This issue was reported by @hest.

Version 0.1.8

Released on May 13th 2014.

(by @youknowone)

Version 0.1.7

Released on Nov 5th 2013.

recovery_quantity works. Thanks to Donggeun Lee. (commit c98f348)

Version 0.1.6

Released on Jan 21st 2013.

used_at parameter is allowed to be a datetime object or timestamp number.

Version 0.1.5

Released on Jan 11th 2013.

  • Adds Energy.recover_fully_in() to calculate seconds to be recovered fully. It is useful for making push notification.
  • Supports Python 3 and Jython.

Version 0.1.4

Released on Dec 17th 2012.

Fixes a bug about the timezone of the default time argument. The documentation describes the timezone as UTC but it was a local timezone.

If your server is already using this project and setted with non-UTC timezone, you should override timestamp() to use local timezone.

Version 0.1.3

Released on Dec 11th 2012.

  • Adds future_tolerance parameter to be tolerant of using energy at the future. It is possible if there are several servers.
  • Changes a form of pickled Energy from tuple to dict.
  • Supports Jython.

Version 0.1.2

Released on Oct 12th 2012.

  • Fixes an error when the energy has Energy.used_at before initialization.
  • Fixes an error when using specific time for Energy.use().
  • Energy can be compared with number (<, <=, >, >=).

Version 0.1.1

Released on Sep 25th 2012.

  • Supports the argumented arithmetic assignment (+=, -=).
  • Fixes a calculation error when consuming energy over the maximum.

Version 0.1

First public preview release.

Licensing and Author

This project is licensed under BSD. See LICENSE for the details.

I’m Heungsub Lee, a game developer. Any regarding questions or patches are welcomed.

Fork me on GitHub
© Copyright 2012-2013, Heungsub Lee. Created using Sphinx 1.2.2.