Skip to content

Commit

Permalink
large refactoring
Browse files Browse the repository at this point in the history 
Reactive context properties, Better hierarchy and interactivity system, <Canvas> cleanup & outsourced modules
  • Loading branch information
@grischaerbe
grischaerbe committed Jan 21, 2022
1 parent 6baea9e commit ea2f5bf
Show file tree
Hide file tree
Showing 29 changed files with 854 additions and 415 deletions.
163 changes: 84 additions & 79 deletions README.md
View file
Expand Up @@ -70,6 +70,8 @@ It provides strictly typed components to quickly and easily build three.js scene

It also aims to provide the building blocks to quickly extend threlte when it's needed.

> :warning: threlte is still in development and you should expect breaking changes. Check the release notes before updating. If you want to be in the safe side, install threlte with `npm i threlte three --save-exact` to lock the version.
## Getting started

Install threlte and three.js:
Expand Down Expand Up @@ -357,10 +359,11 @@ The `<Canvas>` component provides two very useful contexts: `ThrelteContext` and

```ts
type ThrelteContext = {
size: { width: number; height: number }
pointer?: Vector2
size: Readable<Size>
pointer: Writable<Vector2>
pointerOverCanvas: Writable<boolean>
clock: Clock
camera?: Camera
camera: Writable<Camera>
scene: Scene
renderer?: WebGLRenderer
composer?: EffectComposer
Expand All @@ -369,8 +372,9 @@ type ThrelteContext = {

type ThrelteRootContext = {
setCamera: (camera: Camera) => void
linear: boolean
resizeOptions?: UseResizeOptions
linear: Writable<boolean>
flat: Writable<boolean>
dpr: Writable<number>
addPass: (pass: Pass) => void
removePass: (pass: Pass) => void
addRaycastableObject: (obj: Object3D) => void
Expand All @@ -384,15 +388,7 @@ type ThrelteRootContext = {
}
```
See `useThrelte` and `useThrelteRoot` on how to use these.
```ts
type UseResizeOptions = {
axis?: 'horizontal' | 'vertical' | 'both'
runOnInit?: boolean
debounce?: number
}
```
See [`useThrelte`](#leftwards_arrow_with_hook-usethrelte) and [`useThrelteRoot`]((#leftwards_arrow_with_hook-usethrelteroot)) on how to use these.
### Components
Expand All @@ -410,7 +406,9 @@ name: type

The `<Canvas>` component is the root of your three.js scene.

By default, the `<canvas>` element and the renderer will resize to fit the parent element whenever the window resizes.
By default, the `<canvas>` element and the renderer will resize to fit the parent element whenever the window resizes. Provide the property `size` to set a fixed `<canvas>` size.

`<Canvas>` also provides a default camera, located at `{ z: 5 }`.

###### Properties <!-- omit in toc -->

Expand All @@ -423,11 +421,8 @@ frameloop: 'always' | 'demand' = 'demand'
debugFrameloop: boolean = false
shadows: boolean = true
shadowMapType: THREE.ShadowMapType = THREE.PCFSoftShadowMap
resizeOptions: {
axis?: 'horizontal' | 'vertical' | 'both'
runOnInit?: boolean
debounce?: number
} | undefined = undefined
size: { width: number, height: number } | undefined = undefined
rendererParameters: THREE.WebGLRendererParameters | undefined = undefined
```

###### Bindings <!-- omit in toc -->
Expand Down Expand Up @@ -490,8 +485,8 @@ mesh: THREE.Mesh
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
click: CustomEvent<ThreltePointerEvent>
contextmenu: CustomEvent<ThreltePointerEvent>
pointerup: CustomEvent<ThreltePointerEvent>
Expand Down Expand Up @@ -541,8 +536,8 @@ group: THREE.Group
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :globe_with_meridians: \<Object3D>
Expand Down Expand Up @@ -587,15 +582,17 @@ object: THREE.Object3D
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :globe_with_meridians: \<GLTF>

To use DRACO compression, provide a path to the DRACO decoder.
To use KTX2 compressed textures, provide a path to the KTX2 transcoder.

You are able to change the property `url` to load new 3D content. New content will be swapped as soon as loading is finished.

###### Example <!-- omit in toc -->

```svelte
Expand Down Expand Up @@ -638,8 +635,11 @@ scene: THREE.Group
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
load: GLTF // The content finished loading
unload: undefined // New content finished loading and the old content is unloaded and disposed
error: string // An error occured while loading and parsing
viewportenter: undefined
viewportleave: undefined
```

#### :recycle: Object Instances
Expand Down Expand Up @@ -708,8 +708,8 @@ inViewport: boolean
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :recycle: \<MeshInstance>
Expand Down Expand Up @@ -761,8 +761,8 @@ inViewport: boolean
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
click: CustomEvent<ThreltePointerEvent>
contextmenu: CustomEvent<ThreltePointerEvent>
pointerup: CustomEvent<ThreltePointerEvent>
Expand Down Expand Up @@ -815,8 +815,8 @@ inViewport: boolean
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :recycle: \<LightInstance>
Expand Down Expand Up @@ -868,8 +868,8 @@ inViewport: boolean
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

#### :high_brightness: Lights
Expand Down Expand Up @@ -913,8 +913,8 @@ light: THREE.AmbientLight
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :high_brightness: \<DirectionalLight>
Expand Down Expand Up @@ -977,8 +977,8 @@ light: THREE.DirectionalLight
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :high_brightness: \<HemisphereLight>
Expand Down Expand Up @@ -1024,8 +1024,8 @@ light: THREE.HemisphereLight
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :high_brightness: \<PointLight>
Expand Down Expand Up @@ -1078,8 +1078,8 @@ light: THREE.PointLight
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :high_brightness: \<SpotLight>
Expand Down Expand Up @@ -1137,8 +1137,8 @@ light: THREE.SpotLight
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

#### :movie_camera: Cameras
Expand Down Expand Up @@ -1187,8 +1187,8 @@ camera: THREE.OrthographicCamera
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

##### :movie_camera: \<PerspectiveCamera>
Expand Down Expand Up @@ -1236,15 +1236,16 @@ camera: THREE.PerspectiveCamera
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
```

#### :repeat: Controls

##### :repeat: \<OrbitControls>

The component `<OrbitControls>` must be a direct child of a camera component and will mount itself to that camera. As soon as the OrbitControls are mounted, the frame loop will continously run.
The component `<OrbitControls>` must be a direct child of a camera component and will mount itself to that camera.
If the properties `autoRotate` or `enableDamping` are set to true, the frame loop will run continously.

###### Example <!-- omit in toc -->

Expand Down Expand Up @@ -1316,9 +1317,9 @@ controls: THREE.OrbitControls
###### Events <!-- omit in toc -->

```ts
change: CustomEvent<undefined>
start: CustomEvent<undefined>
end: CustomEvent<undefined>
change: undefined
start: undefined
end: undefined
```

#### :lipstick: Post Processing
Expand Down Expand Up @@ -1478,8 +1479,8 @@ text: Text
###### Events <!-- omit in toc -->

```ts
viewportenter: CustomEvent<undefined>
viewportleave: CustomEvent<undefined>
viewportenter: undefined
viewportleave: undefined
click: CustomEvent<ThreltePointerEvent>
contextmenu: CustomEvent<ThreltePointerEvent>
pointerup: CustomEvent<ThreltePointerEvent>
Expand Down Expand Up @@ -1574,18 +1575,20 @@ rootCtx: ThrelteRootContext
#### :leftwards_arrow_with_hook: useThrelte

This hook lets you consume the state of the `<Canvas>` component which contains the renderer, camera, scene and so on.
This hook lets you consume the state of the `<Canvas>` component which contains the renderer, camera, scene and so on.
It is recommended to set the camera via the property `setCamera` of the [root context]((#leftwards_arrow_with_hook-usethrelteroot)).

```ts
const {
size, // { width: number; height: number }
pointer, // Vector2 | undefined
clock, // Clock
camera, // Camera | undefined
scene, // Scene
renderer, // WebGLRenderer | undefined
composer, // EffectComposer | undefined
invalidate, // (reason?: string) => void
size, // Readable<Size>
pointer, // Writable<Vector2>
pointerOverCanvas, // Writable<boolean>
clock, // Clock
camera, // Writable<Camera>
scene, // Scene
renderer, // WebGLRenderer
composer, // EffectComposer
invalidate, // (reason?: string) => void
} = useThrelte()
```

Expand All @@ -1604,23 +1607,25 @@ invalidate('changed material color')
#### :leftwards_arrow_with_hook: useThrelteRoot

This hook lets you consume the root context. Although it can be useful, this is mostly used internally.
This hook lets you consume the root context. Although it can be useful, this is mostly used internally.
The properties `linear`, `flat` and `dpr` are reactive and can also be set.

```ts
const {
setCamera, // : (camera: Camera) => void
linear, // : boolean
resizeOptions, // ?: UseResizeOptions
addPass, // : (pass: Pass) => void
removePass, // : (pass: Pass) => void
addRaycastableObject, // : (obj: Object3D) => void
removeRaycastableObject, // : (obj: Object3D) => void
addInteractiveObject, // : (obj: Object3D) => void
removeInteractiveObject, // : (obj: Object3D) => void
interactiveObjects, // : Set<Object3D>
raycastableObjects, // : Set<Object3D>
raycaster, // : Raycaster
lastIntersection, // : Intersection<Object3D<Event>> | null
setCamera, // (camera: Camera) => void
linear, // Writable<boolean>
flat, // Writable<boolean>
dpr, // Writable<number>
addPass, // (pass: Pass) => void
removePass, // (pass: Pass) => void
addRaycastableObject, // (obj: Object3D) => void
removeRaycastableObject, // (obj: Object3D) => void
addInteractiveObject, // (obj: Object3D) => void
removeInteractiveObject, // (obj: Object3D) => void
interactiveObjects, // Set<Object3D>
raycastableObjects, // Set<Object3D>
raycaster, // Raycaster
lastIntersection, // Intersection<Object3D<Event>> | null
} = useThrelteRoot()
```

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
@@ -1,6 +1,6 @@
{
"name": "threlte",
"version": "0.2.1",
"version": "1.0.0",
"author": "Grischa Erbe <hello@legrisch.com> (https://legrisch.com)",
"license": "MIT",
"scripts": {
Expand Down

0 comments on commit ea2f5bf

Please sign in to comment.