My Gully, in Pixels

The scene establishes where you are; HTML carries what you came to read. Holding that boundary keeps an article selectable and scrollable while its newspaper still belongs to the street.

The garage monitor hosts a same-origin project iframe, which separates scene navigation from document navigation: the street controls the camera and monitor placement, and the embedded site owns its content and scrolling. Semantic actions are instrumented with PostHog, so engagement can be measured per destination.

The key module boundaries are stagedLoader.js for arrival and reveal, main.js for route coordination, destination controllers such as contactExperience.js for camera and input ownership, and pixelRenderer.js for the presentation pipeline. Clear boundaries mean a visual bug can be traced to a specific responsibility.

Takeaway: decide which layer owns each concern (place, content, build) before writing features.

Local space, world space, screen space

Moving a stall should move its paper, camera target, and clickable contact rows together. Hardcoded world coordinates would break on every layout revision.

Instead, the exported model carries named markers such as Contact_PaperAnchor. In a scene graph, each object’s transform is relative to its parent, and composing those transforms gives its world transform. createContactLayout() derives positions, directions, the drag plane, and camera shots from that one anchor.

A local paper point projects to the screen as:

$M$ is the model matrix including parent transforms, $V$ is the view matrix (the inverse camera transform), and $P$ is the projection matrix. Dividing by $w$ is the perspective divide. Normalized device coordinates then map to viewport CSS pixels:

screenX = (ndc.x + 1) × width / 2
screenY = (1 − ndc.y) × height / 2

Y is flipped because screen Y grows downward. Any canvas offset is added when positioning elements outside the canvas.

The contact rows are defined as rectangles in the newspaper artwork’s UV space. Once the reveal and camera move finish, their corners map onto the final flat paper surface, inherit the anchor transform, and project into HTML link targets. They stay inactive while the folds are moving. The result is a printed advertisement that behaves like a real web page, without rendering the document into WebGL.

Picking is the reverse journey

A pointer position converts to normalized device coordinates; Three.js casts a ray from the camera and intersects scene geometry. The hit then has to resolve to an intended destination, so the picker filters out decorative foreground geometry, transparent sprite areas, and nested model children rather than taking the first intersection.

Input also needs intent: a tap must not fire after a drag or pinch. The picker tracks the pressed target, cancels the tap after 6 CSS pixels of movement, and ignores multi-pointer gestures. Destination controllers suspend street interactions while they own the view.

Takeaway: an asset is an interface contract. Names, scale, orientation, and transform inheritance matter as much as appearance. When the garage was enlarged and a neighboring stall moved, checks against exported markers and geometry kept screens, shutters, and camera framing aligned.

A visitor selects Projects, the garage entrance starts, and then they select Contact. If both experiences keep updating the camera, they fight over it.

The camera therefore has exactly one active owner. The route coordinator releases the old experience before another can acquire it, and a monotonically increasing navigation token rejects stale asynchronous continuations.

Simplified from the coordinator:

const request = ++routeToken;
await releasePreviousExperience();
if (request !== routeToken) return;
await enterRequestedExperience();

The critical moment is after await: while one request waits, a newer one can arrive. Comparing tokens stops the older request from resuming as if nothing changed. The coordinator repeats this check after every awaited release.

The token guards continuations; controllers handle the rest: stopping in-flight tweens, releasing input, and restoring state. Network requests need their own cancellation, such as an AbortSignal.

Nested Contact routes (paper, stall overview, photo album) share one saved street camera position and target. Saving again at each subview would overwrite the return point with a close-up. Reduced motion shortens the transitions but reaches the same final state.

Takeaway: camera animation is a state-management problem. Camera phase, shutter position, lighting, route, and input availability are separate state dimensions that a single isOpen flag cannot represent.

Download order and presentation order are separate concerns. The road should establish the space before shops appear, even if a small skyline file finishes first.

createStagedLoader() runs two concurrent loaders over a priority-sorted job list. Models are prepared while hidden, and a separate sequence reveals road, pavement, lamps, shops, skyline, and details in order. Road and pavement are visual groups extracted from the same GLB.

// Simplified structure.
startTwoWorkers(prioritySortedJobs);

for (const stage of presentationOrder) {
  const results = await resultsFor(stage);
  await reveal(successfulRoots(results));
}

Shop picking enables after the shop reveal, destination choreography waits for full scene readiness, and optional traffic starts last. That gives four distinct states: loaded, visible, interactive, and ready for a close-up.

A failed job records the failure and resolves, so later stages continue. Reduced motion keeps the sequence and drops the fade. The concurrency cap of two is a tunable policy. These loaders are async tasks on the main thread, not Web Workers, so they schedule network and decode work rather than parallelize it.

