Village Veil — GDevelop Implementation Blueprint

Project: Village Veil (formerly CHORUS) | Engine: GDevelop | Platform: Mobile-first (iOS + Android)

1. GDevelop Scene Architecture

1.1 Scene Overview

Scene Name	Purpose	What It Shows	Transitions To
Boot	Initialize game, load saved data	Brief logo splash (1-2s)	→ Main Menu
Main Menu	Game entry point	Title logo, "Play" button, "Settings" button, cause meter preview	→ Day Scene (Play), → Settings
Day Scene	Village building & actions	Isometric village view, 4-10 homes, action buttons, cause meter, resource counters	→ Night Scene (sun sets), → Main Menu
Night Scene	Mosquito defense gameplay	Top-down dark village, mosquito waves approaching homes, tap/swipe controls	→ Dawn Reveal (morning)
Dawn Reveal	Morning results screen	Sunrise animation, protected/breached home summary, sick family indicators	→ Day Scene
Milestone Popup	Impact celebration	Cause meter full, AMF distribution info, shimmer cascade, share prompt	→ Day Scene (dismiss)
Settings	Options menu	Sound toggle, music toggle, AdMob test mode, reset progress	→ Main Menu

1.2 Scene Transition Logic

Boot:
  ├─ Load saved game data from Storage
  ├─ Initialize global variables (netsOwned, causePoints, villageLevel)
  └─ Wait 1.5 seconds → Main Menu

Main Menu:
  ├─ Display: Game title, Play button, Settings button
  ├─ Play button tapped → Day Scene
  └─ Settings button tapped → Settings

Day Scene:
  ├─ Display village state (homes, pools, resources)
  ├─ Day timer reaches 0 OR player taps "Sleep" button → Night Scene
  └─ Home button tapped → Main Menu

Night Scene:
  ├─ Spawn mosquito waves (timed intervals)
  ├─ All waves cleared OR all homes breached → Dawn Reveal
  └─ Player taps "Skip Night" → Dawn Reveal (partial results)

Dawn Reveal:
  ├─ Play sunrise animation (8-10 seconds)
  ├─ Display protection tally
  └─ Tap anywhere or "Continue" → Day Scene

Milestone Popup:
  ├─ Triggered when causePoints >= threshold (2000 = $2,000)
  ├─ Play celebration sequence
  └─ Tap "Share" (opens native share) OR "Continue" → Day Scene

2. Object Inventory

2.1 Sprite Objects

Village Elements

Object Name	Type	Description	Size (MVP)
Home_01 to Home_10	Sprite	Individual houses (unlocked progressively, protected)	64x64 px
Pool_Stagnant	Sprite	Mosquito breeding water	48x48 px
Net_Item	Sprite	Draggable bed net icon	32x32 px
CommunityCenter	Sprite	Health post / well / gathering space	96x96 px
Brush_Vegetation	Sprite	Overgrown areas to clear	48x48 px

Night Mode

Object Name	Type	Description	Size (MVP)
Mosquito_Basic	Sprite	Slow single mosquito	16x16 px
Mosquito_Darting	Sprite	Fast, direction change	16x16 px
Mosquito_Swarm	Sprite	Group of 4-6 mosquitoes	32x32 px
Mosquito_Stealth	Sprite	Semi-transparent, hard to see	16x16 px

2.2 Particle Emitters

Emitter Name	Particle Type	Purpose
Fireflies	Small yellow dots	Night ambient effect
Pool_Drain	Water droplets	Pool draining animation
Net_Shimmer	Sparkles	Net placement success
Swat_Hit	Yellow/gold sparks	Mosquito swatted
Milestone_Cascade	Gold sparkles	Celebration

3. Core Event Sheet Logic

3.1 Day Phase: Pool Draining

EVENT: Pool Tapped
────────────────────────────────
CONDITIONS:
  └─ Mouse/Touch Tapped on Pool_Stagnant
      (Object: Pool_Stagnant)
      (Cursor: is in collision with Pool_Stagnant)

ACTION:
  ├─ Play animation "draining" on Pool_Stagnant
  │
  ├─ Create particle emitter "Pool_Drain" at Pool_Stagnant
  │
  ├─ Tween: Scale Pool_Stagnant to 0 over 3 seconds
  │       (Duration: 3000ms)
  │
  ├─ Wait 3 seconds (using Timer)
  │
  ├─ Hide Pool_Stagnant
  │
  ├─ Change variable "causePoints" +10
  │
  ├─ Create floating text "+10" at Pool_Stagnant position
  │
  └─ Update Cause Meter display

