Chronicles of Devlandia

"Solve the Map, Break the Code, Find the Treasure."

A browser game for an HCI course project. Explore the snowy C++ Peaks with your AI drone, fix a CSS bug at the terminal gate to open the way north, survey the Frozen River, walk west into Dev Village, where Ada the villager has hints, go south into the Dense Forest, where a ranger keeps a campfire, walk west out of the forest into the Sunbaked Desert, or east to Sunny Beach.

Along the way, 11 language treasure chests ask questions in HTML, CSS, PHP, Python, Java, C#, SQL, C++ and JavaScript, and each one you answer earns a badge. In the village, the Syntax Matcher at the Syntax Terminal prints an access code that unseals the Archive, and the Codex keeps every badge you've earned with the question behind it. Team games have a chat box, and every game has a small command line.

Built with Vite, React 19, TypeScript and Tailwind CSS 4. Play with a keyboard on a computer, or with on-screen touch controls on a phone or tablet. The layout fits screens down to 360px wide, and on a desktop the map fills most of the window.

Getting started

npm install
npm run dev      # http://localhost:5173
npm test         # unit + component tests (Vitest)
npm run build    # type-check and build to dist/

How to play

Action	Keyboard	Touch screen
Move	W A S D or arrow keys	D-pad under the map (tap = one step, hold = keep moving)
Inspect / interact with a nearby point	E	[E] button (lights up when something is in range)
Open or close the Codex	C	[C] Codex in the top bar
Close the terminal or the Codex	Esc or [X] CLOSE	[X] CLOSE
Chat (team) or type a command (solo)	Enter or / from the map, then Esc to go back to walking	the CHAT / COMMANDS tab beside the log

The touch controls only appear on touch screens; keyboard players never see them. To try the game on a phone on the same Wi-Fi, run npm run dev -- --host and open the Network link it prints.

• Continue after a refresh: a solo game saves itself in this browser as you play (your place, HP, time, items, badges and class, kept per account or for the guest). After a refresh or reopening the tab, the game resumes by itself where you were (no click needed). [=] Menu still leaves to the main menu, which then shows Continue above Solo Quest; Solo Quest starts a fresh game. Windows that were open (terminals, the Codex) come back shut. Team games are not saved, because the room lives on the server; a refresh returns to the menu. Private windows or blocked storage just forget.

• A bigger map: the map now fills the window. Zoom (− and + at the map's top-right; the label shows the zoom as a multiple of the fit, like 1.5×) steps up one whole pixel at a time so the art stays sharp; once the map is larger than the window it scrolls with you. It starts on auto, which steps up once if the fit would leave wide empty bands, and your choice is remembered in this browser. Full-screen map (F or the ⛶ button) hides the side panels, keeps a slim top bar (hearts, time, Help, Codex, Menu) and shows the newest log line over the map; the full log stays available to screen readers. F or ✕ (or Esc, where the browser's own full screen was used) goes back. A phone held sideways gets the full-screen layout by itself, with the move pad and [E] button floating over the map instead of in a bar under it.

• Health: Your health is 5 hearts (5 HP, one per heart, with the number beside them). The river costs a heart every 4.5 seconds, and every wrong answer costs a heart (at a chest, the gate, the cipher, the signal tower circuit, the matcher, the sandcastle, the Archive keypad or the lighthouse lamp; the log says so, and at your last heart a wrong answer downs you and closes the window). Only food heals, and each piece restores one heart. The map flashes red when you are hurt and green when you heal, and at 2 hearts or less the hearts pulse, the screen edges glow red and the log warns you once (the flashes and pulse stay still if your device is set to reduce motion). You get food from the world and from NPCs: a healing herb in the Dense Forest, a cactus fruit in the Sunbaked Desert and a glass of cold lemonade on the Sunny Beach, and a garden carrot beside the Dev Village garden (pick one with E beside it, or tap its button once you stand there), the ranger's stew once you bring her the three glow mushrooms, the nomad's waterskin once you bring her the three water jars, and the Ski Lodge keeper's soup. Food goes into your bag and is eaten from the inventory (see Food below). In team games, appears when a teammate stands beside you: it hands them one of your own pieces of food (you must have one; you can give one every 10 seconds). They eat it themselves, so a teammate can never change your HP directly.

