Added <Ballpit /> background

src/constants/Categories.ts

@@ -90,6 +90,7 @@ export const CATEGORIES = [
       'Threads',
       'Grid Motion',
       'Orb',
+      'Ballpit'
     ]
   }
 ];

src/constants/Components.ts

@@ -75,7 +75,8 @@ const backgrounds = {
   'hyperspeed': () => import('../demo/Backgrounds/HyperspeedDemo.vue'),
   'shape-blur': () => import('../demo/Backgrounds/ShapeBlurDemo.vue'),
   'balatro': () => import('../demo/Backgrounds/BalatroDemo.vue'),
-  'orb': () => import('../demo/Backgrounds/OrbDemo.vue')
+  'orb': () => import('../demo/Backgrounds/OrbDemo.vue'),
+  'ballpit': () => import('../demo/Backgrounds/BallpitDemo.vue'),
 };
 
 export const componentMap = {

src/constants/code/Backgrounds/ballpitCode.ts

@@ -0,0 +1,23 @@
+import code from '@content/Backgrounds/Ballpit/Ballpit.vue?raw';
+import type { CodeObject } from '../../../types/code';
+
+export const ballpit: CodeObject = {
+  cli: `npx jsrepo add https://vue-bits.dev/ui/Backgrounds/Ballpit`,
+  installation: `npm i three`,
+  usage: `<template>
+  <div class="relative w-full h-[500px] overflow-hidden">
+    <Ballpit
+      :count="200"
+      :gravity="0.7"
+      :friction="0.8"
+      :wallBounce="0.95"
+      :followCursor="true"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import Ballpit from "./Ballpit.vue";
+</script>`,
+  code
+};

src/content/Backgrounds/Ballpit/Ballpit.vue

@@ -0,0 +1,909 @@
+<script setup lang="ts">
+import { gsap } from 'gsap';
+import { Observer } from 'gsap/Observer';
+import {
+  ACESFilmicToneMapping,
+  AmbientLight,
+  Clock,
+  Color,
+  InstancedMesh,
+  MathUtils,
+  MeshPhysicalMaterial,
+  Object3D,
+  PerspectiveCamera,
+  Plane,
+  PMREMGenerator,
+  PointLight,
+  Raycaster,
+  Scene,
+  ShaderChunk,
+  SphereGeometry,
+  SRGBColorSpace,
+  Vector2,
+  Vector3,
+  WebGLRenderer,
+  type MeshPhysicalMaterialParameters,
+  type WebGLRendererParameters
+} from 'three';
+import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
+import { defineProps, onMounted, onUnmounted, ref } from 'vue';
+
+gsap.registerPlugin(Observer);
+
+interface MaterialParams extends MeshPhysicalMaterialParameters {
+  metalness?: number;
+  roughness?: number;
+  clearcoat?: number;
+  clearcoatRoughness?: number;
+}
+
+interface Props {
+  className?: string;
+  followCursor?: boolean;
+  count?: number;
+  colors?: number[];
+  ambientColor?: number;
+  ambientIntensity?: number;
+  lightIntensity?: number;
+  materialParams?: MaterialParams;
+  minSize?: number;
+  maxSize?: number;
+  size0?: number;
+  gravity?: number;
+  friction?: number;
+  wallBounce?: number;
+  maxVelocity?: number;
+  maxX?: number;
+  maxY?: number;
+  maxZ?: number;
+  controlSphere0?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  className: '',
+  followCursor: true,
+  count: 200,
+  colors: () => [0, 0, 0],
+  ambientColor: 0xffffff,
+  ambientIntensity: 1,
+  lightIntensity: 200,
+  materialParams: () => ({
+    metalness: 0.5,
+    roughness: 0.5,
+    clearcoat: 1,
+    clearcoatRoughness: 0.15
+  }),
+  minSize: 0.5,
+  maxSize: 1,
+  size0: 1,
+  gravity: 0.5,
+  friction: 0.9975,
+  wallBounce: 0.95,
+  maxVelocity: 0.15,
+  maxX: 5,
+  maxY: 5,
+  maxZ: 2,
+  controlSphere0: false
+});
+
+const canvasRef = ref<HTMLCanvasElement | null>(null);
+const spheresInstanceRef = ref<CreateBallpitReturn | null>(null);
+
+interface PostProcessing {
+  setSize: (width: number, height: number) => void;
+  render: () => void;
+  dispose: () => void;
+}
+
+interface XConfig {
+  canvas?: HTMLCanvasElement;
+  id?: string;
+  rendererOptions?: Partial<WebGLRendererParameters>;
+  size?: 'parent' | { width: number; height: number };
+}
+
+interface SizeData {
+  width: number;
+  height: number;
+  wWidth: number;
+  wHeight: number;
+  ratio: number;
+  pixelRatio: number;
+}
+
+class X {
+  #config: XConfig;
+  #postprocessing: PostProcessing | null = null;
+  #resizeObserver?: ResizeObserver;
+  #intersectionObserver?: IntersectionObserver;
+  #resizeTimer?: number;
+  #animationFrameId: number = 0;
+  #clock: Clock = new Clock();
+  #animationState = { elapsed: 0, delta: 0 };
+  #isAnimating: boolean = false;
+  #isVisible: boolean = false;
+
+  canvas!: HTMLCanvasElement;
+  camera!: PerspectiveCamera;
+  cameraMinAspect?: number;
+  cameraMaxAspect?: number;
+  cameraFov!: number;
+  maxPixelRatio?: number;
+  minPixelRatio?: number;
+  scene!: Scene;
+  renderer!: WebGLRenderer;
+  size: SizeData = {
+    width: 0,
+    height: 0,
+    wWidth: 0,
+    wHeight: 0,
+    ratio: 0,
+    pixelRatio: 0
+  };
+
+  render: () => void = this.#render.bind(this);
+  onBeforeRender: (state: { elapsed: number; delta: number }) => void = () => {};
+  onAfterRender: (state: { elapsed: number; delta: number }) => void = () => {};
+  onAfterResize: (size: SizeData) => void = () => {};
+  isDisposed: boolean = false;
+
+  constructor(config: XConfig) {
+    this.#config = { ...config };
+    this.#initCamera();
+    this.#initScene();
+    this.#initRenderer();
+    this.resize();
+    this.#initObservers();
+  }
+
+  #initCamera() {
+    this.camera = new PerspectiveCamera();
+    this.cameraFov = this.camera.fov;
+  }
+
+  #initScene() {
+    this.scene = new Scene();
+  }
+
+  #initRenderer() {
+    if (this.#config.canvas) {
+      this.canvas = this.#config.canvas;
+    } else if (this.#config.id) {
+      const elem = document.getElementById(this.#config.id);
+      if (elem instanceof HTMLCanvasElement) {
+        this.canvas = elem;
+      } else {
+        console.error('Three: Missing canvas or id parameter');
+      }
+    } else {
+      console.error('Three: Missing canvas or id parameter');
+    }
+    this.canvas!.style.display = 'block';
+    const rendererOptions: WebGLRendererParameters = {
+      canvas: this.canvas,
+      powerPreference: 'high-performance',
+      ...(this.#config.rendererOptions ?? {})
+    };
+    this.renderer = new WebGLRenderer(rendererOptions);
+    this.renderer.outputColorSpace = SRGBColorSpace;
+  }
+
+  #initObservers() {
+    if (!(this.#config.size instanceof Object)) {
+      window.addEventListener('resize', this.#onResize.bind(this));
+      if (this.#config.size === 'parent' && this.canvas.parentNode) {
+        this.#resizeObserver = new ResizeObserver(this.#onResize.bind(this));
+        this.#resizeObserver.observe(this.canvas.parentNode as Element);
+      }
+    }
+    this.#intersectionObserver = new IntersectionObserver(this.#onIntersection.bind(this), {
+      root: null,
+      rootMargin: '0px',
+      threshold: 0
+    });
+    this.#intersectionObserver.observe(this.canvas);
+    document.addEventListener('visibilitychange', this.#onVisibilityChange.bind(this));
+  }
+
+  #onResize() {
+    if (this.#resizeTimer) clearTimeout(this.#resizeTimer);
+    this.#resizeTimer = window.setTimeout(this.resize.bind(this), 100);
+  }
+
+  resize() {
+    let w: number, h: number;
+    if (this.#config.size instanceof Object) {
+      w = this.#config.size.width;
+      h = this.#config.size.height;
+    } else if (this.#config.size === 'parent' && this.canvas.parentNode) {
+      w = (this.canvas.parentNode as HTMLElement).offsetWidth;
+      h = (this.canvas.parentNode as HTMLElement).offsetHeight;
+    } else {
+      w = window.innerWidth;
+      h = window.innerHeight;
+    }
+    this.size.width = w;
+    this.size.height = h;
+    this.size.ratio = w / h;
+    this.#updateCamera();
+    this.#updateRenderer();
+    this.onAfterResize(this.size);
+  }
+
+  #updateCamera() {
+    this.camera.aspect = this.size.width / this.size.height;
+    if (this.camera.isPerspectiveCamera && this.cameraFov) {
+      if (this.cameraMinAspect && this.camera.aspect < this.cameraMinAspect) {
+        this.#adjustFov(this.cameraMinAspect);
+      } else if (this.cameraMaxAspect && this.camera.aspect > this.cameraMaxAspect) {
+        this.#adjustFov(this.cameraMaxAspect);
+      } else {
+        this.camera.fov = this.cameraFov;
+      }
+    }
+    this.camera.updateProjectionMatrix();
+    this.updateWorldSize();
+  }
+
+  #adjustFov(aspect: number) {
+    const tanFov = Math.tan(MathUtils.degToRad(this.cameraFov / 2));
+    const newTan = tanFov / (this.camera.aspect / aspect);
+    this.camera.fov = 2 * MathUtils.radToDeg(Math.atan(newTan));
+  }
+
+  updateWorldSize() {
+    if (this.camera.isPerspectiveCamera) {
+      const fovRad = (this.camera.fov * Math.PI) / 180;
+      this.size.wHeight = 2 * Math.tan(fovRad / 2) * this.camera.position.length();
+      this.size.wWidth = this.size.wHeight * this.camera.aspect;
+    } else {
+      const cam = this.camera as unknown as {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+        isOrthographicCamera: boolean;
+      };
+      if (cam.isOrthographicCamera) {
+        this.size.wHeight = cam.top - cam.bottom;
+        this.size.wWidth = cam.right - cam.left;
+      }
+    }
+  }
+
+  #updateRenderer() {
+    this.renderer.setSize(this.size.width, this.size.height);
+    this.#postprocessing?.setSize(this.size.width, this.size.height);
+    let pr = window.devicePixelRatio;
+    if (this.maxPixelRatio && pr > this.maxPixelRatio) {
+      pr = this.maxPixelRatio;
+    } else if (this.minPixelRatio && pr < this.minPixelRatio) {
+      pr = this.minPixelRatio;
+    }
+    this.renderer.setPixelRatio(pr);
+    this.size.pixelRatio = pr;
+  }
+
+  get postprocessing() {
+    return this.#postprocessing;
+  }
+  set postprocessing(value: PostProcessing | null) {
+    this.#postprocessing = value;
+    if (value) {
+      this.render = value.render.bind(value);
+    } else {
+      this.render = this.#render.bind(this);
+    }
+  }
+
+  #onIntersection(entries: IntersectionObserverEntry[]) {
+    this.#isAnimating = entries[0].isIntersecting;
+    if (this.#isAnimating) {
+      this.#startAnimation();
+    } else {
+      this.#stopAnimation();
+    }
+  }
+
+  #onVisibilityChange() {
+    if (this.#isAnimating) {
+      if (document.hidden) {
+        this.#stopAnimation();
+      } else {
+        this.#startAnimation();
+      }
+    }
+  }
+
+  #startAnimation() {
+    if (this.#isVisible) return;
+    const animateFrame = () => {
+      this.#animationFrameId = requestAnimationFrame(animateFrame);
+      this.#animationState.delta = this.#clock.getDelta();
+      this.#animationState.elapsed += this.#animationState.delta;
+      this.onBeforeRender(this.#animationState);
+      this.render();
+      this.onAfterRender(this.#animationState);
+    };
+    this.#isVisible = true;
+    this.#clock.start();
+    animateFrame();
+  }
+
+  #stopAnimation() {
+    if (this.#isVisible) {
+      cancelAnimationFrame(this.#animationFrameId);
+      this.#isVisible = false;
+      this.#clock.stop();
+    }
+  }
+
+  #render() {
+    this.renderer.render(this.scene, this.camera);
+  }
+
+  clear() {
+    this.scene.traverse(obj => {
+      const mesh = obj as unknown as {
+        isMesh?: boolean;
+        material?: {
+          dispose: () => void;
+          [key: string]: unknown;
+        };
+        geometry?: {
+          dispose: () => void;
+        };
+      };
+      if (mesh.isMesh && mesh.material && mesh.geometry) {
+        if (typeof mesh.material === 'object' && mesh.material !== null) {
+          Object.keys(mesh.material).forEach(key => {
+            const matProp = mesh.material![key] as unknown;
+            if (matProp && typeof matProp === 'object' && matProp !== null) {
+              const disposable = matProp as { dispose?: () => void };
+              if (typeof disposable.dispose === 'function') {
+                disposable.dispose();
+              }
+            }
+          });
+          mesh.material.dispose();
+          mesh.geometry.dispose();
+        }
+      }
+    });
+    this.scene.clear();
+  }
+
+  dispose() {
+    this.#onResizeCleanup();
+    this.#stopAnimation();
+    this.clear();
+    this.#postprocessing?.dispose();
+    this.renderer.dispose();
+    this.isDisposed = true;
+  }
+
+  #onResizeCleanup() {
+    window.removeEventListener('resize', this.#onResize.bind(this));
+    this.#resizeObserver?.disconnect();
+    this.#intersectionObserver?.disconnect();
+    document.removeEventListener('visibilitychange', this.#onVisibilityChange.bind(this));
+  }
+}
+
+interface WConfig {
+  count: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+  maxSize: number;
+  minSize: number;
+  size0: number;
+  gravity: number;
+  friction: number;
+  wallBounce: number;
+  maxVelocity: number;
+  controlSphere0?: boolean;
+  followCursor?: boolean;
+}
+
+class W {
+  config: WConfig;
+  positionData: Float32Array;
+  velocityData: Float32Array;
+  sizeData: Float32Array;
+  center: Vector3 = new Vector3();
+
+  constructor(config: WConfig) {
+    this.config = config;
+    this.positionData = new Float32Array(3 * config.count).fill(0);
+    this.velocityData = new Float32Array(3 * config.count).fill(0);
+    this.sizeData = new Float32Array(config.count).fill(1);
+    this.center = new Vector3();
+    this.#initializePositions();
+    this.setSizes();
+  }
+
+  #initializePositions() {
+    const { config, positionData } = this;
+    this.center.toArray(positionData, 0);
+    for (let i = 1; i < config.count; i++) {
+      const idx = 3 * i;
+      positionData[idx] = MathUtils.randFloatSpread(2 * config.maxX);
+      positionData[idx + 1] = MathUtils.randFloatSpread(2 * config.maxY);
+      positionData[idx + 2] = MathUtils.randFloatSpread(2 * config.maxZ);
+    }
+  }
+
+  setSizes() {
+    const { config, sizeData } = this;
+    sizeData[0] = config.size0;
+    for (let i = 1; i < config.count; i++) {
+      sizeData[i] = MathUtils.randFloat(config.minSize, config.maxSize);
+    }
+  }
+
+  update(deltaInfo: { delta: number }) {
+    const { config, center, positionData, sizeData, velocityData } = this;
+    let startIdx = 0;
+    if (config.controlSphere0) {
+      startIdx = 1;
+      const firstVec = new Vector3().fromArray(positionData, 0);
+      firstVec.lerp(center, 0.1).toArray(positionData, 0);
+      new Vector3(0, 0, 0).toArray(velocityData, 0);
+    }
+    for (let idx = startIdx; idx < config.count; idx++) {
+      const base = 3 * idx;
+      const pos = new Vector3().fromArray(positionData, base);
+      const vel = new Vector3().fromArray(velocityData, base);
+      vel.y -= deltaInfo.delta * config.gravity * sizeData[idx];
+      vel.multiplyScalar(config.friction);
+      vel.clampLength(0, config.maxVelocity);
+      pos.add(vel);
+      pos.toArray(positionData, base);
+      vel.toArray(velocityData, base);
+    }
+    for (let idx = startIdx; idx < config.count; idx++) {
+      const base = 3 * idx;
+      const pos = new Vector3().fromArray(positionData, base);
+      const vel = new Vector3().fromArray(velocityData, base);
+      const radius = sizeData[idx];
+      for (let jdx = idx + 1; jdx < config.count; jdx++) {
+        const otherBase = 3 * jdx;
+        const otherPos = new Vector3().fromArray(positionData, otherBase);
+        const otherVel = new Vector3().fromArray(velocityData, otherBase);
+        const diff = new Vector3().copy(otherPos).sub(pos);
+        const dist = diff.length();
+        const sumRadius = radius + sizeData[jdx];
+        if (dist < sumRadius) {
+          const overlap = sumRadius - dist;
+          const correction = diff.normalize().multiplyScalar(0.5 * overlap);
+          const velCorrection = correction.clone().multiplyScalar(Math.max(vel.length(), 1));
+          pos.sub(correction);
+          vel.sub(velCorrection);
+          pos.toArray(positionData, base);
+          vel.toArray(velocityData, base);
+          otherPos.add(correction);
+          otherVel.add(correction.clone().multiplyScalar(Math.max(otherVel.length(), 1)));
+          otherPos.toArray(positionData, otherBase);
+          otherVel.toArray(velocityData, otherBase);
+        }
+      }
+      if (config.controlSphere0) {
+        const diff = new Vector3().copy(new Vector3().fromArray(positionData, 0)).sub(pos);
+        const d = diff.length();
+        const sumRadius0 = radius + sizeData[0];
+        if (d < sumRadius0) {
+          const correction = diff.normalize().multiplyScalar(sumRadius0 - d);
+          const velCorrection = correction.clone().multiplyScalar(Math.max(vel.length(), 2));
+          pos.sub(correction);
+          vel.sub(velCorrection);
+        }
+      }
+      if (Math.abs(pos.x) + radius > config.maxX) {
+        pos.x = Math.sign(pos.x) * (config.maxX - radius);
+        vel.x = -vel.x * config.wallBounce;
+      }
+      if (config.gravity === 0) {
+        if (Math.abs(pos.y) + radius > config.maxY) {
+          pos.y = Math.sign(pos.y) * (config.maxY - radius);
+          vel.y = -vel.y * config.wallBounce;
+        }
+      } else if (pos.y - radius < -config.maxY) {
+        pos.y = -config.maxY + radius;
+        vel.y = -vel.y * config.wallBounce;
+      }
+      const maxBoundary = Math.max(config.maxZ, config.maxSize);
+      if (Math.abs(pos.z) + radius > maxBoundary) {
+        pos.z = Math.sign(pos.z) * (config.maxZ - radius);
+        vel.z = -vel.z * config.wallBounce;
+      }
+      pos.toArray(positionData, base);
+      vel.toArray(velocityData, base);
+    }
+  }
+}
+
+interface ShaderUniforms {
+  [key: string]: { value: number | Vector2 | Vector3 | Color | boolean };
+}
+
+interface ShaderObject {
+  uniforms: ShaderUniforms;
+  fragmentShader: string;
+  vertexShader: string;
+}
+
+interface UniformValue {
+  value: number | Vector2 | Vector3 | Color | boolean;
+}
+
+class Y extends MeshPhysicalMaterial {
+  uniforms: { [key: string]: UniformValue } = {
+    thicknessDistortion: { value: 0.1 },
+    thicknessAmbient: { value: 0 },
+    thicknessAttenuation: { value: 0.1 },
+    thicknessPower: { value: 2 },
+    thicknessScale: { value: 10 }
+  };
+
+  declare defines: { [key: string]: string };
+
+  constructor(params: MaterialParams) {
+    super(params);
+    this.defines = { USE_UV: '' };
+    this.onBeforeCompile = shader => {
+      Object.assign(shader.uniforms, this.uniforms);
+      shader.fragmentShader =
+        `
+        uniform float thicknessPower;
+        uniform float thicknessScale;
+        uniform float thicknessDistortion;
+        uniform float thicknessAmbient;
+        uniform float thicknessAttenuation;
+        ` + shader.fragmentShader;
+      shader.fragmentShader = shader.fragmentShader.replace(
+        'void main() {',
+        `
+        void RE_Direct_Scattering(const in IncidentLight directLight, const in vec2 uv, const in vec3 geometryPosition, const in vec3 geometryNormal, const in vec3 geometryViewDir, const in vec3 geometryClearcoatNormal, inout ReflectedLight reflectedLight) {
+          vec3 scatteringHalf = normalize(directLight.direction + (geometryNormal * thicknessDistortion));
+          float scatteringDot = pow(saturate(dot(geometryViewDir, -scatteringHalf)), thicknessPower) * thicknessScale;
+          #ifdef USE_COLOR
+            vec3 scatteringIllu = (scatteringDot + thicknessAmbient) * vColor;
+          #else
+            vec3 scatteringIllu = (scatteringDot + thicknessAmbient) * diffuse;
+          #endif
+          reflectedLight.directDiffuse += scatteringIllu * thicknessAttenuation * directLight.color;
+        }
+
+        void main() {
+        `
+      );
+      const lightsChunk = ShaderChunk.lights_fragment_begin.replace(
+        /RE_Direct\( directLight, geometryPosition, geometryNormal, geometryViewDir, geometryClearcoatNormal, material, reflectedLight \);/g,
+        `
+          RE_Direct( directLight, geometryPosition, geometryNormal, geometryViewDir, geometryClearcoatNormal, material, reflectedLight );
+          RE_Direct_Scattering(directLight, vUv, geometryPosition, geometryNormal, geometryViewDir, geometryClearcoatNormal, reflectedLight);
+        `
+      );
+      shader.fragmentShader = shader.fragmentShader.replace('#include <lights_fragment_begin>', lightsChunk);
+      if (this.onBeforeCompile2) this.onBeforeCompile2(shader);
+    };
+  }
+  onBeforeCompile2?: (shader: ShaderObject) => void;
+}
+
+const XConfig = {
+  count: 200,
+  colors: [0, 0, 0],
+  ambientColor: 0xffffff,
+  ambientIntensity: 1,
+  lightIntensity: 200,
+  materialParams: {
+    metalness: 0.5,
+    roughness: 0.5,
+    clearcoat: 1,
+    clearcoatRoughness: 0.15
+  },
+  minSize: 0.5,
+  maxSize: 1,
+  size0: 1,
+  gravity: 0.5,
+  friction: 0.9975,
+  wallBounce: 0.95,
+  maxVelocity: 0.15,
+  maxX: 5,
+  maxY: 5,
+  maxZ: 2,
+  controlSphere0: false,
+  followCursor: true
+};
+
+const U = new Object3D();
+
+let globalPointerActive = false;
+const pointerPosition = new Vector2();
+
+interface PointerData {
+  position: Vector2;
+  nPosition: Vector2;
+  hover: boolean;
+  onEnter: (data: PointerData) => void;
+  onMove: (data: PointerData) => void;
+  onClick: (data: PointerData) => void;
+  onLeave: (data: PointerData) => void;
+  dispose?: () => void;
+}
+
+const pointerMap = new Map<HTMLElement, PointerData>();
+
+function createPointerData(options: Partial<PointerData> & { domElement: HTMLElement }): PointerData {
+  const defaultData: PointerData = {
+    position: new Vector2(),
+    nPosition: new Vector2(),
+    hover: false,
+    onEnter: () => {},
+    onMove: () => {},
+    onClick: () => {},
+    onLeave: () => {},
+    ...options
+  };
+  if (!pointerMap.has(options.domElement)) {
+    pointerMap.set(options.domElement, defaultData);
+    if (!globalPointerActive) {
+      document.body.addEventListener('pointermove', onPointerMove as EventListener);
+      document.body.addEventListener('pointerleave', onPointerLeave as EventListener);
+      document.body.addEventListener('click', onPointerClick as EventListener);
+      globalPointerActive = true;
+    }
+  }
+  defaultData.dispose = () => {
+    pointerMap.delete(options.domElement);
+    if (pointerMap.size === 0) {
+      document.body.removeEventListener('pointermove', onPointerMove as EventListener);
+      document.body.removeEventListener('pointerleave', onPointerLeave as EventListener);
+      document.body.removeEventListener('click', onPointerClick as EventListener);
+      globalPointerActive = false;
+    }
+  };
+  return defaultData;
+}
+
+function onPointerMove(e: PointerEvent) {
+  pointerPosition.set(e.clientX, e.clientY);
+  for (const [elem, data] of pointerMap) {
+    const rect = elem.getBoundingClientRect();
+    if (isInside(rect)) {
+      updatePointerData(data, rect);
+      if (!data.hover) {
+        data.hover = true;
+        data.onEnter(data);
+      }
+      data.onMove(data);
+    } else if (data.hover) {
+      data.hover = false;
+      data.onLeave(data);
+    }
+  }
+}
+
+function onPointerClick(e: PointerEvent) {
+  pointerPosition.set(e.clientX, e.clientY);
+  for (const [elem, data] of pointerMap) {
+    const rect = elem.getBoundingClientRect();
+    updatePointerData(data, rect);
+    if (isInside(rect)) data.onClick(data);
+  }
+}
+
+function onPointerLeave() {
+  for (const data of pointerMap.values()) {
+    if (data.hover) {
+      data.hover = false;
+      data.onLeave(data);
+    }
+  }
+}
+
+function updatePointerData(data: PointerData, rect: DOMRect) {
+  data.position.set(pointerPosition.x - rect.left, pointerPosition.y - rect.top);
+  data.nPosition.set((data.position.x / rect.width) * 2 - 1, (-data.position.y / rect.height) * 2 + 1);
+}
+
+function isInside(rect: DOMRect) {
+  return (
+    pointerPosition.x >= rect.left &&
+    pointerPosition.x <= rect.left + rect.width &&
+    pointerPosition.y >= rect.top &&
+    pointerPosition.y <= rect.top + rect.height
+  );
+}
+
+class Z extends InstancedMesh {
+  config: typeof XConfig;
+  physics: W;
+  ambientLight: AmbientLight | undefined;
+  light: PointLight | undefined;
+
+  constructor(renderer: WebGLRenderer, params: Partial<typeof XConfig> = {}) {
+    const config = { ...XConfig, ...params };
+    const roomEnv = new RoomEnvironment();
+    const pmrem = new PMREMGenerator(renderer);
+    const envTexture = pmrem.fromScene(roomEnv).texture;
+    const geometry = new SphereGeometry();
+    const material = new Y({ envMap: envTexture, ...config.materialParams });
+    material.envMapRotation.x = -Math.PI / 2;
+    super(geometry, material, config.count);
+    this.config = config;
+    this.physics = new W(config);
+    this.#setupLights();
+    this.setColors(config.colors);
+  }
+
+  #setupLights() {
+    this.ambientLight = new AmbientLight(this.config.ambientColor, this.config.ambientIntensity);
+    this.add(this.ambientLight);
+    this.light = new PointLight(this.config.colors[0], this.config.lightIntensity);
+    this.add(this.light);
+  }
+
+  setColors(colors: number[]) {
+    if (Array.isArray(colors) && colors.length > 1) {
+      const colorUtils = (function (colorsArr: number[]) {
+        let baseColors: number[] = colorsArr;
+        let colorObjects: Color[] = [];
+        baseColors.forEach(col => {
+          colorObjects.push(new Color(col));
+        });
+        return {
+          setColors: (cols: number[]) => {
+            baseColors = cols;
+            colorObjects = [];
+            baseColors.forEach(col => {
+              colorObjects.push(new Color(col));
+            });
+          },
+          getColorAt: (ratio: number, out: Color = new Color()) => {
+            const clamped = Math.max(0, Math.min(1, ratio));
+            const scaled = clamped * (baseColors.length - 1);
+            const idx = Math.floor(scaled);
+            const start = colorObjects[idx];
+            if (idx >= baseColors.length - 1) return start.clone();
+            const alpha = scaled - idx;
+            const end = colorObjects[idx + 1];
+            out.r = start.r + alpha * (end.r - start.r);
+            out.g = start.g + alpha * (end.g - start.g);
+            out.b = start.b + alpha * (end.b - start.b);
+            return out;
+          }
+        };
+      })(colors);
+      for (let idx = 0; idx < this.count; idx++) {
+        this.setColorAt(idx, colorUtils.getColorAt(idx / this.count));
+        if (idx === 0) {
+          this.light!.color.copy(colorUtils.getColorAt(idx / this.count));
+        }
+      }
+
+      if (!this.instanceColor) return;
+      this.instanceColor.needsUpdate = true;
+    }
+  }
+
+  update(deltaInfo: { delta: number }) {
+    this.physics.update(deltaInfo);
+    for (let idx = 0; idx < this.count; idx++) {
+      U.position.fromArray(this.physics.positionData, 3 * idx);
+      if (idx === 0 && this.config.followCursor === false) {
+        U.scale.setScalar(0);
+      } else {
+        U.scale.setScalar(this.physics.sizeData[idx]);
+      }
+      U.updateMatrix();
+      this.setMatrixAt(idx, U.matrix);
+      if (idx === 0) this.light!.position.copy(U.position);
+    }
+    this.instanceMatrix.needsUpdate = true;
+  }
+}
+
+interface CreateBallpitReturn {
+  three: X;
+  spheres: Z;
+  setCount: (count: number) => void;
+  togglePause: () => void;
+  dispose: () => void;
+}
+
+function createBallpit(canvas: HTMLCanvasElement, config: Partial<typeof XConfig> = {}): CreateBallpitReturn {
+  const threeInstance = new X({
+    canvas,
+    size: 'parent',
+    rendererOptions: { antialias: true, alpha: true }
+  });
+  let spheres: Z;
+  threeInstance.renderer.toneMapping = ACESFilmicToneMapping;
+  threeInstance.camera.position.set(0, 0, 20);
+  threeInstance.camera.lookAt(0, 0, 0);
+  threeInstance.cameraMaxAspect = 1.5;
+  threeInstance.resize();
+  initialize(config);
+  const raycaster = new Raycaster();
+  const plane = new Plane(new Vector3(0, 0, 1), 0);
+  const intersectionPoint = new Vector3();
+  let isPaused = false;
+  const pointerData = createPointerData({
+    domElement: canvas,
+    onMove() {
+      raycaster.setFromCamera(pointerData.nPosition, threeInstance.camera);
+      threeInstance.camera.getWorldDirection(plane.normal);
+      raycaster.ray.intersectPlane(plane, intersectionPoint);
+      spheres.physics.center.copy(intersectionPoint);
+      spheres.config.controlSphere0 = true;
+    },
+    onLeave() {
+      spheres.config.controlSphere0 = false;
+    }
+  });
+  function initialize(cfg: Partial<typeof XConfig>) {
+    if (spheres) {
+      threeInstance.clear();
+      threeInstance.scene.remove(spheres);
+    }
+    spheres = new Z(threeInstance.renderer, cfg);
+    threeInstance.scene.add(spheres);
+  }
+  threeInstance.onBeforeRender = deltaInfo => {
+    if (!isPaused) spheres.update(deltaInfo);
+  };
+  threeInstance.onAfterResize = size => {
+    spheres.config.maxX = size.wWidth / 2;
+    spheres.config.maxY = size.wHeight / 2;
+  };
+  return {
+    three: threeInstance,
+    get spheres() {
+      return spheres;
+    },
+    setCount(count: number) {
+      initialize({ ...spheres.config, count });
+    },
+    togglePause() {
+      isPaused = !isPaused;
+    },
+    dispose() {
+      pointerData.dispose?.();
+      threeInstance.dispose();
+    }
+  };
+}
+
+onMounted(() => {
+  const canvas = canvasRef.value;
+  if (!canvas) return;
+
+  const { followCursor, ...restProps } = props;
+
+  const safeMaterialParams = {
+    metalness: props.materialParams.metalness ?? 0.5,
+    roughness: props.materialParams.roughness ?? 0.5,
+    clearcoat: props.materialParams.clearcoat ?? 1,
+    clearcoatRoughness: props.materialParams.clearcoatRoughness ?? 0.15
+  };
+
+  spheresInstanceRef.value = createBallpit(canvas, {
+    ...restProps,
+    followCursor,
+    materialParams: safeMaterialParams
+  });
+});
+
+onUnmounted(() => {
+  if (spheresInstanceRef.value) {
+    spheresInstanceRef.value.dispose();
+  }
+});
+</script>
+
+<template>
+  <canvas ref="canvasRef" :class="['w-full', 'h-full', props.className]" />
+</template>

