# How to build a ModTrick mod

**Site:** https://modtrick.com · **Law:** [EVERYTHING-IS-A-MOD.md](./EVERYTHING-IS-A-MOD.md)  
**Audience:** humans + all code agents (Grok, Claude, Codex, Cursor).

---

## 1. What you ship

```
mods/<id>/
  mod.json          # ASEC contract (required)
  <entry>-mod.js    # ES module with createX export (required)
  AGENT.md          # agentic install/verify steps (required for universal mods)
  README.md         # optional human notes
  index.html        # optional live demo (acceptance test)
  assets/           # optional textures, glb, audio
```

**id** = kebab-case, stable, matches `mod.json.id` and folder name.

---

## 2. Factory API (GENESIS)

Use the shared kit when possible:

```js
// entry: foo-mod.js
import * as THREE from "three";
import { injectHost, mergeConfig, withConfig } from "../_shared/mod-kit.js";

export function createFoo(scene, options = {}) {
  const opt = injectHost(options); // camera/renderer/domElement/bus from ModRuntime
  const { publicCfg } = mergeConfig({ speed: 1, enabled: true }, opt);
  let cfg = { ...publicCfg };

  const handle = {
    id: "my-foo",
    addTo(target = scene) { /* scene.add(...) */ return handle; },
    removeFrom(target = scene) { /* scene.remove(...) */ return handle; },
    update(time, dt, bus, host) { /* per-frame */ return handle; },
    getConfig() { return { ...cfg }; },
    configure(partial = {}) { cfg = { ...cfg, ...partial }; return handle; },
    dispose() { /* free GPU + listeners */ },
  };
  return withConfig(handle, () => handle.getConfig(), (p) => handle.configure(p));
}

export default createFoo;
```

Conventions:

| Method | Required | Notes |
|--------|----------|--------|
| `createX(scene, options)` | yes | Named export = `mod.json.export` |
| `addTo` / `removeFrom` | recommended | ModRuntime calls `addTo` if present |
| `update(time, dt, bus, host)` | if animated | MGS maintain |
| `getConfig` / `configure` | **recommended** | Hot tunables without rewrite |
| `dispose` | yes if listeners/GPU | |

**Config guide:** [MOD-CONFIG.md](./MOD-CONFIG.md) · **Machine catalog:** [/agents/mod-catalog.json](../agents/mod-catalog.json)

---

## 3. `mod.json` checklist (ASEC)

Copy from any live mod under `/mods/*/mod.json`. Must include:

- **meta.assumptions / provides / contracts**
- **genesis.scaffold / minimal** (minimal must match real API)
- **shadow.residuals / failureModes**
- **mgs.install / tune / verify / maintain**
- `entry`, `export`, `engine`, `version`, `license`
- `agent`: `"./AGENT.md"`

---

## 4. AGENT.md checklist (universal agents)

```markdown
# Agent — <Name>
**id:** …  **export:** createX
## When to install
## Steps (numbered)
## Coupling / conflicts
## Verify
## Refuse
```

Agents read this **after** `mod.json` when integrating into a game.

---

## 5. Assets

| Type | Placement | Notes |
|------|-----------|--------|
| Procedural | generated in entry | Prefer zero network |
| Textures | `assets/*.png` | Relative URLs from demo |
| GLB | `assets/*.glb` | Load via `threejs-gltf-kit` |
| CDN | absolute URL | Document CORS in SHADOW |

Register public assets in `js/catalog.js` when they should appear in the library UI.

---

## 6. Demo page (recommended)

Minimal demo = acceptance test for `asec.mgs.verify`:

```html
<script type="importmap">{ "imports": { "three": "...", "three/addons/": "..." } }</script>
<script type="module">
  import * as THREE from "three";
  import { createX } from "./x-mod.js";
  // scene, camera, renderer…
  const mod = createX(scene, { … }).addTo?.(scene);
  function frame(t) { mod.update?.(t, dt); renderer.render(scene, camera); requestAnimationFrame(frame); }
</script>
```

---

## 7. Register on the site

1. Add folder under `mods/<id>/`  
2. Catalog row in `js/catalog.js` (tier free, category, pack)  
3. Pack membership (e.g. `core-gameplay`)  
4. List in `agents/bootstrap.json` → `mods[]`  
5. Deploy Pages  
6. Skill references if onboard changes  

---

## 8. Popular starter set (shipped)

| id | Role |
|----|------|
| `threejs-sky` | Atmosphere + clouds + lights |
| `threejs-ocean` | FFT-spectrum water |
| `threejs-orbit-camera` | Orbit/pan/zoom |
| `threejs-fps-controller` | WASD + pointer lock |
| `threejs-post-fx` | Bloom/vignette grade |
| `threejs-particles` | Fire/smoke/sparks/magic |
| `threejs-interact` | Raycast click/hover |
| `threejs-gltf-kit` | Load/place GLB |
| `threejs-grid-floor` | Prototype stage |
| `threejs-hud` | DOM HUD overlay |
| `threejs-collectibles` | Proximity pickups + bus.score |
| `threejs-minimap` | Canvas minimap + markers |
| `threejs-simple-character` | Capsule player body |
| `threejs-third-person` | Follow cam + WASD |
| `threejs-health` | HP bar + damage/heal |
| `threejs-timer` | Count-up / countdown |
| `threejs-npc` | Look-at NPCs + dialogue |
| `threejs-weather-rain` | Rain VFX |
| `threejs-inventory` | Slot inventory UI |
| `threejs-checkpoint` | Pads + respawn |
| `threejs-audio-bus` | Ambient + SFX |
| `threejs-billboards` | World text labels |
| `threejs-quest` | Objective tracker |
| `threejs-portal` | A↔B teleport pads |
| `threejs-day-cycle` | Auto sky time |
| `threejs-toast` | Notifications |
| `threejs-debug-stats` | FPS overlay |
| `threejs-currency` | Wallet |
| `threejs-dialogue-box` | Multi-line dialogue |
| `threejs-light-rig` | Key/fill/rim lights |

**Test game:** `/game/outpost/` — wires 10+ mods on a shared bus.

Compose these before inventing new systems.

---

## 9. Agent prompt (paste)

```
Build a ModTrick mod named <id>:
1. Follow https://modtrick.com/docs/HOW-TO-BUILD-A-MOD.md
2. Full ASEC mod.json + AGENT.md + entry createX
3. No free-floating shaders outside the package
4. Name SHADOW residuals honestly
5. Register in catalog if public
```