The top bar shows the time with a small pixel icon: a sun by day, a sunset at dusk and a moon at night. The map is drawn in pixel art on a canvas: snowy peaks, the frozen river, the meadow and the dense forest, with your hooded explorer and your AI drone. In team games your teammates are explorers in their own colours. Bushes, rocks and trees mark the edge of the walkable area, with a gap in the hedge where the path leads west, and a stone wall with a barred gate closes off the north. Dev Village has huts, a well and fences around a dirt square, and the whole village is one big meadow (no snow and no wall, so you can walk its north half too): a windmill whose sails turn, a pond with a footbridge, a town square with a fountain and benches, an orchard, a fenced crop field and three more huts, joined to the main road by a new dirt road. The huts have smoke curling from their chimneys, windows and a lantern that glow from dusk, three villagers who pace the road and square, a pecking chicken, two garden plots in the south and a market stall (all decoration: only Ada talks, and nothing in the village changes your stats). The smoke and the villagers stand still if your device is set to reduce motion. The mini-map shows the village, the Peaks, the desert, the forest, the beach and Foggaten Island side by side, with yours outlined. Pixels stay sharp at any screen size; on some laptop scaling settings (such as Windows at 125 %) the map is drawn a little smaller to keep them sharp. If your device is set to reduce motion, characters step instead of gliding and the blinking lights, pulses and glints stay still.

Accounts and saved badges

The game opens on a login screen. Log in or Sign up with a name (3–12 letters, digits, - or _) and a password (8 or more characters), Sign in with Google, or Play as guest. Signed-in players keep their 11 badges, and the answers behind them, on any computer: each new game starts with them earned, and the Codex shows the question you actually answered. Guests can play Solo Quest and Team Lobby too, but nothing of theirs is saved. Quest progress, your position and your inventory are not saved.

