three-swizzle

Add GLSL-style swizzle masks for your three.js vectors (Vector2, Vector3, and Vector4), with full TypeScript support too.

What is a swizzle mask, you may ask? A swizzle mask lets you select specific vector components in a custom order to create a new vector.

import * as THREE from 'three'
import 'three-swizzle'

const v3 = new THREE.Vector3(2, 7, 5)
const a = v3.swizzle('xz') // Vector2 { x:2, y:5 }
v3.swizzle('yzx', v3) // Vector3 { x:7, y:5, z:2 }
const b = v3.swizzle('xzx') // Vector3 { x:2, y:5, z:2 }

I find this feature when making shaders very useful, but no JS framework that works with vectors ever has it, so here we are. (In GLSL, the shader language, you would do it like v3.xz, but using a method and a string is much more performant and JS-friendly)

Install

Available currently only on npm

• npm install three-swizzle three
• pnpm install three-swizzle three

Features

• Swizzle vectors using three naming sets:

  • xyzw (classic)
  • rgba (color style)
  • stpq (texture style)

• Supports getting and setting via the same method:

  v.swizzle(mask) // getter → returns new vector
  v.swizzle(mask, value) // setter → modifies the vector

• Fully typed with TypeScript autocomplete for masks.

• Works for Vector2, Vector3, and Vector4.

Usage

Import three-swizzle. It automatically adds the function swizzle to the vector prototypes, so you can access it more easily. So, you can do swizzle(v, '...'), or you could do v.swizzle('...'). Note: the getter only returns the swizzled value, while the setter modifies the vector.

Vector2

import * as THREE from 'three'
import 'three-swizzle'
// or import { swizzle } from 'three-swizzle'

const v2 = new THREE.Vector2(1, 2)

// Getter
const xy = v2.swizzle('yx') // Vector2 { x:2, y:1 }

// Setter
v2.swizzle('xy', new THREE.Vector2(5, 6))
console.log(v2) // Vector2 { x:5, y:6 }

Vector3

const v3 = new THREE.Vector3(1, 2, 3)

// 2-letter getter → Vector2
const v2sw = v3.swizzle('zy') // Vector2 { x:3, y:2 }

// 3-letter getter → Vector3
const v3sw = v3.swizzle('zxy') // Vector3 { x:3, y:1, z:2 }

// 2-letter setter
v3.swizzle('xy', new THREE.Vector2(10, 20))
console.log(v3) // Vector3 { x:10, y:20, z:3 }

// 3-letter setter
v3.swizzle('xzy', new THREE.Vector3(7, 8, 9))
console.log(v3) // Vector3 { x:7, y:9, z:8 }

Vector4

const v4 = new THREE.Vector4(1, 2, 3, 4)

// Getter
const v2sw = v4.swizzle('zw') // Vector2
const v3sw = v4.swizzle('xzw') // Vector3
const v4sw = v4.swizzle('wzyx') // Vector4

// Setter
v4.swizzle('xy', new THREE.Vector2(5, 6))
v4.swizzle('xzw', new THREE.Vector3(7, 8, 9))
v4.swizzle('wzyx', new THREE.Vector4(1, 2, 3, 4))

Notes

Only valid masks are allowed (length matches vector dimension and characters are in the correct set), just like in GLSL.

Swizzle characters cannot be mixed between naming sets.

Prototypes are patched inside the library.

Build

Run npm run dev to run test.ts, run npm run build and npm publish --access public to publish. Don't forget to change the version number in your package.json!