@vibes.diy/prompts 5.5.5 → 5.5.7

package/llms/image-gen.md

@@ -57,6 +57,20 @@ The input image is automatically resized (max 1024px) and compressed as JPEG bef
 
 Load a previously generated image by `_id` — if the doc has a `prompt` but no `_files` yet, the component generates one: `<ImgGen _id="my-image-id" database={database} />`
 
+## Illustrations That Are Part of an Item's Identity
+
+When an item's picture is intrinsic to what it is — a card in a deck, a creature in a bestiary, a product in a catalog, a character in a cast — render `<ImgGen>` **by default** for every such item that lacks an image, so the illustration appears as soon as the item does. Because ImgGen auto-generates when the target doc has a `prompt` but no `_files` yet, mounting it directly on the item is all it takes:
+
+```jsx
+<ImgGen
+  _id={card._id}
+  database={database}
+  prompt={`Illustration of ${card.title}. ${card.description ?? ""}`}
+/>
+```
+
+Do **not** hide first generation behind an "Illustrate" / "Generate image" button — a button leaves every item blank until tapped, which reads as "the app has no pictures." Reserve buttons and `showControls` for *regeneration* of an image that already exists. (For incidental or user-optional images — an avatar upload, a one-off hero graphic — an explicit action is still fine; this rule is about items whose identity includes a picture.)
+
 ## Gallery Pattern
 
 Browse stored images with `useLiveQuery`. Building a gallery below the generator:

package/llms/index.d.ts

@@ -6,9 +6,10 @@ export { imageGenConfig } from "./image-gen.js";
 export { webAudioConfig } from "./web-audio.js";
 export { d3Config } from "./d3.js";
 export { threeJsConfig } from "./three-js.js";
+export { voxelConfig } from "./voxel.js";
 export { webxrConfig } from "./webxr.js";
 export { useViewerConfig } from "./use-viewer.js";
 export { useVibeConfig } from "./use-vibe.js";
 export { createVibeConfig } from "./create-vibe.js";
 export type { LlmConfig } from "./types.js";
-export declare const allConfigs: readonly [import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig];
+export declare const allConfigs: readonly [import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig, import("./types.js").LlmConfig];

package/llms/index.js

@@ -6,6 +6,7 @@ import { imageGenConfig } from "./image-gen.js";
 import { webAudioConfig } from "./web-audio.js";
 import { d3Config } from "./d3.js";
 import { threeJsConfig } from "./three-js.js";
+import { voxelConfig } from "./voxel.js";
 import { webxrConfig } from "./webxr.js";
 import { useViewerConfig } from "./use-viewer.js";
 import { useVibeConfig } from "./use-vibe.js";
@@ -18,6 +19,7 @@ export { imageGenConfig } from "./image-gen.js";
 export { webAudioConfig } from "./web-audio.js";
 export { d3Config } from "./d3.js";
 export { threeJsConfig } from "./three-js.js";
+export { voxelConfig } from "./voxel.js";
 export { webxrConfig } from "./webxr.js";
 export { useViewerConfig } from "./use-viewer.js";
 export { useVibeConfig } from "./use-vibe.js";
