Introduction ........................................................................................................................................ 2
Goals and objetives ............................................................................................................................. 2
Scope ................................................................................................................................................... 2
Document information........................................................................................................................ 3
Application .......................................................................................................................................... 5
Summary ......................................................................................................................................... 5
Features........................................................................................................................................... 5
Data to use ...................................................................................................................................... 5
Climate data ................................................................................................................................ 5
Overview ......................................................................................................................................... 7
Game Design ................................................................................................................................... 9
Game rules .................................................................................................................................. 9
Thermometer behavior ........................................................................................................... 9
Points per object ..................................................................................................................... 9
Difficulty logic .......................................................................................................................... 9
User actions ............................................................................................................................... 11
Animations ................................................................................................................................ 12
Delimiters .................................................................................................................................. 12
Rendering layers ........................................................................................................................ 13
Objects and final art .................................................................................................................. 13
Architecture .................................................................................................................................. 14
API ............................................................................................................................................. 14
Game architecture ........................................................................Error! Bookmark not defined.
Documentation ............................................................................................................................. 16
Game web services / API ........................................................................................................... 16
Get Countries ........................................................................................................................ 16
Get ClimateData .................................................................................................................... 16
API database dictionary............................................................................................................. 16
Table: JOB_LOG ..................................................................................................................... 16
Table: COUNTRY .................................................................................................................... 17
Table: CLIMATE...................................................................................................................... 17
References......................................................................................................................................... 18
Introduction
This document describes all the information related to the development of a mobile app for the
World Bank’s (WB) climate contest (apps for climate). The idea is to develop an app that will show
in the best way possible the information related to climate changes and weather behavior.
The app will be developed for the mainstream in form of a game. The idea of basing the app for
the mainstream is to inform them about climate changes and raise the awareness regarding how
they affect and impact the world.
Goals and objetives







Develop a mobile game app capable of showing WB’s information to the mainstream in an
interactive way.
Develop a mobile game app capable of raising the awareness of the player regarding to
climate changes.
Analyze WB’s data and understand its purposes.
Design a mobile game in terms of GUI, game mechanics and source code architecture.
Design a user friendly game.
Develop connectivity to WB’s APIs in order to use data.
Log all the development process in documents.
Scope
The game will be developed only for the Android technology, using version 2.2 as the main SDK
platform. Will only support smartphones (tables are not part of the scope).
The game will also connect to WB indicators API in order to obtain and inform the player about
other relevant information.
Document information
Version: 1.0
Author(s):
Alejandro Mostajo S.
Jose Cruz M.
Start date: 2012/01/23
End date: 2012/01/26
Description:
 Introduction section added.
 Objectives section added.
 Scope section added.
 Application summary and features sections added.
 Application data section added.
 References section added.
Version: 1.1
Author(s):
Alejandro Mostajo S.
Jose Cruz M.
Start date: 2012/01/27
End date: 2012/02/02
Description:
 Introduction changed.
 Objectives changed.
 Scope changed.
 Application summary and features sections changed.
 Application data section changed.
 Game design section added.
Version: 1.2
Author(s):
Alejandro Mostajo S.
Jose Cruz M.
Start date: 2012/02/10
End date: 2012/02/15
Description:
 Application summary section changed.
 Game rules section added.
 Architecture section added.
 Art added.
 Documentation section added.
Version: 1.3
Author(s):
Alejandro Mostajo S.
Jose Cruz M.
Start date: 2012/03/05
End date: 2012/03/13
Description:



