Skip to content

Commit b800e58

Browse files
Add TSL uniform node support to Three.js animate
Resolve node material slots like colorNode/opacityNode to their TSL uniform nodes when animating materials and meshes, and support animating uniform nodes directly. Non-uniform nodes are compiled into the shader so fall through to plain properties. Co-authored-by: Cursor <[email protected]>
1 parent d60a956 commit b800e58

4 files changed

Lines changed: 137 additions & 26 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,17 @@ Motion adheres to [Semantic Versioning](http://semver.org/).
44

55
Undocumented APIs should be considered internal and may change without warning.
66

7+
## [13.2.0] 2026-unreleased
8+
9+
### Added
10+
11+
- `animate` for Three.js supporting objects, materials, shader uniforms, TSL uniform nodes and node material slots like `colorNode`.
12+
- `animate` for vgpu supporting shader uniforms.
13+
14+
### Changed
15+
16+
- Reduced filesize and improved performance of `spring`.
17+
718
## [13.1.1] 2026-08-18
819

920
### Fixed

‎dev/html/src/three-animate.js‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -95,14 +95,16 @@ document.querySelector("#uniform").addEventListener("click", () => {
9595
uniformActive = !uniformActive
9696
status.textContent = "Animating shader uniforms"
9797

98-
animate(
99-
uniforms,
100-
{
101-
progress: uniformActive ? 1 : 0,
102-
tint: uniformActive ? "#fbbf24" : "#22d3ee",
103-
},
104-
{ duration: 1, ease: "easeInOut" }
105-
).then(() => {
98+
Promise.all([
99+
animate(uniforms.progress, uniformActive ? 1 : 0, {
100+
duration: 1,
101+
ease: "easeInOut",
102+
}),
103+
animate(uniforms.tint, uniformActive ? "#fbbf24" : "#22d3ee", {
104+
duration: 1,
105+
ease: "easeInOut",
106+
}),
107+
]).then(() => {
106108
status.textContent = "Uniform animation complete"
107109
})
108110
})

‎packages/motion/src/__tests__/three.test.ts‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,79 @@ describe("motion/three", () => {
8989
expect(uniforms.opacity.value).toBe(1)
9090
})
9191

92+
it("animates TSL uniform nodes directly", async () => {
93+
const progress = { value: 0 }
94+
95+
await animate(progress, 1, { duration: 0.001 })
96+
await nextFrame()
97+
98+
expect(progress.value).toBe(1)
99+
})
100+
101+
it("animates TSL color uniform nodes directly", async () => {
102+
const color = {
103+
getStyle: () => "#000",
104+
set: jest.fn(),
105+
}
106+
const tint = { value: color }
107+
108+
await animate(tint, "#fff", { duration: 0.001 })
109+
await nextFrame()
110+
111+
expect(tint.value).toBe(color)
112+
expect(color.set).toHaveBeenLastCalledWith("#fff")
113+
})
114+
115+
it("animates TSL node material uniforms in favour of plain properties", async () => {
116+
const nodeColor = { getStyle: () => "#000", set: jest.fn() }
117+
const material = {
118+
color: { getStyle: () => "#000", set: jest.fn() },
119+
colorNode: { isUniformNode: true, value: nodeColor },
120+
opacityNode: { isUniformNode: true, value: 0 },
121+
}
122+
123+
await animate(
124+
material,
125+
{ color: "#fff", opacity: 1 },
126+
{ duration: 0.001 }
127+
)
128+
await nextFrame()
129+
130+
expect(nodeColor.set).toHaveBeenLastCalledWith("#fff")
131+
expect(material.color.set).not.toHaveBeenCalled()
132+
expect(material.opacityNode.value).toBe(1)
133+
})
134+
135+
it("ignores non-uniform nodes when resolving material values", async () => {
136+
const material = {
137+
color: { getStyle: () => "#000", set: jest.fn() },
138+
colorNode: { value: 0 },
139+
}
140+
141+
await animate(material, { color: "#fff" }, { duration: 0.001 })
142+
await nextFrame()
143+
144+
expect(material.color.set).toHaveBeenLastCalledWith("#fff")
145+
expect(material.colorNode.value).toBe(0)
146+
})
147+
148+
it("animates TSL node material uniforms via the mesh", async () => {
149+
const mesh = {
150+
position: { x: 0, y: 0, z: 0 },
151+
material: {
152+
opacity: 1,
153+
opacityNode: { isUniformNode: true, value: 1 },
154+
},
155+
}
156+
157+
await animate(mesh, { x: 2, opacity: 0.5 }, { duration: 0.001 })
158+
await nextFrame()
159+
160+
expect(mesh.position.x).toBe(2)
161+
expect(mesh.material.opacityNode.value).toBe(0.5)
162+
expect(mesh.material.opacity).toBe(1)
163+
})
164+
92165
it("updates Three.js color uniforms without replacing them", async () => {
93166
const color = { set: jest.fn() }
94167
const uniforms = { tint: { value: color } }

‎packages/motion/src/three.ts‎

Lines changed: 43 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ export type UniformAnimationTarget<T extends object> = {
2121
[K in keyof T]?: string | number | Array<string | number | null>
2222
}
2323

24+
export type UniformValueAnimationTarget =
25+
| string
26+
| number
27+
| Array<string | number | null>
28+
2429
export interface ObjectEffectValues {
2530
[key: string]: MotionValue | undefined
2631
}
@@ -68,8 +73,13 @@ export function objectEffect(
6873
}
6974

7075
/**
71-
* Animates Three.js uniforms and flattened object properties.
76+
* Animates Three.js uniform nodes, uniforms and flattened object properties.
7277
*/
78+
export function animate(
79+
subject: ThreeUniform,
80+
keyframes: UniformValueAnimationTarget,
81+
options?: AnimationOptions
82+
): AnimationPlaybackControlsWithThen
7383
export function animate<T extends object>(
7484
subject: ThreeUniforms<T>,
7585
keyframes: UniformAnimationTarget<T>,
@@ -82,10 +92,16 @@ export function animate(
8292
): AnimationPlaybackControlsWithThen
8393
export function animate(
8494
subject: object,
85-
keyframes: ObjectAnimationTarget,
95+
keyframes: UniformValueAnimationTarget | ObjectAnimationTarget,
8696
options?: AnimationOptions
8797
): AnimationPlaybackControlsWithThen {
88-
return animateEffect(subject, keyframes, options)
98+
return animateEffect(
99+
subject,
100+
typeof keyframes === "object" && !Array.isArray(keyframes)
101+
? keyframes
102+
: { value: keyframes },
103+
options
104+
)
89105
}
90106

91107
const transformMap = {
@@ -108,8 +124,7 @@ function resolveThreeEffect(
108124
) {
109125
const object = subject as ThreeObject
110126
const resolvedAdapter =
111-
adapter ??
112-
(isUniform(object[key]) ? uniformAdapter : objectAdapter)
127+
adapter ?? (isUniform(object[key]) ? uniformAdapter : objectAdapter)
113128
const initial =
114129
resolvedAdapter === uniformAdapter
115130
? getAnimatableValue((object as Uniforms)[key]?.value)
@@ -135,24 +150,32 @@ function getObjectValue(object: ThreeObject, key: string) {
135150
return getAnimatableValue(object.scale?.x)
136151
}
137152

153+
const node = getNodeUniform(object, key)
154+
if (node) return getAnimatableValue(node.value)
155+
138156
const value =
139157
getProperty(object, key) ??
140158
getProperty(object.material, key) ??
141159
getUniformValue(object.material?.uniforms ?? object.uniforms, key) ??
142160
getVectorComponent(object, key) ??
143161
getVectorComponent(object.material, key) ??
144-
getUniformComponent(
145-
object.material?.uniforms ?? object.uniforms,
146-
key
147-
)
162+
getUniformComponent(object.material?.uniforms ?? object.uniforms, key)
148163

149164
return value
150165
}
151166

167+
/**
168+
* Resolves TSL uniform nodes assigned to node material slots, e.g.
169+
* material.colorNode = uniform(color). Non-uniform nodes are compiled
170+
* into the shader so can't be animated via their value.
171+
*/
172+
function getNodeUniform(object: ThreeObject, key: string) {
173+
const node = object[key + "Node"] ?? object.material?.[key + "Node"]
174+
return node?.isUniformNode ? (node as ThreeUniform) : undefined
175+
}
176+
152177
function getProperty(target: ThreeObject | undefined, key: string) {
153-
return target && key in target
154-
? getAnimatableValue(target[key])
155-
: undefined
178+
return target && key in target ? getAnimatableValue(target[key]) : undefined
156179
}
157180

158181
function getUniformValue(uniforms: Uniforms | undefined, key: string) {
@@ -170,18 +193,14 @@ function getVectorComponent(target: ThreeObject | undefined, key: string) {
170193
function getUniformComponent(uniforms: Uniforms | undefined, key: string) {
171194
const uniform = uniforms?.[key.slice(0, -1)]
172195
return uniform
173-
? getVectorComponent(
174-
{ value: uniform.value },
175-
`value${key.slice(-1)}`
176-
)
196+
? getVectorComponent({ value: uniform.value }, `value${key.slice(-1)}`)
177197
: undefined
178198
}
179199

180200
function getAnimatableValue(value: unknown) {
181201
if (typeof value === "string" || typeof value === "number") return value
182202

183-
return value &&
184-
typeof (value as ThreeObject).getStyle === "function"
203+
return value && typeof (value as ThreeObject).getStyle === "function"
185204
? (value as ThreeObject).getStyle()
186205
: undefined
187206
}
@@ -212,6 +231,12 @@ function setObjectValue(object: ThreeObject, key: string, value: unknown) {
212231
return
213232
}
214233

234+
const node = getNodeUniform(object, key)
235+
if (node) {
236+
setProperty(node, "value", value)
237+
return
238+
}
239+
215240
if (setProperty(object, key, value)) return
216241

217242
const material = object.material

0 commit comments

Comments
 (0)