@@ -28,6 +30,7 @@ export const allConfigs = [
     webAudioConfig,
     d3Config,
     threeJsConfig,
+    voxelConfig,
     fireproofConfig,
     webxrConfig,
     useViewerConfig,

package/llms/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../jsr/llms/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,YAAY;IACZ,cAAc;IACd,cAAc;IACd,QAAQ;IACR,aAAa;IACb,eAAe;IACf,WAAW;IACX,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,cAAc;CACN,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../jsr/llms/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,YAAY;IACZ,cAAc;IACd,cAAc;IACd,QAAQ;IACR,aAAa;IACb,WAAW;IACX,eAAe;IACf,WAAW;IACX,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,cAAc;CACN,CAAC"}

package/llms/voxel.d.ts

@@ -0,0 +1,2 @@
+import type { LlmConfig } from "./types.js";
+export declare const voxelConfig: LlmConfig;

package/llms/voxel.js

@@ -0,0 +1,15 @@
+export const voxelConfig = {
+    name: "voxel",
+    label: "Voxel",
+    description: "Build a Minecraft-style first-person voxel sandbox with Three.js: chunked block world, " +
+        "procedural terrain (noise heightmaps, biomes, caves, ore veins, trees), place/break with a " +
+        "DDA voxel raycast, an AABB player controller with gravity, jump, sprint, auto step-up and " +
+        "un-stick, pointer-lock look with a click-to-play overlay and touch drag, endless chunk " +
+        "streaming, a day/night cycle, ambient mobs, and live multiplayer block edits over Fireproof. " +
+        "minecraft, voxel, block world, sandbox, blocks, mining, building, first-person, 3d game, " +
+        "procedural world, chunks, terrain, overworld, creative mode, survival",
+    importModule: "three",
+    importName: "THREE",
+    importType: "namespace",
+};
+//# sourceMappingURL=voxel.js.map

package/llms/voxel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voxel.js","sourceRoot":"","sources":["../../jsr/llms/voxel.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;IACd,WAAW,EACT,yFAAyF;QACzF,6FAA6F;QAC7F,4FAA4F;QAC5F,yFAAyF;QACzF,+FAA+F;QAC/F,2FAA2F;QAC3F,uEAAuE;IACzE,YAAY,EAAE,OAAO;IACrB,UAAU,EAAE,OAAO;IACnB,UAAU,EAAE,WAAW;CACxB,CAAC"}

package/llms/voxel.md

@@ -0,0 +1,343 @@
+# Voxel worlds — a Minecraft-style first-person block sandbox
+
+When someone asks for "Minecraft", a "block world", a "voxel game", or a
+first-person building/mining sandbox, this is the recipe. It builds on the
+Three.js docs (all the `THREE.*` classes there apply) — this page is the
+voxel-specific architecture that makes such a game actually playable, and it
+calls out the handful of things that make the difference between "cool" and
+"I keep getting stuck / I can't lock my mouse".
+
+The worked example throughout is a real community app, **Voxel World** by
+`isaac-subach` (shared with permission). It ships procedural biomes, caves,
+ore veins, endless chunk streaming, a day/night cycle, live multiplayer edits,
+and ambient wildlife — in a single `App.jsx`. Every pattern below is pulled
+from it.
+
+## The one-file shape
+
+A voxel game is one big imperative Three.js engine wrapped in a thin React
+shell. Build the engine **once** inside a `useEffect(() => {...}, [])` that owns
+the renderer, the world model, and the animation loop; expose a few methods on
+a mutable `state` object (`engineRef.current`) so React can call in. React
+renders only the HUD, the hotbar, and overlays as normal DOM on top of the
+`<canvas>`. Never re-create the engine on re-render, and never drive
+per-frame values through React state — read live values through refs.
+
+```jsx
+function CanvasStage({ engineRef, onReady }) {
+  const canvasRef = React.useRef(null);
+  React.useEffect(() => {
+    const canvas = canvasRef.current;
+    // ... build scene, camera, renderer, world model, loop ...
+    const state = { /* see below */ };
+    engineRef.current = state;
+    // ... requestAnimationFrame(loop); onReady?.() ...
+    return () => { state.running = false; /* dispose everything */ };
+  }, []);
+  return <section className="absolute inset-0"><canvas ref={canvasRef} className="w-full h-full block touch-none" /></section>;
+}
+```
+
+## The data model: a flat block map, not a 3D array
+
+Store the world as **one `Map` keyed by `"x|y|z"` → block-type string**. Sparse,
+trivial to stream, and the same structure works for collision and raycasting.
+
+```js
+const keyOf = (x, y, z) => `${x}|${y}|${z}`;
+const parseKey = (k) => k.split("|").map(Number);
+
+const CHUNK_SIZE = 16;
+const chunkOf = (x, z) => [Math.floor(x / CHUNK_SIZE), Math.floor(z / CHUNK_SIZE)];
+const chunkKey = (cx, cz) => `${cx},${cz}`; // stable string id — compare these, never raw [cx,cz] arrays
+
+const state = {
+  blocks: new Map(),   // "x|y|z" -> type   (the loaded world, terrain + edits)
+  chunks: new Map(),   // "cx,cz" -> Set(blockKey)  currently-resident chunks
+  edits:  new Map(),   // "x|y|z" -> type|null  player edits layered over terrain
+  meshes: new Map(),   // "x|y|z" -> THREE.Mesh  (only for EXPOSED blocks)
+  pos: new THREE.Vector3(0, 20, 0),
+  vel: new THREE.Vector3(),
+  yaw: 0, pitch: 0, keys: {}, onGround: false, fly: false,
+};
+```
+
+Keep block types as a table of face colors so one material set covers the world:
+
+```js
+const BLOCK_TYPES = {
+  grass: { top: 0x5fbf3f, side: 0x7a5230 }, dirt: { top: 0x7a5230, side: 0x6b4626 },
+  stone: { top: 0x8a8a8a, side: 0x7a7a7a }, sand: { top: 0xe0d29a, side: 0xd6c78a },
+  water: { top: 0x3f6fbf, side: 0x3f6fbf }, wood: { top: 0x9a6b3f, side: 0x6b4626 },
+  leaves:{ top: 0x3f8f2f, side: 0x3f8f2f }, /* ...ores, planks, snow, etc. */
+};
+```
+
+## Rendering: mesh only the EXPOSED blocks (this is the whole performance game)
+
+The single most important rule: **do not create a `THREE.Mesh` per stored
+block.** A chunk is thousands of blocks and most are buried. Keep buried blocks
+in the `blocks` map (collision and raycasting read the map, not the scene), and
+only add a mesh when a block has at least one non-occluding neighbor.
+
+```js
+const NB = [[1,0,0],[-1,0,0],[0,1,0],[0,-1,0],[0,0,1],[0,0,-1]];
+function occludes(t) { return t && t !== "water" && t !== "glass" && t !== "leaves"; }
+function isHidden(x, y, z) {
+  for (const [dx, dy, dz] of NB)
+    if (!occludes(state.blocks.get(keyOf(x + dx, y + dy, z + dz)))) return false;
+  return true; // fully enclosed → no mesh
+}
+```
+
+Share one `BoxGeometry` and one material array per type across every block (a
+6-material array lets the top face differ from the sides). When a block is
+placed or broken, refresh that block's mesh **and its six neighbors'** — a
+neighbor that was buried may now be exposed, or vice-versa.
+
+Raycasting and collision must read `state.blocks` (the full model), never the
+meshes — otherwise you can't hit or collide with a face that isn't currently
+meshed.
+
+## Procedural terrain: deterministic noise, layered
+
+Terrain must be a **pure function of world coordinates** so chunks generate
+identically no matter when they stream in. Use hash-based value noise (no
+library, no seeds to thread):
+
+```js
+function hash2(x, z) {
+  let h = x * 374761393 + z * 668265263;
+  h = (h ^ (h >> 13)) * 1274126177; h = h ^ (h >> 16);
+  return (h >>> 0) / 4294967295;
+}
+function smoothNoise(x, z) { /* bilinear-interpolated hash2 with smoothstep */ }
+```
+
+Layer octaves for the height field, add a low-frequency biome field, carve
+caves and place ore with 3D noise, and generate trees in a margin around each
+chunk so canopies that cross chunk borders stay whole:
+
+```js
+function heightAt(x, z) {
+  let h = smoothNoise(x*0.06, z*0.06)*8 + smoothNoise(x*0.03, z*0.03)*5;
+  const mtn = smoothNoise(x*0.012 + 2000, z*0.012 + 2000);
+  if (mtn > 0.6) h += (mtn - 0.6) * 70;             // steep mountain ranges
+  return Math.floor(h);
+}
+function biomeAt(x, z) { /* temp + moisture fields -> plains/forest/desert/snowy/mountains */ }
+function carvedCave(x, y, z) { /* 3D noise > threshold, but keep y<2 solid */ }
+function oreAt(x, y, z)    { /* rarer + deeper = diamond; common + shallow = coal */ }
+```
+
+Generate a chunk into a `Map` and let **player edits override terrain** on load
+so a mined/placed block survives streaming out and back:
+
+```js
+function loadChunk(cx, cz) {
+  const keys = new Set();
+  for (const [k, t] of generateChunkBlocks(cx, cz)) { state.blocks.set(k, t); keys.add(k); }
+  for (const [k, t] of state.edits) {               // edits win over terrain
+    const [ex, , ez] = parseKey(k);
+    if (chunkKey(...chunkOf(ex, ez)) !== chunkKey(cx, cz)) continue; // compare stable keys, not arrays
+    if (t === null) { state.blocks.delete(k); keys.delete(k); }
+    else { state.blocks.set(k, t); keys.add(k); }
+  }
+  for (const k of keys) { const [x,y,z] = parseKey(k); if (!isHidden(x,y,z)) addMesh(k, state.blocks.get(k)); }
+  state.chunks.set(chunkKey(cx, cz), keys);
+}
+```
+
+## Endless streaming: one chunk per frame
+
+Each frame, figure out which chunks should be resident around the player
+(`VIEW_RADIUS` chunks in each direction), enqueue the missing ones sorted
+nearest-first, and load **exactly one per frame** so the framerate never
+stalls. Unload chunks that fall outside the radius (delete their blocks and
+meshes). Never load a whole ring in one frame.
+
+## The player controller — where "Minecraft" is won or lost
+
+### Collision: per-axis AABB + auto step-up + un-stick
+
+Represent the player as an AABB (~0.6 wide, 1.8 tall) and test it against the
+block map. Resolve **each horizontal axis separately** so sliding along a wall
+works. Then add the two things that separate a good controller from a
+frustrating one — these are the exact complaints new voxel apps get ("I keep
+getting stuck", "I get stuck jumping", "I'm trapped in a block"):
+
+- **Auto step-up.** If a horizontal move is blocked but the space one block
+  higher is clear (and you're grounded), step up onto it. This is what lets you
+  walk up stairs and 1-block ledges without hammering the jump key.
+- **Un-stick.** At the top of each frame, if the player's AABB is already
+  inside solid terrain (a block synced in from another player, or fresh terrain
+  generated around you), lift the player up until free. Without this a synced
+  block traps the player permanently.
+
+```js
+function collides(px, py, pz) {
+  const minX = Math.floor(px-0.3+0.5), maxX = Math.floor(px+0.3+0.5);
+  const minZ = Math.floor(pz-0.3+0.5), maxZ = Math.floor(pz+0.3+0.5);
+  const minY = Math.floor(py-1.6+0.5), maxY = Math.floor(py+0.2+0.5);
+  for (let x=minX;x<=maxX;x++) for (let z=minZ;z<=maxZ;z++) for (let y=minY;y<=maxY;y++) {
+    const t = state.blocks.get(keyOf(x,y,z));
+    if (t && t !== "water") return true;
+  }
+  return false;
+}
+
+// each frame, before moving:
+let lifts = 0;
+while (collides(np.x, np.y, np.z) && lifts < 6) { np.y += 1; lifts++; }   // un-stick
+
+const stepAxis = (nx, nz) => {                                            // move + auto step-up
+  if (!collides(nx, np.y, nz)) { np.x = nx; np.z = nz; return; }
+  if (state.onGround && !state.fly && !collides(nx, np.y+1, nz) && !collides(np.x, np.y+1, np.z)) {
+    np.x = nx; np.z = nz; np.y += 1;
+  }
+};
+stepAxis(np.x + move.x, np.z);
+stepAxis(np.x, np.z + move.z);
+```
+
+Gravity/jump: integrate `vel.y -= g*dt`, and when a downward move collides set
+`onGround = true` and zero the velocity; jump only when grounded. Add a **fly
+toggle** (e.g. `F`) that swaps gravity for direct vertical thrust — great for
+building. Add **sprint** (hold `Shift` while moving forward → higher speed, and
+nudge the camera FOV up a few degrees for a sense of speed).
+
+### Looking: pointer lock with a click-to-play overlay (+ touch drag)
+
+Pointer lock is the number-one confusion in browser voxel games: players click
+and nothing happens, or they don't know the mouse controls the camera at all.
+**Always** show an explicit "Click to play" overlay with the control legend,
+and only request lock from that click:
+
+```jsx
+{worldReady && !isTouch && !locked && (
+  <button onClick={() => engineRef.current?.requestLock()}
+    className="absolute inset-0 z-20 flex flex-col items-center justify-center bg-black/55 backdrop-blur-sm">
+    <div className="panel">
+      <h2>Voxel World</h2><p>Click to play</p>
+      {/* WASD move · Mouse look · Shift sprint · Space jump · Left-click break · Right-click place · F fly · 1–9 blocks */}
+    </div>
+    <p className="text-xs opacity-60">Press Esc to release the mouse</p>
+  </button>
+)}
+```
+
+Drive the overlay off the real lock state so it reappears when the player hits
+Esc:
+
+```js
+React.useEffect(() => {
+  const onLock = () => setLocked(!!document.pointerLockElement);
+  document.addEventListener("pointerlockchange", onLock);
+  return () => document.removeEventListener("pointerlockchange", onLock);
+}, []);
+```
+
+In the engine, read `movementX/Y` when `document.pointerLockElement === canvas`
+(clamp per-event deltas — browsers spike them on lock acquire), and fall back to
+**drag-to-look on touch** so phones work without pointer lock. Clamp pitch to
+±1.5 rad. Provide on-screen move/jump/place/break buttons for touch.
+
+### Block targeting: a DDA voxel raycast, not `Raycaster`
+
+Do **not** use `THREE.Raycaster` against the meshes — it misses unmeshed faces
+and is slow. March a DDA ray through the block map from the camera along its
+forward vector; the first solid voxel is the target, and the face you entered
+through gives the placement cell.
+
+```js
+function castTarget() {
+  const d = new THREE.Vector3(0,0,-1).applyEuler(camera.rotation);
+  // ... standard 3D-DDA over integer voxels, max ~7 blocks reach ...
+  // return { x, y, z, face:[fx,fy,fz] } for the first solid, non-water voxel, else null
+}
+```
+
+Left-click breaks the targeted block; right-click (`contextmenu`, prevent
+default) places `selected` on the entered face. **Guard placement** so a player
+can never place a block inside their own AABB. Show a wireframe highlight box on
+the current target each frame, and spawn a quick burst of small colored cubes
+when a block breaks — cheap, and it makes mining feel real.
+
+## Multiplayer: live block edits over Fireproof
+
+Persist each edit as **exactly one document per voxel coordinate** so concurrent
+builders converge and late joiners see the whole world. Give that document a
+**deterministic `_id` of `block:<key>`** so every edit at a coordinate *updates
+the same doc* — do NOT `put` a fresh doc per edit. Without the deterministic id
+Fireproof mints a new `_id` each time, the database grows without bound, and the
+live query below replays every historical value in index order, so a stale doc
+can overwrite a newer break/place. A break writes a `removed: true` tombstone at
+the same id (keep it so the removal survives streaming, rather than deleting it):
+
+```js
+// on place/break — apply locally for instant feedback, then upsert the ONE doc for this cell
+eng.applyBlock(key, type);                    // type=null for a break
+await database.put(brk
+  ? { _id: `block:${key}`, type: "block", key, removed: true,  authorHandle: me?.userHandle, at: Date.now() }
+  : { _id: `block:${key}`, type: "block", key, blockType: type, authorHandle: me?.userHandle, at: Date.now() });
+
+// stream everyone's edits back into the engine — one current doc per coordinate
+const { docs: blockDocs } = useLiveQuery("type", { key: "block" });
+React.useEffect(() => {
+  for (const d of blockDocs) eng.applyBlock(d.key, d.removed ? null : d.blockType);
+}, [blockDocs]);
+```
+
+Apply the local edit **before** the `put` so the world never waits on the
+network, and read live handles/permissions through refs (a value captured in the
+engine closure at load time goes stale — bind live state via `state.on*`
+callbacks or refs, never the closure). Keep the shared world **open** so anyone
+with the link can build — an `access.js` that channels block docs publicly and
+allows anonymous writers:
+
+```js
+export default function (doc, oldDoc, user, ctx) {
+  const WORLD = "world:overworld";
+  if (doc.type === "block") {
+    if (user && doc.authorHandle && doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    return { channels: [WORLD], grant: { public: [WORLD] }, allowAnonymous: true };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
+Do the world's block editing on the **client** regardless of write
+permission (`applyBlock` always runs locally); gate only the **sync** on
+`can.create(...)` so a slow or stale rule binding can never freeze the game.
+
+## Ambient life & atmosphere (cheap, high-impact)
+
+None of this needs persistence — keep it purely visual and client-side:
+
+- **Day/night cycle.** Advance a `dayTime` 0..1, drive the sun/moon position and
+  a blended sky/fog color, and fade light intensity. A full day every few
+  minutes feels right.
+- **Mobs.** Spawn a small capped population near the player: animals that wander
+  by day, zombies that shuffle toward the player at night. Build each from a few
+  `BoxGeometry` parts in a `Group`, apply gravity against `groundYAt(x,z)` (scan
+  the block map downward for the top solid block), let them hop 1-block ledges,
+  and despawn when far or at the wrong time of day.
+- **Clouds.** A `Group` of flattened white boxes high overhead with
+  `fog: false`, following the player horizontally and drifting slowly.
+- **Lighting.** `AmbientLight` + a `DirectionalLight` sun, plus a
+  `HemisphereLight` for soft sky/ground fill so faces aren't flat.
+
+## Performance checklist
+
+- Mesh only exposed blocks; keep buried ones in the map for collision/raycast.
+- Share one geometry + one material set across all blocks.
+- Stream one chunk per frame; unload out-of-range chunks (dispose meshes).
+- Raycast and collide against the block map, never the scene meshes.
+- Cap mobs and particles; dispose geometries/materials on unmount and on
+  chunk unload.
+- `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))` and a `Fog` to bound
+  draw distance.
+
+That set — exposed-face meshing, per-axis collision with step-up and un-stick,
+a click-to-play pointer-lock overlay, a DDA raycast, and per-voxel Fireproof
+docs — is what turns a voxel tech demo into a game people actually play.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "5.5.5",
+  "version": "5.5.7",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -24,9 +24,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "^5.5.5",
-    "@vibes.diy/identity": "^5.5.5",
-    "@vibes.diy/use-vibes-types": "^5.5.5",
+    "@vibes.diy/call-ai-v2": "^5.5.7",
+    "@vibes.diy/identity": "^5.5.7",
+    "@vibes.diy/use-vibes-types": "^5.5.7",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.2"
   },