# LAMA — one world, built by everyone

You are welcome here. Players, developers, artists, and AI agents all build the same
game, in the same repository, through the same front door: **a module**.

## Why modules

The game is a plain `<script>` three.js r128 build — no bundler, no npm, no CDN, no
build step. That is not nostalgia, it is what makes contribution possible: **you can add
to this world with a text editor and a browser.** No toolchain to install, no build to
wait for, no framework to learn first.

The upgrade work on this island was itself done this way. Nine modules were added, each
by a different author, each owning one file and touching nothing else:

| module | what it adds |
|---|---|
| `js/sky.js` | single-scattering sky, two cloud layers, sun disc, real aerial haze |
| `js/water.js` | Gerstner waves, Fresnel reflection, depth colour, shoreline foam |
| `js/terrain.js` | world-space UV ground with procedural albedo + normal |
| `js/vegetation.js` | six instanced species, per-instance tint, vertex-shader wind |
| `js/lighting.js` | PCFSoft sun shadows, frustum refit on the player, contact shadows |
| `js/carmat.js` | clearcoat car paint, flake, real glass, brakes, tyres |
| `js/particles.js` | exhaust, per-wheel surface debris |
| `js/bloom.js` | threshold bloom with a per-eye-correct stereo path |
| `js/grade.js` | filmic tone curve + photographic grade |

They coexist because they follow one rule: **one author, one file.** No module edits
another's file. When a module needs something from another, it asks at runtime and
degrades gracefully if the answer is no.

## The module contract

Create `js/mymodule.js`. It must be a classic script (no `import`), and it must expose
exactly one global. **Use `var`, or assign `window.MYMOD` explicitly** — a top-level
`const` in a classic script is script-scoped and does *not* become a window property.
That single mistake once made the entire effects layer of this game invisible, because
`if (window.FX)` was false forever.

```js
/* js/mymodule.js — a LAMA module.
 * Author: your name            License: CC0 / MIT / whatever you like
 */
var MYMOD = (function () {
  'use strict';

  var S = { scene: null, renderer: null, ready: false, quality: 2 };

  /** Called once by the engine. Everything is optional — implement what you need. */
  function init(scene, renderer, world, opts) {
    S.scene = scene; S.renderer = renderer; S.quality = (opts && opts.quality) || 2;
    S.ready = true;
  }

  /** Once per frame. dt is seconds; camera is the left eye (the right eye follows). */
  function update(dt, camera, world) { if (!S.ready) return; }

  /** Quality tier changed at runtime: 0 low, 1 medium, 2 high. */
  function setQuality(q) { S.quality = q | 0; }

  /** Called when the scene is torn down. Release GPU resources here. */
  function dispose() { S.ready = false; }

  return { init: init, update: update, setQuality: setQuality, dispose: dispose,
           name: 'My Module', author: 'you', version: '1.0.0' };
})();
if (typeof window !== 'undefined') window.MYMOD = MYMOD;   // makes the guard work
```

Register it in `index.html` before `js/game.js`:

```html
<script src="js/mymodule.js"></script>
```

That is the whole integration. `tools/autodeploy.sh` picks the file up automatically —
add it to `JS_FILES` and it is live within 30 seconds, versioned, with a visible
changelog entry.

## The rules that keep one world from becoming nine

These are not style preferences. Each one exists because breaking it broke the game:

1. **One author, one file.** Never edit another module's file. Need a change there?
   Report it; the integrator applies it.
2. **Never assume another module loaded.** Guard with `typeof X !== 'undefined'` and do
   nothing if it is absent. A 404 script tag is silent.
3. **No new dependencies.** No npm, no CDN, no bundler. If it cannot be done with the
   standard library and three.js r128, it cannot be done here.
4. **No asset files.** Generate procedurally — `DataTexture`, shader maths, geometry.
   The game must work with the network off, and it must stay small enough for a phone.
5. **60 fps in stereo is the budget.** Every visual effect is paid twice. Declare a
   quality tier for anything expensive and gate it.
6. **No per-frame allocation.** Pool your objects. A phone notices.
7. **Stereo and the mirror are sacred.** The game renders two eyes with scissor halves
   plus a rear-view mirror render target. Anything that draws a full-screen pass must
   respect the current viewport and scissor, or it will corrupt one eye.
8. **Never claim it works without measuring it.** Software-GL frames are a correctness
   gate, never a performance gate. Say what you could not verify.

## What we ask of a contribution

A module is accepted when it comes with **one runnable check** that fails loudly when the
module breaks — `tools/check-mymodule.mjs`, exiting non-zero. Not a test framework, not a
suite: one file, runnable with `node tools/check-mymodule.mjs`, that proves the thing
works and proves it *can* fail. A check that cannot fail is decoration.

Include in your report, in the file header or the pull request:

- what is now visibly better, in one sentence
- the exact numbers your check printed
- **what you could not verify.** This is the most valuable line. Every module in the
  table above shipped with an honest list of gaps, and that honesty is why the rest of
  its claims could be trusted.

## How to run it

```bash
python3 serve.py                 # https + http on the LAN, needed for iOS deviceorientation
node tools/check-<module>.mjs    # your check
sh tools/autodeploy.sh --once     # build the deploy, verify, publish
```

## For agents

If you are an AI agent working in this repository, the same contract applies, plus two
rules of your own:

- **Read `docs/COMMUNITY.md` (this file) and `babylon/docs/SWARM.md` before touching
  anything.** They define who owns which file.
- **Report gaps rather than hiding them.** An agent that says "I could not verify the
  phone cost" is worth more than one that claims success it did not measure.

## The world we are building

One island. Players drive, walk, swim, race and explore it. Developers add modules that
make it richer. Agents build and verify those modules. Everyone shares one live URL, one
version number, and one visible changelog — so a contribution is visible to every player
within thirty seconds of landing.

The door is open. Add a file.