Skip to content

Add an offline map screen: study, review, hint and answer modes - #10

Open
atorch wants to merge 3 commits into
mainfrom
issue-4-map-review-screen
Open

atorch wants to merge 3 commits into
mainfrom
issue-4-map-review-screen

Conversation

@atorch

@atorch atorch commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

Addresses #4 (Add a map review screen).

Why not Mapbox?

We want something free that we can style down to just borders and labels, and that doesn't let players cheat. I compared the options:

Option Free? Fit
Mapbox (suggested in #4) Needs an account and token, billed per monthly active user beyond a free tier ❌
Google Maps SDK Free on mobile, but needs an API key and billing account; online only; Google's borders ❌
osmdroid Free, but archived in Nov 2024 ❌
MapLibre Native Free, open source, no token; about 19 MB library, minSdk 21 ✅ fallback
Natural Earth data + small custom Canvas view Public domain, no key, works offline ✅ this PR

The map code is about 1,050 lines of plain Android code (CountryMapView, WorldMap, ReviewMap) plus about 1.2 MB of bundled data (roughly 1 MB once compressed in the APK). It has no dependencies and gives full control over what is shown or hidden. If smoother rendering is ever needed, the same data can feed MapLibre later.

What's included

  • Study the Map (new main-screen button): every puzzle country is named. Tap a country to see its name. Names can be turned off to quiz yourself by tapping.
  • Review Map (new button after solving): our route is highlighted (start green, route blue, destination red) and named.
  • Map hint (action bar, while solving): borders only. Only the start, the destination and countries already passed through are named, and tapping reveals nothing.
  • Show me the way (new choice in the give-up dialog): shows one shortest route consistent with progress so far, then closes the puzzle so it can't be completed for credit.

Code

  • scripts/build_world_map.py: standard-library-only Python that turns Natural Earth 1:10m admin-0 polygons into app/src/main/assets/world_map.bin.
    • Three levels of detail, encoded compactly.
    • Topology-preserving simplification: borders are split into shared segments at junctions, so neighbouring countries stay seamless.
    • Maps every puzzle country in strings.xml to map units and fails if any name is missing. This covers the graph's quirks: French Guiana, Kaliningrad, Kingdom of the Netherlands via Sint Maarten, and the UK via Akrotiri/Dhekelia.
  • WorldMap.java: parses the map file, picks a level of detail, does hit testing and name lookup.
  • CountryMapView.java:
    • pan, pinch zoom, fling, double-tap zoom;
    • level-of-detail switching and viewport culling;
    • labels with collision avoidance, and dots for microstates;
    • tap to identify.
  • ReviewMap.java: the activity that implements the four modes above.

Testing

  • The branch is merged with current main (API 36, edge-to-edge). A follow-up commit calls SystemBars.setUp() on the map screen, so the route legend sits below the action bar instead of behind it.
  • ./gradlew build passes in CI and locally: compile, lint and the unit tests.
  • All four modes were run on an API 36 emulator with no crashes: Study, Map hint, Show me the way, and Review Map after solving a puzzle. Tap-to-name, rotation and back navigation work.
  • world_map.bin was parsed independently of the app: all 161 puzzle names resolve.
  • Not yet run on a real device. Pinch zoom, double-tap zoom and smoothness still need a manual test (planned on a Pixel 9).

Open questions

  • Disputed areas (Kosovo, Somaliland, Northern Cyprus, Western Sahara) use Natural Earth's default borders and are drawn grey and unlabelled.
  • "Kingdom of the Netherlands" routes go through Sint Maarten (a quirk of the puzzle graph), so reviewing one zooms out across the Atlantic.
  • Should the hint highlight the destination? Should hints cost something?
  • Android 6–8.1 (unverified): the map draws paths under a large canvas scale, which Android only renders cleanly from API 28. With minSdk 23, older devices may get a blurry map. Not tested: no emulator that old was available.
  • Highlighted route names can overlap each other (for example "Democratic Republic of the Congo" and "Rwanda").
  • After rotating, the map keeps its centre and zoom instead of refitting the route, so part of the route can be cropped in landscape.
  • The map file loads on the main thread when the screen opens. That's fast on modern phones and could move to a background thread if needed.

🤖 Generated with Claude Code

Draws country borders with a small custom Canvas view (CountryMapView) instead of a
map SDK: no API key, no account, no network, no per-user pricing, and full control
over what is (not) shown, which matters for a game that shouldn't let you cheat.

* scripts/build_world_map.py: dependency-free Python pipeline that turns Natural Earth
  1:10m admin-0 polygons (public domain) into app/src/main/assets/world_map.bin
  (~1.2 MB, 3 levels of detail). Simplification is topology-preserving (arcs split at
  junctions, TopoJSON-style) so neighbouring borders never drift apart. Every puzzle
  country name in strings.xml is mapped to map units, including the graph's quirks
  (French Guiana, Kaliningrad, Kingdom of the Netherlands via Sint Maarten, UK via
  Akrotiri/Dhekelia), and the build fails if any name is missing.
* WorldMap: parses the asset, LOD selection, hit testing, name lookup.
* CountryMapView: pan / pinch zoom / fling / double-tap zoom, LOD switching and
  viewport culling, labels with collision avoidance, dots for microstates, tap to
  identify.
* ReviewMap activity:
  - Study the Map (main screen): every puzzle country named, tap for names, and
    "Show country names" can be switched off to quiz yourself.
  - Review Map (after solving): our route highlighted and named.
  - Map hint (action bar, while solving): borders only; just the start, destination
    and countries already visited are named, and tapping reveals nothing.
  - Show me the way (give-up dialog): one shortest route consistent with progress so
    far; the puzzle is closed so it can't then be completed for credit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HwXCdefzsbBmyTLiRAuKxA

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues block TalkBack country identification, remove valid route highlighting for Netherlands aliases, and cause completed puzzles to open the wrong review map after back navigation.

3 open issues
What changed in this PR

Adds an offline map screen for studying countries, reviewing completed routes, viewing hints, and revealing an answer after giving up. It uses bundled Natural Earth data and a custom Android Canvas view without a map SDK or network access.

Changes:

  • Adds map rendering, country identification, pan/zoom gestures, and route highlighting.
  • Connects study, review, hint, and answer modes to the existing puzzle flow.
  • Adds a map-data generator and documents asset regeneration.
File Description
scripts/​build_world_map.py Generates compact map geometry and puzzle-country mappings.
README.md Documents the offline map and regeneration steps.
app/​src/​main/​res/​values/​strings.xml Adds map titles, controls, legends, and messages.
app/​src/​main/​res/​menu/​solve_puzzle.xml Adds the map hint action.
app/​src/​main/​res/​menu/​review_map.xml Adds label visibility and world-view controls.
app/​src/​main/​res/​layout/​activity_solve_puzzle.xml Adds the route review button.
app/​src/​main/​res/​layout/​activity_review_map.xml Defines the map, legend, and status layout.
app/​src/​main/​res/​layout/​activity_main.xml Adds the study map button.
app/​src/​main/​java/​atorch/​shortestpaths/​WorldMap.java Loads map data and provides geometry and country lookup.
app/​src/​main/​java/​atorch/​shortestpaths/​SolvePuzzle.java Tracks the entered route and launches map modes.
app/​src/​main/​java/​atorch/​shortestpaths/​ReviewMap.java Coordinates map modes, highlights, labels, and saved viewport.
app/​src/​main/​java/​atorch/​shortestpaths/​MainActivity.java Opens the study map.
app/​src/​main/​java/​atorch/​shortestpaths/​CountryMapView.java Renders countries and handles gestures and selection.
app/​src/​main/​AndroidManifest.xml Registers the map activity.

Review effort: Balanced

Comment on lines +152 to +155
public boolean onSingleTapConfirmed(MotionEvent e) {
if (tapListener != null && map != null) {
WorldMap.Feature hit = featureAt(e.getX(), e.getY());
tapListener.onCountryTapped(hit == null ? null : map.countryNameFor(hit), hit != null);
Comment on lines +217 to +220
Integer routeColor = routeHighlights.get(selected);
if (routeColor != null) {
mapView.highlightCountry(selected, routeColor, true);
}

atorch commented Nov 3, 2026

Copy link
Copy Markdown
Owner Author

Follow-up idea from #9 (tricky borders), for after this lands:

At world zoom, Ceuta and Melilla are too small to see, so a reviewed route going Spain → Morocco looks like a mistake on this map. That border is on a shortest path in about 14% of puzzles. Nakhchivan (Turkey–Azerbaijan), the Wakhan Corridor (Afghanistan–China) and Kazungula (Botswana–Zambia) have the same problem.

Suggestion: in REVIEW and ANSWER modes, when consecutive route countries cross one of the borders in res/values/tricky_borders.xml (added by the #9 PR, issue-9-tricky-border-hints), draw a marker at the crossing point and show that border's note when it's tapped. This needs one more field per entry: an approximate latitude/longitude for the crossing.


Generated by Claude Code

atorch and others added 2 commits November 13, 2026 23:31
Conflict in SolvePuzzle.java: main moved the answer-checking code out of
onCreate into countryEntered()/moveTo() (and made the puzzle state
non-static, with save/restore), while this branch had added route tracking
to the old inline listener. Kept main's structure, which already records
user_route, and kept this branch's map hooks on top of it: the "Show me
the way" give-up button, reviewMap(), showAnswer() and the map hint menu
item.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Main now targets API 36, where every screen is drawn edge-to-edge. The
other screens call SystemBars.setUp() to stay clear of the bars, but the
map screen predates that, so after the merge its route legend was laid
out underneath the action bar (invisible) and the map ran behind the
navigation bar.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@atorch
atorch requested a balanced review from Copilot November 14, 2026 16:24
@atorch
atorch marked this pull request as ready for review November 14, 2026 16:24

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues can erase route highlights, block accessible country selection, distort initial route framing, and crash map generation when given a bare output filename.

4 open issues
1 resolved since last review

Review effort: Balanced

Comment on lines +221 to +224
if (result == null) {
result = new RectF(primary.bounds);
} else {
result.union(primary.bounds);
for code in GAME_UNITS[name]:
write_varint(out, index[code])

os.makedirs(os.path.dirname(args.out), exist_ok=True)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants