Skip to content

Latest commit

 

History

History
631 lines (434 loc) · 39.2 KB

FunctionalSpecification.md

File metadata and controls

631 lines (434 loc) · 39.2 KB

Green City: Functional Specification Document

Table of contents

Click to unfold

Team members

Role Member name Responsibilities
Project manager Bistrel Tsangue Oversees project progress and ensures deadlines are met.
Program manager Guillaume Deramchi Manages program implementation, coordinates with stakeholders.
Technical lead Lucas Aubard Leads the technical direction and supervises the development team.
Software engineer Victor Leroy Develops game features and ensures code quality.
Software engineer Manech Laguens Implements gameplay mechanics and collaborates on technical tasks.
QA tester Habi Cailleau Tests the game for bugs and ensures quality standards are met.
Technical writer Jason Grosso Documents features, creates user guides, and maintains project documentation.

I. Introduction

  • Current situation: "Green City" is an ongoing project aimed at creating an engaging and educational serious game about climate change. Built on Godot 4.3, it leverages game mechanics to simulate urban sustainability challenges. The project seeks to deliver a polished, professional product that combines education and entertainment while prioritizing its role as a teaching tool.

  • Background: The game integrates elements of city-building and climate education. Players will face realistic challenges such as transitioning from fossil fuels to renewable energy, managing city resources efficiently, and minimizing carbon emissions. Designed to impart critical lessons in sustainability, the game employs interactive scenarios and feedback mechanisms to educate players about the environmental impact of urban planning decisions. The primary audience includes young adults (ages 15–25), educators in environmental science, and individuals interested in sustainability.

  • Initial MVP focus: The MVP will center on core gameplay, including resource management, pollution tracking, and city-building, while strongly emphasizing its educational purpose. It will incorporate tailored feedback mechanisms, climate-related facts, and scenario-based learning to teach players the consequences of their choices. The MVP will act as a proof of concept, demonstrating key sustainable city-building mechanics, such as balancing energy production with pollution control, while guiding players through the broader implications of their decisions on the environment.

II. Personas & use cases

1. Personas

The following personas represent the diverse key player types for Green City. Each persona will interact with the game differently, highlighting its versatility and adaptability to varied educational and engagement needs:

a. Persona 1: Sarah, the concerned parent

Attribute Details
Image
Age 42
Occupation Elementary school teacher
Location Chicago, USA
Tech-savviness Moderate, uses apps and games occasionally
Goals - Teach her children eco-friendly habits.
- Learn practical ways to reduce her family's carbon footprint.
Pain points - Overwhelmed by conflicting information about sustainability.
- Finds most climate education tools too complex or dry.
Motivation - Play Green City with her kids as a bonding activity.
- Discover actionable steps for greener living.

Game approach for Sarah: The game will feature simplified mechanics and clear visual feedback to make it accessible for younger players and their parents. Interactive lessons and achievements will encourage collaboration and discussion about sustainability in the household.

b. Persona 2: Alex, the pragmatic entrepreneur

Attribute Details
Image
Age 35
Occupation Owner of a small tech startup
Location Berlin, Germany
Tech-savviness High, frequently uses digital tools and games for learning
Goals - Understand how sustainability impacts business growth.
- Learn innovative strategies for reducing energy costs.
Pain points - Struggles to balance profit and environmental responsibility.
- Feels climate change discussions are often too idealistic.
Motivation - Explore practical solutions to energy and waste management.
- Simulate real-world decision-making in a fun environment.

Game approach for Alex: The game will incorporate deeper strategic mechanics, such as balancing profits and sustainability. Detailed data and visualizations will provide practical insights into decision-making, reflecting challenges faced by entrepreneurs.

c. Persona 3: Leila, the passionate student

Attribute Details
Image
Age 19
Occupation Environmental science major
Location Rabat, Morocco
Tech-savviness Intermediate, uses technology for research and casual gaming
Goals - Gain deeper insights into how cities contribute to climate change.
- Use knowledge from Green City for her studies and activism.
Pain points - Finds traditional academic tools uninspiring.
- Wants engaging ways to learn while having fun.
Motivation - Test strategies for reducing urban emissions in a risk-free environment.
- Advocate for sustainability using lessons from the game.

