feat(dart): physics_basics example (reactphysics3d_dart + thermion)

.github/workflows/generate-artifacts.yml

@@ -66,6 +66,11 @@ jobs:
           filters: |
             native-changed:
               - 'thermion_dart/native/**'
+              # These drive the web (Emscripten) build too: the Makefile's wasm
+              # target and the scripts it calls decide what goes into the
+              # shipped thermion_dart.wasm.
+              - 'Makefile'
+              - 'scripts/download_reactphysics3d.sh'
             materials-changed:
               - 'materials/**'
               - 'examples/assets/*.mat'
@@ -197,6 +202,20 @@ jobs:
           restore-keys: |
             filament-web-
 
+      # ReactPhysics3D checkout + the published libreactphysics3d.a that gets
+      # linked into thermion_dart.wasm. Keyed on the download script so a tag
+      # bump in it re-fetches.
+      - name: Cache ReactPhysics3D web artifact
+        if: steps.changes.outputs.native-changed == 'true'
+        uses: actions/cache@v4
+        with:
+          path: thermion_dart/native/web/lib/external
+          key: rp3d-web-${{ hashFiles('scripts/download_reactphysics3d.sh') }}
+
+      # Builds the single thermion_dart WASM with ReactPhysics3D linked in via
+      # the EXTERNAL_PROJECTS hook. The engine library comes from the
+      # reactphysics3d_dart release that the download script pins; that
+      # repository's own build-artifacts workflow verifies its exports.
       - name: Compile web
         if: steps.changes.outputs.native-changed == 'true'
         run: make wasm

.tickets/the-tvf4.md

@@ -0,0 +1,39 @@
+---
+id: the-tvf4
+status: in_progress
+deps: []
+links: []
+created: 2026-08-14T14:54:21Z
+type: feature
+priority: 2
+assignee: Nick Fisher
+tags: [dart, examples, physics]
+---
+# Create a Dart sample demonstrating basic physics
+
+Create a Dart sample (thermion example) showing basic physics. Use reactphysics3d_dart for the physics simulation and thermion_dart for rendering.
+
+## Context
+
+- Reference app: ~/Documents/mixworld (Flutter app, mounted read-only).
+  It already wires thermion_dart + reactphysics3d_dart together. Read it to
+  learn the integration pattern.
+- Physics package: reactphysics3d_dart (mounted read-only at
+  /Volumes/T7/projects/reactphysics3d_dart). It is a git repo on branch
+  master. It has an example/ dir with a heightfield example.
+- The sample lives in this repo (thermion), under examples/dart.
+  Follow the existing example structure (examples_lib / web_gallery).
+- Physics + rendering should run in the browser (WASM), like the other
+  dart examples.
+
+## Acceptance criteria
+
+1. New dart example under examples/dart that shows basic physics:
+   objects falling, bouncing, or colliding, rendered with thermion.
+2. Registered in the example registry so it appears in the web gallery
+   (see examples/dart/examples_lib/lib/src/registry.dart and
+   examples/dart/web_gallery).
+3. Works in the browser (WASM build), verified by building/running it.
+4. Code follows existing example style and passes `flutter analyze` /
+   `dart analyze` where applicable.
+

Makefile

@@ -1,3 +1,15 @@
+# ReactPhysics3D is compiled into the single thermion_dart WASM through the
+# EXTERNAL_PROJECTS hook in thermion_dart/native/web/CMakeLists.txt: thermion
+# itself never references the rp3d C API, so its objects are only kept alive by
+# the -Wl,--whole-archive group and its _rp3d_* functions are exported from the
+# same Module object as the _Thermion_* ones. That is what lets one
+# NativeLibrary.initBindings("thermion_dart") serve both packages on the web.
+# scripts/download_reactphysics3d.sh stages the reactphysics3d_dart checkout
+# and the published libreactphysics3d.a that the hook links in.
+# Set EXTERNAL_PROJECTS_CMAKE= (empty) to build a WASM without physics.
+RP3D_EXTERNAL_DIR := thermion_dart/native/web/lib/external
+EXTERNAL_PROJECTS_CMAKE ?= $(RP3D_EXTERNAL_DIR)/reactphysics3d_dart/native/web/reactphysics3d_dart.cmake
+
 wasm:
 	@if [ ! -f thermion_dart/native/web/lib/release/filament-v1.75.0-web-release.zip ]; then \
 		echo "Downloading filament-v1.75.0-web-release.zip..."; \
@@ -9,13 +21,17 @@ wasm:
 	cd thermion_dart/native/web/lib/release && \
 	rm -rf include lib && \
 	unzip -o filament-v1.75.0-web-release.zip
+ifneq ($(strip $(EXTERNAL_PROJECTS_CMAKE)),)
+	scripts/download_reactphysics3d.sh
+endif
 	cd thermion_dart/native/web && \
 	mkdir -p build && \
 	cd build && \
-	emcmake cmake .. && \
+	emcmake cmake $(if $(strip $(EXTERNAL_PROJECTS_CMAKE)),-DEXTERNAL_PROJECTS=$(abspath $(EXTERNAL_PROJECTS_CMAKE)),) .. && \
 	emmake make
 wasm-clean:
 	cd thermion_dart/native/web && rm -rf build
+	@echo "Note: $(RP3D_EXTERNAL_DIR) is kept (cached ReactPhysics3D checkout/artifact)."
 wasm-example-web: 
 	cd examples/dart/js_wasm
 	mkdir -p build