src/demo/Backgrounds/BallpitDemo.vue

@@ -0,0 +1,220 @@
+<template>
+  <TabbedLayout>
+    <template #preview>
+      <div class="relative p-0 h-[500px] overflow-hidden demo-container">
+        <RefreshButton @click="forceRerender" />
+        <p class="z-0 absolute font-black text-[#271e37] text-[200px]">Balls.</p>
+        <Ballpit
+          className="relative"
+          :key="key"
+          :count="count"
+          :gravity="gravity"
+          :friction="friction"
+          :wallBounce="wallBounce"
+          :followCursor="followCursor"
+          :colors="colors"
+        />
+      </div>
+
+      <Customize>
+        <PreviewSwitch title="Display Cursor" v-model="followCursor" @update:model-value="forceRerender" />
+
+        <PreviewSlider
+          title="Ball Count"
+          :min="50"
+          :max="500"
+          :step="10"
+          v-model="count"
+          @onChange="
+            (val: number) => {
+              count = val;
+            }
+          "
+        />
+
+        <PreviewSlider
+          title="Gravity"
+          :min="0.1"
+          :max="1"
+          :step="0.1"
+          v-model="gravity"
+          @onChange="
+            (val: number) => {
+              gravity = val;
+            }
+          "
+        />
+
+        <PreviewSlider
+          title="Friction"
+          :min="0.9"
+          :max="1"
+          :step="0.001"
+          v-model="friction"
+          @onChange="
+            (val: number) => {
+              friction = val;
+            }
+          "
+        />
+
+        <PreviewSlider
+          title="Wall Bounce"
+          :min="0.1"
+          :max="1"
+          :step="0.05"
+          v-model="wallBounce"
+          @onChange="
+            (val: number) => {
+              wallBounce = val;
+            }
+          "
+        />
+      </Customize>
+
+      <PropTable :data="propData" />
+      <Dependencies :dependency-list="['three']" />
+    </template>
+
+    <template #code>
+      <CodeExample :code-object="ballpit" />
+    </template>
+
+    <template #cli>
+      <CliInstallation :command="ballpit.cli" />
+    </template>
+  </TabbedLayout>
+</template>
+
+<script setup lang="ts">
+import { useForceRerender } from '@/composables/useForceRerender';
+import { ref, watch } from 'vue';
+import CliInstallation from '../../components/code/CliInstallation.vue';
+import CodeExample from '../../components/code/CodeExample.vue';
+import Dependencies from '../../components/code/Dependencies.vue';
+import Customize from '../../components/common/Customize.vue';
+import PreviewSlider from '../../components/common/PreviewSlider.vue';
+import PreviewSwitch from '../../components/common/PreviewSwitch.vue';
+import PropTable from '../../components/common/PropTable.vue';
+import RefreshButton from '../../components/common/RefreshButton.vue';
+import TabbedLayout from '../../components/common/TabbedLayout.vue';
+import { ballpit } from '../../constants/code/Backgrounds/ballpitCode';
+import Ballpit from '../../content/Backgrounds/Ballpit/Ballpit.vue';
+
+const { rerenderKey: key, forceRerender } = useForceRerender();
+
+const count = ref(100);
+const gravity = ref(0.5);
+const friction = ref(0.9975);
+const wallBounce = ref(0.95);
+const followCursor = ref(false);
+
+const colors = [0xffffff, 0x000000, 0x27ff64];
+
+watch(
+  [count, gravity, friction, wallBounce, followCursor],
+  () => {
+    forceRerender();
+  },
+  { immediate: true }
+);
+
+const propData = [
+  {
+    name: 'count',
+    type: 'number',
+    default: '200',
+    description: 'Sets the number of balls in the ballpit.'
+  },
+  {
+    name: 'gravity',
+    type: 'number',
+    default: '0.5',
+    description: 'Controls the gravity affecting the balls.'
+  },
+  {
+    name: 'friction',
+    type: 'number',
+    default: '0.9975',
+    description: 'Sets the friction applied to the ball movement.'
+  },
+  {
+    name: 'wallBounce',
+    type: 'number',
+    default: '0.95',
+    description: 'Determines how much balls bounce off walls.'
+  },
+  {
+    name: 'followCursor',
+    type: 'boolean',
+    default: 'true',
+    description: 'Enables or disables the sphere following the cursor.'
+  },
+  {
+    name: 'colors',
+    type: 'array',
+    default: '[0, 0, 0]',
+    description: 'Defines the colors of the balls.'
+  },
+  {
+    name: 'ambientColor',
+    type: 'number',
+    default: '16777215',
+    description: 'Sets the ambient light color.'
+  },
+  {
+    name: 'ambientIntensity',
+    type: 'number',
+    default: '1',
+    description: 'Controls the intensity of ambient light.'
+  },
+  {
+    name: 'lightIntensity',
+    type: 'number',
+    default: '200',
+    description: 'Sets the intensity of the main light source.'
+  },
+  {
+    name: 'minSize',
+    type: 'number',
+    default: '0.5',
+    description: 'Specifies the minimum size of the balls.'
+  },
+  {
+    name: 'maxSize',
+    type: 'number',
+    default: '1',
+    description: 'Specifies the maximum size of the balls.'
+  },
+  {
+    name: 'size0',
+    type: 'number',
+    default: '1',
+    description: 'Initial size value for the cursor ball.'
+  },
+  {
+    name: 'maxVelocity',
+    type: 'number',
+    default: '0.15',
+    description: 'Limits the maximum velocity of the balls.'
+  },
+  {
+    name: 'maxX',
+    type: 'number',
+    default: '5',
+    description: 'Defines the maximum X-coordinate boundary.'
+  },
+  {
+    name: 'maxY',
+    type: 'number',
+    default: '5',
+    description: 'Defines the maximum Y-coordinate boundary.'
+  },
+  {
+    name: 'maxZ',
+    type: 'number',
+    default: '2',
+    description: 'Defines the maximum Z-coordinate boundary.'
+  }
+];
+</script>