The menu shows who is playing, with [ Log out ] (or [ Log in ] for a guest). A signed-in player can add an optional email with [ Add email ]; once it is confirmed, Forgot your password? sends a reset link to it (an account with no email can't reset its password). A Google player picks a name the first time. In a team game your team name is your account name.

Accounts setup (for whoever runs the Supabase project). Accounts use the same Supabase project as Online play, with two tables (profiles, badges) locked so a player can only read and write their own rows, and one Edge Function (account) that signs players up and in by name. In supabase/: apply migrations/20261017000000_accounts.sql, deploy functions/account (supabase functions deploy account --no-verify-jwt, which supabase/config.toml also sets; set the secret SITE_URLS to the comma-separated sites a reset link may return to, for example https://your-game.example,http://localhost:5173, never a wildcard such as *.vercel.app; it reads its service key from the platform's environment, never from this repo), and check the row rules with tests/policies.sql. For Google sign-in, enable the Google provider in Supabase and Google Cloud and list the redirect URLs (the production site, Vercel previews and http://localhost:5173). Turn off "Secure email change" in Supabase Auth settings, or [ Add email ] can never be confirmed (the hidden sign-in address can't receive mail). Password-reset emails go through Supabase's built-in sender, which is heavily rate-limited: add a custom SMTP sender for real use. If the account server can't be reached, the login screen says so and Play as guest still works.

Team Lobby (2–4 players)

From the main menu choose TEAM LOBBY, type a nickname and pick a connection:

• Online: players on different devices, over Supabase Realtime (needs internet and a configured project, see below).
• Same computer: browser windows on one device, no internet needed (handy for demos and testing).

One player presses [ Create Room ] and reads out the 4-letter room code; the others type it and press [ Join ]. The host (the creator) presses [ Start Expedition ] once at least 2 players are in. A player who joins after the start drops straight into the game.

In the game, teammates appear as colored dots with their names, and the top bar shows ROOM <CODE> · <N> online. A teammate in another zone (Peaks, Dev Village, Dense Forest, Sunbaked Desert, Sunny Beach or Foggaten Island) shows only on the mini-map.

• Shared by the team: surveying the river, the Supply Cache loot, the decoded clue, the Golden Semicolon, the north gate, the signal tower (its lifted fog and the bridge), the Archive, and the clock. Everyone's Syntax Terminal prints the same access code, so once one player unseals the Archive it's open for all.
• Your own: your zone, position, HP, terminals and badges. Badges are personal: each explorer opens their own chest.
• Team chat: the lobby and the game share one conversation. Type a message and press Enter (or [ SEND ]), or tap a quick reply (On my way, Need help, Meet at the gate, Found it!, Wait for me, Good job!). Messages are 120 characters at most, one a second; rude words are masked and a nickname that would be masked is refused when you create or join. Two players with the same nickname read as Kai and Kai (2). The CHAT tab shows how many messages you haven't read, and on a phone the top bar does too. /ping marks the map for the whole team.
• Your event log tells you what teammates did, for example "Kai opened the gate.", "Kai went to Dev Village." or "Kai went to Dense Forest." or "Kai earned the SQL Badge." [=] Menu leaves the room.

For teachers. The chat is filtered (rude words in English and Filipino are masked, invisible characters are removed) and rate-limited (one message a second and one ping every 5 seconds per player, checked again on receipt), and a player can mute any teammate; a mute lasts while you are in the room. It is a classroom aid, not a moderated service: a modified copy of the game can still post under another player's roster name, anyone who has the room code can read that room's chat, and nothing is stored anywhere (a refresh or leaving the room clears it). Keep room codes within each team. A team's traffic is at most about 16 position updates, 4 chat messages and 0.8 pings per second.

Online setup. Online play works out of the box with the game's own Supabase project (chronicles-of-devlandia; team play itself uses Realtime only and stores nothing, while accounts add the two tables above). To use a different project, put its URL and publishable key in a .env file (see .env.example):

VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_your_key

If the server can't be reached, Online shows "Can't reach the team server…" and Same computer still works. The claude.ai preview link blocks outside connections, so there only Same computer works (between windows of the same browser).

Character classes

Before Solo Quest and before a team game, Choose your class: Warrior, Archer, Mage, Assassin, Tank or Healer. A class is a look only (an outfit colour and a small item such as a helm, bow, hat, mask, shield or staff); it changes no stat, speed or puzzle. In a team everyone sees each other's class, two players may pick the same one, and the hood colour still tells teammates apart. A signed-in player's last choice is saved in their account's own profile data and preselected next time (no database change); guests start on Warrior and nothing is saved. A class value that is missing or not one of the six is shown as Warrior.

A phone held sideways

Turn a phone to landscape (or use a window shorter than 500 px) and the map goes full-screen with a slim one-row top bar and touch controls over the map. The bar keeps the hearts, the clock and the region, and gains a Food ×N button (the inventory bar is hidden here, so this is how you eat and heal) and a Chat button that opens the chat (or the command line, in solo play) as a sheet over the lower part of the map, with [X] to close it; Help, Codex and Menu become small [?], [C] and [=] keys. The controls are smaller and see-through until you touch them (they wake for two seconds after each touch), and the ⇄ button between them swaps the sides (D-pad on the right, [E] on the left; remembered in this browser). The Stick / Pad button next to it switches the arrow pad (the default) for a joystick: put a thumb on the ring and lean it, and you step the way you lean furthest (up, down, left or right, repeating while you hold; resting in the middle is not a step). The choice is remembered in this browser, works in both the sideways and the upright view, and the four arrow buttons stay in the page for keyboards and screen readers. The bar and controls keep clear of a notch, rounded corners and the home bar (safe-area insets; the page runs edge to edge). On a touch screen the floating [E] prompt chip over the map is hidden, because the big [E] button already says it. The newest log line over the map fades out after about four seconds and shows again with each new line.

Leaderboards

The menu's Leaderboards button shows the top 20 players by badges earned (out of 11). Players with the same count share a rank, and the one who earned their latest badge first is listed first. Anyone can open it, guests included. A signed-in player sees their own row (or their rank if they are outside the top 20) and a Hide me from the leaderboard switch; a hidden player disappears from the list but still sees their own rank. Only names, ranks and counts leave the database: two read-only functions (leaderboard_top, leaderboard_me) do the counting, so the badge and profile tables stay private to their owners. The server stamps each badge's time, so nobody can back-date one to win a tie; badge counts are still self-reported (nothing checks a saved answer), which is fine for a friendly board but not for prizes. It needs supabase/migrations/20261017010000_leaderboards.sql applied after the accounts migration (check it locally with supabase/tests/leaderboard.sql); until then the screen says "Can't reach the leaderboard." and everything else works as before.

Profile photos. A signed-in player can press [ Change photo ] on the Leaderboard screen to choose a picture (JPG, PNG or WebP, up to 10 MB). A crop window opens with a round frame: drag the picture (or use the arrow keys) to choose which part is inside it and zoom with the slider (or + and -, up to 4×); [ Save photo ] keeps it and [ Cancel ] leaves your old photo alone. The browser then cuts exactly the part inside the frame and redraws it as a 96×96 JPEG (which also drops camera data such as location), and only that small file (about 10 KB) is uploaded to a public Supabase Storage bucket called avatars. Each photo is named by a random key held in the avatars table, never by the user id, and leaderboard_top hands out the key, so the list still shows no account ids; a new photo gets a new key, so an old picture is never served from a cache. A round picture sits between the rank and the name, or the first letter of the name when there is none (or it fails to load); [ Remove photo ] deletes it, and hidden players show no photo. Guests cannot upload. There is no automatic moderation: the owner can delete a file in the Supabase dashboard (Storage, avatars) and remove the row from the avatars table. It needs supabase/migrations/20261019000000_avatars.sql applied after the leaderboards one (check it with supabase/tests/avatars.sql; it also replaces leaderboard_top and leaderboard_me with versions that add a photo column; the list keeps working before or after, and until it is applied the photo buttons say "Couldn't save your photo. Try again."). If a replacement upload fails, the old photo is gone too and the player is told to try again.

Hall of Fame

North of Dev Village (walk up the new road at the top of the village, through the gap in its north hedge) lies the Hall of Fame, the leaderboard as a place. The top 10 players stand in it: the first three on the stage, on gold, silver and bronze podium blocks (their hoods match), and ranks 4 to 10 on the ground below. Each is drawn as their own class hero, with a name plate floating above the head: their round profile picture (or the first letter of their name) and their name, cut to eight characters on the plate. Spots nobody has earned yet show a grey silhouette and a ?.

Walk up to a figure and press E (or tap it) to read who they are in the log: Alice: rank 1, 3/11 badges, Mage. Tied players keep their true rank (two players tied for first both read "rank 1"; the stage fills in list order). Names go through the same rude-word filter as the leaderboard. The signpost in the corner explains the place. The list is fetched each time you walk in (not live while you stand there): while it loads the log says "The Hall is waking up…", and if the leaderboard cannot be reached, "Can't reach the leaderboard." and the spots stay empty. Anyone can visit: guests, signed-in players and teammates (hidden players never appear). The world map has a Hall cell above the village.

The class comes from one extra column on leaderboard_top (cls: the class key from the account's private metadata, cut to 12 characters, and nothing else of the metadata). It needs supabase/migrations/20261019010000_leaderboard_class.sql applied after the avatars one: run it in the Supabase SQL Editor (the connector holds DROP statements for approval) and check it with supabase/tests/leaderboard.sql. Until it runs, the client still works: a row without a class is drawn as the default Warrior.

Project layout

src/game/      pure game rules: constants, classes, geometry, clock, cipher, logic, challenges, roll, cards, team, wall, zones, village, forest, island, lamp, reducer
src/learn/     the challenge engine and question bank: live check, shuffling, access codes, the 11 chests and their questions
src/chat/      chat rules and commands: text cleaning and masking, display names, ping places, the command line
src/hooks/     keyboard controls, game timers, team session, chat feed, pings
src/net/       team transports: Supabase (Online), BroadcastChannel (Same computer), in-memory (tests); the shared Supabase client
src/auth/      accounts: name and password rules, the auth client (Supabase and in-memory), useAuth, add-email
src/leaderboard/ the leaderboard: types and parsing, the store (Supabase and in-memory)
src/progress/  saved badges: the store (Supabase and in-memory), restoring a game from them, the saver
supabase/      the accounts and leaderboards migrations, the `account` Edge Function and the SQL checks
src/render/    the pixel-art map: world geometry, sprites, areas/ (each zone's art), terrain, motion, scene description and painting
src/screens/   AuthScreen, ChooseName, SetPassword, ClassPicker, Leaderboard, MainMenu, TeamLobby, ChallengeTerminal + challenge/* (chests, gate, scroll, Matcher, keypad), Codex, LogicModal (tower), chat/* (chat panel and announcer), overworld/*
src/ui/        Panel, Button, Meter, TerminalDialog primitives

Design sources

• Figma Make wireframe: https://www.figma.com/make/Um3mf7sQOJeCYGX5jdffnz/Create-Wireframe--Copy-

• Spec with exact values: docs/superpowers/specs/2026-10-07-devlandia-ui-spec.md

• Visual mockup: docs/reference/game-ui-mockup.svg

• Implementation plan: docs/superpowers/plans/2026-10-07-devlandia-ui.md

• Food (inventory): the healing finds (herb, cactus fruit, cold drink, garden carrot) and the keeper's soup are packed into your bag as food instead of healing on the spot. The first inventory slot shows Food ×N; click it to eat one (+1 HP, never past the maximum; "not hungry" at full health keeps it). The Key slot is still a placeholder. A small pop-up fades over the map when an NPC gives you food ("Thank you!": the ranger's stew, the nomad's waterskin, the keeper's soup) and when you eat or drink ("Yummy!", "Delicious!", "Tasty!", "Mmm, so good!", "Refreshing!", in turn), next to the scroll's "Ohh, a scroll!".