Application summary section changed.
API section changed.
Documentation section changed.
Application
Summary
WB CLIMATE is a game application developed for mobile devices that run Android O.S. The main
idea of this application is to make climate change information from the World Bank available.
The application tries to create awareness about the climate change. It is geared toward all people,
especially the newest generations, our kids.
The main goal of this project is to provide access to the World Bank's information in an easy and
entertaining way. We believe that new generations play a very important role in the world's future
so we tried to focus on them.
We know that all the information about the climate change can be a little bit overwhelming for a
child or adolescent; so we thought of an interactive way to reach out them and still allow them to
understand about the importance of the Earth without boring them.
Since this is an issue that affects all people we came up with WB CLIMATE. It is an interactive, fun
game that shows pertinent facts about climate change in the different countries around the world.
WB CLIMATE also shows how being proactive and doing “small” things like recycling or reducing
toxic waste can help the world be healthier and cleaner.
This application will have a positive impact and help spread out knowledge about how climate
change is a reality and how people need to start working towards a change. The game highlights
how everyone can make a difference and most importantly they can start now.
Features




Play based in real and projected WB data: The game will base all its game-play in the data
obtained by the WB APIs.
Touch-screen interaction: The game will have an intuitive way to play with just touch
screen actions.
Country (location) selection: The game will let the users select a country. If there is data
available through an API call, the game will initialize the difficulty and visuals depending on
the values obtained for the selected location.
Raise awareness: By playing with real data, the users will get informed throughout the
game about the climate changes and country’s indicators.
Data to use
Climate data
Name
Temperature
Precipitation
Description
Temperature is a physical property of matter that quantitatively
expresses the common notions of hot and cold.
In meteorology, precipitation (also known as one of the classes of
hydrometeors, which are atmospheric water phenomena) is any
product of the condensation of atmospheric water vapor that falls
under gravity. The main forms of precipitation include drizzle, rain,
sleet, snow, graupel and hail. It occurs when a local portion of the
atmosphere becomes saturated with water vapour and the water
condenses.
Concept overview
The game will be pretty simple; the screen will have the
Earth at the bottom and the space/atmosphere at the
top, a fog of precipitation will join both through the sky.
The fog of precipitation will move from the Earth to the
atmosphere, the game will throw in the fog at a certain
speed two types of objects to the atmosphere, those
who hurt the environment and those that are
environmentally friendly; the user must remove those
who hurt the environment from the fog into an specific
aspirator and let pass those friendly into the
atmosphere; both actions will grant the user with a
certain amount of points.
If the user let pass a bad object into the atmosphere, or removes a bad object into a wrong
aspirator, or moves a friendly object into an aspirator; the game will subtract points.
A thermometer will indicate when a user finishes the game or its game over; it will turn into green
or red depending on the user’s actions; if the thermometer fills full with red then its game over
(the score then is logged to keep some game stats).
Each round reflects a range of years in the
selected country, this range will alter the
game’s difficulty (like increasing the speed
and the amount of objects thrown per
second) and visual changes (like turning the
sky from blue to red and the fog’s
opaqueness)
depending
on
the
temperature and precipitation data
provided by the WB API.
When the user beats all the available years,
the game will be providing him with
information about how he helped the
planet (by showing a summary of the data
variations), something similar will be
displayed when it’s game over.
Game Design
Game rules
Thermometer behavior
The thermometer will have a range of 0 and 50 points; it will be initialized in 25 points. Depending
on the user actions the thermometer will increase or decrease, if it reaches 50 then it’s game over,
otherwise the user will continue playing until he finishes all the available range of years.
Points per object
These points will affect the games thermometer and the user’s score.
Object event
Friendly object into the [Atmosphere].
Friendly object into an [Aspirator].
Non-Friendly object into a correct [Correct][Aspirator].
Non-Friendly object into an incorrect [Wrong][Aspirator].
Non-Friendly object into the [Atmosphere].
Year range completion.
User Points
+5
-10
+2
-4
-7
+6
Thermometer Points
-5
+10
-2
+4
+7
-6
Difficulty logic
The temperature and precipitation data will affect the game’s difficulty in the following ways (A
range of years will be considered as a round):
Setting the amount of objects to be thrown per round:
The temperature and the years will be part of this difficulty setting. The game will apply
the following formula:
Objects per round = [Round temperature] *
([Round number] * [Temperature variation] * [Difficulty factor])
Where:
 Round temperature: Is the annual average temperature for a range of
years (round).
 Round number: An incremental integer that reflects the number of the
round, the initial number is 0 by default.
 Temperature variation: The temperature variation within rounds, where
the variation will be equals to the current round’s temperature divided by
the previews round temperature.
 Difficulty factor: An approximate to the number of objects we want to
increase per round, 10.15 by default.
Looking at the following example:
Round
0
1
2
Year range
1920-1939
1940-1959
1960-1979
Temperature
19,14
19,12
19,08
Variation
0,000000
0,999198
0,997773
Objects
19
29
39
For this specific country, the game will throw 19 objects in the first round, 29 in the second
and 39 in the third.
Setting the frequency of objects to be thrown per millisecond:
The temperature and the years will be part of this difficulty setting. The game will apply
the following formulas, the first one is the frequency factor per round and the second one
is the frequency per object:
Frequency
Factor =
[Difficulty factor] *(1-([Calc temperature]*
([Round number] *[Increase factor]+10)/10) / [Difficulty factor 2])
Where:
 Difficulty factor: The frequency of seconds we want if the temperature is
zero (4 seconds by default).
 Calc temperature: If the temperature is less than zero, the this value will
be the round number plus 1 minus the temperature variation; otherwise it
will remain with the temperature value.
 Round number: An incremental integer that reflects the number of the
round, the initial number is 0 by default.
 Increase factor: A number to increase the value of the round number (1.5
by default).
 Difficulty factor 2: An approximate to the double or triple of the max
temperature found (75 by default).
The following example shows the calculated frequency factor per round:
Round
0
1
2
3
4
5
6
7
Temperature
23,79194
23,76017
23,84597
24,07689
24,65266
25,10680
25,84193
26,82896
Frequency
2,73
2,54
2,35
2,14
1,90
1,66
1,38
1,07
The following formula will determine the frequency in seconds in which an object is
thrown from the earth to the atmosphere.
Frequency
Seconds =
[Frequency factor] +[Random number]
Where:
 Frequency factor: View previews formula.
 Calc temperature: A random number between +1 and -1.
Setting the speed of the objects:
The precipitation and the years will be part of this difficulty setting. The game will apply
the following formula (A range of years will be considered as a round):
Speed
Factor =
((1-[Precipitation]/10000)*((([Round number]*10)+10)/10))
Where:
 Precipitation: The round’s precipitation.
 Round number: An incremental integer that reflects the number of the
