Add design research: Ingress mechanics + BTC Map API + live Madeira dataset (167 places)
This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
# Regress — Design Notes (v0)
|
||||
|
||||
A location-based capture game in the spirit of *Ingress*, running as a nostr-native
|
||||
app on Archipelago. Instead of Niantic's fictional "portals," Regress uses real
|
||||
Bitcoin-accepting merchant locations pulled from [BTC Map](https://btcmap.org) as
|
||||
the capturable objects. First scope: **Madeira, Portugal**.
|
||||
|
||||
---
|
||||
|
||||
## 1. What Ingress actually does (researched)
|
||||
|
||||
- **Portals** are real-world landmarks agents physically travel to and interact
|
||||
with via the app. In Regress, a **BTC Map place** (merchant/ATM/etc.) is the
|
||||
portal-equivalent.
|
||||
- **XM (Exotic Matter)** is the fictional currency/fuel players collect by
|
||||
walking around; spent on all actions. Needs a Regress equivalent (see open
|
||||
questions below — sats? a synthetic in-app resource? nothing at all?).
|
||||
- **Capturing a neutral portal**: deploying a **resonator** claims it instantly
|
||||
for your faction. Up to 8 resonators per portal ("fully resonated").
|
||||
- **Mods**: optional items that buff a portal's defense/utility.
|
||||
- **Keys & Links**: hacking a portal yields a *key* to it. That key, used at a
|
||||
*different* fully-resonated friendly portal, creates a **link** between the
|
||||
two — you cannot link a portal to itself.
|
||||
- **Control fields**: three mutually-linked portals form a triangle that
|
||||
"fills in" — this is the actual territory-capture unit, not the portals
|
||||
themselves.
|
||||
- **Factions**: Enlightened (green) vs. Resistance (blue); an AI-controlled
|
||||
third faction, Machina (red), exists in later content.
|
||||
- **Attack/defense**: XMP bursters and Ultra Strikes destroy enemy resonators;
|
||||
a portal with zero resonators reverts to neutral and can be recaptured.
|
||||
- **Anomalies**: live, time-boxed global events tied to real Ingress
|
||||
storyline/lore — probably out of scope for v0.
|
||||
|
||||
Sources: [ingress.com](https://ingress.com/en), [Fev Games Ingress guide](https://fevgames.net/ingress/ingress-guide/ingress-overview/), [Fev Games glossary](https://fevgames.net/ingress/ingress-guide/glossary/)
|
||||
|
||||
## 2. BTC Map as the location data source (researched, live-tested)
|
||||
|
||||
BTC Map (`teambtcmap/btcmap-api`) is a real, actively maintained, crowdsourced
|
||||
map of Bitcoin-accepting places, backed by OpenStreetMap tag data. It has a
|
||||
public, unauthenticated **REST API v4** at `https://api.btcmap.org/`.
|
||||
|
||||
Key endpoints we'd actually use:
|
||||
|
||||
- `GET /v4/places?fields=...` — chronological sync of every place, with
|
||||
`updated_since`/`limit` for incremental sync (bring-your-own cache pattern,
|
||||
good fit for a self-hosted Archipelago app that wants an offline-resilient
|
||||
local copy).
|
||||
- `GET /v4/places/search/?lat=&lon=&radius_km=` — places within a radius. This
|
||||
is what a "load the map around me" or "load this island" view would use.
|
||||
- `GET /v4/places/{id}` — single place detail (name, address, phone, website,
|
||||
socials, `osm_id`/`osm_url`, `verified_at`, icon).
|
||||
- `GET /v4/places/{id}/comments`, `/v4/places/{id}/areas` — community
|
||||
comments and country/community area membership.
|
||||
- `GET /v4/areas?lat=&lon=` — which named areas (country/community) contain a
|
||||
point; `GET /v4/areas/{id|alias}` — area metadata + icon image.
|
||||
|
||||
No API key needed for reads. Write/RPC endpoints exist for community editing
|
||||
but aren't needed for a read-only game client.
|
||||
|
||||
**Live-tested against Madeira right now:** a 45 km radius search centered on
|
||||
Funchal (32.7607, -16.9595) returns **167 real, currently-tracked places** —
|
||||
comfortably covers the whole island (~57 km × 22 km). Category breakdown from
|
||||
the actual data:
|
||||
|
||||
| Count | Category (icon) |
|
||||
|---|---|
|
||||
| 35 | restaurant |
|
||||
| 14 | café |
|
||||
| 13 | storefront (general retail) |
|
||||
| 10 | pharmacy |
|
||||
| 7 | hotel |
|
||||
| 6 | bakery |
|
||||
| 5 each | fitness, hair/barber, "business", medical |
|
||||
| ... | long tail: bars, dentists, spas, tour operators, ice cream, a boat charter, a surf shop, a music venue, a bike rental, etc. |
|
||||
|
||||
This is real, not a mock — it's what the live API returns today. Full raw
|
||||
dump saved at `data/madeira-btcmap-2026-08-04.json` for reference (167
|
||||
records: id, lat, lon, name, icon, osm_id, verified_at).
|
||||
|
||||
Source: [btcmap-api docs](https://github.com/teambtcmap/btcmap-api/tree/master/docs/rest/v4)
|
||||
|
||||
## 3. Proposed Regress concept (draft — needs your input)
|
||||
|
||||
Every BTC Map place in scope starts **unclaimed** (Ingress's "neutral grey").
|
||||
Players claim it, link claimed places together, and linked triangles form a
|
||||
**control field** over that territory — same core loop as Ingress, but the
|
||||
portals are real Bitcoin-accepting businesses instead of public art/landmarks.
|
||||
|
||||
### Open questions before I design further
|
||||
|
||||
1. **What does "claiming" cost/require?** Ingress ties everything to XM
|
||||
gathered by physically walking near portals. Options for Regress:
|
||||
- **Physical presence required** (GPS check-in via phone, like Ingress) —
|
||||
most faithful to the genre, but means players must actually be in
|
||||
Madeira.
|
||||
- **Sats/Lightning-gated** — claiming costs a small zap/payment (fits the
|
||||
Bitcoin theme hard, ties into podsteadr's existing Cashu/Lightning
|
||||
plumbing you already have running).
|
||||
- **Nostr-native "proof of visit"** — e.g. NFC/QR at the merchant, or a
|
||||
merchant-signed nostr event, so it's cryptographically real rather than
|
||||
GPS-spoofable.
|
||||
- Some combination.
|
||||
2. **Factions or free-for-all?** Ingress's whole metagame is two-faction
|
||||
conflict. Do you want teams, or is this more like an individual/community
|
||||
"claim businesses you actually support" thing?
|
||||
3. **Does "unclaimed" ever mean anything to the real business owner?** i.e.
|
||||
is there a path for the actual merchant to claim their own listing (like
|
||||
podsteadr's owner-exemption pattern), or is Regress entirely player-vs-
|
||||
player over data about businesses that don't participate?
|
||||
4. **Archipelago integration shape** — same fork as podsteadr had: does
|
||||
Regress run standalone on its own domain (external, identity-aware via the
|
||||
`nostr-provider.js` shim like we just wired for podsteadr), or does it need
|
||||
full orchestrator-managed packaging? I'd default to the podsteadr pattern
|
||||
(external + identity-aware) unless you want it embedded differently.
|
||||
5. **Nostr event shape for claims/links?** Worth defining a custom kind (or
|
||||
piggybacking parameterized replaceable events) early since that's the
|
||||
actual interop surface other clients could read.
|
||||
|
||||
## 4. Next steps once the above is answered
|
||||
|
||||
- Pull the full Madeira dataset via `/v4/places` (chronological sync
|
||||
endpoint) rather than the radius search, so we get a clean incremental-sync
|
||||
foundation instead of a one-off snapshot.
|
||||
- Define the Regress data model: place (from BTC Map, cached locally) →
|
||||
claim → link → field, plus whatever resource economy answers question 1.
|
||||
- Stand up the repo skeleton (backend + frontend, matching the podsteadr
|
||||
stack unless you want something different) and wire BTC Map sync as the
|
||||
first real feature.
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user