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/