# One-shot Tree Leaves Physics Simulation

## Theme: Harbour Plane Tree
A solitary London plane tree (Platanus × acerifolia) stands at the edge of a harbour promenade, cycling through the seasons from spring budburst through autumn leaf fall to winter bareness and back again.

## Systems Specification

### Core Structure
- **Hero Tree**: Single mature plane tree with visible trunk, primary branches, secondary branching, and fine twig structure
- **Canopy**: 150-200 leaves distributed across the branching hierarchy
- **Ground**: Harbour promenade surface with visible paving texture, accumulated leaf litter layer
- **Background**: Subtle harbour atmosphere with cool tones, distant water shimmer

### Season Cycle (Continuous Loop)
1. **Spring Budburst** (15% of cycle)
   - Dormant winter branches awaken
   - Tiny green buds emerge at twig tips
   - Buds swell and unfurl into young leaves
   - Fresh lime-green foliage with high translucency

2. **Summer Canopy** (25% of cycle)
   - Full dense canopy
   - Deep green mature leaves
   - Maximum leaf count and coverage
   - Active photosynthesis glow

3. **Autumn Turn & Shed** (35% of cycle)
   - Progressive colour shift: green → yellow → amber → burnt orange → rust
   - Leaves begin detaching from branch tips inward
   - Increasing wind sensitivity triggers mass shedding
   - Falling leaves spiral and tumble realistically
   - Ground accumulation builds visible carpet

4. **Winter Bareness** (25% of cycle)
   - Nearly bare skeletal branches
   - Last stubborn leaves fall
   - Dormant buds set for next spring
   - Visible branch architecture and harbour backdrop
   - Gradual transition back to budburst

### Physics Systems

#### Branch Physics
- Hierarchical spring-mass system from trunk through primary/secondary branches to twigs
- Secondary motion: parent branch motion propagates to children with phase offset
- Wind response: branches sway with natural frequency based on thickness and length
- Damping: thicker branches move slower, twigs flutter rapidly

#### Leaf Attachment Physics
- Leaves begin rigidly attached to twigs via flexible petiole joints
- Petiole stiffness decreases as autumn progresses
- Wind force accumulates stress on attachment points
- Detachment threshold based on: wind speed × season_factor × random_variation

#### Falling Leaf Physics
- Realistic tumbling: leaves rotate on multiple axes while falling
- Air resistance creates flutter and glide patterns
- Initial velocity inherits from branch motion at moment of release
- Gravity with terminal velocity limiting

#### Wind System
- **Ambient Wind**: Low-frequency Perlin noise field varying across canopy
- **Gust Events**: Periodic stronger pulses from harbour direction
- **User Interaction**: Click/touch creates localised gust; shake on mobile triggers burst
- Wind affects both attached leaves (flutter, stress) and fallen leaves (skittering, drifting)

#### Ground Accumulation
- Fallen leaves settle on paving with realistic collision
- Piles form preferentially in wind shadows
- Older leaves compress and darken over time
- Maximum accumulation prevents infinite buildup (subtle composting/removal)

### Visual Direction

#### Colour Palette
- **Spring**: Fresh lime (#a8d5a2), bud pink (#f4c2c2), bark greys
- **Summer**: Deep forest (#2d5016), bright leaf green (#4a7c2e), harbour blues
- **Autumn**: Gold (#daa520), amber (#ffbf00), rust (#b7410e), burnt orange (#cc5500)
- **Winter**: Bare bark (#5c4033, #4a3728), twig greys, dormant bud browns

#### Atmosphere
- Soft diffused lighting suggesting overcast harbour skies
- Subtle moisture/sheen on leaves and pavement
- Gentle parallax depth between tree, ground, and distant water
- Seasonal colour grading: cool blues in winter, warm golds in autumn

#### Rendering Style
- Clean vector-like aesthetic with organic irregularity
- Leaves as stylised plane tree shapes (palmate lobes)
- Visible but not photorealistic—readable silhouette emphasis
- Smooth anti-aliased lines, no pixelation

### Controls & Interactions
- **Auto-play**: Seamless seasonal loop (default)
- **Season Scrubber**: Drag to manually control season position
- **Wind Toggle**: Calm / Breezy / Gusty presets
- **Shake/Gust**: Mobile shake or desktop click triggers immediate gust
- **Reset**: Return to spring budburst

### Quality Bar
- Canopy must read as one living organism, not particles behind a tree drawing
- Season changes obvious within one viewing loop without user input
- Branch recoil and leaf drag legible before decorative flourishes
- Touch interactions work without hover dependency
- 60fps on modern devices, graceful degradation on lower-end hardware

### Technical Constraints
- Single HTML file with inline CSS and JavaScript
- Canvas-based rendering (2D context)
- No external images or assets
- Responsive to window resizing
- Mobile touch and device orientation support