Karti Tripathi
67f8df8d53
LSE is the third of the three, beside lumbridge-compute and lumbridge-bench: a 3D engine for walkable places. This first commit is the outside of the world — San Francisco — plus the seams the inside will attach to. The engine renders a City and a list of Markers and knows nothing else. It does not know markers are usually companies and it will never learn that "rejected" is red; that mapping lives in an adapter. Which is what lets one renderer serve a private map, a public one, and a self-hoster with no Lumbridge account, none of them a fork of the others. Three things were designed around the licence rather than discovered after it, because each one is a promise Apache 2.0 makes that is easy to break by accident. No trademarks in the repo — logos are fetched at runtime, and public/logos/ is gitignored. No OpenStreetMap-derived coordinates, which is why every coastline in cities/sf.ts was traced by hand: Nominatim output is ODbL, share-alike, and would attach to the whole pack. And no FlightRadar24 client — their terms forbid scraping and redistribution, so flights are an interface with a simulator and open community ADS-B behind it. The privacy constraint and the licence constraint turned out to want the same thing. Geocoded company positions and pipeline status both stay behind Workie's API; the open repo holds the city and the renderer. The tempting shortcut — commit an sf-companies.json — breaks both at once. Ported out of Workie, where a 3D city engine had no business living. Workie's /live is deleted rather than deprecated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
88 lines
2.8 KiB
Markdown
88 lines
2.8 KiB
Markdown
# Lumbridge Simulate Engine
|
|
|
|
**Lumbridge Simulate** — a 3D engine for walkable places. Cities from above,
|
|
buildings from inside, one renderer and one asset library.
|
|
|
|
Apache 2.0. Runs at [lumbridgecorp.com/live](https://lumbridgecorp.com/live).
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Using the engine
|
|
|
|
```ts
|
|
import { createScene } from "@lumbridge/simulate/engine/scene.ts";
|
|
import SAN_FRANCISCO from "@lumbridge/simulate/cities/sf.ts";
|
|
|
|
const scene = createScene(canvas, {
|
|
city: SAN_FRANCISCO,
|
|
markerPalette: { hiring: 0x4ade80, closed: 0xef4444 },
|
|
});
|
|
|
|
scene.setMarkers([
|
|
{ id: "1", lat: 37.7765, lng: -122.4241, label: "Somewhere", colorKey: "hiring" },
|
|
]);
|
|
```
|
|
|
|
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
|
|
src/cities/ data packs — pure geography, no code
|
|
src/adapters/ where outside data plugs in
|
|
```
|
|
|
|
`engine` never imports `cities`; neither imports `adapters`.
|
|
|
|
## Licence
|
|
|
|
Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
|