tinyworld-cctv-truman

name	tinyworld-cctv-truman
description	Use when changing the in-world CCTV / "Truman Show" surveillance cameras in Tiny World Builder — render-to-texture security feeds, the black-and-white CRT/VHS monitor shader, camera placement (lobby side-cams, pumpkincam, treecams), subject tracking, or the lobby screen cutting to live feeds.

Tiny World CCTV / Truman Cameras

Low-res black-and-white security cameras that watch the lobby and feed both physical monitors and the big lobby presentation screen. They idle-sweep, then pan to look at whoever is MOVING nearby — like the hidden cameras in The Truman Show. Do not mount CCTV or the big screen in non-lobby worlds.

Files

• engine/world/62-cctv-truman.js — the core system. IIFE exposing window.__tinyworldCCTV. 4-space body indent on purpose so the duplicate-declaration guard in tools/check.js (which only scans 2-space top-level decls) ignores its locals.
• engine/world/63-cctv-placement.js — mounts cams + monitors on lobby room enter, tears down on non-lobby enter or leave. Exposes window.__tinyworldCCTVPlacement. Lobby detection is window.__TW_LOBBY_WORLD_SLUG || 'tidewater-bay'.
• engine/world/58-lobby-presentation.js — the lobby-only big screen; its tick() cuts between slides and the hottest live feed.
• scripts/landing-feed.js + styles/landing.css — the public landing-page live-worlds panel. World rows are buttons: click once to expand an island CCTV preview (2D canvas from /api/worlds.preview.cells), click again to collapse. This is a lightweight marketing/front-door CCTV treatment, not a Three.js render target.
• Tick wiring: engine/world/25-animation-loop-schema.js calls window.__tinyworldCCTV.tick(t,dt) then window.__tinyworldLobby.tick(t,dt) before renderScene() so feeds captured this frame appear this frame.

How it works

• Each camera owns a PerspectiveCamera + a small WebGLRenderTarget (FEED_W×FEED_H, 4:3). tick() round-robins captures (CAPTURES_PER_FRAME, capped at FEED_FPS) using renderer.setRenderTarget(rt); renderer.render(scene, cam) — always save/restore the previous render target (getRenderTarget()), and bail if renderer/scene aren't ready.
• The monitor material is a ShaderMaterial (CRT_FRAG): luminance B&W, scanlines, a rolling interference bar, hash static, vignette, and uSignal dropout that dissolves toward static. A second canvas texture (tCaption) bakes the camera name + live date/time + blinking REC and is composited in the shader. The material is tagged userData.windowLightEffect = true + lightVisual = true so prepareFadeable() does NOT swap it for a fade material (skill: tinyworld-render-performance).
• Must end the fragment with #include <colorspace_fragment> (r185 output color space), like every other ShaderMaterial here.
• Subjects: setSubjectsProvider(() => [{pos:Vector3, name}]). The room feeds WS.subjects() (self + peer avatar sprite positions). Cameras + monitors live under WS.avatarParent() — the SAME local frame as the avatars and lobby screen — so subject positions need no conversion.
• Truman tracking: aim() scores each in-range subject by prox*0.6 + moved*1.0 (movement dominates) using per-feed last-position memory; it lerps curLook toward the winner (TRACK_LERP) or idle-sweeps (IDLE_LERP). A per-feed activity score spikes on motion and decays (ACTIVITY_DECAY).
• Hot feed: activeFeed(minActivity) / feedsByActivity() let the lobby screen auto-cut to whichever camera has something happening. glitch(id,amt) drops uSignal briefly to sell a cut.

Placement (63)

On lobby enter only (after a 350ms delay so cells + lobby screen exist) it mounts:

• lobby-l / lobby-r — flank both sides of the presentation screen, angled at the crowd (toward +z).
• pumpkincam — over the biggest kind:'pumpkin' cell (scans world[][], sorts by floors).
• treecam-1/2 — over the tallest kind:'tree' cells. Monitors stack up the sides of the lobby screen. window.__tinyworldCCTVFeeds lists mounted feed ids. On non-lobby enter or leave, clear feeds, disable capture, and remove monitors.

Lobby cutting (58)

build() stashes screenMesh + slideMat. The screen is shown only in the configured lobby world, not every island. The state machine auto-advances slides (AUTO_ADVANCE), then after SLIDE_DWELL swaps the screen material to a monitorMaterialFor(hotFeed) for FEED_DWELL, then back. Manual presenter go() and hide() snap back to slides. New API: tick, setCycle, showSlides, showFeed, liveFeed.

QA

• ?cctv=demo (or =1) drops 4 monitors around origin watching a bobbing test subject and self-drives the tick — verifies the CRT look + tracking without a multiplayer room.
• Landing page QA for scripts/landing-feed.js: if local /api/worlds is not available, mock window.fetch('/api/worlds'), append a fresh copy of the script, click .hero-feed-link, and assert .hero-feed.is-expanded, one .hero-feed-cctv-canvas, and the .hero-feed-cctv-meta status/link render. The panel should anchor below the nav (.hero-feed.is-expanded) and scroll internally instead of overflowing the hero.
• Headless sanity: eval module 62 under a THREE stub, addCamera + tick a few frames with a moving subject, assert activeFeed() returns the feed and activity > 0.
• npm run check (duplicate-decl + i18n), npm run smoke, ./publish.sh.

Pitfalls

• Don't capture every feed every frame — round-robin, or the extra renderer.render passes tank FPS (the renderer contract is single-pass per feed; this is the only sanctioned extra-RT path here besides pixelation).
• Don't forget to restore the render target after capturing, or the main scene renders into the last feed's RT (black screen).
• Keep monitor materials off the fade pipeline via the windowLightEffect tag.
• Cameras + monitors MUST be added under avatarParent(), not scene, or they won't inherit the tinyverse scale/offset and subject tracking will be wrong.