round, the initial number is 0 by default.
User actions
Object
Environmentally friendly
object.
Action
Entered into the
[Atmosphere].
Environmentally friendly
object.
Moved from the [Fog] into
an [Aspirator].
Non-environmentally friendly
object.
Moved from the [Fog] into
the [Correct][Aspirator].
Non-environmentally friendly
object.
Moved from [Fog] into a
[Wrong][Aspirator].
Non-environmentally friendly
object.
Entered into the
[Atmosphere].
Any object in the [Fog].
Removed from the [Fog],
grabbed with the touch
screen and then inserted
back again into the [Fog].
Event
The game adds points to the
score.
The
thermometer
increases towards the green color
side.
The game subtracts points from
the score. The thermometer
decreases towards the red color
side.
The game adds points to the
score.
The
thermometer
increases towards the green color
side.
The game subtracts points from
the score. The thermometer
decreases towards the red color
side.
The game subtracts points from
the score. The thermometer
decreases towards the red color
side.
The object continues to move
towards the [Atmosphere] from
the location where it was
inserted.
Animations
Object
Earth.
Fog.
Object in the [Fog].
Object dragged.
Aspirator animation.
Animation
Rotation on its pivot.
Location movement from right to left. From the [Earth] to the
[Atmosphere].
Location movement from right to left. From the [Earth] to the
[Atmosphere].
The object change it’s scales.
Aspirator animation sucking the air.
Delimiters
Object
Aspirator sucking bounds.
Atmosphere bounds.
Object bounds.
Earth and user’s touch
bound.
Fog bounds.
Animation
Will determine from where the aspiration will be able of
sucking an object.
Will determine when an object is passed into the atmosphere.
Invisible bounds if needed for collision detection.
Will determine from where the user will be able to input touch
actions.
Fog bounds.
Rendering layers
Layer
Front layer.
Middle layer 1.
Middle layer 2.
Back layer.
Objects contained
Score, Thermometer, Atmosphere, Earth and Aspirators.
Objects in the fog.
Fog of precipitation.
Sky.
Objects and final art
Object
Type
Friendly
Description
Eco-Friendly bulb
light
Friendly
Recycle trash can
Friendly
Tree
Non- Friendly
Aluminum can
Non- Friendly
Aerosol
Non- Friendly
Car pollution
Non- Friendly
Oil
Architecture
API
WB API
Database
JOB
Web
Services
The game will not consume directly the WB API, instead it will call a customized web service/API
that will provide processed climate data and difficulty settings. By having a separated process like
this, the game gains performance because it will make less API calls and enable us to balance the
game’s difficulty without having to re-compile and build a software update.
A job will run weekly in order to obtaining the climate data available in the WB API and to process
it for game purposes; this also means that there will be an online database with the processed
information.
The job will run the following API configurations:
 Default climate model to use: bccr_bcm2_0
 Default scenario to use: a2
 Default type to use: annualavg
 Start date set as 1900.
