3.0.0-alpha.0 integration

.changeset/calm-bugs-fixed.md

@@ -0,0 +1,17 @@
+---
+"@react-three/rapier": patch
+"@react-three/rapier-addons": patch
+---
+
+Bug fixes for 3.0:
+
+- Forwarded refs on `RigidBody`, colliders and `InstancedRigidBodies` instances are now cleared when the underlying rapier object is destroyed, instead of pointing at freed objects (#780)
+- Trimesh and convex hull colliders now read geometry positions correctly for interleaved, normalized and quantized attributes, and indices are converted to `Uint32Array`; failing to build a collider now throws a descriptive error (#781, #627)
+- Heightfield collider args are scaled per axis and no longer mutated in place, which compounded scale on remount (#564)
+- `mass`, `density` and `massProperties` collider props now update after mount (#711)
+- Re-export `ActiveCollisionTypes`, `ActiveEvents`, `ActiveHooks` and `QueryFilterFlags` from the package index (#703)
+- Add a regression test for changing the `RigidBody` `type` after mount (#314)
+- `InstancedRigidBodies` no longer spreads `key` into JSX, which warned on React 19 (#691)
+- `InstancedRigidBodies` disables frustum culling on its instanced mesh by default, since cached bounds go stale as bodies move; pass `frustumCulled` to re-enable it (#683)
+- Replace `three-stdlib` with `three/examples/jsm` imports and remove the dependency (#698)
+- Document `HeightfieldArgs` (`heights` must have `(rows + 1) * (cols + 1)` values) and warn in development when the length mismatches (#730)

.changeset/character-controller.md

@@ -0,0 +1,10 @@
+---
+"@react-three/rapier": minor
+---
+
+Add a kinematic character controller built on Rapier's `KinematicCharacterController`.
+
+- `useCharacterController(options)` creates and frees the controller (StrictMode safe), applies `offset`, `up`, `slide`, `maxSlopeClimbAngle`, `minSlopeSlideAngle`, `autostep`, `snapToGround`, `applyImpulsesToDynamicBodies`, `characterMass` and `normalNudgeFactor` reactively, and returns a stable `{ controller, move(rigidBody, desiredTranslation, opts) }` api. `move` computes the collision-resolved movement, calls `setNextKinematicTranslation` and returns a pooled `{ movement, grounded, collisions }`.
+- `<CharacterController>` wraps a `kinematicPosition` `RigidBody`. Its ref exposes `{ controller, rigidBody, grounded, setVelocity(v), translate(delta) }`; the desired motion is applied once per fixed physics step with the fixed `dt`, so it is framerate independent. It also accepts `onGrounded`, `onAirborne` (edge triggered) and `onCharacterCollision`.
+
+Options reverting to `undefined` restore Rapier's defaults. `<CharacterController>` defaults to `colliders={false}`. Gravity and jumping are intentionally left to userland. See the `character-controller` demo.

.changeset/pre.json

@@ -0,0 +1,4 @@
+{
+  "mode": "pre",
+  "tag": "alpha"
+}

.changeset/r3f-v10-foundation.md

@@ -0,0 +1,27 @@
+---
+"@react-three/rapier": major
+"@react-three/rapier-addons": major
+---
+
+Move to the React Three Fiber v10 stack and modernize the package format.
+
+### Requirements
+
+- `@react-three/fiber` `>=10.0.0-0` (developed against `10.0.0-canary.a056612`; scheduler fixed-step support needs `@pmndrs/scheduler` 0.3+)
+- `react` `>=19.0 <19.3` (the range r3f v10 supports)
+- `three` `>=0.185.0`
+- Node.js 22+ for tooling (`engines`)
+- `@react-three/rapier-addons` now peers on `@react-three/rapier` `^3.0.0-0`
+
+### Package format
+
+- Built with rollup + esbuild instead of preconstruct. Each package ships an `exports` map with
+  ESM (`dist/index.mjs`) and CommonJS (`dist/index.cjs`) builds and matching type declarations
+  (`.d.mts` / `.d.cts`), and is marked `sideEffects: false`.
+- Deep imports into package internals (e.g. `@react-three/rapier/src/...` or `dist/...` files)
+  are no longer possible; import from the package root.
+
+### Behaviour notes
+
+- Under r3f v10 `useFrame`'s state no longer has `clock`; use `state.elapsed` / `state.delta`
+  in your own frame callbacks.

.changeset/scheduler-fixed-step.md

@@ -0,0 +1,17 @@
+---
+"@react-three/rapier": major
+---
+
+Step physics on the react-three-fiber v10 scheduler.
+
+- With `updateLoop="follow"` (default) and a numeric `timeStep`, each world steps in its own fixed-timestep scheduler phase (`rapier:fixed:<n>`), which runs after r3f's `physics` phase. Changing `timeStep` or `maxSubSteps` retimes that phase in place, and phases are reused when worlds remount. Rendered transforms are synced once per frame in a new `rapier` phase, before `update`, and interpolated by the phase's overstep. A `rapier:late` pass right before `render` re-applies them if an ancestor moved during `update`. The shared `physics` phase timestep is never changed, and multiple `<Physics>` worlds with different `timeStep`s work side by side. Without scheduler fixed-phase support (`@pmndrs/scheduler` < 0.3), the same behaviour runs on an internal accumulator.
+- New `maxSubSteps` prop (default `5`) caps the fixed steps a single frame may run. Surplus time is dropped instead of queued, so slow frames can no longer spiral (#697).
+- **Breaking:** `updatePriority` now only orders this world's jobs within their scheduler phase (higher runs first, the r3f v10 convention). It no longer takes over r3f's render loop. Physics always steps before `update`, and r3f keeps rendering.
+- `paused` banks no time, so resuming does not burst. `step()` from `useRapier()` works while paused and syncs meshes immediately.
+- `useBeforePhysicsStep` and `useAfterPhysicsStep` callbacks receive `(world, dt)`, where `dt` is the step length. Existing single-argument callbacks keep working.
+- Collision, contact-force and soft-body tear events are drained after every substep instead of once per frame.
+- Bodies are synced parent-first into their parent's current space every frame, so moving, rotating or re-parenting an ancestor of a `<RigidBody>` after mount keeps its visual on the simulated body (#36), and nested bodies no longer lag the body that carries them.
+- Interpolation no longer lerps across teleports made in `useBeforePhysicsStep`, manual `step()` calls, `setWorld()`, or `paused`/`interpolate` changes.
+- `<Debug>` reuses one geometry and disposes it on unmount, instead of allocating one per frame and leaking on toggle (#666).
+- With `frameloop="demand"`, the canvas is invalidated once per frame while any non-fixed body is awake.
+- The world is freed after the unmount commit, so child cleanups run against a live world and StrictMode remounts are safe.

.changeset/soft-bodies.md

@@ -0,0 +1,19 @@
+---
+"@react-three/rapier": minor
+---
+
+Add soft bodies: `<SoftBody>` and `useSoftBody`, built on Rapier 0.21's deformable bodies.
+
+Build cloth, rope and volumetric (jelly) bodies from the geometry of a `<mesh>` or `<line>`. Vertices are welded on position only, and the simulated positions are written into the geometry in the parent's local space once per rendered frame, interpolated with the same alpha as the rigid bodies (so cloth attached to an interpolated body stays on it), with normals and bounds recomputed. Tears are handled after every physics substep. Supports pinned particles, attachments to rigid bodies, stiffness/damping/mass, collisions with rigid bodies, and an `onTear` event.
+
+```tsx
+import { SoftBody } from "@react-three/rapier/soft-bodies";
+
+<SoftBody type="cloth" pinned={(p) => p.y > 0.49} stiffness={12}>
+  <mesh position={[0, 3, 0]}>
+    <planeGeometry args={[1, 1, 20, 20]} />
+  </mesh>
+</SoftBody>;
+```
+
+The API lives in the `@react-three/rapier/soft-bodies` entry point (a separate bundle that imports core from `@react-three/rapier`). `RapierContext` gains two internal sets: `softBodyTearCallbacks`, which `<Physics>` fills from Rapier's soft body tear events after each step, and `frameSyncCallbacks`, which `<Physics>` calls once per frame with the interpolation alpha after writing the rigid bodies.

.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# Bulk formatting commits, skipped by `git blame` (GitHub reads this file automatically;
+# locally: git config blame.ignoreRevsFile .git-blame-ignore-revs).
+
+# style: format with prettier 3
+8d7b56b1a0ce4d23fcb275dc72a108aa14c934bf

.github/actions/setup/action.yml

@@ -0,0 +1,26 @@
+name: Setup
+description: Enable Corepack (Yarn 4), set up Node.js with the Yarn cache and install dependencies
+
+inputs:
+  node-version:
+    description: Node.js version
+    default: 22.x
+
+runs:
+  using: composite
+  steps:
+    # Corepack must be enabled before setup-node so its Yarn cache step finds Yarn 4
+    # (the `packageManager` field), not the runner's global Yarn 1.
+    - name: Enable Corepack
+      shell: bash
+      run: corepack enable
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v7
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: yarn
+
+    - name: Install dependencies
+      shell: bash
+      run: yarn install --immutable

.github/dependabot.yml

@@ -6,6 +6,39 @@
 version: 2
 updates:
   - package-ecosystem: "npm"
-    directory: "/packages/react-three-rapier"
+    directory: "/" # yarn workspaces are discovered from the root
     schedule:
       interval: "weekly"
+    groups:
+      minor-and-patch:
+        applies-to: version-updates
+        update-types:
+          - "minor"
+          - "patch"
+    ignore:
+      # three, react/react-dom and @react-three/* track r3f v10 / drei v11 prereleases;
+      # major bumps are deliberate, hand-verified upgrades.
+      - dependency-name: "three"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@types/three"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "react-dom"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@types/react"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@types/react-dom"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "@react-three/*"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        update-types:
+          - "minor"
+          - "patch"

.github/pull_request_template.md

@@ -1,19 +1,22 @@
 ## Description
+
 <!-- A summary of the changes. Add a video or screenshot if it makes sense! -->
 
 ### Type of change
+
 <!-- Remove unrelated items -->
 
 - 🐛 Bug fix
 - ✨ New feature
 - 📦 Other (tests, refactoring, docs, etc.)
 
 ### Checklist:
+
 <!-- Check all that apply, remove any that don't -->
 
 - [ ] 🔍 I have performed a self-review of my code
 - [ ] 💬 I have commented my code, particularly in hard-to-understand areas
 - [ ] 📗 I have made corresponding changes to the documentation
 - [ ] ⭐️ My changes generate no new warnings
 - [ ] 🧪 I have added tests
-- [ ] 🟢 All new and existing unit tests pass
+- [ ] 🟢 All new and existing unit tests pass

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, next]
+  push:
+    branches: [main, next]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - name: Typecheck packages and tests
+        run: yarn typecheck
+      - name: Typecheck demo
+        run: yarn workspace demo typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      # vitest resolves the workspace packages from src, so no build is needed first
+      - name: Test
+        run: yarn vitest run
+
+  build:
+    name: Build & check packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - name: Build
+        run: yarn build
+      - name: publint + arethetypeswrong
+        run: yarn check:packages
+
+  demo:
+    name: Build demo
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - name: Build demo
+        run: yarn demo:build
+
+  lint:
+    name: Lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup
+      - name: Lint
+        run: yarn lint
+      - name: Format
+        if: ${{ !cancelled() }}
+        run: yarn format:check

.github/workflows/r3-rapier-docs.yml

@@ -29,31 +29,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v3.6.0
-        with:
-          node-version: 22.x
-
-      - name: Enable corepack  
-        run: corepack enable
-
-      - name: Install Node Dependencies
-        run: yarn --immutable
+      - uses: ./.github/actions/setup
 
       - name: Run typedoc
         run: yarn docs:build
 
       - name: Setup Pages
-        uses: actions/configure-pages@v2
+        uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           # Upload docs folder
           path: "./packages/react-three-rapier/docs"
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -1,34 +1,44 @@
 name: Release
 
+# `main` publishes stable releases. `next` is the 3.0 integration branch and is in changesets
+# pre mode (.changeset/pre.json, `yarn prerelease:enter`), so the same flow there opens a
+# "Version Packages (alpha)" PR into `next` (the action appends the pre tag) and publishes `x.y.z-alpha.n` under the `alpha`
+# dist-tag, leaving `latest` untouched. Run `yarn prerelease:exit` before merging `next` into
+# `main`.
 on:
   push:
     branches:
       - main
+      - next
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
   release:
     name: Release
+    if: github.repository_owner == 'pmndrs'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # changesets pushes the version branch
+      pull-requests: write # ...and opens the "Version Packages" PR
+      id-token: write # npm provenance / trusted publishing (OIDC)
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
-      - name: Setup Node.js 22.x
-        uses: actions/setup-node@v3
-        with:
-          node-version: 22
-
-      - name: Install Dependencies
-        run: yarn --immutable
+      - uses: ./.github/actions/setup
 
       - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1
         with:
-          publish: yarn release
+          version: yarn changeset:version
+          publish: yarn changeset:publish
           commit: "chore(changeset): release packages"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # This is a Yarn 4 workspace, so changesets publishes with `yarn npm publish`, which
+          # reads YARN_NPM_AUTH_TOKEN rather than NPM_TOKEN. NPM_TOKEN is kept because
+          # changesets/action uses it to write the .npmrc it checks registry state with.
+          YARN_NPM_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}