Physics Scene

This recipe shows how to build a simple physics-driven scene with colorful falling objects.

The concept

We’ll create boxes that fall onto a platform, using scroll position to control the simulation. As you scroll through this section, watch the background — the scene comes alive.

Live demo

Scroll through this section to see boxes drop onto the platform. The scroll position controls how many boxes have fallen — scroll slowly to watch them land one by one.

The scene uses Guacamelee-inspired colors: vibrant magentas, teals, and golds against a dark backdrop.

How it works

Each box position is pre-calculated based on a simple physics simulation. The progress prop (0 to 1) determines how far into the simulation we are:

<script>
  import { T } from '@threlte/core';

  let { progress } = $props();

  // progress controls how many boxes are visible
  // and how far they've fallen
</script>

The scroll-driven approach means zero GPU cost when you’re reading other sections. The Canvas only renders frames while this section is in the viewport.

Building your own

To create a scroll-driven scene in your docs:

Create a scene component in src/lib/scene/scenes/
Accept a progress prop (0-1)
Register it in SceneDirector.svelte
Wrap your content in <SceneRegion scene="your-scene-id">

The progress value maps to how far the viewport center has traveled through your <SceneRegion> element — use it to drive any animation you want.