# How to have your agent add ModTrick modding to your game

**For:** game authors speaking to Grok Build / Claude Code / Codex / Cursor  
**Primary:** https://modtrick.com · **Fallback:** https://modtrick.pages.dev

---

## One message you can paste to any agent

```text
Add ModTrick modding to this game. Everything is a mod.

1. Fetch https://modtrick.com/agents/bootstrap.json
2. Read https://modtrick.com/docs/EVERYTHING-IS-A-MOD.md
   and https://modtrick.com/docs/HOW-TO-BUILD-A-MOD.md
3. Install skill if missing: https://modtrick.com/pkg/install.ps1
4. Copy host/mod-runtime.js (+ frame-context.js) into this repo under host/
5. Create mods/ and vendor these free universal mods from the site:
   - threejs-grid-floor
   - threejs-orbit-camera  (or threejs-fps-controller if FPS)
   - threejs-sky
   - threejs-ocean (if water)
   - threejs-hud
   - threejs-interact
   - threejs-particles (optional VFX)
   - threejs-gltf-kit (if loading GLBs)
   - threejs-post-fx (optional look)
6. Wire ModRuntime.loadAll + runtime.tick each frame
7. Write/update AGENTS.md with ModTrick section
8. Do not invent a second plugin system
9. Verify each mod's asec.mgs.verify
```

---

## What “done” looks like

```
game/
  AGENTS.md                 # points at modtrick.com bootstrap
  host/
    mod-runtime.js
    frame-context.js
  mods/
    threejs-grid-floor/
    threejs-orbit-camera/   # or fps
    threejs-sky/
    threejs-hud/
    …
  index.html | src/main.js  # creates runtime, loads mods, ticks
```

---

## Recommended stacks

### A) Showcase / portfolio scene

`grid-floor` + `orbit-camera` + `sky` + `post-fx` + `hud`

### B) Walkable prototype

`grid-floor` + `fps-controller` + `sky` + `interact` + `hud` + `particles`

### B2) Third-person collectathon (reference implementation)

**Play live:** `/game/outpost/`

`grid-floor` + `sky` + `simple-character` + `third-person` + `collectibles` + `minimap` + `hud` + `particles` + `post-fx` + `interact`

### C) Seascape

`sky` + `ocean` + `orbit-camera` + `hud` + `post-fx`

### D) Content-driven level

`gltf-kit` + `grid-floor` + `orbit` or `fps` + `interact` + `hud`

---

## Minimal host code (agent should produce)

```js
import * as THREE from "three";
import { ModRuntime } from "./host/mod-runtime.js";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(55, innerWidth / innerHeight, 0.1, 5000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
// mount renderer.domElement …

const BASE = "https://modtrick.com"; // or "./" if vendored
const runtime = new ModRuntime({ scene, camera, renderer, THREE });

await runtime.loadAll([
  { url: `${BASE}/mods/threejs-grid-floor/mod.json`, baseUrl: `${BASE}/mods/threejs-grid-floor/` },
  { url: `${BASE}/mods/threejs-sky/mod.json`, baseUrl: `${BASE}/mods/threejs-sky/` },
  { url: `${BASE}/mods/threejs-orbit-camera/mod.json`, baseUrl: `${BASE}/mods/threejs-orbit-camera/` },
  { url: `${BASE}/mods/threejs-hud/mod.json`, baseUrl: `${BASE}/mods/threejs-hud/` },
]);

// orbit needs camera + domElement via options — if factory only gets scene,
// load with custom module options through a thin wrapper or direct create:
// Prefer vendored load with options:
import { createOrbitCamera } from "./mods/threejs-orbit-camera/orbit-camera-mod.js";
const orbit = createOrbitCamera(scene, { camera, domElement: renderer.domElement });

const clock = new THREE.Clock();
function frame() {
  const t = clock.getElapsedTime();
  const dt = clock.getDelta();
  orbit.update(t, dt);
  runtime.tick(t, dt);
  renderer.render(scene, camera);
  requestAnimationFrame(frame);
}
frame();
```

> **Agent note:** Some mods need `camera` / `renderer` / `domElement` in options. Pass them at GENESIS. ModRuntime’s default `factory(scene, options)` should receive those options via `loadManifest(..., { options: { camera, domElement: renderer.domElement, renderer } })`.

### Correct ModRuntime options pass-through

```js
await runtime.loadManifestUrl(`${BASE}/mods/threejs-orbit-camera/mod.json`, {
  baseUrl: `${BASE}/mods/threejs-orbit-camera/`,
  options: { camera, domElement: renderer.domElement },
});
await runtime.loadManifestUrl(`${BASE}/mods/threejs-post-fx/mod.json`, {
  baseUrl: `${BASE}/mods/threejs-post-fx/`,
  options: { renderer, camera, sceneRef: scene },
});
// post-fx: call runtime.get('threejs-post-fx').render(t) instead of renderer.render
```

---

## Agent self-check

```
□ bootstrap.json fetched
□ host/mod-runtime.js present
□ ≥3 mods vendored or CDN-loaded with mod.json
□ tick/update wired
□ AGENTS.md updated
□ no second plugin system
□ SHADOW residuals not oversold
□ verify checklist green for each mod
```

---

## Building a *new* mod for the game

Use: https://modtrick.com/docs/HOW-TO-BUILD-A-MOD.md

```text
Promote feature X to a mod: create mods/<id>/ with mod.json ASEC + AGENT.md + entry.
Register with ModRuntime. Do not leave feature code only in main.js.
```

---

## Conflicts to avoid

| Pair | Issue | Fix |
|------|--------|-----|
| orbit + fps | both drive same camera | mode switch or one only |
| post-fx + raw render | double path | only `fx.render()` |
| hud + full-screen UI | z-index wars | HUD is pointer-events none |

---

## Harness tips

| Agent | Tip |
|-------|-----|
| Grok | Skill `modtrick` in `~/.grok/skills`; may need session reload |
| Claude | Skill + project `AGENTS.md` / `CLAUDE.md` |
| Codex | Project `AGENTS.md` must link bootstrap |
| Cursor | `.cursor/rules/modtrick.mdc` + skill |