Chill Flight

Store metadata

Game title

Chill Flight

Description

A casual flight simulator set in a vast, ever-changing world.

Drift along to lofi beats as you explore diverse landscapes featuring dynamic weather, day-night cycles, and biomes that shift with each journey.

Music by Purrple Cat.

Have a chill flight.

Keywords

flight,simulator,chill,lofi,relaxing,procedural,exploration,ambient,casual,cozy,zen,plane,flying

Music

In-game radio features tracks by Purrple Cat (Used with permission/attribution).

Music plays at half volume, about where background music usually sits in a game (the tracks are mastered at streaming loudness), and drops lower while paused (MUSIC_VOLUME in audio.js). iOS ignores web audio volume, so on iPhone and iPad it plays at full volume.

To start without sound (say, on a train), tap the speaker button under Start on the title screen. It turns off both music and sound effects, and the choice is saved: later visits skip the title screen and start silently. Either can be turned back on in settings.

Sound effects

Procedural sound effects generated in real time with the Web Audio API provide ambient immersion without adding download weight.

• Engine: Synthesizes a warm piston propeller tone (sub-octave rumble, dual oscillators, an upper-mid rasp that carries on phone speakers, and propeller chop) pitched and getting louder with airspeed and throttle. The jet has a turbine whine that climbs with the throttle instead. While music is on, the engine plays 12 dB quieter (ENGINE_MUSIC_DUCK in sfx.js) so its drone sits under the music instead of competing with it. Twin-engine aircraft feature dual asynchronous props with acoustic beat frequencies.
• Ambiance: When parked on land, tranquil environmental soundscapes fade in: meadow crickets at dusk and night, or a soft countryside breeze during the day. On water, small waves lap at the floats.
• Events and places: A thump on touchdown and a splash on water landings, tyre rumble while taxiing, spray hiss on the water, the landing gear's clunk, wind rushing past when the plane falls, rain on the canopy, thunder rolling in a moment after each lightning flash (nearer strikes sooner, louder and with a crack), the roar and spray of every waterfall, placed where it lands so it pans across as you fly past and grows as you approach, typed dialog blips pitched per person, and a soft chime when a job step is done or a waypoint is reached. Each can be switched off on its own and auditioned in the sound lab (debug/debug-sound.html).
• Controls: Sound effects can be toggled in the pause menu settings or temporarily via the ?sfx=0 / ?sfx=1 URL parameter. Sound effects automatically mute when paused and stop entirely while the game is in the background. With no saved choice they follow the music setting.

Biomes

The world is organized around a central coordinate system (0,0) where latitude (Z) and longitude (X) determine the primary environmental shifts.

The land is a continent with sea on every side (continentPast in chill-flight-logic.js). Its outline is one of five hand-made shapes (CONTINENTS), which the world seed picks between, so each day's world may have a different one (about a fifth each); the continent URL parameter forces one. Each shape is a few overlapping, tilted ellipses for the main continent and one for the eastern land, blended where they meet and warped by smooth noise at the 1 to 3 degree scale, so the coasts lean, taper and hook rather than following the lines of latitude and longitude:

• Leaning: The body tilts from north-west to south-east, with a long peninsula running south-west and a cape in the north.
• Taper: Wide in the north, narrowing south to a point, like Africa or South America.
• Crescent: A western arm curves south and hooks round toward the east, sheltering a bay.
• Lobes: Two big lobes on a diagonal, a high north-west and a low south-east, joined at the waist.
• Boot: A long leg runs south-east from the west, ending in a toe and a heel at about 12 to 14 South, with a deep gulf inside it.

Every outline also keeps the island sea (ISLAND_SEA), and none touches the heartland: within 2.5 degrees of 1 West, 0 (X = -5000, Z = 0), which takes in spawn, the falls, the volcano and Meadow and Lagoon Fields, no coast shapes the land, and coasts fade in out to 4 degrees. The eastern land rises out of the island sea along a wandering line around 10 East (X = 50000), with a cape at 1.5 North and a bay at 4.5 South. The main continent's own east coast, around 0 longitude, wanders up to about 1.2 degrees east or west with latitude outside the heartland (eastCoastShift), so it doesn't run straight down a meridian.

Across the outline, a band 10000 units wide becomes rugged coast (coastDetail): coves and spits, broad bights and headlands, fjords cutting inland, island chains breaking off, and barrier islands with lagoons behind them. How broken the coast is varies along it, from smooth shores to stretches thick with fjords and islands. Past it lies open sea. The coast only cuts into the land, never raises it, so where the outline crosses the island sea, the sea stays open. The western alien land runs right out to the west coast. On the south coast, drowned land becomes a warm, shallow sandy shelf instead of deep sea, out to about 5000 units past the outline: turquoise water 2 to 4.5 units deep, reefs just under the surface and low sand cays (southShelfFloor).

Biome	Direction	Latitude/Longitude	Primary Characteristics
Temperate	Central	Around (0, 0) (Center)	Lush green plains and thick forests. High density of civilization (houses, barns, windmills).
Snowy	North	Negative Z (North Latitude)	Frozen terrain, snow-capped mountains, icy water, pine forests, and light snow whenever cloud is overhead (never from a clear sky).
Desert	South	Positive Z (South Latitude)	Sandy dunes, reddish rock canyons, turquoise water, cactuses, and dead trees.
Archipelago	East	Positive X (East Longitude)	Coastlines flatten starting at 0.0 Longitude, leading to large island chains beyond 0.6 East (X > 3000).
Lake District	West	Negative X (West Longitude)	Long lakes filling the valleys between hills and ranges, west of 0.7 West (X < -3500), within about 2 degrees of the equator.
Alien Zone	Far East/West	From about 10.0 East/West	Warped, jagged alien topography with glowing neon seas and surreal colors.

1. Temperate central (the heartland)

