# Everything Is a Mod

**Canonical host:** https://modtrick.com (Cloudflare: https://modtrick.pages.dev)  
**Audience:** game hosts, three.js apps, and **all code-build agents** (Grok Build, Claude Code, Codex, Cursor, and peers).  
**Splash:** [/](https://modtrick.com/) · **Docs hub:** [/docs/](https://modtrick.com/docs/) · **Proof:** [/game/outpost/](https://modtrick.com/game/outpost/)

This is the fixed architecture of ModTrick. Do not invent a parallel plugin system.

> **One-liner:** If it ships in the game, it is a mod. If it is a mod, it has ASEC.  
> If it has ASEC, ModRuntime can load it. If ModRuntime can load it, this site can teach it.

---

## 1. Thesis

A **mod** is the only first-class extension unit.

| Not a mod | Is a mod |
|-----------|----------|
| Ad-hoc paste of a shader | Packaged entry + `mod.json` contract |
| “Just a utility script” | Declares META assumptions + MGS lifecycle |
| Hard-coded feature flag soup | GENESIS create API + SHADOW residuals |
| Asset dump with no host API | Host loads via ModRuntime |

**Everything** that changes runtime behavior is a mod:

- Rendering (ocean, sky, post-FX)
- Content (meshes, packs, levels)
- Systems (AI, economy, input)
- UI shells, audio, networking adapters
- Tooling that injects into the game loop

If it is not a mod, promote it: add `mod.json`, an entry export, and register it with the host.

---

## 2. ASEC layer contract (required on every mod)

Every mod ships **META / GENESIS / SHADOW / MGS** (ASEC). Layers do not commute blindly on MGS; they do on pure META/SHADOW reads.

### META — contracts

- **assumptions** — what the host must already provide (`THREE`, sun vector, clock…)
- **provides** — what the mod exports (mesh, lights, `update`, events)
- **contracts** — coordinate system, units, frame semantics

### GENESIS — create

- Scaffold / factory: `createX(host, options) → ModHandle`
- One-line minimal install example that actually matches the API

### SHADOW — honesty

- Residuals (approximations, missing GPU paths)
- Failure modes (missing deps, silent white-out foam, etc.)
- Never claim “complete” when residual remains

### MGS — lifecycle (ordered)

1. **install** — place files, register with host  
2. **tune** — parameters that matter  
3. **verify** — observable pass criteria  
4. **maintain** — per-frame / dispose / hot-reload  

MGS steps are ordering-sensitive. Do not “tune before install” or “dispose mid-update” without a new trace.

---

## 3. `mod.json` shape (normative)

```json
{
  "id": "kebab-case-unique",
  "name": "Human Title",
  "version": "1.0.0",
  "engine": "threejs",
  "engines": [">=0.160.0"],
  "entry": "./entry-mod.js",
  "export": "createThing",
  "description": "one line",
  "asec": {
    "meta": {
      "assumptions": [],
      "provides": [],
      "contracts": {}
    },
    "genesis": {
      "scaffold": "import { createThing } from './entry-mod.js'",
      "minimal": "const m = createThing(host).addTo(host.scene);"
    },
    "shadow": {
      "residuals": [],
      "failureModes": []
    },
    "mgs": {
      "install": "...",
      "tune": [],
      "verify": "...",
      "maintain": "..."
    }
  },
  "features": [],
  "license": "MIT"
}
```

Host games **must** prefer reading `mod.json` over guessing exports.

---

## 4. Host architecture (game = mod runtime)

```
┌─────────────────────────────────────────────┐
│  Game / App                                  │
│  ┌─────────────┐  ┌──────────────────────┐  │
│  │ Clock/Input │  │ Scene / World State  │  │
│  └──────┬──────┘  └──────────┬───────────┘  │
│         │                    │               │
│  ┌──────▼────────────────────▼───────────┐  │
│  │           ModRuntime                    │  │
│  │  load(manifest) → mount → tick → dispose│  │
│  └──────┬──────────┬──────────┬────────────┘  │
│         │          │          │               │
│    ┌────▼──┐  ┌────▼──┐  ┌───▼────┐          │
│    │ ocean │  │  sky  │  │  …N   │  mods     │
│    └───────┘  └───────┘  └────────┘          │
└─────────────────────────────────────────────┘
              ▲ fetch catalog / packages
              │
     https://modtrick.com  (registry + demos + docs)
```

### ModRuntime duties

1. **Discover** — local `mods/**/mod.json` and/or catalog API from modtrick.com  
2. **Validate** — engine version, required assumptions  
3. **Genesis** — dynamic `import(entry)`, call named `export`  
4. **Wire** — `addTo(scene)`, register on tick list  
5. **Couple** — publish bus: e.g. sky → `sunDirection` → ocean  
6. **SHADOW log** — surface residuals to console/dev overlay once  
7. **MGS maintain** — ordered `update(dt)` / `dispose()`  

Reference host: `/host/mod-runtime.js` in this repo.

### Coupling rule

Mods **do not** deep-import each other by path when avoidable.  
They couple through **host-provided contracts** (shared vectors, event bus, frame context):

```js
const ctx = {
  time, dt, camera, scene, renderer,
  bus: { sunDir, sunColor, fogHints },
};
sky.update(dt);
sky.getSunDirection(ctx.bus.sunDir);
ocean.update(ctx.time, ctx.bus.sunDir, sky.getSunColor(), camera, sky.getSkyHints());
```

---

## 5. How the site teaches the game

| Site surface | Host/agent use |
|--------------|----------------|
| `/` catalog | Human browse |
| `/assets/`, `/packs/` | Discover modules by pack |
| `/mods/<id>/` | Live demo = acceptance test |
| `/mods/<id>/mod.json` | Machine contract |
| `/mods/<id>/*-mod.js` | Entry source / download |
| `/docs/EVERYTHING-IS-A-MOD.md` | Architecture law |
| `/docs/agents/` | Agent bootstrap |
| `/agents/bootstrap.json` | Machine operant (install + steps) |
| `/llms.txt` | Agent discovery index |

**Teach loop for a game project:**

1. Agent/human opens modtrick.com (or bootstrap.json).  
2. Pick mods by engine (`threejs` first).  
3. Copy or vend `mod.json` + entry into `game/mods/<id>/`.  
4. Host registers mods in ModRuntime.  
5. Run demo verify criteria from MGS.verify.  
6. Ship; residuals stay named in SHADOW.

---

## 6. Agent law (all harnesses)

When building or extending a game against ModTrick:

1. **Read first:** `https://modtrick.com/agents/bootstrap.json` then this doc.  
2. **Never** dump raw shader code into the app root without a mod package.  
3. **Always** add or update `mod.json` ASEC when creating features.  
4. **Prefer** existing catalog mods over reimplementation.  
5. **Disclose** SHADOW residuals; do not upgrade “approx” to “physically complete” silently.  
6. **Order** MGS: install → tune → verify → maintain.  
7. **Couple** via host bus, not private cross-imports, unless the pack is co-versioned.  
8. **Domain:** prefer **modtrick.com**; fallback **modtrick.pages.dev** if DNS lag.

---

## 7. Tarski residuals (named)

- Not every engine adapter exists yet (three.js first; Unity/Godot/Unreal are future packs).  
- Catalog “GLB” rows may be metadata placeholders until binary assets ship.  
- Lifetime/checkout is founder-stage; free modules are the decidable path today.  
- Full GPU IFFT / full volume cloud raymarch remain SHADOW on current free shader mods.

These residuals are **not** excuses to skip the mod architecture.

---

## 8. One-liner

> **If it ships in the game, it is a mod. If it is a mod, it has ASEC. If it has ASEC, the host can load it. If the host can load it, modtrick.com can teach it.**