Game approach for Leila: Green City will include advanced learning modules, such as detailed scenarios and dynamic events, to challenge Leila’s understanding of urban sustainability. Integration of data-driven results and optional complex settings will align with her academic needs.

d. Persona 4: Mark, the climate skeptic

Attribute Details
Image
Age 50
Occupation Construction manager
Location Houston, USA
Tech-savviness Low, mostly uses technology for work-related purposes
Goals - Prove that concerns about climate change are exaggerated.
- Understand the game’s perspective on environmental issues.
Pain points - Believes climate change data is often biased or alarmist.
- Prefers practical, measurable solutions over theoretical debates.
Motivation - Challenge his views through gameplay scenarios.
- See if the game’s mechanics reflect his perspective of economic growth.

Game approach for mark: The game will emphasize visual evidence of environmental changes and the economic impacts of pollution. Balanced scenarios will allow Mark to explore different perspectives, fostering critical thinking and constructive debate.

2. Use cases

a. Use case 1: Sarah, the concerned parent

Attribute Details
Image
Goal Teach her children about eco-friendly habits in an interactive way.
Steps 1. Sarah starts a new game with her 10-year-old child.
2. Together, they build a small city, starting with renewable energy.
3. They explore pollution indicators and add parks to reduce smog.
4. The game provides feedback about real-world impacts of choices.
Outcome - Sarah and her child learn about renewable energy and urban greenery.
- The game sparks conversations about eco-friendly steps at home.

b. Use case 2: Alex, the pragmatic entrepreneur

Attribute Details
Image
Goal Explore strategies for balancing business growth with sustainability.
Steps 1. Alex starts the game.
2. He prioritizes building industrial zones, generating pollution.
3. He introduces green policies to mitigate pollution costs.
Outcome - Alex learns how sustainable investments improve long-term profitability.

c. Use case 3: Leila, the passionate student

Attribute Details
Image
Goal Understand the impact of urban planning decisions on climate change.
Steps 1. Leila experiments with energy options to minimize emissions.
2. She uses the carbon meter to track urban sprawl’s effects.
3. She writes an academic report using in-game data.
Outcome - Leila gains deeper understanding of climate systems and urban impact.

d. Use case 4: Mark, the climate skeptic

Attribute Details
Image
Goal Test the validity of climate change claims through gameplay.
Steps 1. Mark plays, skeptical of the game’s premise.
2. He experiments with renewable energy policies.
3. He compares costs of coal vs. solar and notices pollution impacts.
Outcome - Mark sees the economic and social benefits of sustainable policies.

III. Goal / scope

1. Primary goal

The primary goal is to develop a game that simulates environmental challenges to educate young adults and students on climate change, sustainability, carbon footprint. Players must balance economic development with sustainable practices, making choices that prioritize long-term environmental health. Players will need to decide whether to build industrial facilities that boost the economy but increase pollution. Alternatively, they can invest in renewable energy sources, which cost more initially but lead to long-term sustainability.

2. Scope of work

a. MVP scope

  • Resource management: Players allocate renewable (e.g., solar energy) and non-renewable (e.g., fossil fuel) resources while managing the city’s finances.
  • Pollution tracking: Pollution levels will be visually represented to show the city's health and the impact of player decisions over time. The pollution levels will be supplied by CO2, methane emissions and carbon footprint of each action the player does, and will modify the only pollution bar percentage.
  • Educational feedback: Visual feedback (pollution indicators, health bars) helps players understand the consequences of their actions.
  • Simple decision-making: Players make straightforward decisions regarding renewable energy, waste management, and city expansion.

b. Future vision scope

  • Advanced resource management: Introduce more complex resource types (e.g., food, advanced energy systems).
  • Pollution mitigation: Advanced tools to reduce pollution, like tree planting, public transit, and waste management systems.
  • Complex decision-making: Balancing industrial growth, environmental sustainability, and citizen satisfaction.

c. Priority objectives

  • Promote renewable energy: Encourage players to prioritize renewable energy to minimize the carbon footprint.

  • Emphasize waste management: Highlight managing waste through recycling, composting, and waste-to-energy plants.

  • Foster public awareness: Include public campaigns to raise awareness about sustainability.

  • Game complexity: The game will be simple to grasp, with intuitive mechanics suitable for all ages. The MVP will focus on core features like resource allocation and pollution tracking, while future versions will expand these features for more depth.

  • Target outcomes:

    • Players understand the importance of balancing city growth with sustainable practices.
    • Players learn the impact of resource choices on pollution, quality of life, and growth.
    • Players develop a sense of responsibility regarding environmental impacts.

