MapTap practice project: session summary and Codex handoff

Updated October 21, 2026.

Purpose and working context

Brian plays the daily MapTap geography game with Bellese’s executives. He generally scores around 850-870 and finishes behind the CEO and COO. The immediate goal is repeated practice that improves geographic recall and transfers to the actual game. He is comfortable treating geography as a long-term learning project.

The practice target is recognizing where cities lie from landforms, coastlines, mountains, rivers, lakes, and oceans. Brian already handles globe rotation and tapping competently. Those mechanics were context for the game, not a separate training objective. Physical atlases support his learning, but daily games provide too few repetitions. He may play five sessions consecutively or roughly 25 practice rounds per day.

Latest decision: continue in the actual website directory

Continue implementation in a Codex project opened on the directory or repository containing the website. Inspect that checkout and its instructions before editing. Brian expects to publish through his GitHub Pages site. No repository name, Pages URL, branch, or deployed version was supplied in this conversation, and no GitHub deployment was performed here.

The latest requested implementation work is replacing the imagery with satellite imagery resembling MapTap and adding zoom and pan. These changes have been discussed but have NOT been implemented in the delivered ZIP. This document is the handoff for that work.

Current deliverables

  • MapTap_Topographic_City_Study_Maps.pdf: four labeled study maps, one per country. These use colored shaded relief, not photographic satellite imagery.
  • MapTap_Remedial_Practice.zip: working static HTML/CSS/JavaScript game, with its map assets and README.
  • MapTap_Project_Handoff.md: this summary. This is the only Markdown summary created in the visible session. There is no earlier geography summary file identified here.

Original workspace locations, which are historical references and may not exist in a future project:

/workspace/scratch/a5afd7ff40d7/output/pdf/MapTap_Topographic_City_Study_Maps.pdf
/workspace/scratch/a5afd7ff40d7/output/bundles/MapTap_Remedial_Practice.zip
/workspace/scratch/a5afd7ff40d7/maptap-remedial-practice/dist/
/workspace/scratch/a5afd7ff40d7/maptap-remedial-practice/render_assets.py

The PDF and ZIP were saved as persistent downloads. Bring the ZIP or the existing website checkout into the future project; this summary contains context, not the image files or complete source.

Current game behavior

  • Every session has four rounds, one randomly chosen city from each of Brazil, China, Australia, and Russia.
  • Country order is shuffled. Each country has a five-city pool.
  • A city and country are shown. The user taps the map once.
  • Immediate feedback shows the guess in blue, the target in gold, a connecting line, great-circle distance, a 0-100 score, and a short geographic cue.
  • After four rounds, the game shows a normalized 0-1000 score and individual round results.
  • “Repeat this set” repeats the same targets in the same order.
  • “New random set” draws a fresh session. A city may repeat by chance.
  • Sessions are unlimited. There is no timer, account, server, leaderboard, sharing workflow, or saved history.
  • The current game has no zoom or pan. Its canvas uses a pointerup event to submit a guess.

Immediate work: satellite imagery

Brian clarified that “topographic” meant the satellite appearance he sees in MapTap. He likes the existing shaded-relief maps because they recall a globe his grandfather owned, but visual similarity to MapTap matters more for practice transfer.

Use natural-looking Earth imagery with terrain, vegetation, water, and coastlines. Keep city names, roads, and political overlays out of the question view. The existing ETOPO raster has faint linework baked into it and should not be treated as the final visual reference.

Inspect MapTap’s publicly delivered imagery and rendering approach to determine an appropriate visual match. Brian explicitly authorized examining its public code for relevant mechanics. During this session, the assistant reviewed public pages and the FAQ, but did NOT inspect MapTap’s JavaScript bundles, discover its texture URLs, or establish its imagery provider. Do not claim that any of those technical details are already known.

Choose an imagery source with sufficient detail for the added zoom. Retain required attribution and document any API setup if a service is used. The delivered game currently needs no network connection or API key; a service-based replacement may change that property. A fixed offline raster can also work if its resolution supports the chosen zoom range.

Immediate work: zoom and pan