3.2 Night Phase: Mosquito Spawning

EVENT: Spawn Mosquito Wave
────────────────────────────────
CONDITIONS:
  └─ Timer "WaveInterval" >= 5 seconds

ACTION:
  ├─ Reset Timer "WaveInterval"
  │
  ├─ Change variable "currentWave" +1
  │
  ├─ Update Wave display text
  │
  ├─ Create Mosquito_Basic at Random edge position
  │       (Quantity: 1 + currentWave / 2)
  │
  ├─ IF currentWave >= 4: Create Mosquito_Darting
  ├─ IF currentWave >= 7: Create Mosquito_Swarm  
  └─ IF currentWave >= 10: Create Mosquito_Stealth

3.3 AdMob Rewarded Video Trigger

EVENT: Show Ad Prompt
────────────────────────────────
CONDITIONS:
  └─ Player taps "Watch Ad" button

ACTION:
  ├─ Load Rewarded Ad (AdMob)
  │       (Ad Unit ID: "ca-app-pub-xxx/yyy")
  │
  ├─ Wait for ad to load
  │
  └─ Show Rewarded Ad

EVENT: Grant Ad Reward (Callback)
────────────────────────────────
CONDITIONS:
  └─ AdMob Rewarded Video Completed

ACTION:
  ├─ Change variable "causePoints" +50
  ├─ Change variable "adsWatched" +1
  ├─ Create floating text "+50 CAUSE POINTS!"
  ├─ Play reward sound
  └─ Check for cause milestone

4. Asset Specification

4.1 Free/CC Licensed Asset Packs

Asset Pack	Source	License	Use
Kenney Assets	opengameart.org / kenney.nl	CC0 / Public Domain	Primary MVP sprites
PWL Platformer Tiles	opengameart.org	CC-BY 3.0	Day background tiles
Game-Icons.net	game-icons.net	CC-BY 3.0	Buttons, net icons
Bfxr	bfxr.net (web tool)	CC0	All SFX

5. First Build Session Roadmap

Hour 1: Project Setup & Basic Village

Create GDevelop account, start new project (5 min)
Set canvas size: 720x1280 (portrait, mobile) (5 min)
Import placeholder sprites (10 min)
Create Day Scene with tiled background (10 min)
Place 4 home sprites in a row (10 min)
Add "Drain Pool" button and basic tap interaction (15 min)
Test: Tapping pool makes it disappear + score increases (5 min)

Hour 2: Day/Night Transition & Actions

Create Night Scene with dark background (10 min)
Add "Sleep" button → transitions Day → Night (10 min)
Add basic mosquito sprite spawning (timer-based) (15 min)
Add tap-to-destroy mosquito interaction (15 min)
Add net placement (drag from inventory to home) (15 min)
Test: Full day → night → swat cycle (5 min)

Hour 3: UI, Save/Load & Ad Integration

Add cause meter UI (text + progress bar) (10 min)
Set up Storage save/load for netsOwned (15 min)
Integrate AdMob rewarded video (test mode) (20 min)
Add milestone popup (10 min)
Add Main Menu scene with Play/Settings (10 min)
Final test: Full game loop (5 min)

Deliverable after Session 1: A playable loop where player can drain pools, place nets, defend against mosquitoes at night, and watch rewarded ads to earn cause points.

6. GDevelop-Specific Notes

6.1 Required Extensions

Extension	Purpose
AdMob	Rewarded video ads (built-in)
Tween	Smooth animations (built-in)
Particle System	Fireflies, swat effects (built-in)
Storage	Save/load game data (built-in)
Pathfinding	Mosquito movement

6.2 Mobile Canvas Setup

Project Settings → Display:
  ├─ Game resolution: 720 x 1280
  ├─ Render mode: Adaptive (letterbox)
  ├─ Orientation: Portrait
  └─ Canvas resize policy: Scale with viewport

6.3 Save/Load Pattern

JSON Structure:
{
  "netsOwned": 3,
  "causePoints": 450,
  "totalNetsFunded": 1000,
  "villageLevel": 2,
  "homesUnlocked": [true, true, true, true, false, false],
  "lastPlayedTimestamp": 1707000000
}

Save: Storage → Write JSON to storage (Key: "VillageVeilSave")
Load: Storage → Load from storage (Key: "VillageVeilSave")

Document version 1.0 — Builder's Technical Reference