IV. Functional requirements

1. Gameplay mechanics

a. MVP functional limits

To ensure focused development and avoid scope creep, the following functional limits are established for the MVP:

  • City size: Players can build a city with up to 30 buildings (e.g., residential, commercial, industrial, and parks). Once a building is placed, it is possible to remove it but it will consume energy, inciting players to be careful about smart building placement.
  • Resource types: The MVP includes only two energy types: renewable (solar energy) and non-renewable (fossil fuels). Advanced energy systems (e.g., nuclear, wind turbines) will not be implemented in the MVP.
  • Pollution tracking: Pollution is measured using a single pollution bar ranging from 0% (clean) to 100% (critical).
  • Win/Lose conditions: Pollution and energy management are the only criteria for winning or losing. No population satisfaction or other secondary metrics will be included.
  • UI components: The dashboard displays energy consumption, pollution levels, and financial status only. Advanced visual indicators (e.g., trend graphs, detailed notifications) are excluded.

b. Future vision

  • Building upgrades: Players upgrade buildings to improve efficiency (e.g., reducing energy consumption).
  • Dynamic pollution control: Advanced tools like public transit and green technologies reduce pollution levels.

2. UI components

a. MVP

  • Simple dashboard: Displays essential metrics like energy consumption, financial status, and pollution levels. A news ticker-like banner will be displayed on the main screen, displaying random facts about climate change, which will be rolling through the screen.

b. Future vision

  • Detailed notifications: Prompts and messages guide players through complex decisions.
  • Advanced visual indicators: Charts and graphs provide comprehensive feedback (e.g., pollution trends, energy usage over time).

3. Player interactions

a. MVP

  • Construction: Players place and remove basic buildings.
  • Basic decision-making: Players decide on energy use, construction, and waste management.
  • Feedback mechanisms: Visual cues (e.g., changes in city aesthetics) help players understand their impact.

b. Future vision

  • Advanced construction: Players upgrade buildings for increased efficiency.
  • Complex decision-making: Players balance economic growth, environmental health, and citizen satisfaction.
  • Enhanced feedback: Audio cues and detailed notifications provide deeper insights.

V. Dependencies & priorities

1. Feature dependencies and priorities

a. Priorities for MVP development

The following features are categorized by their priority level for the MVP:

High priority (must-have):

  • Basic building placement for 5 structure types: residential, industrial, commercial, parks, and energy plants.
  • Pollution tracking via a simple visual bar.
  • Resource allocation for renewable and non-renewable energy.
  • Basic win/lose conditions based on pollution and energy levels.

Medium priority (nice-to-have):

  • UI enhancements, such as hover tooltips for buildings.
  • Simple tutorial for new players.
  • Expanded pollution indicators, such as changing colors in the city layout.

Low priority (optional for MVP):

  • Dynamic pollution control (e.g., introducing green spaces).
  • Detailed visual feedback, such as graphs or animations.

b. Priorities for future development

To guide future updates, the following features are prioritized based on their potential impact, development complexity, and alignment with the game's goals:

High priority (post-MVP must-have):

  • Dynamic pollution control: Introduce tools like tree planting, waste recycling, and public transit to allow players to actively mitigate pollution.
  • Building upgrades: Enable upgrading buildings to increase efficiency and reduce resource consumption.
  • Population metrics: Add a population satisfaction meter influenced by pollution, resource allocation, and city infrastructure.

Medium priority (post-MVP nice-to-have):

  • Advanced energy options: Expand energy types to include wind turbines, geothermal, and nuclear power plants.
  • Random events: Introduce dynamic challenges such as extreme weather events or economic downturns.

Low priority (optional for future updates):

  • Multiplayer mode: Enable competitive or cooperative gameplay for up to four players.
  • Aesthetic enhancements: Add visual and sound design elements to improve immersion, such as detailed animations or custom city designs.