• Location: The area surrounding the equator (Z=0, 0.0 Latitude) and prime meridian (X=0, 0.0 Longitude).
• Landscape: A mix of rolling plains (#7CB342) and dense deciduous forests (#388E3C).
• Key Features:
  • Structures: Most common area for houses, barns, windmills, and monasteries. Houses have steep gabled roofs with overhanging eaves and vary in proportion (long farmhouses, narrow townhouses), and gather in villages and hamlets on flat ground, in short rows that share their village's orientation, with only a few lone farmhouses between them (terrain-gen.js). Now and then a highway runs through a denser village: a stretch of 350 to 800 units lined on both sides with houses facing the road, a second row behind them toward the middle, and gaps for lanes, thinning out at its ends. Each road (the cross-country one too, short of its run in to Meadow Field) is split into 6,000-unit stretches and about half hold one, built only where the roadside is dry and flat (roadVillageHouses in terrain-gen.js). Where the cross-country highway crosses a north-south one, a market town spreads around the crossing: rows of houses back to back on a street grid lined up with the north-south highway, with cross streets every 150 units or so, bigger two-story houses in the middle, and thinning out into scattered houses at its edge. The first crossing's town (0.8 West, 0.3 South / X=-3800, Z=1500 on most seeds) is the biggest, about 650 units across from the crossing; the others are smaller. Crossings in the alien lands get no town (townHouses in terrain-gen.js). At night, houses keep their own hours in eight groups: their lights come on one group at a time as it gets dark, go out one group at a time between about 21:30 and 00:30 (one group stays up all night), and come back on for early risers before dawn (windowGlow in game-loop.js). Barns, windmills, monasteries and castle ruins also need fairly flat ground. Houses take regional styles: grey stone with slate roofs in the snowy north, and ochre adobe with flat roofs and no chimneys in the arid south.
  • Plains and plateaus: Between the mountains, a slow field tens of kilometers across gives the land broad character: open plains where the hills settle into gentle lowland, and plateaus, tablelands about 170 m higher behind steep escarpments. The rest is rolling hills, so long flights change character (landformAt in chill-flight-logic.js).
  • Farmland: Around the villages, gentle ground below the upland woods is a patchwork of strip fields in wheat, barley, young green crops, dark green rows and plowed earth, with some left as pasture. The land is split into parcels about 1,500 units across, each turned to its village's orientation, so neighboring parcels meet at an angle. Fields are cleared of the woods, and hedgerows of bushes and the odd tree run along most field edges ( and in ).

Lake district (the west)

• Location: West of 0.7 West (X < -3500), fading in over 0.8 degrees, between about 1.8 North and 1.8 South (Z between -9000 and 9000, fading out by 2.6 degrees).
• Landscape: The valley floors are flooded, so lakes take the shape of the valleys: long lakes fingering between the hills and ranges, with the land around them easing down to gentle shores. How high the water reaches varies slowly across the region, so there are lake-filled districts and drier ones, different for each world seed. Rivers and the west coast highway run through (VALLEY LAKES in getElevation, chill-flight-logic.js).
• Islands: Some larger lakes have wooded islands, which rise at most to the height of the land around the lake.

2. The frozen north

• Location: Snow starts around Latitude 1.5 North (Z = -7500) and deepens gradually to full cover by 2.5 North (Z = -12500). Away from spawn's longitudes (more than 2.5 degrees either side of 1 West), the snow line wanders up to about a degree north or south in long curves (snowWobble), so it doesn't follow a line of latitude; near spawn it holds still, keeping the falls clear of the snow. The snowline on mountains comes down gradually from 1,150 units near the equator to 750 by 1.0 North, so the first northern range is green and rocky with snow-capped peaks, and then with the snow cover down to the valleys. Ground, water ice, trees and snowfall all use one snow cover function (snowFactorAt in chill-flight-logic.js). The sea past the north coast is frozen from around 4.0 North (Z < -20000), past a lane of open water along the shore whose width wanders from nothing (ice frozen to the shore, in among the islands) to about 9000 units (open bays), and a band of floes that grow larger and closer together over 12500 units until they join into solid pack (seaIceAt).
• Landscape: Permanent snow cover (#FFFFFF) even at lower altitudes. White-tinted forests (#8BA192). Past the north coast, the open water along it and a broken edge of floes, the ocean freezes over into a solid, jagged pack ice shelf (#A2B4BC) that rises out of the water. Lakes on the land stay open. In bright midday sun, snow and ice are dimmed slightly and shifted cool (uSnowExposure) so their shading stays visible instead of washing out to flat white.
• Weather: Light snow whenever there's cloud overhead, with occasional global breaks. Cloud builds sooner over the snow, so snowy weather is common, but it never snows from a clear sky.
• Key Features:
  • Mountain ranges: The first range north always rises around 1.0 North (Z = -5000), south of the snow, so it's green with snow-capped peaks; ranges further north vary by world seed and are snowbound. Ranges start at 0.5 West (X = -2500) and reach full height by 1.5 West (X = -7500), with sharp, ridged peaks up to 1600 units.
  • The far north: From about 3 North the low ground isn't all snow. The wind scours small patches of grey-green tundra, and tors (steep, lumpy knobs of dark rock 45 to 115 units high) break through in scattered districts, kept clear of the highway (torAt in chill-flight-logic.js); steep banks show bare rock too. North of about 4.4 North the land's lakes and rivers freeze over into a flat sheet of blue-white ice, with smooth, ragged edges where it meets open water; highway bridges still cross them.
  • Objects: Snowmen, chimney smoke from houses, and frost-covered pine trees.
  • Water: Icy, pale blue water (#88CCFF) that transitions into solid, textured cyan ice (#6CA6A8) shelves and floating icebergs in the deep north.

3. The arid south (Arizona style)

• Location: Latitude 1.5+ South (Z > 7500). Like the snow line, the desert's edge wanders up to about a degree north or south away from spawn's longitudes (desertShift).
• Landscape: Reddish-orange sand (#F4A460) and deep red canyon rock (#C24B2B).
• Key Features:
  • Mountain ranges: The first range south always rises around 1.0 South (Z = 5000), still green. Ranges further south vary by world seed; in the desert (beyond about 2.3 South, Z = 11500) they become broad mesas and rugged red-rock peaks.
  • Desert lowland: From about 2.2 South the low ground between the ranges is shaped by the desert (desertLowlandAt in chill-flight-logic.js). Dune fields cover most of it: long ridges up to about 44 units high and 400 apart, lying across a wind from the west-south-west, with gentle windward slopes and steep lee faces, and the hills beneath them flatten into a sand sea (duneAt). Lone mesas and buttes stand out on the flats, one in most 2.5 km cells: flat tops 190 to 330 units up with sheer walls over a talus skirt, some with a smaller butte on top, kept clear of the airfields, the canyon and the highway (mesaAt). Inland lakes dry to white salt pans just above the water; a lake reaching toward the coast keeps water at its seaward end.
  • Vegetation: Cactuses and skeletal "dead" trees.
  • The canyon: A Grand Canyon cuts the desert south of spawn's longitudes, at about 1 East (see Landmarks).
  • Water: Deep turquoise tropical-style water (#00CED1). The south coast is warm and shallow: a sandy turquoise shelf with reefs and sand cays (see Biomes above).

4. Coastal islands (the east)

• Location: Longitude 0.0+ East (X > 0), transitioning to full ocean and islands beyond 0.6 East (X > 3000). Outside the heartland the continent's east coast wanders up to about 1.2 degrees either side of 0 longitude.
• Landscape: The land flattens significantly into sandy beaches before transitioning into the deep ocean.
• Key Features:
  • Islands: Island chains generated by domain-warped noise, featuring jagged coastlines and sharp, rugged mountain peaks rising from the sea. From about 2.5 to 9.5 East a second field of clusters fills the gaps between the first, so the crossing to the alien land has islands along the way on every seed (midSea in getElevation).
  • Vegetation: Palm trees (#689F38) are found exclusively along these coasts.
  • Maritime: Sailboats and pirate ships, only within about 4 km (8000 units) of land, so the open ocean past the coasts and islands is empty (BOAT_MAX_OFFSHORE in terrain-gen.js).

5. The alien territory (the extremes)

• Location: The far extremes of the map, from about 10.0 East (X > 50000) or 10.0 West (X < -50000). Neither edge is straight: the eastern land rises out of the island sea along a wandering line with a cape and a bay (eastLandLon), and the western alien land begins along a line that wanders up to about 1.4 degrees either way (westAlienEdge); the alien colours follow the same edges (alienAt).
• Landscape: Highly distorted, jagged crystalline peaks and surreal terrain generation.
• Key Features:
  • Terrain Warping: The far East is a basalt honeycomb: hexagonal columns about 1000 units across, flat-topped and sheer-sided, each its own height (taller toward the middle of the land), with ravines between them that flood into channels on low ground. Whole columns are land or sea, so its swirling, domain-warped islands have stepped, hexagonal coasts (basaltAt in chill-flight-logic.js). The far West features massive geometric stepped plateaus, crystal spires and deep chasms.
  • Props: Ordinary trees, buildings and birds give way to alien ones (giant mushrooms in the East, clusters of glowing crystals in pink, orange and violet in the West) a little way in, where the alien terrain and colours have taken hold (alienAt above 0.3). The West is wild country from the same line: its highways have no streetlights or lane markings, and no sailboats or pirate ships sail its coasts.
  • Colors: Normal biomes are completely overtaken by vibrant, neon hues (cyan in the East, magenta in the West) that wash over the landscape. In the West the colours take over twice as fast as the terrain changes and cover the snow and grass completely, with pale pink crystal spires, so the spires never stand on green fields or read as snowy peaks.
  • Seas: The water transforms into a bright glowing liquid that bleeds smoothly onto the alien shorelines.

[!NOTE] Water surface: Water mirrors the sky with a Fresnel reflection (looking down you see the water, toward the horizon you see the sky's colors), and the sun lays a glitter path across it from the horizon toward the viewer, golden at low sun, with sparkles up close. At night the moon lays a silver path the same way, visible even for a thin crescent. Open water (about 10 units deep) is opaque deep blue; shallows around islands and shores turn turquoise. The water's depth is sampled per pixel from each chunk's terrain height grid (a small texture per water chunk), so shallows and foam follow the shore in smooth curves; color and transparency use that depth softened over about 200 units for a gradual blend, and the swell calms in shallow water. A band of foam lines every shore at the same width (its distance to shore is estimated from how quickly the depth changes), with rings that roll toward the beach. The swell is three waves in different directions, so the surface doesn't read as regular stripes.

Dynamic Coastlines: Across all biomes, wherever the procedural water intersects with the land, the water's color dynamically blends into a white foam (#EEEEEE) to simulate natural shorelines and river banks.

Atmosphere & Sky Colors

A whole day lasts 6 minutes, and every player sees the same time of day (it follows the wall clock). The clock doesn't run evenly: it slows down where the sky is most colorful and speeds through the rest, by sun height (computeTimeOfDay in chill-flight-logic.js). Each sunrise and sunset gets 45 seconds of peak color (the sun within about 6 degrees of the horizon), 40 seconds of golden light (6 to 24 degrees up) and 40 seconds of twilight glow (6 to 30 degrees below); full daylight takes 65 seconds and full night 45. timeSpeed speeds the whole cycle up or slows it down (see URL parameters). In golden light the sky stays blue, with a wide gold glow around the sun, while the sunlight and the light from the sky turn warm from about 33 degrees up; the sunset palette's colors take over the sky only as the sun nears the horizon. The sky's colors blend with their saturation kept (lerpKeepSaturation in game-loop.js), since a plain blend from the day's blue to a sunset orange passes through grey.

The game features a custom atmospheric scattering shader that dynamically handles transitions from day to sunset to night based on the sun's directional lighting, mie scattering, and a volumetric sun bloom effect. Around sunrise and sunset the sky also varies around the compass: warm and bright toward the sun, cooler away from it, with the earth's shadow (a blue band) and the pink "belt of Venus" low in the sky opposite the sun in the minutes around sunset and sunrise (sun within about 3 degrees above to 9 below the horizon), while the zenith keeps the palette's deeper color. The sky dome, the directional fog and water reflections all compute the sky with one shared function (SKY_COLOR_GLSL in constants.js), so distant land fades into exactly the sky behind it. The sky has three cloud layers on one plane above the world (CLOUD_GLSL in constants.js): high cirrus streaks stretched along the wind, patches of mackerel sky (rows of small, soft-edged puffs, built from ripples across and along the wind rather than a noise threshold, so they don't look like cutouts up close) and puffy cumulus, whose noise is warped so the edges curl into billows. How much of each the sky has changes from day to day: each in-game day (starting at midnight) picks a cloud mood from the world seed and the day, so a given clock always shows the same sky: fair (scattered cumulus), mixed (cumulus with some cirrus), mackerel, high (cirrus over a mostly clear sky) or busy (all three). On about 60% of days the mackerel and cirrus build up around sunrise and sunset, giving the low sun more cloud to light. A new day's mix eases in over about half a minute (cloudMoodForDay in chill-flight-logic.js, updateCloudMood in game-loop.js), and the debug menu shows the day's mood under cloud cover, where you can also force a mood or step to other days' clouds. The weather still leads: as it turns overcast (where rain and snow fall), it takes over from the mood, with full cumulus, no less cover than the weather's, and the cirrus and mackerel fading behind the deck, so rain never falls from a clear sky (see Overcast skies). Cumulus edges are crisp in the distance and soften as clouds get closer, with their thin edges lit bright, so clouds don't look like paper cutouts when flying near them. Cirrus is lit as if slightly higher, so it keeps its sunset color a little longer. Clouds are lit for the time of day too: as the sun gets low it lights them from below, gold in the golden hour and fiery orange with the sun on the horizon, while clouds opposite it catch pink light and their shaded sides turn dusky plum and violet. In the minutes after sunset (the afterglow) they glow crimson toward the sunset and pink opposite, then dim to a moonlit grey-blue for the night, silver near the moon, which has a soft halo (brighter toward full moon; in ). The water reflects the clouds at the same positions (the cloud noise and lighting are shared GLSL, in ).

To ensure every day looks unique while maintaining cinematic quality, the sky color engine utilizes a Hybrid Palette System:

• Dynamic Zenith (Top Color): The overarching sky color is procedurally generated each in-game day, offering infinite variations of cyan, deep blue, and twilight purple.
• Curated Horizon (Bottom Color): To prevent "muddy" or washed-out sunsets, the horizon color is strictly selected from a curated list of highly vibrant, hand-crafted sunset palettes (such as Golden Hour, Arctic Mist, or Tropical Dawn).
• Smart Pairing: The system automatically categorizes the procedural zenith color and pairs it with the most complementary curated horizon color, guaranteeing a stunning sunset every time.

Weather

Weather is dynamic and procedural, tied to three noise maps that drift over the world and to the player's latitude: small, quick cloud patches, slower storm systems, and a big, slow field for the snow country's light snow (weatherAt and WEATHER in chill-flight-logic.js).

Overcast skies

Overcast conditions occur when the cloud patch noise is high (cover builds smoothly from about 0.65 to full at 1.0, or from about 0.5 over the snow), or as a storm system approaches: its overcast builds ahead of the rain. The sky follows the cover gradually, with a time constant of about 12 seconds (CLOUD_EASE_SECONDS in game-loop.js), so clouds build and clear over half a minute or so rather than snapping. Rain and snow fall only under thick cover, and there the overcast overrides the day's cloud mood, so the sky above is always full of cloud. As the cover thickens toward a storm, the clouds darken from white to a grey deck: rain clouds slightly darker than the overcast sky in their gaps, snow clouds (where storms bring snow, sleet in between) a lighter grey (stormDeckShade in constants.js); at sunrise and sunset the deck still takes the low sun's color, a little muted.

• Atmospheric effects:
  • Celestial visibility: Stars and the Aurora Borealis become invisible. The Sun and Moon are dimmed.
  • Lighting: Sunlight and Moonlight intensity is reduced, shifting to ambient, diffuse lighting.
  • Fog: Fog thickens with cloud cover, reducing visibility (see Fog).
  • Colors: The sky and fog colors blend towards a dark, stormy gray.

Storms and precipitation

Storms come from the storm noise, whose systems (about 10 km across) drift slowly, so a storm is something you fly into rather than a flicker. The sky clouds over first (storm noise from about 0.78), then a drizzle starts (0.8) and builds to a downpour (0.92) over 10 to 15 seconds at cruise. At 150 kts it rains 3 or 4 times an hour for about a minute each (nine in ten are over within 2 minutes), about 6% of the time; parked, a storm takes about 2 minutes to pass over. Thick overcast covers the heartland about 12% of the time, against 6% for the cloud patches alone. Rain eases in and out over about 6 seconds on top of that, snow over about 8 (RAIN_EASE_SECONDS and SNOW_EASE_SECONDS in weather-manager.js). Light rain and snow are fewer drops, not just fainter ones: the drop count and their opacity each follow the square root of the amount, so a drizzle is sparse but visible. npm run test:weather flies a plane through hours of weather and checks these numbers. The type of precipitation depends on your latitude (Z coordinate):

• The deep north (Latitude > 2.5 North / Z < -12500): Storms intensify the already frequent snowfall.
• The transition zone (Latitude 1.5 to 2.5 North / Z between -7500 and -12500): Sleet (a mix of rain and snow).
• Temperate and equator (Latitude 2.0 South to 1.5 North / Z between 10000 and -7500): Full rain.
• Desert border (Latitude 2.0 to 3.0 South / Z between 10000 and 15000, following the desert's wandering edge): Light rain that quickly dries up as you move further south.
• Deep desert (Latitude > 3.0 South / Z > 15000): Dry storms (the sky becomes overcast, but no rain falls).

Fog

Fog density follows the conditions; the thickest applicable condition wins:

• Clear skies: Light fog, so distant mountains stay crisp on sunny days.
• Morning fog: Builds from 04:00, is thickest from about 05:30 to 07:30, and burns off by 10:00.
• Clouds: Fog thickens as cloud cover increases.
• Rain and snow: The thickest fog, closing in the horizon.
• After rain: Mist lingers after precipitation stops and clears over about two minutes.

The values live in FOG in chill-flight-logic.js. The debug menu's clear-sky fog slider overrides the clear-sky density; the other conditions still thicken it from there.

Atmospheric phenomena

• Shooting stars: Rare shooting stars streak across the clear night sky.
• Rainbows: Dynamic rainbows can appear when the sun shines shortly after a rainstorm.

Permanent weather

• Snowy biome: Light snow follows its own big, slow noise field (falling where it is above about 0.52) and brings its own cloud, so it snows about 40% of the time in the snow country, in spells of a few minutes, but never from a clear sky. It starts where the snow cover starts (Latitude 1.5 North, Z = -7500), reaches its usual amount where the cover is full (2.5 North, Z = -12500), and keeps getting a little heavier to 4 North (Z = -20000). Cloud patches also build sooner over the snow (from about 0.5 instead of 0.65; SNOW_CLOUD_HEADSTART in WEATHER).

Debug menu weather entries

The telemetry overlay provides real-time values for the weather system:

• Overcast: The current interpolated overcast value (0.0 to 1.0), determining cloud density and atmospheric effects.
• Storm: The storm noise here. Overcast builds from about 0.78 and rain or snow from 0.8 (the snow country's light snow has its own field).
• Precip: How hard it is raining or snowing around the camera (0.0 to 1.0 of full rain or full snow, whichever is more).
• Zone: The current climate zone based on latitude (Snow, Sleet, Rain, Dry edge, Desert).
• Snow α: The visual opacity of the snow particle system (maxes out at 0.8).
• Rain α: The visual opacity of the rain particle system (maxes out at 0.5).
• Fog: The current density of the scene fog.

Woods

Broadleaf trees have cloud-shaped canopies (a core with smaller lumps around a dome) and pines have tiers ending in drooping branch tips. Trees grow in woods rather than an even scatter (terrain-gen.js). A forest's density rises from thin edges to dense cores, where a spot can hold several trees, and a larger clump pattern breaks woods into groves and clearings; lone trees stand out in the open near them. Woods are mixed: valleys mostly broadleaf, with conifers taking over up the hillsides. Woods climb the hills to a tree line that is about 600 units high in the south, 400 by 1 North, and comes down toward the valleys with the snow, wobbling so it isn't a contour line. Over the last 150 units below it the woods thin out and shrink to stunted conifers; above it there's a band of yellow-green alpine meadow turning to scree, then bare rock from 150 units above the tree line (treeLine in terrain-gen.js). Steep slopes carry few trees and low ground near water up to half again as many, trees deep in the woods grow bigger than those at the edges, and each is nudged off the terrain grid (its height re-sampled) so they don't line up. The ground under thick woods is darkened, like canopy seen from above. There are about three times as many trees as the old even scatter on the mid preset and up (1.3 times on low, for slower devices), which costs about 1.5 ms of GPU time per frame on an M1 MacBook Air at mid; trees switch to their simple far shapes 2 chunks out to help pay for it.

Landmarks

These areas are layered on top of the primary biomes using noise-based "patches":

• Fall colors: Heading north is like driving from Long Island up to the Adirondacks in October. South of the equator the broadleaf trees are green; from about 0.2 North they start to turn, each tree at its own point, into maple red, orange, birch yellow or oak russet, and by about 1 North they've all turned, with the evergreens standing green among them. From 1.3 North they drop their leaves, leaving bare trees by the snow line at 1.5 North. Higher ground turns a little earlier, a slow wobble keeps the front from being a straight line, and the ground under the woods turns russet with the leaves (fallTurnAt and fallBareAt in chill-flight-logic.js).
• Cherry blossom groves: Rare pink-tinted forests (#F8BBD0). These are the only places where Pagodas will spawn.
• The equator river: A massive, meandering river that runs primarily East-West around Z=0 (0.0 Latitude), across the continent from the western alien land to its estuary on the east coast. It features fluctuating widths (80 to 300 units) and smooth, carved banks.
• Grid rivers: Smaller rivers running East-West along some of the one-degree latitude bands (5,000 units apart) north and south of the equator: the world seed gives each band a mountain range, a minor river or neither (the first bands, at 1 North and 1 South, always hold mountain ranges; proceduralTerrainType). These feature widths of 60 to 200 units and have unique snaking patterns determined by the world seed, and end where they reach a coast.
• Estuaries and tributaries: Rivers widen over the last 6 km before the east coast (1.0 West to 0.2 East) into broad estuaries, up to 4.5 times as wide at the mouth. Inland, side streams join them from the north or south at irregular, seed-chosen spots (up to one per 7 km of river), running 2.5 to 5 km, meandering and narrowing toward their source, and stopping at the foot of mountains. All water sits at sea level, so rivers have no falls of their own (see waterfalls below).
• Waterfalls: A few great waterfalls rather than many awkward ones: where a stream meets a tall, sheer drop into open water, off a sea cliff, a lake shore or the wall of a fjord. Only about one chunk in five can have one (its random number has to beat the four chunks beside it, so falls are never side by side, even along a long cliff coast), and few places pass, so there's about one per 120 chunks, or 270 km², around spawn. The terrain worker (findWaterfall in terrain-gen.js, with its own random numbers so the chunk's other props don't move) follows the steepest way down its height grid from each high point to the water, and traces the stream feeding it up the valley floor, each step to the higher neighbor that drains into it, for up to 300 units; where the stream runs down steep rock, that stretch becomes part of the fall. A fall has to be at least 150 units tall and 1.5 times as tall as it is long, fed by at least 100 units of gentle stream, and land where at least 30% of the ground within 150 units is water. The steepest, tallest such fall in the chunk wins. The worker also sends the patch of height grid around the fall and stream, so the waterfall () can clear the terrain as drawn: each row across it is level, just above the ground under its middle, and where a gully's sides stand higher it moves out from the rock until it clears them, hanging in front like a curtain. It's a ribbon of falling water, widening toward the bottom, with streaks pouring down it and ragged edges, a ring of churning foam where it lands and soft mist rising around it, with puffs of mist rolling out across the water (). The water glows a little so it stays white on the shady side of a cliff. Above the fall, the stream lies on the ground, blue with white flecks drifting downstream toward the edge. Where its source has room, a small pond feeds it, its water 4 units above the source, reaching out until the ground rises above it (the shore) or drops away, and rounded off so it doesn't run out in spikes along the valley. Where the falls are depends on the world seed, except for the falls landmark north of spawn (below).

Liveries

The plane's color is deterministically chosen based on a hash of the player's unique UID. There are 8 available liveries:

• Sunset Coral
• Chill Teal
• Muted Sage
• Lofi Purple
• Ocean Slate
• Soft Sand
• Deep Rose
• Charcoal Black

You can pick a livery for one visit with the ?livery= URL parameter: an index (0-7) or a name (coral, teal, sage, purple, slate, sand, rose, black).

Wildlife

The world is populated with dynamic, procedural wildlife that adds life to the environment:

• Geese: Flocks of Canada geese fly in V-formations across the sky. They sleep and disappear at night, resuming their flight in the morning. A flock stays in view wherever it flies, even far from where it set off (and after that area of the world unloads), until it's too far away to see.
• Hawks: Solitary hawks glide on thermal currents, dynamically transitioning between flapping and soaring.
• Seagulls: Flocks of gulls circle over coastal regions and beaches.
• Penguins: Animated waddling penguins inhabit the icy terrain and floating icebergs of the deep north.

Planes

There are four planes to fly, picked on the pause menu's Flight tab (or with V). Each has its own speed and handling, kept close enough that every one still flies gently (PLANE_HANDLING in constants.js). Under the plane buttons, three bars compare the chosen plane's top speed, agility and float (how slowly it can fly) with the best of the four.

Plane	Top speed	Falls below	Level from	Throttle (up / down, kts/s)	Agility	Barrel roll
Biplane	280 kts	40 kts	80 kts	40 / 30	1.3	~1.7 s
Seaplane	380 kts	55 kts	100 kts	50 / 30	1	~2.2 s
Twin	500 kts	65 kts	115 kts	60 / 20	0.75	~2.8 s
Jet	800 kts	75 kts	130 kts	70 / 25	1	~2.1 s

• Biplane: slow and nimble, the one for aerobatics.
• Seaplane: the all-rounder.
• Twin: fast and heavy, for long trips. It turns wide, rolls lazily, needs more speed (and runway) to stay up, and coasts a long way when you throttle back.
• Jet: the fastest, with twin tails and swept wings. It needs speed to stay up, lands fast, and its turbine whine climbs with the throttle.

Agility scales how quickly a plane rolls and pitches toward the controls and how sharply it turns for a given bank. All planes also turn more gently when fast: full turn rate up to 150 knots, easing down to 70% of it at 450 knots and up (TURN_FADE_FROM_KTS and the rest in game-loop.js). Warping to an airport arrives at an approach speed to suit the plane (90 knots in the seaplane).

Other planes

A few other planes share the sky, so now and then you spot someone else up there (traffic.js, with the flight math in traffic-logic.js). Up to three are around at a time: each appears 4.5 to 6 km away, small in the haze, on a course across your part of the sky, and is gone once it's 8 km off; a new one turns up every 15 to 45 seconds. They fly the game's four planes in random liveries, wander in gentle banked turns at their own cruising height, scan up to 9 km ahead along their course to start a gentle climb early before hills and ridges, hold their height across valleys before easing back down, turn away from steep mountains, and never dip below 40 units over the ground. At night they show navigation lights: red on the left wingtip, green on the right and a white strobe on the tail. They pace you, so you can find one and follow it around: within 800 units a plane flies at your speed, a little slower while it's ahead of you (so you catch up) or faster while it's behind, matching you exactly within 150 units, and it eases back to its own cruising speed (105 to 170 knots) once you leave. It never drops below 100 knots, where planes sink. Fly within 250 units of one for 3 seconds to earn the Wingman achievement. Zen mode hides them, and ?traffic=0 or =1 sets them for one visit (overriding zen).

Flying together

Fly with up to three friends (multiplayer.js, with the rules and smoothing in multiplayer-logic.js). The 👥 button on the pause menu opens Fly together: set the name shown over your plane, then Invite friends starts a room and shares a link (the phone's share sheet, or the link copied on a computer), or type a friend's 4-character room code and Join. Codes leave out the look-alikes (0/O and 1/I/L). A link carries the room and its world's seed, so friends in other time zones, or opening it the next day, fly the same world; joining by code from a different day's world reloads into theirs. Links from the apps point at the website.

• In a room: everyone sees each other's planes in their own plane type and livery, with their name and distance over them ("Lauren · 150 m"), propellers turning and gear going up and down. A friend in the pause menu shows as a translucent ghost with (paused) on their marker and in the panel, with propellers stopped and immunity in tag. Toasts say who joined and left. The panel lists who's flying with a Fly to button that puts you just off their wing, heading their way, and joining puts you there to start. Time of day already follows the wall clock, so everyone has the same sky.
• Smoke: airshow smoke (X) shows for everyone, and while you're in a room every plane's smoke, yours included, takes its livery's colour mixed half and half with white. Solo smoke stays white.
• Finding each other: friends out of view show at the screen's edge as a chevron pointing their way with their name and distance, like the waypoint marker. Friends show on the minimap (held at its edge when further) and on the fullscreen map with their names, as arrows in their livery colour. Zen hides the markers.
• Waving: H (or 👋 in the quick menu, shown while in a room) waggles your wings, and everyone else sees it on your plane. Not while on the ground or water.
• Bots: Fly with bots starts a room of your own with bots in the other three seats, and Fill empty seats with bots in a room does the same for any seats nobody's using (bot-logic.js flies them; npm run test:bots). They have bird callsigns with 🤖 and their own planes and liveries. Whoever turns them on flies them on their own device and sends their positions along with their own, so everyone sees the same bots with no change to the relay; if that player leaves, their bots go too. When someone joins, a bot flies off to make room. Friends and bots in buggies show as buggies. In a buggy (in a round of buggy tag, or out of games while you drive) a bot drives along the ground: it steers around ground too steep to climb, turns toward open ground when it gets held up, and is put back beside you if it gets boxed in. Out of games a flying bot keeps a spot off your wing, catches up after a warp, circles overhead while you're parked and waggles back when you wave. In tag a bot that's it chases the nearest person (before other bots, and never whoever just tagged it) a little slower than a player who's it, reacting late to turns and switching targets when a chase gets nowhere; a bot running hangs about near whoever's it to score, circling closer in daring spells and further out in wary ones, weaves away low when they get within about 130 m, dawdles now and then, and drifts back toward everyone when there's no one to run from.
• Tag: Play a game in the panel opens a picker with Tag and Race; starts a game with you as "it", locks everyone to your plane for the round (without overwriting their saved choice; started from the buggy, everyone drives buggies, set down on the ground), and gathers the others ahead of you. While you're it, your top speed is boosted by 15% ( in ), shown as a gold stretch past the usual MAX on the throttle that the knob glides into at full throttle (no text says so), and everyone who isn't it has smoke forced on. Fly within 60 m of a friend to tag them; they're then it, after 4 seconds' grace to get away. A round lasts 2 minutes (), and everyone who isn't it scores points for staying near whoever is: 3 a second within 300 m, 1 a second out to 800 m (), with a soft gold glow round the screen's edge while scoring (brighter when close). Each player counts their own points (and their bots') and sends them with their position. A chip at the top shows who's it, your points and the time left, their name gets "(it)", toasts say who tagged whom, and the panel lists everyone's points (most first, with hidden during the round). When time's up, whoever's it ends the round a second later with everyone's final points (anyone does after 4 seconds, should they not), and the most points wins. Whoever is it decides the tag from what their own screen shows, so lag never causes an argument. Paused players cannot tag and cannot be tagged. If it leaves, the game carries on with the next player as it (the same one on every screen); alone, the game ends. ends it early for everyone, with the points so far, and latecomers join the round in progress (with the time left) from zero.

Buggy

Pick the buggy in the pause menu (or press V until it comes up) to drive instead of fly (buggy.js, model in buggy-model.js). Switching to it in the air sets it down on the ground below, rolling on at up to its top speed of 240 knots; switching back to a plane leaves the plane on its wheels where the buggy was. It drives on the ground, the highways and their bridges, and on water it turns into a hovercraft, its wheels folded flat, and carries on at speed. Stuck somewhere (trying to go, but not 20 m further on after 5 seconds) it's put back on the nearest highway, facing along it, or where it was last driving well if there's no highway near (rescue-logic.js; npm run test:rescue).

• Throttle slider: sets baseline cruise speed. The buggy accelerates to and holds this speed while you steer.
• Joystick / directional control: one-handed driving. Speed-dependent turning radius smoothly expands as you speed up (from ~5 m radius for nimble parking to ~195 m at 150 kts, ~348 m at 200 kts, ~500 m at 240), paired with a progressive analog steering curve. Small thumb adjustments around center give subtle, stable lane tracking on straight highways without twitching, while full stick deflection provides controlled highway cornering authority. Push up / Arrow up / W to temporarily boost up to top speed. Pull down / Arrow down / S to smoothly brake to a stop, then continue holding to reverse. Releasing the stick automatically brakes and resumes cruising forward at your preset speed.
• Catching air: driving at high speed up an incline, steep hill, or ramp crest reliably launches the buggy into the air in a natural ballistic flight arc, with pitch easing along the trajectory before touching down smoothly onto its suspension. The ground throws it up at no more than 80 units/s (about a 30 m jump). In the air, steering turns the buggy to line up the landing, though it carries on the way it was going.
• Grip and drifting: tyres hold firm, predictable grip in ordinary turns. Hold the stick hard over (or an arrow key) above 90 kts and the buggy leans in: the tail kicks out into a drift (about 25° on dirt, 14° on the road, wider past 180 kts), turning tighter and scrubbing speed. Ease off to straighten up, which takes longer the faster you go. Touch screens provide clean, single-handed control without pedal buttons cluttering the view.
• Double-tap moves, like the planes' (keyboard arrows or WASD, gamepad D-pad and bumpers; on touch, double-tap the screen's left or right third, or in the middle column above the buggy or on it, as for the planes, and the joystick still steers through the move; the middle column's up zone reaches down to 48% of the screen's height and the down zone starts at 60%, at the buggy's roof):
  • Double-tap up: hop, about 6 m (off water too). Keep holding up to float it higher (about 10 m) and steer in the air: the stick turns it about twice as fast and its path follows the nose.
  • Double-tap left / right and hold: power slide. The tail kicks out at once, from as slow as 30 kts, wider than leaning in, with the tyres letting go. Let go to straighten up.
  • Double-tap down and hold: hard brake, twice the ordinary brakes, to a halt (it never reverses while held). Steering at the same time swings the tail round in a handbrake turn.
• Smooth highway ride: critically damped suspension and continuous road deck sampling give a smooth, stable ride over roads and rolling terrain. Multi-level overpass and underpass junctions pass cleanly.

Knocking things over

Run into almost anything, in the buggy or flying low, and it breaks (breakables.js, maths in breakables-logic.js). Trees, cacti, snowmen, streetlights, tents, the airport tower and windsock and signs, and the lighthouse (its light goes out) topple away from you and stay down (a fallen streetlight's lamp goes out). Houses, straw huts, pagodas, barns, monasteries, windmills, castle ruins and hangars fold in with their roof, chimney or sails thrown off among blocks of rubble and dust, and a barn's silo topples on its own. Bushes get flattened, boulders shatter into stones, campfires are knocked apart, piers smash into planks, icebergs crack into glassy chunks and ice floes into flat slabs that float where they land, parked planes tumble across the apron, and sailboats and pirate ships roll over and sink. Penguins and birds get out of the way instead: a penguin hops off its floe, out of your path, and dives in when you come within about 100 m (it's back next time the area loads), and a hawk or gull flaps off when you fly close and drifts back to its circle. Geese hold their V (startling one is its own achievement). A rock arch comes down in its blocks, but only if you hit the rock: flying through the gap is safe. Bridges and waterfalls never break. Each hit costs a little speed (a house more than a tree, the buggy more than a plane), with a camera jolt, a crack or crunch (its own switch in the sound lab) and a haptic tap. You never crash. What you knock over stays down for the session, even after flying away and coming back; reloading restores the world. In multiplayer each player's game runs the same check for the friends it shows, so you see their wreckage too, with nothing extra sent over the network (a friend who joins later doesn't see what came down before).

Bumping into each other

Planes and buggies don't fly or drive through each other (bumps.js, maths in bumps-logic.js; npm run test:bumps). Touch a friend's plane, a bot or one of the air traffic planes and you're both shoved apart sideways, lose a little speed and wobble, with a camera jolt, a thud (its own switch in the sound lab), a puff and a haptic tap; then the two pass through each other for a moment so you can't get stuck together. Bumps count in races and in buggies too. Each game shoves its own player, bots and traffic, so nothing extra goes over the network. Bots keep clear of everyone, sidestepping anyone about to come too close, so a bump with one is usually your doing.

Scraping walls

The plane's middle keeps a cushion of about 5 m above the ground, which lifts it over hills (flight-physics.js). Its wingtips and nose touch steep ground too (steeper than about 35°: cliffs, canyon walls, mountainsides), so a wall pushes you off sideways instead of popping you straight up (wall-scrape.js, maths in wall-scrape-logic.js; npm run test:wall-scrape). Graze a wall with a wingtip and the plane slides off it, sparks flying from the tip, with a rasp (its own switch in the sound lab), a wobble that lifts the wing away from the wall, a small camera jolt and a haptic tap; it loses a little speed while scraping. Fly nose first into a wall and you glance off it: the plane is held out of the rock while its heading swings along the wall, the way nearer where you were heading (dead on, the way you're banked), losing a quarter of its speed, with a shower of sparks and a bigger jolt; gentler slopes still lift you as before. Try hard enough to crash (crash.js, maths in crash-logic.js; npm run test:crash)—flying dead on at high speed into a steep cliff, nose-diving or stalling hard into the ground or water, or grinding nose first into a wall or plowing through several buildings in a row before the strain fades—and the plane breaks into tumbling pieces that scatter and bounce on the ground or splash into the water: the camera pulls back to orbit the wreck for a moment, then tilts up and swings in behind a fresh plane in clear air overhead, facing downhill away from the cliff at cruise speed (in a multiplayer room, friends see your plane break apart and respawn overhead too).

Landing

Every plane can land on water and on land: the biplane, jet and twin engine on their wheels, and the seaplane on its pontoons, which slide along gentle ground and runways like skids. Fly low and slow, under the plane's level speed (100 knots in the seaplane; see Planes), and the plane settles gently (flight-physics.js): the slower you fly the faster it sinks, from none at 100 knots to about 8 m/s at 50 knots in the seaplane (sinkRateAt), easing in and out over about a second as the speed changes. Below about 70 knots the nose dips a little, so you can see the plane is slow; around 60 to 75 knots is a comfortable approach in the seaplane (lower in the biplane, higher in the twin). Slower still, the plane falls out of the sky: from its stall speed (55 knots in the seaplane) down to 20 knots below it gravity blends in, accelerating it toward the ground as it tumbles, harder the faster it falls. A nose the tumble tips down doesn't win back speed, so it stays in the fall until you open the throttle; then the fall fades over about a second as it powers out, like pulling out of a dive. On touching down the throttle eases back to idle, so the plane slows to a stop on its own; open the throttle again and it stays open for the takeoff run, then pull up to lift off.

• Landing gear: The seaplane's pontoons and the twin's and jet's wheels come down within about 30 m of the water or ground when you're descending or slow, and fold away above about 40 m; they have to be all the way down to touch down on land. The biplane's wheels are fixed.
• Where to land: Wheels touch down on ground gentler than 15°, and once rolling stay down on slopes up to 30°, so a bumpy meadow doesn't bounce you; on steeper ground the plane keeps its usual height above the terrain. The wheels follow the ground as drawn, and the plane tilts to the slope it's parked on, then levels out gently over about half a second after takeoff (TILT_LEVEL_SECONDS in flight-physics.js). The highways are landable too: over a highway the wheels touch down on the road deck, bridges included (sampleRoad in terrain-chunks.js), and with the gear up the plane keeps its usual height above the deck. Flying under a bridge passes beneath it.
• Spray, wake and dust: Setting down on water throws a sheet of spray off both pontoons with a low mist, and moving on the water leaves two lines of foam spreading into a V behind you, riding the swell, with spray off the bow at speed. Wheels touching down kick up a puff: grey tire smoke on a runway, apron or road, dust the colour of the ground elsewhere, bigger for a harder landing. Rolling on dirt, sand or grass leaves a low dust trail off the wheels, and opening the throttle at low speed blows dust back behind the propellers. Skimming low over the water, within about 20 m on the altimeter, throws up a rooster tail of spray behind you and leaves a faint line of foam, stronger the lower and faster you fly. Pulling hard (a loop, an Immelmann or a sharp turn) streams thin white vapour off the wingtips, and the engine coughs a puff of grey smoke when you open the throttle from a standstill. Drifting sailboats and patrolling pirate ships leave a V of foam behind them too. They come from one shared pool of soft particles, drawn in a single call, whose motion and fading are worked out in the vertex shader from where and when each was spawned (particles.js).

People and jobs

People wait at the airports with jobs for you, always there but never in the way: land at an airport with nothing on and someone there says hi and offers one of their jobs, which you can take (Sure thing) or turn down (Not right now; they'll ask again next time).

Ray	Doug	Bonnie	Esther
Meadow Field	Mesa Field	Meadow Field	Mesa Field
Coffee artisan	Cheese fries & karaoke	Moonwater enthusiast	Protein scientist

Tim	Marielle	Erin	Lauren
Lagoon Field	Lagoon Field	Sagebrush Field	Sagebrush Field
Optimist golfer	Bookworm & tea lover	Tennis & knitting	Knitting & tennis

• Round trip or one way: a round trip sends you to an airport to pick something up and back to whoever asked; a one-way job ends when you drop off where it sends you. They thank you when it's done.
• Landing counts: land on the destination's runway and slow below 20 knots on your wheels (or the seaplane's pontoons); landing anywhere else changes nothing.
• Waypoint: points to the next airport each time, so you can fly there yourself or hand it to the autopilot (which circles the field; the landing is yours). It stays until you land there, and clearing it on the map drops the job. Setting another waypoint is a detour: the job stays on, and once the detour is reached or cleared the waypoint points back to the job's airport.
• Who asks: where several people share an airport, the one you've helped least asks first.
• Talking: people talk in a dialog box along the bottom of the screen with a pixel-art face on their own background color, whose mouth moves as the words type out and who blinks now and then. Some people change outfits for particular jobs, like tennis clothes for a tennis job. Tap or click it (or press Enter) to show the whole line, then the next. When they ask, answer with the buttons, or Enter or Y for yes and N for not right now. Pickups and finished jobs show as toasts.
• HUD: on a job, the cockpit readout's CHILL-FLIGHT line becomes who it's for, what's in the hold and where it's going, with AUTO in red while the autopilot flies.
• People screen: the 📇 button on the pause menu (next to 🏆) shows everyone with their face, airport and the jobs you've done for them. People you haven't met yet are a silhouette and "???", with just their airport.
• No money yet: jobs just count. Money can come later, once there's something to buy.

Progress is saved between visits. The people, their lines and their jobs are in people.js (the format is described at its top) and their faces in faces.js, one each under their name, with any outfits a job can put them in (a job's outfit); their SVGs are exported to assets/faces/ with npm run export:faces; the rules are in jobs-logic.js (tested by scripts/test-jobs.js, which also checks people.js is filled in and points at real airports, everyone has a face of their own, and the SVGs in assets/faces/ match faces.js); the dialog box is dialog.js, the HUD and landing check jobs.js, and the People screen people-screen.js.

Controls

Multiple control methods are supported: keyboard, mouse or trackpad, and gamepad.

Keyboard & mouse controls

General flight

• Arrow up / down: Control pitch (climb / dive). Both climb and dive ease in and out as a gradual transition.
• Arrow left / right: Control roll and turning.
• Shift + arrow up / down: Throttle control (increase / decrease speed).
• Mouse wheel / trackpad scroll: Smoothly adjust throttle (increase / decrease speed).
• C: Cycle the camera: follow, first person, bird's eye (straight down, north up) and cinematic.
• Trackpad pinch / Ctrl + scroll: Zoom the follow, bird's eye and cinematic cameras in and out (the bird's eye view from about 180 m to 1 km above the plane, 510 m as it starts; the chase cameras from about half to three times their usual distance; first person doesn't zoom). Each camera keeps its own zoom while you switch between them.
• M: Open or close the fullscreen map. The game pauses while it's open, and closing it (M, Escape or the Resume bar along the bottom) goes straight back to flying.
• Shift+M: Toggle the minimap overlay.
• L: Toggle headlight.
• H: Waggle your wings at friends flying with you (in a Fly together room).
• X: Toggle airshow smoke, a white trail from the tail that hangs in the sky for about 18 seconds, long enough to fly a lazy circle back through it (also the smoke button in the quick menu on touch devices).
• V: Cycle active vehicle (switch between the vintage biplane, the seaplane, the twin-engine transport, the jet and the buggy).
• Shift + A: Toggle autopilot. It flies to your waypoint and circles it once there (slowing to 120 kts), until you set another. With no waypoint it tours the landmarks: it flies to the nearest one it hasn't visited (the waypoint marker shows the way and the distance left), circles it once and moves on to the next. It cruises at least about 150 m up and keeps about 80 m over the highest ground along its course, looking 9,000 units ahead (and a little to either side close in) so it climbs early and gently (about 7 degrees) rather than late and steeply. Past high ground it holds its height until it's well clear, then comes down gently, so it rides over hilly country instead of bobbing over every rise, and it damps its pitch with its vertical speed so it eases onto a new height. It circles a waypoint or landmark 120 units over the highest ground around it (autopilot.js). In the buggy it drives instead, at about 100 kts: to your waypoint, slowing as it gets close and parking there, or with no waypoint it tours the landmarks like the planes, driving a slow lap round each one (about 150 m out, at 60 kts) before moving on to the next, and skipping one it can't get to (no closer in 90 s, such as one up a peak). On a road going roughly its way it follows the road, keeping right of the centre line. It steers round ground too steep to drive and, held up against a bank, backs off and tries another way, the same way the bots drive ( in , using ). Steering with the arrow keys, the touch joystick, drag-steer or a gamepad stick turns it off (mouse and tilt steering don't, since they're always steering).

Special maneuvers

• Double-tap arrow up and hold: Perform a steep climb. It ramps up smoothly to a 60° climb and eases back to level flight on release.
• Triple-tap arrow up and hold: Perform a loop. The pitch rate eases in from the climb, floats over the top and eases out onto level flight, and the speed dips over the top so the loop comes round to the height it started at. Once started, a loop always comes round to level; still holding as it nears level goes round again.
• Double-tap arrow down and hold: Perform a steep dive. It ramps down smoothly to a 70° dive and eases back to level flight on release.
• Triple-tap arrow down: Perform an Immelmann turn (climbing half-loop followed by a half-roll into reverse heading). It carries on from the plane's pitch and pitch rate, rolls out any bank early in the pull-up, and can't start on the ground or mid-loop.
• Double-tap arrow left / right and hold: Perform a sharp turn (steep 78° bank with accelerated turn rate and elevator back-pressure).
• Triple-tap arrow left / right and hold: Perform a barrel roll. It eases in and rolls as long as you hold, about two seconds a roll (quicker in the biplane, slower in the twin).

Free camera mode (if active)

• Arrow keys: Move camera horizontally.
• Q / E: Move camera vertically (down / up).
• Shift: Boost camera movement speed.

Controller support

Full gamepad support mapped to standard flight controls.

• Left analog stick: Control pitch (up/down) and roll (left/right).
• Right trigger (RT): Accelerate.
• Left trigger (LT): Decelerate.
• Left bumper (LB) / right bumper (RB): Control roll. Double-tap to trigger a sharp turn, or triple-tap to trigger a barrel roll.
• D-pad: Mapped to arrow keys for menu navigation and alternative flight control.
• Button A: Select / enter.
• Start / menu button: Toggle pause menu.
• Select / back button: Toggle mobile action menu.

Touch & mobile controls

When playing on a touch device, specialized UI and controls become available:

• Virtual joystick: A premium, floating virtual joystick appears on screen for smooth, thumb-based flight control. It remains active and visible during double-tap-and-hold gestures (such as sharp turns, steep climbs, dives, and barrel rolls), allowing continuous steering throughout maneuvers.
• Control schemes: The Controls setting on the pause menu's Settings tab lets you choose between virtual joystick, device tilt (gyroscope), or directional button steering.
• Throttle: The slider next to the quick menu sets your speed: drag or tap anywhere on it, from a stop on the left to the plane's top speed (MAX) on the right. The knob shows the speed you've set in knots: amber where the plane sinks (50 to 100 knots in the seaplane), and red where it falls out of the sky (the striped band on the left marks where the fall starts, at 55 knots in the seaplane; see Planes). Left alone for about four seconds, the throttle fades back until you use it again. Keys, the scroll wheel and a gamepad move the knob too. The plane follows at a steady rate (in the seaplane, speeding up about 50 knots a second and slowing about 30), easing in over the last few knots, while the SPD readout shows its actual speed. On a desktop it works with the mouse.
• Pinch to zoom: Put two fingers on the view together and pinch to zoom the follow, bird's eye or cinematic camera in and out (each keeps its own zoom). In the cinematic camera, dragging the two fingers also swings the shot around the plane (it stays where you leave it), while one finger steers as in every other view (a gamepad's stick still swings the shot there). While they're down they don't steer or count as taps; a finger left down after the pinch does nothing until it lifts. A second finger that comes down later (tapping a stunt while steering) still works as before.
• Fullscreen world map: Tap the map button in the quick menu (the ^ button at the bottom left) to open the full screen map. It pauses while open; tap Resume along the bottom to go back to flying. Press and hold / drag to pan across the world, pinch with two fingers to zoom in and out, double-tap to zoom in, and tap the locate button at the bottom right to re-center on your plane. Tap a spot to pin it (a tap near a landmark or airport picks that place, with its name and who's there), then Warp here to jump there (to an airport, lined up to land; to a landmark, facing it) or Set waypoint to fly there with a marker showing the way.
• Airshow smoke: The smoke button in the quick menu (the ^ button at the bottom left) toggles a white smoke trail from the tail, like the X key.

WebXR & VR headset support

Chill Flight supports immersive virtual reality on devices such as the Meta Quest 2 via the Meta Quest Browser or any WebXR-compliant browser:

• Enter VR: An opt-in "VR" button appears in the pause menu and initial splash screen when a compatible WebXR VR headset is detected. Phones and tablets don't get it, even where the browser offers phone VR (Android Chrome's Cardboard-style mode).
• Head tracking: Full 6DoF head tracking allows you to look around freely from either the follow chase view or cockpit first-person view.
• Touch controllers: Use the right analog thumbstick for pitch and roll steering, right trigger to accelerate, and left trigger to decelerate.
• In-game pause menu: Press the left controller Y button or click either thumbstick to bring up the 3D in-world pause menu. Select options using the laser pointer trigger, or press A to resume flight and B to exit VR.
• Performance: Automatically enables fixed foveated rendering and unlocks high display refresh rates (72 Hz / 90 Hz).

Graphics & settings

The game features automatic graphics preset detection that evaluates your device's hardware capabilities upon loading and seamlessly scales visual fidelity to ensure a smooth frame rate.

• Presets (low / mid / high / ultra): These presets automatically adjust render resolution, shadow maps, draw distances, and mesh densities. Mid and up also draw the distant terrain ring (see below); low fades the land into the sky at the draw distance instead.
• Manual override: You can manually override the auto-detected graphics preset on the pause menu's Settings tab.

Preset	Chunk radius	Active chunk grid	Draw distance	Mesh density (SEGMENTS)	Triangles per chunk	Resolution scale	Visual effects
Low	4 chunks	9 × 9 (up to 81 chunks)	6,000 units	20	800	Fixed 0.5×	Off (optimized)
Mid	6 chunks	13 × 13 (up to 169 chunks)	9,000 units	30	1,800	Up to 1.5× (dpr × 0.75)	Full
High	7 chunks	15 × 15 (up to 225 chunks)	10,500 units	40	3,200	Up to 1.5× (dpr)	Full
Ultra	8 chunks	17 × 17 (up to 289 chunks)	12,000 units	50	5,000	Up to 2.0× (dpr)	Full

Note: Full visual effects include real-time shadows, transparent water and clouds, and procedural sky clouds. The low preset disables these to minimize overdraw and maximize frame rate on lower-end devices.

Looking toward the sun on mid and up (both art styles) adds a subtle lens flare: a faint warm halo and a few pale ghosts mirrored through the middle of the screen (lens-flare.js). Terrain, planes and clouds in front of the sun hide it, and it fades as the sun sets and toward the screen's edges. It is off on low and in VR. The flare URL parameter scales it (flare=2 is twice as strong) or turns it off (flare=0).

Art style

Besides its low-poly look (the default), the game has an anime art style, inspired by Studio Ghibli backgrounds: painterly light and color, a deep blue sky, ink outlines (bold on mountains and land, lighter on the plane), soft brushwork in the distance, a soft glow and big puffy clouds.

Choose it on the pause menu's Settings tab (Art style: low poly or anime). The choice is saved on the device, and changing it restarts the game, since the style is set up as the game loads. The style URL parameter (anime, or lowpoly for the low-poly look) overrides the saved choice. The low-poly look doesn't change at all with another style off. In code and saved settings the low-poly look is called classic, and style=classic works too.

What the anime style changes:

• Light and color (art-style.js): smooth shading instead of flat facets; sun and moon light in three soft steps, like cel shading with soft edges; lavender shadows instead of grey (cool blue on snow and other near-white surfaces, which lavender turns pink); slightly warmer light and fewer plastic highlights; no near-black colors (dark colors lift toward lavender grey, strongly colored ones partly toward their own hue); near-white surfaces a little darker, so white paint keeps its shading at noon instead of turning flat white; a gentle color grade.
• Land and trees (terrain-geometry.js, constants.js): grass and other vegetation drift between warm yellow-green and cool blue-green in broad washes, with smaller lighter and darker patches like uneven paint (fading out before the distant terrain ring). Bare rock (steep ground that isn't grass or snow) is shaded by its facets on top of the smooth lighting, so mountains keep their ridges and gullies in sun and shade. Tree canopies and bushes break into leafy clumps with lavender gaps, anchored to each tree so they sway with the leaves.
• Sky (SKY_COLOR_GLSL, CLOUD_GLSL, TOWER_GLSL in constants.js; src/shaders/sky.frag.glsl): by day the zenith is deeper and more saturated and the blue reaches further down toward the pale horizon, and the warm halo round the sun is tighter, so a low sun doesn't wash out a quarter of the sky (the fog and water reflections follow, since they share the sky's color); cumulus are bigger and rounder, with crisp edges and two tones (lit and a lavender shade; a storm deck is shaded gently instead, since its flattened light breaks two tones into blotches); the mackerel sky's puffs become crisp "sheep clouds" with a lavender rim away from the sun; cirrus becomes broad, crisp brush strokes with lavender lower edges; and on cumulus days, towering clouds of stacked round puffs rise from the horizon, with bright rims on their tops and sunward sides and bases that dissolve into the haze. They stand on the visible horizon (the far edge of the land and sea, uTowerHorizon), which drops below eye level as you climb, so from high up they still rise from the haze rather than showing their straight-sided bases. Each day has its own skyline of towers, which drifts slowly around the horizon with the wind and fades away as the sky turns overcast. The moon hides behind them. Water reflects the anime cumulus (not the towers). cloudStyle=classic keeps the low-poly look's clouds and sky (and no towers) with the rest of the anime style.
• Water: on the open sea, light painted strokes ride the wave crests and drift with the swell, faded out in the distance; rivers, ponds and lakes stay calm. The depth gradient from turquoise shallows to deep blue is the same as in the low-poly look.

Differences by preset and mode:

	Low	Mid	High / Ultra	VR
Light, color, land, trees, water	Yes	Yes	Yes	Yes
Anime clouds and horizon towers	No (low has no sky clouds)	Yes	Yes	Yes
Ink outlines and haze	Yes	Yes	Yes	No
Glow	Yes	Yes	Yes	No
Brushstroke (Kuwahara) filter	No	Yes	Yes	No
FXAA edge smoothing	No	No	Yes	No

Cost: on an M1 MacBook Air at the mid preset, the anime style takes about 12.7 ms of GPU time per frame against 9.1 ms for low poly (+39%, over npm run bench's four views with the clock pinned), a steady 3–4 ms in every view and still inside a 60 fps frame. The biggest single part is the brushstroke filter (about 1.5 ms). The horizon towers cost under 1 ms even when they fill the horizon: updateTowerSlices() in sky-uniforms.js draws their outline into a small texture when they change, and the sky reads it, instead of testing every puff shape per pixel, which cost 10–13 ms. The offscreen target isn't multisampled: antialiasing it cost about 3 ms. QUERY=style=anime npm run bench times the anime style.

How it's built:

• art-style.js reads the choice (ART_STYLE; ART_PAINTED for anime's look; ART_POST for a style with the post pass; ART_CLOUDS) and, for anime, patches three.js's shared lighting shader chunks once at load, so every lit material picks up the light and color changes without per-material code. It also wires the Settings select.
• createMaterial() (constants.js) turns off flat shading for the anime style; materials created with foliage: true get the leafy clumps (with their own shader cache key, since every createMaterial() hook shares one source text).
• ANIME_SKY (prepended to CLOUD_GLSL) and ANIME_TOWERS (TOWER_GLSL, shared by the sky and the moon so both agree where the towers are) switch the sky shaders; ANIME_TERRAIN and ANIME_WATER are added to the terrain and water shaders.
• renderFrame() (outline-pass.js) replaces the game loop's renderer.render(); it renders straight to the screen for the low-poly style and in VR. The pass's shader gets the style as a define (ANIME) for its own steps.

Dynamic performance scaling

In addition to static presets, the game includes a runtime DynamicPerformanceMonitor that continuously tracks a 30-frame rolling average frame time and smoothly adjusts multiple graphics subsystems in tandem.

It lowers rendering resolution and the per-frame chunk building budget. Prop distances (houses, barns, boats) stay at the graphics preset's value: shrinking them under load made houses visibly pop in close by.

Tiered scaling thresholds

Adjustments occur across four frame-time thresholds with a 30-frame hysteresis cooldown between adjustments:

Load state	Frame time threshold	Effective FPS	DRS resolution multiplier	Terrain chunk budget
Normal / recovery	≤ 17.50 ms	≥ 57 FPS	Recovers +0.05 (max 1.0×)	4.0 ms / frame
Slight overload	> 20.00 ms	< 50 FPS	Unchanged (1.0×)	3.0 ms / frame
Moderate overload	> 25.00 ms	< 40 FPS	−0.05 step (floor 0.8×)	2.0 ms / frame
Severe overload	> 33.33 ms	< 30 FPS	−0.10 step (floor 0.8×)	1.0 ms / frame

With ?adaptive=0 none of this happens: the preset's full quality holds however slow the frames. The promo renders use it, since their frames are stepped at a fixed 1/30 s, which would otherwise read as a slow game.

Subsystem behaviors

• Dynamic resolution scaling (DRS): Scales the WebGL renderer's pixelRatio relative to the graphics preset's base pixel ratio down to a floor of 80% under moderate or severe load (< 40 FPS). This directly reduces fragment shading load and screen-space overdraw while maintaining visual fidelity above native 1:1 screen resolution on high-DPI displays.
• Adaptive chunk budget: Terrain workers compute each chunk's heights, colors, and prop placements; the main thread then builds the chunk's meshes from that result within an adaptive per-frame time allowance (processChunkQueue in terrain-chunks.js). Under normal conditions, chunk building runs up to 4.0 ms per frame, dropping to 1.0 ms under severe load to eliminate stutter during flight. A chunk is generated entirely on the main thread only if workers are unavailable or its worker job failed.
  • Boot override: During the initial startup loading screen (isPaused && !isIntroTransitionActive), the chunk budget is temporarily boosted to 33.0 ms per frame so the initial world geometry generates almost instantaneously.
• Shadows and night culling:
  • The plane's shadow on water: Over land the plane casts into the sun's shadow map like everything else, so its shadow drapes over trees, roofs and hills. On water the few shadow-map texels across the plane broke into a flickering comb, so once its shadow is over water (the water at least 1 unit deep, handing back as soon as it reaches land, so a shadow skimming a beach doesn't flip back and forth) the plane stops casting and its silhouette is drawn on the water instead (plane-shadow.js): each frame the plane is rendered from the sun into a 256×256 texture, and a quad on the water projects it along the sun, so the shadow follows banking, pitch and rolls. Its blur grows with height like a real penumbra (1.6 units plus 1% of the distance to the water, matched to the shadow map's blur so the switch at the coast barely shows), it fades out about 1 km up, and it fades with the sun's share of the light, so it goes at night and under overcast. It's off with the rest of the shadows on the low preset.
  • Every frame: The sun's shadow map is redrawn every frame, even under load. Redrawing it only every few frames made the plane's shadow visibly step along behind the plane.
  • Night culling: The sun casts light and shadows only while it is at or above the horizon (sunLightFactor; before sunrise and after sunset its light goes to the sky light instead). Once it is down (sunLightFactor < 0.05), shadows are completely disabled (shadowCadence = 0, renderer.shadowMap.needsUpdate = false), saving the entire shadow pass when shadows are visually imperceptible.

Rendering optimizations

These keep draw calls, triangles, and per-frame work down; keep them in mind when adding new props or materials:

• Culled chunk props: Each chunk's instanced props (houses, rocks, boats, etc.) get a bounding sphere around their own instances, padded 160 units for boats drifting and smoke rising after the build, so three.js skips those outside the camera or shadow view. Pooled instanced meshes would otherwise keep stale automatic bounds, so these spheres are set when a chunk is built (enableChunkInstanceCulling in terrain-chunks.js). A sphere around the whole chunk let about half of these draws through.
• Tiled world-wide instances: Trees and other world-wide props are instanced per type in tiles of 4 × 4 chunks, so tiles outside the view (including everything behind the plane) aren't drawn (GlobalInstanceManager).
• Distant terrain ring: Beyond the draw distance, coarse terrain continues out to 27 km (far-terrain.js), so distant islands, coasts and mountain ranges show on the horizon. It uses the same generator as the near chunks (terrain-gen.js, on the terrain workers) with 9,000-unit cells on a ~333-unit grid and no props, about 40 draw calls. Far cells are only requested once the near chunk queue is empty, and they rebuild only when the plane enters a new cell. Inside the draw distance the ring sinks below the ground so the near chunks cover it (a vertex offset rather than a pixel discard, which keeps early depth rejection), and it fades into the shared sky color with distance. Sea areas are flattened and shaded as water reflecting the sky.
• Shadow coverage: The sun's 2048×2048 shadow map covers a 4,096-unit square that sits 1,400 units ahead of the plane along the camera's heading (SHADOW_LOOK_AHEAD in game-loop.js), so shadows reach about 3.5 km ahead. Shadows fade out over the outer 10% of the square (patched into three.js's shadow shader in sky.js), so they grow in gradually instead of popping in at its edge. The square moves in whole shadow texels, so shadows hold still as it follows the plane, and it turns with the sun in steps rather than every frame, which would redraw every shadow edge a fraction of a texel over and make them shimmer. The steps shrink as the sun gets low (from half a degree with the sun 45° or more up to a tenth near the horizon, updateShadowSnapping in game-loop.js), since low sun stretches shadows the most and a fixed step made long shadows visibly jump.
• Tree shadows near the plane only: The sun's shadow volume reaches about 4,500 units from the plane, so only trees within 4 chunks cast shadows, through shadow-only meshes that draw nothing on screen.
• Distant and shadow detail: Beyond 2 chunks (~3 km), rounded tree canopies, palm trunks, and cacti draw as simple shapes fitted to the original model's bounds, and bushes and snowmen aren't drawn. Bushes and rounded canopies also cast shadows with those simple shapes: the shadow map is 2 units per texel, so their detail doesn't show in shadows. Palm fronds cast with a version without their notches (216 triangles instead of 504), which keeps their star-shaped shadow. See and in .

URL parameters

The game supports various URL query parameters for deep linking to specific locations, times, or configurations. Combine parameters using standard URL query syntax (e.g., ?lat=1.0N&lon=0.5W&tod=0.25).

Location and orientation

• lat: Starting latitude (e.g., 1.0N, -1.0).
• long or lon: Starting longitude (e.g., 0.5W, 0.5).
• alt: Starting altitude in meters, as the altitude readout shows it (e.g., 200).
• heading: Starting compass heading in degrees (0 = North, 15 = a little west of north). Without it, the plane starts at 15 at spawn (so the Falls aren't dead ahead) and at 0 when the URL sets a position.
• pitch: Starting pitch angle in degrees.
• roll: Starting bank angle in degrees (positive banks left, negative right). It holds while the free camera freezes the plane; in flight the flight model takes over.
• speed: Starting flight speed multiplier (e.g., 1.0, 2.0, 0).
• plane or vehicle: Initial aircraft model (biplane, the default, the vintage biplane; seaplane, a monoplane on floats; twin; jet, a swept-wing fighter; or buggy, to drive). classic, the seaplane's old name, still works.
• buggy: 0 or false hides the buggy in the pause menu, on V and in plane.
• livery: Plane color for this visit (not saved): an index (0-7) or a name (coral, teal, sage, purple, slate, sand, rose, black).
• map: Load a specific pre-configured map location (e.g., long-island).

Environment and time

• tod: Time of day (value between 0.0 and 1.0, where 0 is midnight and 0.5 is solar noon).
• timeSpeed: Speed multiplier for the day/night cycle (set to 0 to lock the time of day).
• clock: The world clock, in milliseconds since 1970. It sets what follows the real date and time: the moon phase, the aurora, procedural weather and the day's sky palette. With timeSpeed=0 it stays put.
• cloudTime: How far the clouds have drifted, in seconds. Together with seed (the cloud pattern), clock and timeSpeed=0, a URL gives the same sky on every load.
• cloudMood: Force the day's cloud mood instead of the one seed and clock pick: fair, mixed, mackerel, high or busy (see the clouds description above).
• seed: Integer world seed for procedural terrain generation.
• continent: Force the continent's outline instead of letting the seed pick it: leaning, taper, crescent, lobes or boot.
• theme: The visual theme to load (e.g., standard).
• style: anime, or lowpoly for the low-poly look (low-poly and classic also work), overriding the art style chosen in Settings (see Art style).
• outline: With the anime style, set to 0 to turn off the ink outlines.
• brush, haze: With the anime style, set to 0 to turn off the brushstroke (Kuwahara) filter or the aerial-perspective haze, for comparing.
• fxaa: With the anime style, 1 or 0 turns FXAA edge smoothing on or off whatever the graphics preset (by default it's on for high and ultra only).

Camera and system

• camera: Start in a camera mode: follow (default), first-person, birds-eye or cinematic. The C key cycles them. birds-eye-close and birds-eye-far start the bird's eye view zoomed in or out.
• angle: With camera=cinematic, which of its preset angles (0-4: side-on, low from the front, front quarter, high above, wing tip).
• camOffset: A custom chase camera, x,y,z relative to the plane's heading (x to the right, y up, z behind; negative z is ahead, looking back). It follows the plane, so it works for stills and moving shots. camLook (x,y,z, same frame, default the plane) is the point it looks at and fov its field of view (default 65).
• headlight: Set to 1 to start with the headlight on.
• jobs: reset starts people and jobs over, as if you'd never met anyone (handy for reading their lines again).
• freecam or freeCamera: Set to true to start immediately in the free camera mode (bypassing cinematic intros). The plane holds still. Inherits starting location from lat, long/lon, and alt, or from x, y, and z.
• camX, camY, camZ, camHeading, camPitch: With freecam, place the free camera separately from the plane: the camera goes here and the plane where x/y/z (or lat/long/alt), heading, pitch and roll say, e.g. a plane frozen mid-bank in the rock arch, filmed from the beach. Any left out start at the plane. Without them, x/y/z, heading and pitch place the free camera.

Development

Prerequisites

Ensure you have Node.js installed.

Installation

Clone the repository and install the required dependencies:

npm install

Running locally

To launch the local development server with Hot Module Replacement (HMR):

npm run dev

Once started, open http://localhost:5173 in your browser.

[!NOTE] During development, game modules (e.g., game.js, airplane.js) are served unbundled, so console log line numbers match the source files.

Code structure

The game is made of ES modules in the repository root. src/main.js is the entry point for index.html: it imports every game module, in dependency order, and prints the startup banner. src/debug-models.js is a smaller entry point for the model debug page (debug/debug-models.html).

• Import what you use. Modules share code only through import/export, never through window globals. A module may only import modules listed before it in src/main.js, which keeps the dependency graph free of cycles.
• Shared mutable values live in state.js. ES modules can't reassign another module's exports, so values that more than one module writes (state.timeOfDay, state.isPaused, state.cameraMode, etc.) live on the single state object.
• Calls into later modules go through hooks.js. When an earlier module must call a function from a module that loads after it (for example, pausing the game from the native app-lifecycle handler), the later module registers it on hooks when it loads, and callers use hooks.togglePause?.().
• Network calls always have a deadline. Use fetchWithTimeout() / withTimeout() from network.js. On a network that drops packets (e.g. a subway), navigator.onLine is still true and an unbounded request can hang for minutes; the game treats "too slow" like "offline" (e.g. music falls back to the bundled track).
• Terrain generation runs in a web worker. The generation code (heights, colors, prop placement) lives in terrain-gen.js. terrain-worker.js is a thin module worker around it, created by terrain-worker-manager.js; Vite bundles it automatically. terrain-chunks.js builds each chunk's meshes from the result, and runs terrain-gen.js itself only as a fallback, so both paths produce the same world. A worker that doesn't answer a job within 10 seconds (for example, its script never finished loading on a bad network) is replaced, and that chunk is built on the main thread; if no worker ever answers, terrain generation moves to the main thread entirely.
• The map renders on its own workers. The fullscreen map is drawn from cached tiles (map-tiles.js) rendered by map-worker.js, a thin worker around map-render.js, which the map export page shares. The named places on the map and minimap, which are also the autopilot's tour stops, live in one list in landmarks.js.

Testing

npm test

Runs ESLint, syntax checks, procedural terrain invariant tests, HTML script reference checks, a check that no code reads a window property that nothing assigns, the module import-order check, and tests for the network timeout helpers, the fog model, the terrain worker pool (dead or failing workers, and custom maps reaching every worker), the day's cloud mood (scripts/test-cloud-moods.js), people and their jobs (scripts/test-jobs.js), flying together (scripts/test-multiplayer.js: the relay's rules, invite links and smoothing other planes through late, lost and bunched-up updates), and headless autopilot and flight simulation (scripts/test-sim.js: airport approach and departure clearance, runway touch-and-go rollout, ridge avoidance, orbit stability, stall recovery, and job reachability).

npm run test:browser

Loads the game and the debug pages in headless Chrome against the running dev server (npm run dev). After pressing start, it flies and drives the controls through the keyboard (throttle, steering, camera, weather, minimap, pause menu), checking their effects in the HUD and debug panel. It fails on any JavaScript error, failed request, or unresponsive control, and checks that the terrain workers reply. It also simulates a network where every third-party host drops every packet (e.g. a subway) and checks that the page still paints and starts, and that music falls back to the bundled track.

npm run test:build

Runs the same game checks against a production build written to a temporary directory (never docs/).

npm run test:road-landings

With npm run dev running, lands each plane on the highways (open road, a viaduct, the cross-country highway, a junction, across a road and at a highway end) and warps one away while parked. Fails on height jumps between frames, repeated bounces, or not coming to a stop on the wheels. PLANES=jet,biplane picks planes.

Screenshots and render benchmarks

With the dev server running, these open the game in headless Chrome with start=1&ui=0&music=0 (see URL parameters), wait until the terrain around the camera has loaded, and then work from there.

node scripts/shot.js out.jpg "x=0&y=413&z=0&heading=45&pitch=-4&tod=0.61"
node scripts/shot.js out.jpg "<view 1>" "<view 2>"   # out-1.jpg, out-2.jpg

Saves a screenshot of each view (the query takes the game's URL parameters; the free camera and a frozen time of day are the defaults). It prints any page errors and exits with an error if there were some, so it also catches shader compile errors. SIZE=1600x900, SCALE=1 and SETTLE_MS=4000 set the window size, pixel density and extra wait.

npm run bench [-- label]

Times full frames of four fixed views (grassland, sunset over the sea, mountains, forest) at the mid preset's resolution on a 1440x900 Retina screen, and prints the median GPU time per frame (from WebGL timer queries, the most precise number), the wall time per frame, the part spent in JavaScript, draw calls and triangles. VIEWS=land,sunset picks views, PRESET the graphics preset and QUERY adds URL parameters (e.g. QUERY=style=anime). The numbers drift by about half a millisecond over minutes, so to compare two versions, alternate runs of each.

Promotional screenshots and video

npm run promo:sheet [-- shot ...]     # small renders and a contact sheet, for scouting angles
npm run promo:stills [-- shot ...]    # each shot for each still target
npm run promo:view                    # open promo/index.html, a page for browsing the stills
npm run promo:artwork                 # single images: the YouTube thumbnail (1280x720) and the App Store header (3840x1646, a PNG: App Store Connect rejects a JPEG header) and search results asset (3840x2560)
npm run promo:video -- <target>       # the clips, then the edited video
npm run promo:urls [-- shot ...]      # a dev server link to each shot, to adjust it
STYLE=anime npm run promo:stills      # any of these in the anime art style, into promo/anime/

Renders the shots in scripts/promo-shots.js, each a set of URL parameters, so the chosen views live in source control. To change one, open its link from urls (the dev server, with the debug menu), adjust the view, copy it with the debug menu's copy URL button and paste the whole link as the shot's query; then re-run stills or video. A shot can add portrait parameters for portrait targets, such as another camera position. A clip can also fly scripted maneuvers with moves: keyframes of [seconds from the start of filming, roll in degrees (positive to the left), pitch in degrees (positive nose up)], eased between and held after the last. The flight model does the turning and climbing, and stills ignore moves. Shots from straight behind the plane use the game's chase camera with the interface on (ui=1), as players see it; the others each have their own angle (head-on, side-on, from above, from below, front quarters, high and wide). Every shot shares one world and clock but sets its own cloudMood, so the set shows the different skies (busy or mackerel skies for the sunrises and sunsets). TARGETS there sets the outputs: App Store screenshots for iPhone 6.9" (1320x2868) and 6.3" (1206x2622, the size App Store Connect requires) and iPad (2064x2752), the website (1920x1080) and social sharing (1200x630), and the videos: App Store previews for iPhone (886x1920) and iPad (1200x1600), which open straight on gameplay and end on the app icon, the name and the music credit ("Music by Purrple Cat"), and a 1920x1080 trailer for the website, YouTube and Google Play, which opens on the icon and name and ends with the music credit and the web address, with the game's version small in the lower right corner. The cards sit over a blurred, darkened frame of the clip next to them, so the video fades into them. Phone and tablet targets emulate a touch device, so shots with ui=1 show the touch controls. The video is the clips (shots with seconds, in list order) between the target's title and end cards, joined by crossfades, with the bundled Purrple Cat track faded in and out (MUSIC=file, or none for silence).

It builds the game into a temporary directory (never docs/), or uses GAME_URL (e.g. the dev server), and keeps the renders out of analytics. Output goes to promo/ (OUT=dir, ignored by git). stills also writes promo/index.html, a page for browsing the stills by device (iPhone, iPad, web, social) or by shot; npm run promo:view rewrites and opens it. The npm scripts run node scripts/promo.js <mode>. Every shot runs on a virtual clock: the page's requestAnimationFrame, performance.now and Date.now are replaced and the script steps the frames. While the scene loads and settles, frames pass almost no time, so a flying plane holds its starting position however slowly the frames render; then PREROLL seconds (1.5) play so the chase camera settles, and the still or clip starts. A shot can ask for a longer run-up with preroll, for things that build up slowly, like the aurora fading in. Clips advance exactly 1/30 s per frame. Every mode renders the low-poly look by default; STYLE=anime renders the same shots in the anime art style, into promo/anime/ (so the store gets each screenshot and video twice). Options: SHEET (the target the contact sheet shrinks, default web), STILLS (comma-separated still targets), SETTLE_MS (extra wait after the game loads, before a still or a clip, default 1000) and FPS (30). Needs ffmpeg (brew install ffmpeg) and Chrome, at its default macOS location or CHROME_PATH. Render on a Mac: Chrome uses the GPU through Metal there, while elsewhere WebGL runs in software and a video takes hours:

npm run promo:video -- iphone-preview
npm run promo:stills

Model debug page

Debug pages live in debug/ and are available only during development (they aren't part of the production build). Start at http://localhost:5173/debug/debug.html, which links to standalone viewers like the model viewer (/debug/debug-models.html) and the face viewer (/debug/debug-faces.html, everyone's face and outfits in faces.js still or talking, or as a silhouette; #ray links to one; tapping a person opens their dedicated dialog viewer at /debug/debug-person.html?person=name to inspect and test all their dialog variants and job offers). These pages allow you to inspect and preview in-game geometries and structures in isolation, making it easy to tweak vertices, test materials, and verify rotations before adding them to the procedural world.

The map export page (/debug/debug-export-map.html) renders any area of the world, picked by centre lat/long and size in degrees, in the in-game map's colours or as a grayscale heightmap, and downloads it as a PNG. Whole world renders everything out to the open ocean (44° by 24°) in a couple of seconds. URL parameters prefill the form: seed, continent, lat, long, w, h (degrees), upp (units per pixel), mode=gray, grid=0, and run=1 to render on load.

Production build

To optimize, minify, and bundle the entire codebase for deployment:

npm run build

This builds the optimized code into the docs/ folder (which is deployed to Cloudflare Pages):

• Game modules and third-party dependencies (three, @sentry/browser) are bundled and minified. The debug pages are dev-only and aren't included.
• The terrain web worker is bundled into its own file.

Previewing production build

Since the development server (npm run dev) serves files dynamically from source, relative asset paths (like those requested by query parameters) will not resolve correctly when navigating directly to folders inside the dev environment.

To test the actual, fully-bundled production build locally exactly as it will run in production:

npm run preview

Once started, open http://localhost:4173 in your browser. This spins up a lightweight server hosting your compiled docs/ directory. You can test production features and parameters (such as http://localhost:4173/?map=long-island) flawlessly!

Preview builds

Every push to main runs the Deploy preview GitHub Actions workflow (.github/workflows/preview.yml). It runs npm test, builds the game without minification and with source maps, and deploys it to preview.chill-flight.pages.dev. The build goes to dist/, so docs/ and the production site are untouched.

Preview builds are labeled with the next patch version and a -preview suffix (e.g., 0.9.44-preview), and their Sentry errors are reported under the preview environment. The workflow can also be run by hand from the Actions tab.

Version management

The application's version number is managed using a single-source-of-truth system centered around package.json.

To release a new production version:

• Release builds (npm run release): Running this command automatically bumps the patch version of the application (e.g., 0.8.7 -> 0.8.8), builds the optimized frontend assets, and packages them inside docs/ in a single step!
• Commit, tag, and deploy (npm run release:tag): After compiling and generating release notes in RELEASE_NOTES.md, the release bundle is committed as Release vX.Y.Z. Running npm run release:tag tags the commit, deploys the web release to Cloudflare Pages and itch.io (via Butler), builds and publishes Android to Google Play, builds and delivers iOS to App Store Connect / TestFlight, pushes the commit and tags to GitHub, and outputs a formatted summary with release notes and App Store Connect links for final submission. Use --skip-mobile or --web-only to skip mobile builds, and --skip-itch to skip the itch.io upload.

For local development compiles, standard compilation is done via npm run build, which compiles the assets without modifying any version numbers.

If you need to manually perform a custom version bump (e.g., for major or minor releases):

1. Automated CLI: Run the standard npm command to bump the version without creating git tags:

   npm version <new-version> --no-git-tag-version
   

   (e.g., npm version 0.9.0 --no-git-tag-version) This automatically updates both package.json and package-lock.json.

2. Manual Update: Alternatively, you can directly edit the "version" field in package.json. The next time you run any package operation, npm will automatically keep package-lock.json in sync.

When a build is run, the bundler reads the version and injects it dynamically into the in-game UI. The desktop build (Tauri) is also linked and will update automatically.

Native mobile app development (Capacitor)

This project uses Capacitor to build fully native apps for iOS and Android.

Sync and run iOS app

To sync the latest web assets with the iOS project and open Xcode:

npm run ios

Build and upload iOS app

To sync web assets, compile, archive, export a signed .ipa, and upload directly to App Store Connect / TestFlight:

npm run ios:build

App Store Connect API credentials can be placed in ios/appstore.properties (see ios/appstore.properties.example for details). If credentials are not configured, the script exports the signed .ipa and opens the archive in Xcode Organizer for manual one-click distribution.

Sync and run Android app

To sync the latest web assets with the Android project and open Android Studio:

npm run android

Build and publish Android release bundle

To sync web assets, compile, sign with your keystore, and export a release Android App Bundle (.aab):

npm run android:build

Signing credentials and optional Google Play API credentials can be placed in android/keystore.properties (see android/keystore.properties.example for details). When a Google Play service account JSON key is provided (at android/play-service-account.json or referenced in properties), the script automatically publishes the bundle directly to Google Play Console. If not configured, the signed bundle is exported to android/app/release/app-release.aab for manual upload.

Desktop app development (Tauri)

This project uses Tauri to build lightweight, native desktop apps for macOS, Windows, and Linux.

Run desktop app in development

To run the application locally in a native desktop window with hot-reloading:

npx tauri dev

Build desktop app for production

To package and compile the production desktop application:

npm run build && npx tauri build

This compiles the web assets into docs/ and triggers the Rust compiler to bundle them into a native desktop installer.

itch.io web package and deployment

To package the game as an HTML5 web build ready for upload to itch.io:

npm run build:itch

This compiles the web client into an isolated temporary directory (keeping docs/ untouched) and creates dist/chill-flight-itch.zip with index.html at the root of the archive, formatted to itch.io's HTML5 upload requirements.

To upload the build directly to itch.io via the butler CLI:

npm run deploy:itch

This uses butler push to deliver the build to cowneck/chill-flight:html5 tagged with the current version. The deployment is also run automatically during production releases (npm run release:tag). Use --skip-itch to skip the itch.io upload step during release. Requires butler to be authenticated (butler login or setting BUTLER_API_KEY).

Multiplayer relay (Cloudflare Worker)

The multiplayer relay is a Cloudflare Worker with Durable Objects that runs separately from the web client.

Run relay locally

npm run relay:dev

Deploy relay to Cloudflare

npm run relay:deploy

See relay/README.md for architecture details, allowed origins, and configuration.