From fb32783225204dda58c9e00cf2d69647176ef6ef Mon Sep 17 00:00:00 2001 From: Justin Oros Date: Thu, 21 May 2026 15:57:30 -0700 Subject: [PATCH] Update README with all current features, file list, and NPC sprite documentation --- README.md | 152 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 18a6953..c0e8478 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Journey through towns, each covering a different Azure exam. Play on your phone, **Current towns:** | Town | Exam | Status | |---|---|---| -| ๐Ÿ˜๏ธ Fundamentals Town | AZ-900: Azure Fundamentals | โœ… Available | +| ๐Ÿ˜๏ธ AZ-900 Town | AZ-900: Azure Fundamentals | โœ… Available | | ๐Ÿ™๏ธ Administrator City | AZ-104: Azure Administrator | ๐Ÿ”œ Coming soon | | ๐Ÿ—๏ธ Developer District | AZ-204: Azure Developer | ๐Ÿ”œ Coming soon | | ๐Ÿ”’ Security Stronghold | AZ-500: Azure Security | ๐Ÿ”œ Coming soon | @@ -24,10 +24,18 @@ Journey through towns, each covering a different Azure exam. Play on your phone, ``` pokeazure/ -โ”œโ”€โ”€ index.html โ† Game screens & structure -โ”œโ”€โ”€ style.css โ† GBA Pokรฉmon aesthetic, fully responsive -โ”œโ”€โ”€ game.js โ† Game engine, controller, walking, save system -โ”œโ”€โ”€ questions.json โ† Questions & answers (organised by town/exam) +โ”œโ”€โ”€ index.html โ† Game screens & structure +โ”œโ”€โ”€ style.css โ† GBA Pokรฉmon aesthetic, fully responsive +โ”œโ”€โ”€ game.js โ† Game engine, controller, walking, save system +โ”œโ”€โ”€ questions.json โ† Questions & answers (organised by town/exam) +โ”œโ”€โ”€ music.mp3 โ† Overworld background music (looping) +โ”œโ”€โ”€ music-rival.mp3 โ† Battle/question screen music (looping) +โ”œโ”€โ”€ player.png โ† Player sprite sheet +โ”œโ”€โ”€ oak.png โ† Professor Oak NPC sprite +โ”œโ”€โ”€ gary.png โ† Rival Gary NPC sprite +โ”œโ”€โ”€ joy.png โ† Nurse Joy NPC sprite +โ”œโ”€โ”€ jenny.png โ† Officer Jenny NPC sprite +โ”œโ”€โ”€ favicon.ico โ† Browser tab icon โ””โ”€โ”€ README.md ``` @@ -36,7 +44,7 @@ pokeazure/ ## ๐Ÿ•น๏ธ Host on GitHub Pages (free) 1. Create a GitHub repo named **`pokeazure`** -2. Upload all **4 files**: `index.html`, `style.css`, `game.js`, `questions.json` +2. Upload all files to the root of the repo 3. Go to **Settings โ†’ Pages โ†’ Source: `main` branch, `/ (root)` folder** 4. Hit **Save** โ€” live in ~60 seconds at `https://justinoros.github.io/pokeazure` @@ -44,50 +52,55 @@ No server, no database, no cost. --- -## ๐ŸŽฎ GBA Controller Overlay +## ๐ŸŽฎ Controls -On mobile, a semi-transparent Game Boy Advance-style controller overlays the bottom of the screen: +### Mobile Portrait +A semi-transparent GBA-style controller overlays the bottom of the screen, split into two panels: +- **Left panel**: D-pad + SELECT/START +- **Right panel**: A and B buttons -| Control | Action | -|---|---| -| **D-pad** | Walk the player around the map | -| **A button** (red) | Talk to NPC on map ยท Confirm answer in battle ยท Advance dialog | -| **B button** (blue) | Talk to NPC on map ยท Advance dialog | -| **SELECT / START** | Decorative โ€” reserved for future use | - -The controller is hidden on desktop (โ‰ฅ900px wide) โ€” use the keyboard instead. - ---- - -## โŒจ๏ธ PC Keyboard Controls +### Mobile Landscape +The controller moves to side panels flanking the game screen: +- **Left panel**: D-pad + SELECT/START (stacked vertically) +- **Right panel**: A and B buttons (diagonal layout) +### PC Keyboard | Key | Action | |---|---| | **WASD / Arrow keys** | Walk player on map | | **E / Enter** | Talk to NPC ยท Confirm answer ยท Advance dialog | | **X** | Talk to NPC ยท Advance dialog | -| **1 / 2 / 3 / 4** | Quick-pick answer directly | +| **1 / 2 / 3 / 4** | Quick-pick answer | | **Space** | Advance dialog | --- -## ๐Ÿ—บ๏ธ Map & Walking +## ๐Ÿ—บ๏ธ Map & Gameplay -- The player sprite walks freely around the overworld map using the D-pad or WASD -- Walking animations change based on direction (left, right, up, down) -- Press **A**, **B**, **E**, or **Enter** at any time to talk to the NPC and start the question -- Tapping the NPC sprite directly also triggers the conversation +- Player walks freely in all 4 directions across a large 2D world +- A directional arrow indicates where the next NPC is โ€” hides when the NPC is on screen +- Walk up to an NPC and press E/A to start a question +- After answering, the next NPC spawns in a random direction (never the opposite of the last) +- Trees render above the player for depth +- NPCs float with a gentle animation + +--- + +## ๐ŸŽต Music + +- **Overworld** (`music.mp3`): plays while walking the map +- **Battle** (`music-rival.mp3`): plays during question/answer screen +- **Result screen**: silent +- Toggle mute with the ๐ŸŽต button in the HUD --- ## ๐Ÿ’พ Save System -Progress is stored in the player's browser (`localStorage`) automatically: - -- **Auto-saves** after every answered question and on map return โ€” a ๐Ÿ’พ icon flashes to confirm -- **Continue screen** appears on next visit showing trainer name, progress %, and score -- **New Game** option always available โ€” prompts confirmation before erasing save -- Save clears automatically on completion so the next run starts fresh +- **Auto-saves** after every answered question +- **Continue screen** on return visits showing trainer name, progress, and score +- **Shuffled question order** is saved so continuing always resumes at the correct question +- **New Game** option prompts confirmation before erasing --- @@ -95,25 +108,22 @@ Progress is stored in the player's browser (`localStorage`) automatically: | Feature | Detail | |---|---| -| GBA controller overlay | D-pad + A/B buttons, semi-transparent, mobile only | -| Walking player | Moves freely on map, directional walk animations | -| Mobile-first design | Full-screen on phones with safe-area support, framed on desktop | -| localStorage save | Auto-save with continue screen on return visits | -| Multi-exam structure | Each town covers a different Azure certification exam | -| Single & multi-select | "Choose two" questions require selecting both correct answers before confirming | -| Randomised answer positions | Correct answer shuffled to a random slot โ€” no pattern to exploit | -| Numbered answers | Options labelled 1/2/3/4 (not A/B/C/D) | -| Name entry | On-screen pixel keyboard, just like the real game | -| Typewriter text | Authentic dialog effect, tap/press to skip | -| 22 NPC characters | Professor Oak, Misty, Brock, Giovanni, Lanceโ€ฆ | +| Free 2D movement | Walk in any direction, camera follows player | +| Random NPC directions | Next NPC spawns in a random direction each leg (no U-turns) | +| PNG NPC sprites | NPCs use pixel art PNG files; emoji fallback for unassigned NPCs | +| Mobile portrait & landscape | Fully optimised controller layout for both orientations | +| Single & multi-select questions | "Choose two" shows CONFIRM button; single select is immediate | +| Shuffled question order | Different order every new game | | Streak bonuses | 3ร— correct = +150 pts ๐Ÿ”ฅ, 5ร—+ = +200 pts ๐Ÿ”ฅ | -| Milestone badges | Earned at Q25, Q50, Q75, Q100 per town | +| Milestone badges | Cloud Explorer (Q25), Azure Apprentice (Q50), Cloud Practitioner (Q75), AZ-900 Champion (Q100) | | Correct answer reveal | Wrong answers show the right answer + full explanation | -| Scanline overlay | Authentic CRT/GBA screen effect | +| Tap anywhere to continue | Result screen advances on any tap/click, not just CONTINUE button | +| Rival battle music | Separate music track plays during questions | +| Player faces last direction | Idle sprite faces the last direction walked | --- -## ๐Ÿ“š AZ-900 Topics Covered (Fundamentals Town) +## ๐Ÿ“š AZ-900 Topics Covered (AZ-900 Town) | Domain | Topics | |---|---| @@ -128,14 +138,14 @@ Progress is stored in the player's browser (`localStorage`) automatically: ## โž• Adding a New Town (Exam) -To add a new exam, add a new level object to the `levels` array in `questions.json`: +Add a new level object to the `levels` array in `questions.json`: ```json { "levels": [ { "id": 1, - "name": "Fundamentals Town", + "name": "AZ-900 Town", "exam": "AZ-900", "questions": [ ... ] }, @@ -153,7 +163,7 @@ To add a new exam, add a new level object to the `levels` array in `questions.js ## โž• Adding Questions -**Single-answer question:** +**Single-answer:** ```json { "id": 101, @@ -165,11 +175,11 @@ To add a new exam, add a new level object to the `levels` array in `questions.js } ``` -**Multi-select question (choose two):** +**Multi-select (choose two):** ```json { "id": 102, - "npc": "Misty", + "npc": "Nurse Joy", "text": "Which two options are correct? (Choose two)", "options": ["Option A", "Option B", "Option C", "Option D"], "answers": [0, 2], @@ -177,30 +187,46 @@ To add a new exam, add a new level object to the `levels` array in `questions.js } ``` -- `answer` (single integer) = 0-based index of the one correct option -- `answers` (array of two integers) = 0-based indices of both correct options -- The game detects which mode to use automatically and shows a CONFIRM button for multi-select - --- -## ๐Ÿง‘ Adding NPCs +## ๐Ÿง‘ Adding NPC Sprites -In `game.js`, add to the `NPC` object at the top: +In `game.js`, update the `NPC` object at the top: ```js const NPC = { - 'Your NPC Name': '๐Ÿง‘', - ... + 'Professor Oak': 'oak.png', // PNG file in repo root + 'Nurse Joy': 'joy.png', + 'Brock': '๐Ÿง—', // emoji fallback still works }; ``` -Then reference `"npc": "Your NPC Name"` in `questions.json`. +- PNG filenames are relative to the repo root (no path needed) +- Any NPC not in the object falls back to `๐Ÿง‘` + +--- + +## ๐Ÿ”ง Rebranding (CONFIG object) + +To create a version for a different exam set, update the `CONFIG` object at the top of `game.js`: + +```js +const CONFIG = { + gameName: 'PokรฉAzure', + subject: 'Azure', + examName: 'AZ-900', + townName: 'AZ-900 Town', + saveKey: 'pokeazure_save_v1', + introLines: [ ... ], + namePrompt: '...', +}; +``` --- ## ๐Ÿ“ฑ Mobile Tips - Add to Home Screen on iOS/Android for a full-screen app-like experience -- The game uses `100dvh` and `env(safe-area-inset-bottom)` for notched phones (iPhone X+) -- Tap anywhere on the dialog box during the intro to skip the typewriter and advance -- Tap the NPC sprite directly on the map as an alternative to pressing A/B +- The game uses `100dvh` and `env(safe-area-inset-*)` for notched phones +- Tap anywhere on the result screen to continue (no need to find the CONTINUE button) +- Rotate to landscape for a wider game view with side-panel controls