tera/CONTRIBUTING.md

# Contributing to Tera

Thanks for wanting to. Two sections matter before any others — the inbound
grant, because it is what keeps this repo's licensing claims true, and the four
hard rules, because a change that breaks one of them cannot be merged no matter
how good it is.

---

## The inbound grant

**By submitting a contribution to this repository — a pull request, a patch, a
commit, or a suggested change in any form — you agree to the following, and the
act of submitting it is the agreement. There is nothing extra to sign.**

1. You license your contribution under the **Apache License, Version 2.0**, on
   the terms in [LICENSE](LICENSE).

2. **For any change under `src/assets/`**, you *additionally* dedicate the
   **artistic output** of that contribution — the meshes, geometry, textures,
   materials, palettes and images it produces — to the public domain under
   **CC0 1.0**, on the terms in [`src/assets/LICENSE-ART`](src/assets/LICENSE-ART).
   Where a dedication is not possible under the law that applies to you, you
   grant the equivalent unconditional licence described in that file.

3. You certify that the contribution is your own work, or that you have the
   right to submit it under these terms; that you are not knowingly including
   anyone else's copyrighted material, trademark, or data carrying obligations
   this repository cannot meet (see the hard rules below); and that you
   understand the contribution and this record of it are public and permanent.

If your employer has rights in your work, get their sign-off before you submit.
If you cannot make all three certifications for some part of a change, say so in
the pull request and it will be sorted out before merge rather than after.

### Why this is standing rather than per-PR

Apache 2.0 §5 supplies a default inbound=outbound grant, so contributions arrive
Apache-2.0 whether or not anyone says so. **There is no equivalent default for
CC0.** A single merged pull request under `src/assets/` whose author never said
the words would leave that contribution Apache-only, which would make
`LICENSE-ART`'s dedication false for part of the library — and copyright cannot
be taken back afterwards, so it would also be unfixable. Stating the grant here
and treating submission as acceptance is what stops that from being possible.

The reasoning is recorded in [CONTRACT.md](CONTRACT.md) §3.1, and the carve-out
is in [NOTICE](NOTICE), which is what a downstream consumer actually reads to
learn this repo is not uniformly Apache-2.0.

---

## The four hard rules

These are licensing and privacy constraints, not preferences. Each has its full
reasoning in [ARCHITECTURE.md](ARCHITECTURE.md) §3 or [CONTRACT.md](CONTRACT.md).

**1. No binary art in `src/**`, ever.** No textures, no glTF, no logos, no
fonts, no images. Every mesh is a function composing cached unit primitives and
every texture is drawn on a 2D canvas from seeded noise. This is what gives the
repo zero asset-licensing exposure, and it is worth more than the quality
ceiling it costs.

CI enforces this by enumerating tracked files with `git ls-files`, never by
walking the working tree — so your own legally-clean `.glb` sitting in
`public/props/` is invisible to the check and cannot fail your build. Those
directories (`public/props/`, `public/kits/`, `public/offices/`, `docs/`) are
self-hoster space and are git-ignored on purpose.

**2. No OpenStreetMap-derived coordinates.** OSM and Nominatim output is ODbL,
whose share-alike terms cannot be reconciled with Apache 2.0. Note that keeping
such rows out of the repo does *not* discharge the obligation — serving a
snapshot of them publicly is Public Use of a Derivative Database either way. The
sanctioned geocoder is the US Census Geocoder (`geocoding.geo.census.gov`), a US
Government work in the public domain. Google, Mapbox and HERE do not solve this
either; their terms restrict storing and redistributing what they return.
Geography in `src/cities/` is traced by hand.

**3. No trademarks.** Organisation logos are fetched at runtime by the
consuming application and are never committed here.

**4. The engine takes no position on what data means.** `markers.ts` renders
`Marker[]` with an opaque `colorKey`; `src/assets/` renders a `SurfaceRole` and
an opaque colour key one level in. Neither will ever learn that a marker is a
company, that a status maps to a colour, or that a seat has a person in it.
That is what lets one engine serve a private map and a public one without either
being a fork — and, for interiors, what lets the office geometry be open-source
while who is sitting in `eng-04` stays private data behind an API.