Provide both gesture controls and visible controls:

  • Phone: pinch to zoom and drag to reposition.
  • Laptop: wheel/trackpad zoom and drag to reposition.
  • Visible plus and minus buttons for either device.

Zoom must help precise placement while preserving accurate coordinates. The map, guess marker, target marker, and connecting line must share the same transformation. Convert pointer coordinates back through the viewport transformation before calculating longitude and latitude.

Separate a deliberate tap from a drag or pinch. The existing unconditional pointerup answer handler must change so that releasing a navigation gesture does not submit an answer. Bound zoom and pan to usable ranges. A reset-view control is a reasonable small implementation detail.

Countries and current city pools

These are the cities in the delivered game. They were carried forward as priority targets from the discussion. The visible record does not contain an archive-frequency count supporting a claim that these are the five most frequently used cities per country. Treat them as the current practice pool, not a verified historical ranking.

Brazil

  • São Paulo: latitude -23.5505, longitude -46.6333.
  • Rio de Janeiro: latitude -22.9068, longitude -43.1729.
  • Brasília: latitude -15.7939, longitude -47.8828.
  • Porto Alegre: latitude -30.0346, longitude -51.2177.
  • Belo Horizonte: latitude -19.9167, longitude -43.9345.

China

  • Hong Kong: latitude 22.3193, longitude 114.1694.
  • Shenzhen: latitude 22.5431, longitude 114.0579.
  • Nanjing: latitude 32.0603, longitude 118.7969.
  • Hangzhou: latitude 30.2741, longitude 120.1551.
  • Urumqi: latitude 43.8256, longitude 87.6168.

Australia

  • Sydney: latitude -33.8688, longitude 151.2093.
  • Perth: latitude -31.9523, longitude 115.8613.
  • Brisbane: latitude -27.4698, longitude 153.0251.
  • Canberra: latitude -35.2809, longitude 149.1300.
  • Adelaide: latitude -34.9285, longitude 138.6007.

Russia

  • Moscow: latitude 55.7558, longitude 37.6173.
  • St. Petersburg: latitude 59.9311, longitude 30.3609.
  • Yekaterinburg: latitude 56.8389, longitude 60.6057.
  • Vladivostok: latitude 43.1155, longitude 131.8855.
  • Irkutsk: latitude 52.2869, longitude 104.3050.

Current source and packaging

The ZIP extracts to a MapTap_Remedial_Practice/ folder containing:

index.html
styles.css
data.js
game.js
README.txt
assets/
  brazil.jpg
  china.jpg
  australia.jpg
  russia.jpg

index.html supplies the game and summary views. styles.css defines a responsive dark interface. data.js supplies country extents, city coordinates, image paths, and learning cues through window.MAPTAP_DATA. game.js handles selection, canvas rendering, coordinate conversion, scoring, and repetition. Scripts are ordinary browser scripts, with no build step, modules, fetch requests, or external dependencies at runtime.

The separate authoring script render_assets.py uses Python, Matplotlib, and Basemap to produce the current ETOPO images. It is outside the delivered ZIP. Those Python packages are not needed to play the game.

Projection and coordinate conversion

All game map images use Mercator projection and these geographic bounds:

  • Brazil: west -75.5, east -32.0, south -35.5, north 6.0; image 1600 by 1619 pixels.
  • China: west 72.0, east 136.0, south 17.0, north 54.5; image 1600 by 1200 pixels.
  • Australia: west 111.0, east 155.5, south -45.0, north -9.0; image 1600 by 1491 pixels.
  • Russia: west 19.0, east 145.0, south 40.0, north 76.0; image 1600 by 971 pixels.

Longitude maps linearly to horizontal position. Latitude maps through log(tan(pi/4 + latitudeRadians/2)). pointToCoordinate and coordinateToPoint implement the forward and inverse conversions. Pointer positions are scaled from the displayed canvas rectangle to its intrinsic pixel dimensions.

Replacement imagery must match the declared bounds and projection, or the conversion must be updated. The Russia crop contains all five targets but does not include the country’s entire far eastern extent. The PDF’s final Russia page uses Lambert conformal conic projection; it is not interchangeable with the game’s Mercator image.

Scoring and public MapTap findings

