billpwchan/sakura-fantasy

You sit in a tomabune, a reed-roofed river boat, while a boatman sculls you down a river. You pass through:

• morning mist on the shallows;
• an avenue of cherry trees;
• a vermilion drum bridge;
• a village beneath a five-storey pagoda;
• a bamboo gorge;
• a tunnel of a thousand torii;
• a lake where a torii stands in the water.

Then the season turns and the journey begins again.

Every tree, flower and blade of grass is drawn from photogrammetry scans of real Japanese plants. The light follows the sun through the day, and the weather changes. The music is composed as you travel, for koto, shakuhachi and shō, among field recordings from temples and gardens in Kyoto and beyond.

It is about 10,000 lines of plain JavaScript on three.js, with no engine and no framework.

_{The same trees across the year: blossom, then summer green, then autumn colour turning leaf by leaf, then snow on the boughs.}

朝霧の瀬  Shallows of Morning Mist Reeds, stones and heavy dawn mist.	桜並木  The Cherry Avenue Banks lined with sakura, and rafts of fallen petals.
朱の太鼓橋  The Vermilion Drum Bridge The boat passes under the arch.	五重塔の里  Village of the Five-Storey Pagoda A pagoda, a hall and a belfry. The bell tolls as you arrive.
竹林峡  The Bamboo Gorge Cliffs, walls of bamboo and a waterfall.	千本鳥居  A Thousand Gates A straight channel under forty-one vermilion gates.
御神木の湖  Lake of the Sacred Tree An island's giant sakura and a torii standing in the water.	花火  Summer fireworks On summer nights. Each boom arrives at the speed of sound.

Each place opens with a classical haiku chosen for it and for the season.

Thirteen of these scenes are free to download as 4K wallpapers (3840×2160, straight from the renderer).

Real plants. Leaves, blossom and grasses are rendered in Blender into photo atlases (colour, AO and normal), from CC0 scans of Japanese species:

• sakura, momiji and konara;
• black pine and sugi;
• bamboo, azalea, susuki and reeds.

Trees are grown in code and instanced. They have three detail tiers by distance from the river, and up close they swap to full detail.

Light, air and weather.

• A sun and sky for any hour, with height fog and god rays.
• Five weathers: clear, mist, rain, storm and snow.
• Snow that settles on boughs, roofs and banks.

Water. Reflections stretch and break in the ripples, and blur with distance as real water does, so the river never reads as a mirror. Gusts roughen it in drifting patches. Lanterns, fireflies and fireworks all reflect, and each burst lays a broken column of its colour on the water. The boat leaves a Kelvin wake and a bow wave, foam gathers along the shore and petals rest on the surface.

The boat and its crew.

• The boat is built plank by plank in Blender.
• The boatman and the passenger are MPFB bodies, dressed in clothes made for them: a hanten and sugegasa; a furisode, brocade obi and a red wagasa.
• He sculls with two-bone IK, his hands on the ro through every stroke.

Night. Lit windows, foxfire wisps and lanterns floating on the lake. Sky lanterns rise from the island.

Sound.

Every recording is placed by place, season and hour. The score →

Smooth. The valley is generated in a pool of workers. A frame-time governor keeps the render scale where frames hold their budget. The quick tier draws the first frame, and full-detail assets stream in behind it.

The kanji dock sets the season, hour, weather, camera and sound, and the scroll of the journey jumps to any place.

git clone https://github.com/billpwchan/sakura-fantasy.git
cd sakura-fantasy
npm install
npm run dev          # http://127.0.0.1:5190

npm run build writes a static site to dist/ that any web server can host. The assets are in the repository, so nothing else needs downloading.

Any scene can be opened straight from the URL, skipping the opening:

For example, autumn dusk at the bridge or a winter night in the village.

On an Apple M4 Max at 1920×1080 @2×, the full tier runs at 60 fps with a p95 frame time of 18.4 ms. The governor holds the render scale at 1.0 for most of the river and 0.85–0.95 in the cherry avenue, the heaviest stretch. Phones and tablets get the quick tier.

src/
├── main.js        boot, frame loop, input
├── core/          render passes, post chain, shared uniforms, loaders
├── env/           time of day, season and weather
├── world/         layout, terrain, water, trees, grass, buildings, props, boat, people, sky
├── fx/            petals, leaves, snow, rain, fireflies, wisps, lanterns, fireworks
├── journey/       the voyage, the camera director, the haiku
├── audio/         score, soundscape, sound bank
└── ui/            loader, title, chapter cards, dock, About, photo mode
public/assets/     textures and atlases, models, KTX2 transcoder, audio
pipeline/          offline asset tools (Blender, Node, Python)
scripts/           texture fetch, perf and capture harnesses
deploy/            Docker + Caddy deployment

The same author's other real-time scenes, each open source and running in the browser.

Halcyon A tropical atoll through one day: FFT ocean, reef, bioluminescent night · live

移ろい Utsuroi A Kyoto house and garden, walked from first light to last · live

霓虹天頂 Neon Zenith A rain-soaked cyberpunk Hong Kong you can fly through (WebGPU) · live

The plants, textures, people and most recordings are CC0 or public domain. Two statues and six recordings are CC BY. Every source and its author is listed in CREDITS.md.

The project was inspired by Meng To's Sakura River Valley. None of its code or assets are used.

The code is under the MIT licence. The assets keep their own licences, listed in CREDITS.md.