feat: Add @typegpu/three package and Three.js integration example (#1453)

* feat: tgpu.comptime, tgpu.rawCodeSnippet and `this` allowed in TypeGPU
shader functions

* Fix tests

* Better docs for rawCodeSnippet

* Docs for comptime

* - Namable comptime - Turned `extensionEnabled` into a comptime function

* Fixes

* Add @typegpu/three package and Three.js integration example (very WIP)

* Update tgpuThree.ts

* Three.js types for example code view

* More tweaks and experiments

* More work

* A bit more work

* More work

* Using @typegpu/noise in Three.js

* Add a new example

* Testing compute in Three.js

* Update examples

* Update typegpu-material.ts

* Update index.ts

* Some more work

* Works again

* TypeGPU compute shaders in TSL!

* A bit of a refactor of the cloth example

* Cleanup 🧹

* Comparing Three and TypeGPU output

* triNoise3D in TypeGPU

* comptime

* Support for 'this' in TypeGPU shader functions

* Update verlet.ts

* feat: Attractors example (#1949)

* Tweaks

* feat: Tweaks to feat/tgpu-three (#1954)

* Some review fixes

* Thumbnails and tags

* Comptime fromTSL

* Update shellless.test.ts

* fix: Calling `toTSL` multiple times (#1974)

* feat: Inform user about type mismatches (#1988)

* Fix renderer resizing when browser zoom

* docs: Cloth example controls (#1986)

* feat: ThreeJS 'Compute Particles' with tgpu (#1947)

* feat: ThreeJS 'Compute Geometry' with tgpu (#1948)

* feat: ThreeJS 'Compute Snow Particles' example in tgpu (#1972)

* fix: @typegpu/three toTSL should have a per-stage namespace (#1994)

---------

Co-authored-by: Iwo Plaza <iwoplaza@gmail.com>
Co-authored-by: Aleksander Katan <56294622+aleksanderkatan@users.noreply.github.com>
Co-authored-by: Rafal Lukosz <93160829+lursz@users.noreply.github.com>
Co-authored-by: Szymon Szulc <103948576+cieplypolar@users.noreply.github.com>

Author: 5 people

apps/typegpu-docs/astro.config.mjs

@@ -211,9 +211,15 @@ export default defineConfig({
               label: '@typegpu/noise',
               slug: 'ecosystem/typegpu-noise',
             },
+            {
+              label: '@typegpu/three',
+              slug: 'ecosystem/typegpu-three',
+              badge: { text: 'new' },
+            },
             {
               label: '@typegpu/sdf',
               slug: 'ecosystem/typegpu-sdf',
+              badge: { text: 'new' },
             },
             DEV && {
               label: '@typegpu/color',

apps/typegpu-docs/package.json

@@ -28,7 +28,9 @@
     "@typegpu/color": "workspace:*",
     "@typegpu/geometry": "workspace:*",
     "@typegpu/noise": "workspace:*",
+    "@typegpu/three": "workspace:*",
     "@typegpu/sdf": "workspace:*",
+    "three": "catalog:example",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "arktype": "catalog:",
@@ -68,9 +70,9 @@
     "@types/babel__standalone": "^7.1.9",
     "@types/babel__template": "^7.4.4",
     "@types/babel__traverse": "^7.20.7",
-    "@types/dom-mediacapture-record": "^1.0.22",
     "@types/node": "^24.7.0",
     "@vitejs/plugin-basic-ssl": "^2.1.0",
+    "@types/three": "catalog:types",
     "@webgpu/types": "catalog:types",
     "astro-vtbot": "^2.1.6",
     "autoprefixer": "^10.4.21",

apps/typegpu-docs/public/assets/threejs/compute-geometry/LeePerrySmith.glb

@@ -0,0 +1,5 @@
+Creative Commons Licence
+Infinite, 3D Head Scan by Lee Perry-Smith is licensed under a Creative Commons Attribution 3.0 Unported License.
+Based on a work at www.triplegangers.com.
+Permissions beyond the scope of this license may be available at http://www.ir-ltd.net/
+Please remember: Do what you want with the files, but always mention where you got them from...

apps/typegpu-docs/public/assets/threejs/compute-geometry/LeePerrySmith_License.txt

@@ -0,0 +1,101 @@
+---
+title: "@typegpu/three"
+---
+
+[TSL (Three.js Shading Language)](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language#function) is a node-based shader composition system for Three.js. Shader logic and control flow is built up by composing special functions,
+with a focus on composability, intuitive sharing of logic across modules and customizability. TypeGPU fits naturally into this system thanks to the `@typegpu/three` package. You can choose to write your TSL building blocks in TypeGPU, which has a few benefits:
+- Control-flow like `if` statements and `for` loops makes use of familiar JavaScript syntax instead of special functions.
+- The code you write is semantically valid JavaScript, with types flowing through each expression.
+- Unit-testability, since you can call these functions on the CPU
+
+Below are a select few cases comparing TSL and TypeGPU:
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Node definition
+
+TSL:
+```ts
+const simulate = Fn(() => {
+  //
+  // ... TSL code ...
+  //
+});
+```
+
+TypeGPU:
+```ts twoslash
+import * as t3 from '@typegpu/three';
+// ---cut---
+const simulate = t3.toTSL(() => {
+  'use gpu';
+  //
+  // ... TypeGPU code ...
+  // 
+});
+```
+
+## Function definition
+
+TSL:
+```ts
+const oscSine = Fn(([t = time]) => {
+  return t.add(0.75).mul(Math.PI * 2).sin().mul(0.5).add(0.5);
+});
+```
+
+TypeGPU:
+```ts twoslash
+import * as std from 'typegpu/std';
+// ---cut---
+const oscSine = (t: number) => {
+  'use gpu';
+  return std.sin((t + 0.75) * Math.PI * 2) * 0.5 + 0.5;
+};
+```
+
+## If statements
+
+TSL:
+```ts
+If(instanceIndex.greaterThanEqual(uint(vertexCount)), () => {
+  Return();
+});
+```
+
+TypeGPU:
+```ts twoslash
+import * as t3 from '@typegpu/three';
+declare const vertexCount: number;
+const some = () => {
+// ---cut-before---
+if (t3.instanceIndex.$ >= vertexCount) {
+  return;
+}
+// ---cut-after---
+};
+```
+
+## For loops
+
+TSL:
+```ts
+Loop({ start: ptrStart, end: ptrEnd, type: 'uint', condition: '<' }, ({ i }) => {
+	const springId = springListBuffer.element( i ).toVar( 'springId' );
+	const springForce = springForceBuffer.element( springId );
+	const springVertexIds = springVertexIdBuffer.element( springId );
+	const factor = select( springVertexIds.x.equal( instanceIndex ), 1.0, - 1.0 );
+	force.addAssign( springForce.mul( factor ) );
+});
+```
+
+TypeGPU:
+```ts
+for (let i = ptrStart; i < ptrEnd; i++) {
+  const springId = springListBuffer.$[i];
+  const springForce = springForceBuffer.$[springId];
+  const springVertexIds = springVertexIdBuffer.$[springId];
+  const factor = std.select(-1, 1, springVertexIds.x === idx);
+  force = force.add(springForce.mul(d.f32(factor)));
+}
+```

apps/typegpu-docs/src/content/docs/ecosystem/typegpu-three.mdx

@@ -0,0 +1 @@
+<canvas data-fit-to-container></canvas>