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.

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. 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 §3.1, and the carve-out is in 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 §3 or 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

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.