# Lodestar design notes

## The brief

Combine two existing GameLab ideas with a third the site had never touched, for phones in portrait or landscape and for desktop, and lean on phone sensors that games rarely use.

- **From Blackbird Recon (SR-71 and Black Budget Bird):** long night navigation over a planet. The real SR-71 steered with an astro-inertial system that tracked stars, even in daylight. Songbirds steer by stars too.
- **From Ephemeris Lens (MMS4 and its sequel):** the Earth's magnetic field as real physics, and the storms that shake it when the solar wind reconnects with the magnetosphere.
- **New: bird migration and magnetoreception.** A first-year thrush has never seen its wintering grounds. It carries an inborn heading and the senses to hold it.

Breathglass already used the microphone (breath), orientation (gravity), motion (swing), camera (light) and vibration. Waymark used GPS and the camera. Lodestar uses the two that were left: the **magnetometer** and the **speaker and microphone together as sonar**.

## Senses

| Sense | How it's read | What it does | Without it |
| --- | --- | --- | --- |
| Magnetometer | `deviceorientationabsolute` (Android), `webkitCompassHeading` (iOS) | The world lines up with real north. You turn your body to steer. | Drag, or A/D and arrow keys |
| Magnetic noise | Drift between the magnetic and gyro-only orientation, or a raw `Magnetometer` where exposed | Shakes the bird's magnetic sense, like a geomagnetic storm | Off |
| Orientation | Same events | Pitch looks up and down; roll keeps the horizon level | Drag up and down, or W/S |
| Ultrasonic sonar | 19 kHz tone out, `AnalyserNode` in, Doppler sidebands | Each hand wave is a wingbeat | Tap, the Flap button, or Space |

### Heading from the phone

The rotation matrix comes straight from the W3C Euler angles (Z-X'-Y''). The direction you look "through" the phone is its back (device -z). When the phone lies flat that points at the floor, so the heading blends toward the top edge of the screen instead (screen orientation taken into account). iOS reports a relative alpha plus a compass heading; the offset between them is learned while the phone isn't upright and then applied to the smooth gyro alpha.

### Room noise

On Android Chrome, `deviceorientation` is gyro and accelerometer only, while `deviceorientationabsolute` adds the magnetometer. The gap between their alphas should drift slowly. A magnet near the phone swings the absolute one and not the relative one. The jump in the gap, above a two degree dead band, is the noise level.

### Sonar

A hand moving at 1 m/s shifts a 19 kHz echo by about 2v/c × f ≈ 110 Hz. With an 8192-point FFT at 48 kHz, bins are 5.9 Hz wide, so that's about 19 bins. The detector:

1. finds the carrier peak near the expected bin;
2. measures the spectrum on each side relative to the peak (so speaker volume drops out), against a per-bin baseline learned while nothing moves;
3. sums the excess above and below the carrier: total is motion, the balance is direction;
4. learns the mean and spread of "still" motion and fires a wingbeat on a crossing well above it, with hysteresis and a 170 ms refractory period.

If the mic can't hear the tone at 19, 18.5, 18 or 17 kHz (some phones filter high frequencies), sonar says so and the game uses taps. `echoCancellation`, `noiseSuppression` and `autoGainControl` are all switched off, or the browser would helpfully remove the very signal we want.

## Navigation model

The player faces a true heading. The bird's **inner compass** (the tape at the top) shows that heading plus an error. The error wanders (an Ornstein-Uhlenbeck process) with a spread set by whichever cues are available, combined as independent estimates (1/σ² adds):

- stars: 4°, scaled by how much sky is visible;
- magnetic: 5° after a sunset calibration, 10° without, plus up to 25° in a geomagnetic storm and up to 28° from room noise;
- twilight glow: 5°, only near dusk and dawn;
- flock: up to 25% tighter while you stay with the others ("many wrongs" averaging).

Inside cloud the error never drops below 18°. Under low cloud, a city's glow drags the error toward the city, so a player who trusts the tape gets pulled in. The rendered sky is always true, so a player who knows where Polaris should be can catch the lie.

Scoring is the distance-weighted average angle between your **ground track** and the bearing to the next stopover. Wind matters: you have to crab into a crosswind.

## The world

- **Field:** first-degree IGRF-2025 (g10 = -29350.0, g11 = -1410.3, h11 = 4545.5 nT). It puts the geomagnetic pole at 80.8°N, 72.8°W, and gives inclinations within a few degrees of the full model over North America.
- **Sky:** 70 named stars, J2000 positions, no precession. The faint field is generated in galactic coordinates and concentrated on the galactic plane. Sun and Moon use the standard low-precision almanac formulas.
- **Route:** eastern Swainson's thrushes, autumn: Thompson, Interlake, Red River, Minnesota River, Des Moines River, Ozarks, Ouachitas, Chenier Plain, Yucatán, Petén, La Mosquitia, Talamanca.
- **Weather:** a Markov chain of situations (cold front, high pressure, south winds, rain, trade winds), deterministic per run and day. Wind strengthens with height and veers.
- **Lights:** cities by metro population, generated farm and small-town lights on land, gas platforms where they cluster off Louisiana and Texas, blinking towers near cities.
- **Time:** one real second is four minutes of night. A night is two to three minutes of play.

## What's real and what's game

Real: the star positions, the Sun and Moon, the dipole field, the route, the sunset calibration behaviour, the inclination compass, light-pollution attraction, tower and window hazards, platform rests, the Gulf crossing.

Game: fat numbers are in the right range but tuned for pace. The veil is one hypothesis drawn literally. Coastlines and rivers are sketched from a few dozen points. Weather is invented, though it behaves like autumn on the Plains.

## Files

`flight.js` (one night), `world.js` (route, places, weather), `field.js`, `sky.js`, `geo.js`, `sonar.js` and `orient.js` are pure modules with Node tests. `sensors.js`, `audio.js`, `render.js`, `mapview.js`, `labs.js` and `main.js` run in the browser. No build step and no libraries.