VI. Acceptance criteria

  • Gameplay verification:

    • Players can place buildings, allocate resources, and track CO₂ and methane emissions.
    • Players achieve varying levels of success based on their management of resources, emissions, and long-term sustainability goals.

  • User interface:

    • MVP: The UI must be intuitive, with responsive elements like buttons, dashboards, and emission tracking bars (CO₂ and methane).
    • Future vision: The UI must provide advanced feedback and clear indicators, such as detailed graphs or notifications explaining trends and changes.

  • Educational content:

    • Players receive relevant foundational knowledge about climate change, emissions, and sustainability:
      • The difference between CO₂ and methane, their sources, and their impact on climate change.
      • The relationship between energy production (fossil fuels vs. renewable energy) and carbon emissions.
      • Basic concepts of carbon footprint and its importance in sustainability.
    • Educational feedback includes:
      • Real-time updates on the consequences of player decisions (e.g., how industrial zones increase emissions).
      • Comparisons of different choices, such as the trade-offs between short-term economic gain and long-term ecological health.
      • Contextual explanations for game metrics (e.g., why methane emissions are displayed alongside CO₂).
    • Players understand not only the impact of their choices but also why these impacts matter by linking them to basic scientific principles.

VII. Design specifications

  • UI layout: Mockups or design prototypes should illustrate MVP and future UI versions. The MVP should have a clean layout focusing on ease of navigation.

  • UX elements: The user experience should prioritize accessibility and engagement. The MVP will offer a linear flow, while the future version may include branching decisions and tutorials.

1. Mockups and screenshots

Here are some mockups of what the game should be looking like, using Canva and the Starter Kit City Builder from Kenney Assets:

How the overall game should look like:

Here is an example of the moment before placing a building:

Here is how the contextual menu should look like when you click on a building (ecological upgrade, economical upgrade, destroy, and information about the building and how it affects our environment):

VIII. Non-functional requirements

  • Performance: Ensure the game runs smoothly at 60 FPS on mid-range devices.

  • Scalability: The game must handle large-scale city data without issues. The MVP introduces base data management, while future versions implement optimizations.

  • Accessibility: Adjustable text sizes, colorblind-friendly palettes, and simplified UI modes for younger audiences or those with impairments.

IX. Win / lose conditions

1. Win condition:

a. MVP

  • Players win by maintaining pollution levels below a defined threshold and providing enough renewable energy for five in-game years. This indicates that the city has successfully achieved sustainable growth.

b. Future vision

  • Players achieve milestones in sustainable growth, public awareness, and resource efficiency.

2. Lose condition:

a. MVP

  • Players lose if pollution exceeds a critical threshold for more than one in-game year, leading to city collapse.

b. Future vision

  • Players lose due to resource depletion, public dissatisfaction, or financial collapse.

X. Impact of management on gameplay

  • Good management:

    • Steady growth: Players receive more income for further development, similar to how cities with strong policies on renewable energy and efficient infrastructure see economic growth over time.
    • Positive feedback: The city becomes greener, with visual indicators of progress, much like how cities that invest in public parks and green spaces often see improved quality of life.

  • Poor management:

    • Deterioration: Rising pollution levels lead to resource scarcity and visible degradation, similar to cities experiencing severe smog and environmental decline due to poor regulations.
    • Negative feedback: Pollution indicators, such as smog, increase, showing declining sustainability, much like how poor urban planning can lead to visible pollution and declining living conditions.
    • Citizen dissatisfaction: Reduced productivity, abandoned buildings, and city decline, similar to urban decay seen in cities that fail to manage resources effectively.

XI. Out of scope

1. Features Planned for Future Updates

a. Future Features and Improvements

The following features are not included in the MVP but are planned for future updates to expand the game’s depth:

  • Population metrics: Adding a population satisfaction meter based on city pollution, resource allocation, and available services.
  • Dynamic pollution Control: Implementing tools like tree planting, waste recycling, and public transit systems.
  • Building upgrades: Allowing players to upgrade existing structures to increase efficiency and reduce resource consumption.
  • Advanced energy options: Expanding energy types to include wind turbines, geothermal, and nuclear power plants.
  • Random events: Introducing unexpected challenges like extreme weather events or economic downturns to increase replayability.
  • Multiplayer mode: Enabling competitive or cooperative gameplay for up to four players.

These features will be prioritized based on player feedback and available resources following the MVP release.

XII. Security

  • Data security: Implement data protection protocols. All saved data must be secure to prevent unauthorized access. Specific measures include data encryption (e.g., AES-256) for all stored player data, secure communication channels (e.g., HTTPS), and regular security audits to identify vulnerabilities.

  • Authentication: Outline player identification mechanisms if needed, such as profile creation or save encryption. Multi-factor authentication (MFA) may also be considered for added security.

XIII. Timeline

1. Phase 1: Research and functional specification (Deadline: 11/22)

  • Deliverables:
    • Identify core educational objectives for the game.
    • Research scientific data on climate change and urban sustainability to inform gameplay mechanics.
    • Develop the functional specification document, detailing the game's features and use cases.
  • Outcome: A finalized functional specification document that establishes the foundation for the project.

2. Phase 2: Technical specification and project setup (Deadline: 11/29)

  • Deliverables:
    • Write the technical specification document, defining the architecture and technical requirements.
    • Set up the Godot 4.3 project repository and integrate assets from the Starter Kit.
    • Establish workflows for coding, testing, and asset integration.
  • Outcome: A comprehensive technical specification document and a fully initialized project environment.

3. Phase 3: Prototype and test planning (Deadline: 12/6)

  • Deliverables:
    • Develop the basic game loop with placeholder assets.
    • Implement initial gameplay mechanics, including building placement and resource tracking.
    • Draft the test plan, outlining scenarios, test cases, and acceptance criteria.
  • Outcome: A functional prototype and a detailed test plan for validating the game.

4. Phase 4: MVP coding and iteration (Deadline: 12/13)

  • Deliverables:
    • Implement core gameplay mechanics, including pollution tracking and educational feedback.
    • Integrate assets from Kenney’s library for visual consistency.
    • Conduct iterative testing to resolve bugs and refine the user experience.
    • Develop the user manual, covering gameplay, mechanics, and educational content.
  • Outcome: A polished MVP with core functionality, supporting documentation, and an optimized user experience.

5. Phase 5: Final presentation and delivery (Deadline: 12/20)

  • Deliverables:
    • Conduct comprehensive QA testing to ensure stability and usability.
    • Prepare a professional presentation showcasing the game’s educational objectives and gameplay features.
    • Deliver a live demo highlighting the game’s mechanics and educational impact.
    • Submit all final deliverables, including code, documentation, and testing results.
  • Outcome: A completed game, ready for stakeholder evaluation and presentation.

XIV. Localization

1. Supported languages

The game will initially support English only for the MVP:

Future updates may include additional languages based on player demographics and demand, such as French, Spanish, German, or Arabic.

2. Localization strategy

The following steps outline the localization strategy for the future version of "Green City":

a. Text externalization

  • All in-game text, including dialogues, menus, and tooltips, will be stored in external resource files (e.g., JSON, CSV, or PO files). This ensures that translations can be easily added or updated without modifying the codebase.

b. Font and text formatting

  • Fonts that support multiple character sets, such as Latin, Cyrillic, and Arabic scripts, will be used to ensure compatibility across languages.
  • Text alignment and formatting will dynamically adapt to account for differences in word length and reading direction (e.g., right-to-left for Arabic).

c. Cultural relevance

  • Icons, symbols, and examples will be reviewed to ensure they are culturally neutral and globally relatable.
  • Environmental scenarios (e.g., renewable energy solutions) will include options relevant to different regions, such as solar power in sunny climates or wind turbines in coastal regions.

d. Voiceovers and audio

  • If voiceovers are added in future versions, localized voice acting will be implemented. For the MVP, text-based subtitles will suffice.

3. Localization tools

To streamline the localization process, the following tools will be considered:

  • Crowdin or POEditor: For collaborative translation management.
  • Godot's built-in localization system: For handling multiple language files and dynamic text loading.

4. Testing and validation

Before releasing localized versions, the following will be tested:

  • Text rendering and alignment for all supported languages.
  • Consistency and accuracy of translations.
  • User feedback to ensure translations are culturally and contextually appropriate.

5. Future plans

In future updates, localization may also include:

  • Regional-specific tutorials or examples (e.g., explaining carbon offset programs common in Europe).
  • Dynamic adaptation to local metrics (e.g., Celsius/Fahrenheit for temperature, kilometers/miles for distance).
  • Broader language support based on user feedback and analytics.

XV. Glossary