The job will call the API and query the data for a list over 230 locations; it will stop querying a
country after 10 consecutive failure calls.
The indicators API will be also used to retrieve some country facts. The job will query randomly the
following indicators:
Description
% of agriculture land
% of forest land
Wood fuel.
Surface land
Net capital account
Agriculture employment
CO2 Emissions
Access to electricity
GDP
Access to adequate water
Alternative energy
Indicator code
AG.LND.AGRI.ZS
AG.LND.FRST.ZS
AG.FRST.PROD.WOOD
AG.SRF.TOTL.K2
BN.TRF.KOGT.CD'
SL.AGR.EMPL.ZS'
EN.ATM.CO2E.PC'
EG.ELC.ACCS.ZS
NY.GDP.MKTP.CD'
SH.H2O.SAFE.RU.ZS
EG.USE.COMM.CL.ZS
Documentation
Game web services / API
The web services or API will provide the game with processed WB climate data.
Get Countries
Returns the list of available countries.
Call
Input
Output
Format
http://www.amsgames.com/mobile/wbclimate/wsGetCountries.php
None
NAME: The name of the country.
ISO3: The country’s ISO3 code.
DIFFICULTY_LEVEL: The country’s difficulty level in terms of game-play.
Json
Get ClimateData
Returns the list of rounds and the difficulty settings for each country.
Call
Input
http://www.amsgames.com/mobile/wbclimate/wsGetClimateData.php
ISO3: Country ISO 3 code.
Example (inputs passed as query string parameters):
…wsGetClimateData.php?ISO3=[value]
Output
Format
YEAR_RANGE: The range of years for a specific round (for example: 19201939).
TEMPERATURE: The round’s average temperature.
ROUND: The round number.
OBJECTS_X_ROUND: The number of objects to be thrown in a round.
OBJECT_SPEED_FACTOR: The round’s speed factor.
OBJECT_FREQUENCY_FACTOR: The rounds frequency factor.
FACT_MESSAGE: A location’s fact message to display in the round.
Retrieved from WB’s indicators.
DIFFICULTY_LEVEL: The country’s difficulty level in terms of game-play.
Json
API database dictionary
The database will run in MySql engine.
Table: JOB_LOG
Logs the summary of every run of the job that gets and process the WB climate data.
Column
LOG_TIME
DURATION
TABLES_CREATED
Keys
PK
Type
TIMESTAMP
DOUBLE
BIT
Description
Record’s creation date and time.
Job duration in seconds.
Flag that indicates if the job had to
create a table.
Table: COUNTRY
Holds the list of countries and their respective ISO codes.
Column
ISO2
ISO3
NAME
DIFFICULTY_LEVEL
Keys
PK
Type
CHAR(2)
CHAR(3)
VARCHAR(50)
INT(1)
Description
Country ISO2 code.
Country ISO3 code.
Country name.
Difficulty level.
Table: CLIMATE
Holds the processed climate data and difficulty settings per country.
Column
COUNTRY_ISO3
YEAR_RANGE
ROUND
TEMPERATURE
TEMPERATURE_
VARIATION
Keys
PK
PK
Type
CHAR(3)
VARCHAR(9)
INT
DOUBLE
DOUBLE
PRECIPITATION
PRECIPITATION_
VARIATION
DOUBLE
DOUBLE
OBJECTS_X_ROUND
OBJECT_SPEED_
FACTOR
OBJECT_FREQUENCY_
FACTOR
FACT_MESSAGE
INT
DOUBLE
LAST_UPDATE
DIFFICULTY_LEVEL
DATETIME
INT(1)
DOUBLE
VARCHAR(255)
Description
Country ISO3 code.
The range of years per round.
The number of round.
The round’s average temperature.
The percentage variation of the
temperature when compared to the
last range of yearsThe round’s average precipitation.
The percentage variation of the
precipitation when compared to the
last range of yearsThe quantity of objects per round.
Object speed factor per round.
Object’s appearance frequency per
round.
A location’s fact message retrieved
from WB’s indicators.
The records last update date.
Difficulty level.
References
Basic Call Structure, World Bank, obtained on the 23th of January 2012.
http://data.worldbank.org/node/11
Climate Data API, World Bank, obtained on the 24th of January 2012.
http://data.worldbank.org/developers/climate-data-api
Geo Names Web Services Documentation, GeoNames, obtained on the 24th of January 2012.
http://www.geonames.org/export/web-services.html
World Countries API, GeoNos, obtained on the 24th of January 2012.
http://www.geognos.com/geo/en/world-countries-API.html#h.xmg4e4bg5vjb
Location and maps, Google , obtained on the 24th of January 2012.
http://developer.android.com/guide/topics/location/index.html
Country queries, World Bank, obtained on the 26th of January 2012.
http://data.worldbank.org/node/18
Inidicators queries, World Bank, obtained on the 26th of January 2012.
http://data.worldbank.org/node/203
Facebook tutorial, Facebook developers, obtained on the 26th of January 2012.
https://developers.facebook.com/docs/mobile/android/build/
Twitter4J API, Twitter, obtained on the 26th of January 2012.
http://twitter4j.org/en/index.jsp
Temperature, Wikipedia, obtained on the 26th of January 2012.
http://en.wikipedia.org/wiki/Temperature
Precipitation (meteorology), Wikipedia, obtained on the 26th of January 2012.
http://en.wikipedia.org/wiki/Precipitation_(meteorology)
Gross domestic product, Wikipedia, obtained on the 26th of January 2012.
http://en.wikipedia.org/wiki/Gross_domestic_product
Wood fuel, Wikipedia, obtained on the 26th of January 2012.
http://en.wikipedia.org/wiki/Wood_fuel
Climate change and agriculture, Wikipedia, obtained on the 26th of January 2012.
http://en.wikipedia.org/wiki/Climate_change_and_agriculture
Wiki API, MediaWiki, Wikipedia, obtained on the 26th of January 2012.
http://www.mediawiki.org/wiki/API
Google Chart API, Google, obtained on the 29th of January 2012.
http://code.google.com/intl/pl-PL/apis/chart/image/docs/making_charts.html
Custom list view, Software Passion, obtained on the 30th of January 2012.
http://www.softwarepassion.com/android-series-custom-listview-items-and-adapters/
Texture Packer, obtained on the 7th of February 2012.
http://www.texturepacker.com/download/