Willow Ferry · 柳渡

English · 中文

Live: https://bacchus-wen.github.io/willow-ferry/ (best in desktop Chrome, Edge or Safari; falls back to WebGL2 where WebGPU is missing)

Follow the water. Come home a little late.

A water town south of the river (Jiangnan), rendered live in the browser: white walls and dark tiles, horse-head fire walls, lattice shopfronts under lantern-hung eaves, a stone arch bridge, wupeng boats and willows over jade water. Five times of day (afternoon, golden hour, blue hour, moonlit night, misty rain), DSLR-style depth of field, sun and moon glitter on the water, low mist banks, and an ambience synthesised in the browser.

Everything is made by code, following @chetanankola's approach: an AI writes Blender Python that builds the geometry, materials and lighting and exports GLB; it reads the renders and validation reports, then revises the scripts; three.js (WebGPU + TSL) presents the result.

Run

cd web
npm install
npm run dev          # http://127.0.0.1:5230  (WebGPU Chrome; falls back to WebGL2)
npm run build        # production build into web/dist

URL parameters (screenshots and debugging): ?preset=golden|afternoon|blue|night|dawn|morning|rain&view=hero|bridge|landing|pavilion|overview|boat&ui=0&dof=0&ap=2.8&drift=0&intro=0&clock=0 (clock=0 stops the day at the chosen hour)

Controls: drag to look · scroll to glide · WASD to walk (Shift faster, Q/E up and down) · click to focus · 1–5 time of day · hold T to let the hours pass · ←/→ viewpoints · H hides the interface. Aboard the boat: ←/→ (A/D) steer, ↑ (W) row harder, ↓ (S) ease off; let go and it drifts back to its line.

Every push to main builds web/ with GitHub Actions (.github/workflows/deploy.yml) and publishes it to GitHub Pages. All runtime asset URLs go through web/src/base.js and Vite builds with a relative base, so the site works under any sub-path. The original GLBs (web/public/assets/models/*.glb) are not in the repository (the Blender scripts rebuild them); the site uses the meshopt copies in web/public/assets/m/.

Pipeline

blender/textures/build_textures.py   procedural tileable textures (whitewash, tiles, wood, lattice, bamboo, indigo cloth, foliage atlases, caustics…)
blender/textures/sky_process.py      Poly Haven sky HDRIs -> web sky + environment light + sun/moon direction
blender/textures/import_polyhaven.py Poly Haven scanned textures -> web textures
blender/assets/*.py                  single assets: lantern, wupeng boat, stone arch bridge, willow, broadleaf trees, peach blossom, river stones, lilies, reeds, props
blender/assets/stonekit.py           embankment kit: ashlar blocks, coping, step slabs, mooring stones, mooring posts (one GLB each, instanced on the web)
blender/world/house.py               house generator v3: lattice doors / plank shutters / plaster fronts, tiled pent roofs on brackets, real lattice over paper, horse-head gables, stacked-tile ridges, laundry poles
blender/world/town.py                procedural town: frontage plots, house types, fire walls by height, walled gardens; only the hero house at the landing is pinned by hand
blender/world/build_world.py         the whole town: land blocks, stone embankments, walkways, landings, houses, lantern strings, tea pavilion, distant hills
blender/world/test_house.py          close-up acceptance renders of sample houses (1–2 m)
blender/tools/beauty_asset.py        close-up acceptance renders of one asset (low warm sun)
tools/compress_models.sh             meshopt compression into web/public/assets/m/
tools/shoot.mjs                      headless browser screenshots for reviews

Run any Blender script with blender -b --factory-startup -P <script>. Assets write a GLB, blender/out/<…>/report.json (triangles, problem list) and preview renders.

Specs: docs/asset-contract.md (coordinates, naming, materials, budgets), docs/art-direction.md, docs/quality-bar.md (in Chinese).

Web app (web/src)

File	What it does
main.js	boot, main loop, URL parameters, intro shot
presets.js	every parameter of the five looks (sun, sky, fog, water, lights, grade, particles, mist, sound, cloud shadows)
day.js	the day as one loop (golden hour → blue hour → night → dawn → morning → afternoon, ~7 min): stops, their timing, sun and moon paths
atmosphere.js	the day clock and smooth blending between hours
world/sky.js	photographic sky with crossfades, environment light, moon, height fog
world/water.js	water: reflection, refraction, turbidity, absorption, glitter, moon path, rain ripples, wind patches, the boat's wake and bow waves
world/clouds.js	cloud shadows drifting over the town, hills and water
world/materials.js	TSL materials rebuilt by name: water-line stains, moss, caustics, weathering, wind, window and lantern glow
world/world.js	loads the town and assets, instancing, detail LOD, BVH
world/grass.js / fx.js	grass, fireflies, motes, rain
post.js	SSAO (ambient only), mist banks, bloom, depth of field, grade, FXAA
camera.js	viewpoints, drag / scroll / WASD, the boat ride (with a glide onto the bow), autofocus
boat.js	the helm: steering, rowing and return to the line; free water measured along the loop so the boat never meets a wall
audio.js	Web Audio ambience synthesised live
ui.js	interface

Performance

• Layers: 0 = main shapes; 1 = fine detail (cover tiles, lattice, brass), main view only and hidden beyond 28 m; 2 = under water (canal bed, pebbles), never reflected; 3 = stone kit and trees, kept out of the SSAO pre-pass.
• The key light's shadow map is redrawn when the light moves and every fifth frame otherwise.
• Boat parts are merged by material on load (quantized meshopt attributes are expanded to float first).
• On the development Mac at 1600×900: about 10 ms per frame for the hero view and 8 ms for the landing (after warm-up).

Credits and licenses

• Sky HDRIs (CC0, Poly Haven): kloofendal_48d_partly_cloudy_puresky, kloppenheim_06_puresky, qwantani_dusk_2_puresky, kloppenheim_07_puresky, overcast_soil_puresky
• Scanned textures (CC0, Poly Haven): white_rough_plaster, rock_tile_floor, stone_tiles_02, grassy_cobblestone, rock_boulder_dry, weathered_brown_planks, ganges_river_pebbles, bark_brown_02, granular_concrete
• Everything else (textures, every model and all sound) is generated by the scripts in this repository.
• Concept art (reference only, not used on the site): assets/generated/codex/concept-v1/, made with an AI image model.

How it was made

Claude (Opus 5.5) planned the work, built the web side and integrated everything; Codex (GPT-6 Astra) wrote asset scripts, the art specs and the reviews. Tasks and reviews are in .agent-tasks/. Every round ends the same way: screenshots from the reference angles go side by side with the references, a deliberately harsh art-director review lists fatal / important / nice-to-have problems, and the fatal and important ones are fixed before the round is shown.