Everything must work with **no account, no Supabase project, no API key and no
network**. That is the acceptance test, and CI runs it: `docker compose up`
under `env -i`, asserting `GET /api/v1/health` returns 200.

---

## Contributing an asset

Assets live in `src/assets/` and are procedural TypeScript. The pieces:

| file | what it holds |
| --- | --- |
| `kit.ts` | `AssetId`, `AssetDef`, the registry, `createAssetContext` |
| `materials.ts` | `MaterialRegistry`, keyed on the closed `SurfaceRole` union |
| `palette.ts` | the interior palette, derived from the city's by declared HSL shifts |
| `parts.ts` | the shared cached unit-primitive bin, and `MeshBin` |
| `textures.ts` | every texture, drawn with Canvas2D and seeded noise |

Conventions, in order of how often they are got wrong:

- **Metres. 1 unit = 1 m.** The city is not on this scale and cannot be; that is
  why an office gets its own `THREE.Scene`.
- **Build out of `parts`, not out of fresh geometry.** Every unit part is 1 m in
  each dimension with its base on `y = 0`, and assets place them with scaled
  local matrices. This is what keeps a 1,200-object office at about thirty draw
  calls, and it is also what makes independently-written assets look like one
  library rather than eighteen dialects.
- **Ask for a `SurfaceRole`, never a colour.** Roles are named after the object
  (`deskSurface`, `partitionFabric`), never after the finish. If you need a role
  that does not exist, add it in three places — the union in `materials.ts`, its
  spec below it, and its shift in `ROLE_SHIFTS` — and the compiler will not let
  you forget the third.
- **Namespace built-ins `tera:`.** Your own assets get your own namespace, and
  `overrides: "tera:desk.workstation"` reskins the reference office without
  forking it. That mechanism is the point; use it rather than editing built-ins.
- **`footprint()` must not build anything.** Layout asks how big things are far
  more often than it asks for their geometry.
- **Determinism.** Any randomness comes from `ctx.rand`, seeded per instance. A
  world that reshuffles itself between visits is a lava lamp, not a place.
- **Nothing throws.** An unregistered id draws a placeholder box; an unknown
  surface id falls back to a role. A pack with one typo in it should still open.

Doors and windows are `Opening` records punched out of a wall, not assets. There
is deliberately no `tera:shell.door` — see `interiors/types.ts`.

---

## Contributing a city

Write `src/cities/<id>.ts` exporting a `City`: coastline and parks traced by
hand, hills as radial peaks, a street bearing per district. A city pack is pure
data, which is what makes it reviewable. Rule 2 above applies with no exceptions.

---

## House style

- **Comments explain *why*, not *what*.** The line below a comment already says
  what it does. What it cannot say is that an earlier version rejection-sampled
  buildings uniformly and looked like rubble, or that four comparisons took the
  terrain build from 2.3 s to 1.0 s. Write those down; they are the expensive
  part. Read two or three existing files before you write your first one.
- Prose comments, full sentences. Section headers are `// ---- Name ----`, and
  that is the only decoration in the repo.
- Strict TypeScript with `noUncheckedIndexedAccess`, `noUnusedLocals`,
  `noUnusedParameters` and `verbatimModuleSyntax`. Index access needs a
  null-check or a `?? fallback`, type-only imports say `import type`, and
  relative imports carry the `.ts` extension.
- No new runtime dependency without a reason in the pull request. The dependency
  check is an allowlist that names why each one is permitted, not a count.

## Running it

```bash
npm install
npm run dev        # the demo app
npm run typecheck  # tsc --noEmit
npm run build      # typecheck, then vite build
```

The two CI jobs that gate the repo are `git clone && npm ci && npm run build`,
and the zero-config `docker compose up` health check described above. If a
change makes either of those need a key, an account or a network call, it is the
change that is wrong.