@velox/three Stable
Declarative 3D scene composition for VeloxKit. Renders into a native <Canvas3D> surface using a custom wgpu/Vello 3D pipeline with Phong lighting.
Install
npm install @velox/threeQuick start
import { Canvas3D } from 'veloxkit'
import { Scene, PerspectiveCamera, Mesh, AmbientLight, DirectionalLight } from '@velox/three'
import { BoxGeometry, MeshStandardMaterial } from '@velox/three'
function ThreeDemo() {
return (
<Canvas3D width={600} height={400}>
<Scene background="#0d0d14">
<PerspectiveCamera fov={60} position={[0, 1, 4]} />
<AmbientLight intensity={0.3} />
<DirectionalLight position={[2, 4, 3]} intensity={1.0} />
<Mesh
geometry={<BoxGeometry width={1} height={1} depth={1} />}
material={<MeshStandardMaterial color="#00A878" />}
position={[0, 0, 0]}
rotation={[0.5, 0.8, 0]}
/>
</Scene>
</Canvas3D>
)
}Animated scene
import { Canvas3D, useAnimationFrame } from 'veloxkit'
import { Scene, PerspectiveCamera, Mesh, DirectionalLight } from '@velox/three'
import { SphereGeometry, MeshStandardMaterial } from '@velox/three'
import { useRef } from 'react'
function SpinningBall() {
const rotRef = useRef(0)
const [rot, setRot] = useAnimationState(0)
useAnimationFrame((dt) => {
rotRef.current += dt * 0.001
setRot(rotRef.current)
})
return (
<Canvas3D width={400} height={300}>
<Scene background="#0d0d14">
<PerspectiveCamera fov={60} position={[0, 0, 3]} />
<DirectionalLight position={[1, 2, 2]} intensity={1} />
<Mesh
geometry={<SphereGeometry radius={0.8} widthSegments={32} heightSegments={32} />}
material={<MeshStandardMaterial color="#8888ff" />}
rotation={[0, rot, 0]}
/>
</Scene>
</Canvas3D>
)
}Loading GLTF models
import { Canvas3D } from 'veloxkit'
import { Scene, PerspectiveCamera, Model, DirectionalLight } from '@velox/three'
import { useRef, useEffect } from 'react'
function ModelViewer({ path }: { path: string }) {
const canvasRef = useRef(null)
return (
<Canvas3D ref={canvasRef} width={800} height={600}>
<Scene background="#1a1a2e">
<PerspectiveCamera fov={45} position={[0, 1, 5]} />
<AmbientLight intensity={0.5} />
<DirectionalLight position={[3, 5, 3]} intensity={1.2} />
<Model src={path} scale={[1, 1, 1]} position={[0, 0, 0]} />
</Scene>
</Canvas3D>
)
}Components
<Scene>
Root 3D scene container.
| Prop | Type | Default | Description |
|---|---|---|---|
background | string | '#000000' | Background color |
<PerspectiveCamera>
| Prop | Type | Default | Description |
|---|---|---|---|
fov | number | 60 | Vertical field of view (degrees) |
position | [x, y, z] | [0, 0, 3] | Camera world position |
target | [x, y, z] | [0, 0, 0] | Look-at target |
near | number | 0.1 | Near clip plane |
far | number | 1000 | Far clip plane |
<Mesh>
| Prop | Type | Default | Description |
|---|---|---|---|
geometry | ReactElement | — | Geometry component |
material | ReactElement | — | Material component |
position | [x, y, z] | [0, 0, 0] | World position |
rotation | [x, y, z] | [0, 0, 0] | Euler angles (radians) |
scale | [x, y, z] | [1, 1, 1] | Scale per axis |
<Model>
| Prop | Type | Description |
|---|---|---|
src | string | Absolute or relative path to .glb/.gltf file |
position | [x, y, z] | World position |
rotation | [x, y, z] | Euler angles (radians) |
scale | [x, y, z] | Scale per axis |
Geometries
| Component | Props |
|---|---|
<BoxGeometry> | width, height, depth |
<SphereGeometry> | radius, widthSegments, heightSegments |
<PlaneGeometry> | width, height |
Lights
| Component | Props |
|---|---|
<AmbientLight> | intensity, color |
<DirectionalLight> | position, intensity, color |
Materials
| Component | Props |
|---|---|
<MeshStandardMaterial> | color |
@velox/three renders into a native GPU surface using VeloxKit's wgpu pipeline — not Three.js or WebGL. The API is Three.js-inspired but uses a custom renderer.