The official public site examined was https://maptap.gg/, with practice information at https://maptap.gg/practice and scoring explanations at https://maptap.gg/faq.

Its FAQ reported that practice uses distance scores, averages round scores into a 0-1000 total, and omits the daily game’s country/continent score floors. It described full credit within about 22 km and an example of 81 points at 1,000 km. These were public statements reviewed during the session, not findings from its source code.

The delivered game’s distance is calculated with the haversine formula using Earth radius 6371.0088 km. Its scoring approximation is:

if (km >= 16250) return 0;
return Math.round(100 * Math.max(0, 1 - km / 16250) ** 3.4);

This approximates the public examples; it is not a verified copy of MapTap’s exact formula. In particular, its rounding does not explicitly guarantee full credit throughout the published 22 km radius. The session score is round(mean(roundScores) * 10). The header uses the average of answered rounds so far.

Exact scoring replication is secondary to useful repetition. Do not describe these practice scores as directly equivalent to daily scores with different weighting and floors.

Validation completed and remaining

Completed in the prior build: JavaScript syntax checks; desktop browser loading; a full four-round session; correction display and summary; same-set restart; image inspection; ZIP integrity validation. Browser logs contained extension messages, with no observed application error.

Phone-sized browser testing and actual iPhone use were not demonstrated. The CSS is responsive and the input uses pointer events, but the earlier promise to test phone-sized tapping was not fulfilled in the visible record.

For the imagery and zoom change, verify marker alignment after zoom/pan, inverse coordinate conversion at multiple positions, gesture-versus-tap handling, phone layout, and continued session/repetition behavior. Avoid overlap between marker labels when the guess lands near the correct point. Keep the whole map and controls practical to use on smaller screens; the desktop initial map previously extended below the viewport.

Deployment and phone use

The current bundle can run by opening index.html in a desktop browser. Hosting the static files makes phone access straightforward. GitHub Pages was the user’s intended hosting choice.

Place the bundle’s contents in the intended served directory, preserving the relative asset paths. It can occupy its own subdirectory on an existing Pages site; replacing the site’s root was not requested. index.html is the directory entry point. Inspect the actual repository’s Pages configuration before changing deployment. No hosting change is authorized merely by reading this handoff.

Longer-term geography work

Brian originally asked whether previous daily games could identify recurring or likely targets, especially in Brazil, China, Australia, and Russia. A future research session could establish actual historical counts and selection patterns if asked. Do not silently expand the immediate imagery/zoom work into an archive project.

The study approach is mnemonic drill with meaningful correction: locate, tap, see the right position, repeat. Brian values learning through play and enough repetitions for recall to improve. He does not need an elaborate product to achieve that goal.

Separate creative game idea

Brian also discussed a later geography/trivia game about imagined places and literary settings. A possible round presents four maps, asks which map matches a clue, then asks the player to locate the place. Successive decisions could earn points. Categories might include mythology/fantasy and literary settings in Britain, America, France, and elsewhere. Real literary settings could use labeled city maps, for example identifying London for Oliver Twist.

This is a separate future concept, not part of the remedial drill’s current implementation scope. It also serves Brian’s broader goal of using the tools and skills he has to put creative work into the world and demonstrate his ability to turn ideas into working artifacts.

Suggested session boundaries for the future project

Implementation session: imagery and controls

Use this handoff and the actual website source. Implement satellite imagery, pinch/wheel/button zoom, and pan while retaining accurate taps and the existing repetition loop. Work directly in the project checkout.

Content session: city selection and study cues

Use the existing 20-city pool as the starting point. If Brian requests research, verify historical MapTap frequency separately from population rankings or intuition. Improve study content only within the requested scope.

Creative session: literary and imaginary maps

Develop the distinct trivia concept independently of the remedial game’s immediate changes. Preserve its geographic slant and learning purpose.

Collaboration preferences from this conversation

Keep replies brief, concrete, and focused on the current question. Avoid expanding into unrelated implementation choices or long explanations. Brian explicitly rejected numbered conversational replies and repeated proceed gates earlier in this discussion. Deliver actual clickable download links for files; the initial PDF output directive was not visible to him. State precisely what has been implemented, tested, or merely proposed.