# Tera

The map view of **Lumbridge Simulate** — cities from above, in three.js.
Its other half, **Spaces**, is the offices you walk into: one engine and one
asset library, seen from outside and from inside.

Apache 2.0. Runs at [tera.lumbridgecorp.com](https://tera.lumbridgecorp.com).

![San Francisco](docs/sf.jpg)

---

## What it is

An engine plus data packs. The engine renders terrain, coastline, a built city
on real street grids, bridges, roads, markers and air traffic. A *city pack* is
pure data — coastlines, hills, districts, landmarks, camera chapters — so adding
a city is a data contribution anyone can review, not a fork.

San Francisco ships today. Los Angeles / Orange County / Riverside is next; New
York after that.

A **plan view** sits top right: the board drawn flat, with the footprint of the
camera's own frustum on it, so you can see where you are looking from outside
the shot. Click or drag it to move the camera; scroll it to dolly. It is a 2D
canvas rather than a second WebGL context, drawn from the same city pack, and it
follows the sun into the night along with everything else.

## Who sees what

Three tiers, resolved once at boot by `src/access.ts`:

| | anonymous | signed in | admin |
|---|---|---|---|
| the map, the plan view, the named chapters | ✅ | ✅ | ✅ |
| the office | public depth — shell, furniture, viewpoints, nobody home | full depth, with presence | full depth |
| live markers and live traffic | — | ✅ | ✅ |
| the godmode panel (`G`) — clock, weather override, counters | — | — | ✅ |

**These are drawing decisions, not a security boundary**, and `src/access.ts`
says so at length. Live data and office presence are withheld by the *API*, from
a caller it does not recognise; the client tier stops the app asking for
something it will not get. Admin is granted only by `TERA_ADMIN_SUBJECTS` on the
server — never inferred in the browser, and never from an API that failed to
answer. A deployment with no API at all is open, because "clone it and it works"
is the promise; it is not "clone it and you are an administrator".

## Quick start

```bash
npm install
npm run dev
```

## Using the engine

```ts
import { createScene } from "@lumbridge/tera/engine/scene.ts";
import { createStage } from "@lumbridge/tera/engine/stage.ts";
import SAN_FRANCISCO from "@lumbridge/tera/cities/sf.ts";

// One stage per canvas, for the life of the page. Cities are put on it and
// taken off again; a renderer per city leaks its shadow map on every switch.
const stage = createStage(canvas);

const scene = await createScene(stage, {
  city: SAN_FRANCISCO,
  markerPalette: { hiring: 0x4ade80, closed: 0xef4444 },
});

scene?.setMarkers([
  { id: "1", lat: 37.7765, lng: -122.4241, label: "Somewhere", colorKey: "hiring" },
]);
```

`createScene` is async because the heightfield is built in a Worker — half a
million samples, about 730 ms on the Bay Area, and not on the main thread. It
resolves to `null` if the build was abandoned through `options.signal`, which is
what makes switching city mid-build cheap.

The engine renders `Marker[]` and looks colours up by `colorKey` in a palette
you supply. It does not know what your markers *mean* — that mapping lives in
your adapter. This is what lets one renderer serve a private map coloured by
one scheme and a public map coloured by another, without either being a fork.

## Adding a city

Write `src/cities/<id>.ts` exporting a `City`. Trace the coastline and parks by
hand, place hills as radial peaks, and give each district its street bearing.

Two rules, and they are not stylistic:

- **Do not import geometry from OpenStreetMap.** OSM and Nominatim output is
  ODbL — share-alike, and incompatible with this repo's licence.
- **Do not commit logos or brand assets.** They are trademarks, not code.

See [ARCHITECTURE.md](ARCHITECTURE.md) §3 for the full reasoning, and
[NOTICE](NOTICE) for the attribution and data-provenance statement.

## Aircraft

The engine takes a `FlightSource`. Two ship here: `SimulatedFlights` (original,
flies real approach and departure corridors) and `AdsbFlights` (open community
ADS-B feeds such as adsb.lol).

FlightRadar24 is deliberately absent — their terms forbid scraping and forbid
redistributing their data, so a client for it cannot live in an Apache-2.0
repository. Commercial sources belong in private deployments. The best long-term
answer is an RTL-SDR receiver: first-party data with nothing to comply with.

## Layout

```
src/engine/    renderer — terrain, blocks, structures, markers, flights, scene, minimap
src/cities/    data packs — pure geography, no code
src/adapters/  where outside data plugs in
src/tools/     instruments — god-only, dynamically imported, never statically
```

`engine` never imports `cities`; neither imports `adapters`.

Nothing under `src/tools/` may be reached by a static import from the app. It is
loaded by one `await import()` behind `access.can.debug`, so a visitor who is
not an admin does not download the code at all — which is the strongest
available reading of "nothing here runs for a non-god visitor": not a hidden
panel, not a disabled panel, no panel. `src/tools/index.ts` states the rule and
what silently undoes it.

## Licence

Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).