Resource lifetime is part of the feature

Removing a mesh from the scene does not free its GPU geometry, materials, textures, or render targets, so cleanup follows ownership rules. A temporary fade material is disposed while the shared texture it uses stays owned by the loaded asset.

The photo wall is a good example: it borrows model meshes, creates replacement geometry, materials, and a texture atlas, then restores the borrowed state and releases its own allocations on exit. Generation counters reject async results that arrive after teardown, and abort signals cancel loads where supported.

Takeaway: a feature includes its exit path. Listeners, timers, observers, GPU allocations, and late async results need as much care as the entrance animation.

Pixel mode combines Three.js’s RenderPixelatedPass and OutputPass with a custom color-quantization shader. The design goal is a stylized street where selected signs and artwork stay legible at close range.

Why sharp artwork still needs depth

Drawing a crisp sign over the finished image would make it visible through walls. The renderer reconstructs full-resolution depth first:

Pixelated scene → output conversion → color quantization
Clear depth → visible-geometry depth only → sharp artwork with depth testing

The depth-only pass disables color writes, so it records nearer geometry without touching the composed image, and the sharp pass then respects occlusion. Selected sprites are excluded from the coarse pass so no pixelated duplicate shows behind them. A finally block restores visibility, color-write flags, background, auto-clear, and the shadow-update flag even if a pass throws.

Pixel size and color are separate controls

Block size is specified in CSS pixels and multiplied by device-pixel ratio, so at DPR 2 a 4 px block spans 8 device pixels. Mobile and close Contact views use smaller blocks.

For a normalized color channel $c$ with $L=16$ levels, quantization is:

Sixteen levels per channel give 4,096 base colors; blending by strength $s$ softens the result between them. Tone mapping, output color-space conversion, and quantization are distinct steps, and their order changes the final image.

Takeaway: a low-resolution look can require extra full-resolution work. Pixel mode adds passes, so performance has to be measured, not assumed. If the pipeline fails to initialize or render, the app falls back to Original mode.

Corner bends and separate panels satisfied simple bounds but missed the silhouette I wanted. Continuous procedural versions improved the surface, yet good-looking endpoints hid awkward in-between folds. The breakthrough was changing the representation and the brief together.

Author the shape; play the result

The source is an editable Blender scene. A cloth-assisted study provides the starting motion; sculpted poses and cleanup give full control over the choreography. The export is a connected 4,225-vertex grid with UVs, a closed basis shape, and 24 position-and-normal morph targets. One two-second Unwrap clip uses step interpolation to hold 25 poses at 12 poses per second.

poseIndex = min(24, floor(elapsedSeconds × 12))

At runtime, the adapter maps elapsed time to clip time; the browser plays back authored poses with no physics solve. Baked normals keep shading correct for each shape, bounds cover every pose, and shadow and outline updates follow pose changes. The printed front and blank back share geometry and morph weights with separate materials. The newspaper texture can change independently, as long as the contact-row coordinates still match its layout.

Two clocks, one reveal

The camera approaches for 1.8 seconds while the parcel stays closed. The two-second unwrap starts with the 4.2-second overhead push, and links and food dragging wait for both to finish. Leaving before the cue keeps the parcel closed; leaving after it starts lets playback complete. The revealed state and dragged food positions persist across visits until reload. Reduced motion jumps straight to the final pose.

Arrival, animation completion, and interaction readiness are separate states, and a slow or stalled approach frame cannot trigger the reveal early.

Validation

Checks run on all 25 exported poses for finite geometry, topology, concealment, clearance, and a flat contact footprint. Four stretched pin corners initially produced needle-like edges; cleanup cut the maximum edge-length ratio from 20.26× to 3.72×, now guarded by a 4× regression ceiling. Eighteen lifecycle cases cover cue timing, interruption, return visits, and readiness. Pipeline checks confirm that a standard export preserves the saved scene and that swapping the artwork leaves the GLB unchanged.

Geometry checks and visual review cover different failures: topology checks confirm one connected sheet, and visual review catches self-intersection and awkward folds. The art-directed approach trades physical exactness for precise control over the choreography.

Takeaway: when parameter tuning stops helping, change the representation. “Passes the geometry checks” and “looks like someone unwrapping lunch” are separate acceptance criteria.

The role documents give every agent the same project context and a distinct review responsibility. It is a development protocol built on general-purpose AI assistants with role-specific instructions. New assets get broad review; narrow revisions involve only the affected specialists. Findings are consolidated before a single implementer touches the scene.

Takeaway: delegate with a bounded brief, one writer, and evidence-based acceptance. I own the direction and the final call.