diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index b1d6da95..8b49c056 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -8,22 +8,20 @@ env: jobs: lint: name: Lint - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 strategy: matrix: - node-version: [18] + node-version: [20] steps: - name: Checkout uses: actions/checkout@v4 - - name: Setup Pnpm - uses: pnpm/action-setup@v2 - with: - version: 8 + - name: Setup pnpm + uses: pnpm/action-setup@v4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - cache: 'pnpm' + cache: pnpm - name: Install dependencies run: pnpm install - name: Run Lint diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c4b18cb..fc21c48c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,86 @@ + + +## [4.0.0-rc.2](https://github.com/Tresjs/cientos/compare/4.0.0-rc.1...4.0.0-rc.2) (2024-07-26) + +## [4.0.0-rc.1](https://github.com/Tresjs/cientos/compare/4.0.0-rc.0...4.0.0-rc.1) (2024-07-25) + + +### Features + +* **fbo:** add autoRender flag as an option to useFBO ([#458](https://github.com/Tresjs/cientos/issues/458)) ([ddcd4ac](https://github.com/Tresjs/cientos/commit/ddcd4ac36cfd5b5cbb06e967878a9468b390a17c)) + +## [4.0.0-rc.0](https://github.com/Tresjs/cientos/compare/4.0.0-next.1...4.0.0-rc.0) (2024-07-24) + + +### Features + +* **Sparkles:** invalidate on update ([#446](https://github.com/Tresjs/cientos/issues/446)) ([cbfd226](https://github.com/Tresjs/cientos/commit/cbfd226b94fb363f3a59a735365c679e8142420f)) + + +### Bug Fixes + +* reimplement ContactShadows for v4 ([#449](https://github.com/Tresjs/cientos/issues/449)) ([d71c328](https://github.com/Tresjs/cientos/commit/d71c328969da64beee05088ced05bd7b632d6f31)) +* update to core v4.2.2 to remove warning on invalidation ([42afa6e](https://github.com/Tresjs/cientos/commit/42afa6e67962796d2ce076a29917262f9ca09ea5)) + +## [4.0.0-next.1](https://github.com/Tresjs/cientos/compare/3.9.0...4.0.0-next.1) (2024-07-17) + + +### ⚠ BREAKING CHANGES + +* **MeshReflectionMaterial:** add features/docs, reorganize + +### Features + +* 423 enable on demand render mode usage ([#436](https://github.com/Tresjs/cientos/issues/436)) ([b3eef40](https://github.com/Tresjs/cientos/commit/b3eef40430d23e2ba6c5a195c0cf510c0bc54ce9)) +* **AnimatedSprite:** add asSprite prop ([7a14b55](https://github.com/Tresjs/cientos/commit/7a14b5592d78f57785d04bd1484a35e501b7cceb)) +* **AnimatedSprite:** dispose texture onUnmounted ([18d6904](https://github.com/Tresjs/cientos/commit/18d6904570cc34ca9c3e64e6b42ec5c639a6e885)) +* **AnimatedSprite:** remove explicit click event ([042c350](https://github.com/Tresjs/cientos/commit/042c350883aec53bdf0331cc4b3378e06d87fb88)) +* **AnimatedSprite:** remove unnecessary Suspense ([082d695](https://github.com/Tresjs/cientos/commit/082d695f1a6843a8fa5edcd8e6c32ec8530a03a9)) +* **app:** 421 Update components to use useLoop instead of useRenderLoop ([ad3b290](https://github.com/Tresjs/cientos/commit/ad3b290c4afb3adf5bf36ccf02d08ea1beb98bc8)) +* **app:** Add the option for x and y in mouseparallax component ([#444](https://github.com/Tresjs/cientos/issues/444)) ([12d5834](https://github.com/Tresjs/cientos/commit/12d5834becba2cdfc26300fd5bf1ec1f9e26afe3)) +* re-remove tweakpane ([#425](https://github.com/Tresjs/cientos/issues/425)) ([72284ce](https://github.com/Tresjs/cientos/commit/72284ce2e0e378d353b3573a6216ad6f6dcd4425)) +* update to core v4.2 ([14b30f9](https://github.com/Tresjs/cientos/commit/14b30f99282ed3cb1d21cbdf31e672867d79f27c)) + + +### Bug Fixes + +* **Lensflare demo:** add camera [#435](https://github.com/Tresjs/cientos/issues/435) ([#441](https://github.com/Tresjs/cientos/issues/441)) ([981de57](https://github.com/Tresjs/cientos/commit/981de572c97183b8d2070925daa8209d2fa6b55e)) +* **MeshReflectionMaterial:** add features/docs, reorganize ([58703e3](https://github.com/Tresjs/cientos/commit/58703e362bbe731a56b7ce903160df13513ec18a)) +* remove hardcoded speed number, that setting at 0 doesn't stop the effect ([e67f3a2](https://github.com/Tresjs/cientos/commit/e67f3a295025ca1bfb1c0f664ceccefac389e0af)) +* **SkyDemo:** value.value -> value ([82fe77b](https://github.com/Tresjs/cientos/commit/82fe77b4dc11fd23b47e40bc33a843dc69cf017f)) +* **types:** fixed types generics for `useGLTF` ([#448](https://github.com/Tresjs/cientos/issues/448)) ([62a9bcc](https://github.com/Tresjs/cientos/commit/62a9bcc2d4490c7493667c3316441b5363cb42fc)) +* uncomment section ([fac2253](https://github.com/Tresjs/cientos/commit/fac22534818a15d49f631b790185f4f1266c7339)) +* vue attrs hyphenation issues ([4f9b61b](https://github.com/Tresjs/cientos/commit/4f9b61b954a916d8f8880798f06c03b79092896b)) + +## [4.0.0-next.0](https://github.com/Tresjs/cientos/compare/3.9.0...4.0.0-next.1) (2024-03-27) + + +### ⚠ BREAKING CHANGES + +* **app:** 349 Remove directives from cientos +* **app:** 227 Change the keyboardcontrols implementation + +### Features + +* add arrow keys support ([39e2094](https://github.com/Tresjs/cientos/commit/39e2094338ba37613b189e7d593ecc2b0a35680b)) +* **AnimatedSprite:** add AnimatedSprite, playground, docs ([d6ea81b](https://github.com/Tresjs/cientos/commit/d6ea81b5540c2f4bf0f233e269ed98992ee8a551)) +* **AnimatedSprite:** allow [numCols, numRows] as atlas prop ([3309d9c](https://github.com/Tresjs/cientos/commit/3309d9c24ee1d006b41bdeaa29eac7c8f9658342)) +* **AnimatedSprite:** always emit last frame name on loop and on end ([ed16136](https://github.com/Tresjs/cientos/commit/ed16136a84143396ae8accc327429c1ef1fbdd1b)) +* **AnimatedSprite:** change default fps ([44831a4](https://github.com/Tresjs/cientos/commit/44831a492e6a881061b9a113d1a627026b172056)) +* **app:** 227 Change the keyboardcontrols implementation ([fed0f86](https://github.com/Tresjs/cientos/commit/fed0f86b3c92aa8ea86be0e6193e1639d421bcc2)) +* **app:** 227 Final details, ready to go ([6f06213](https://github.com/Tresjs/cientos/commit/6f06213d92f9b389c3d1fca377002ae0b060c87b)) + + +### Bug Fixes + +* **AnimatedSprite:** return nullFrame animation if requested animation not found ([453819e](https://github.com/Tresjs/cientos/commit/453819e0237b58177a34bbeee0af4ce44252195c)) +* **Atlas:** add missing argument to function call ([e6b147e](https://github.com/Tresjs/cientos/commit/e6b147e45520238e8fd467863972af8fe8f8ec37)) + + +### Code Refactoring + +* **app:** 349 Remove directives from cientos ([8fc4cd5](https://github.com/Tresjs/cientos/commit/8fc4cd582ba85cc09e000627449622e8861ec76a)) + ## [3.9.0](https://github.com/Tresjs/cientos/compare/3.8.0...3.9.0) (2024-05-07) ### Features @@ -38,6 +121,22 @@ * transformControls throws error when switching active camera ([f1a477a](https://github.com/Tresjs/cientos/commit/f1a477a46c341f6ed4e58fce1e8999e19feba8d0)) * **type:** correct the east description ([c26da1f](https://github.com/Tresjs/cientos/commit/c26da1f11524f2445a1b0653f35354de4d3b10ed)) +## [4.0.0-next.0](https://github.com/Tresjs/cientos/compare/3.8.0...4.0.0-next.0) (2024-03-27) + + +### Features + +* **app:** 252 adding ocean component ([7efb293](https://github.com/Tresjs/cientos/commit/7efb29300a5cda624801316e6bc4f33a88e8de04)) +* **app:** 252 Renamed as ocean, add sky support ([473bac6](https://github.com/Tresjs/cientos/commit/473bac61d9831b9334f4ba78b0d4ab979b7b167f)) +* **app:** Add RoundedBox component ([8b6cb67](https://github.com/Tresjs/cientos/commit/8b6cb67b686bf242aa6e96c3b68af535ddb944d1)) + + +### Bug Fixes + +* **app:** 252 Apply review feedback ([4449208](https://github.com/Tresjs/cientos/commit/4449208fccedca0a37ea2e62142b00188a21e0ad)) +* apply feedback ([3a50bc2](https://github.com/Tresjs/cientos/commit/3a50bc29c00dd64775643ab08fe3e5ba569c8248)) +* little detail in the interface ([fb6456a](https://github.com/Tresjs/cientos/commit/fb6456a063cc28868fe0178b28695c04ad812ccc)) + ## [3.8.0](https://github.com/Tresjs/cientos/compare/3.7.0...3.8.0) (2024-02-07) ### Features diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 69987042..bd03f28e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,20 +1,8 @@ import { defineConfig } from 'vitepress' import { resolve } from 'pathe' -import componentList from '../component-list/components' const whitelist = ['TresCanvas', 'TresLeches', 'TresScene'] -const collapsedSidebarCategories = new Set(['Materials', 'Shapes', 'Misc', 'Directives']) -const sidebar = [ - { - text: 'Guide', - items: [{ text: 'Introduction', link: '/guide/' }], - }, - ...componentList, -].map( - c => collapsedSidebarCategories.has(c.text) ? Object.assign(c, { collapsed: true }) : c, -) - // https://vitepress.dev/reference/site-config export default defineConfig({ title: 'Cientos', @@ -65,7 +53,116 @@ export default defineConfig({ { text: 'Examples', link: 'https://lab.tresjs.org/' }, ], - sidebar, + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/guide/' }, + { text: 'Migration from v3', link: '/guide/migrating-from-v3' }, + ], + }, + { + text: 'Abstractions', + items: [ + { text: 'Text3D', link: '/guide/abstractions/text-3d' }, + { text: 'Levioso (Float)', link: '/guide/abstractions/levioso' }, + { text: 'useAnimations', link: '/guide/abstractions/use-animations' }, + { text: 'MouseParallax', link: '/guide/abstractions/mouse-parallax' }, + { text: 'Lensflare', link: '/guide/abstractions/lensflare' }, + { text: 'Reflector', link: '/guide/abstractions/reflector' }, + { text: 'GlobalAudio', link: '/guide/abstractions/global-audio' }, + { text: 'Fbo', link: '/guide/abstractions/fbo' }, + { text: 'useFBO', link: '/guide/abstractions/use-fbo' }, + { text: 'useSurfaceSampler', link: '/guide/abstractions/use-surface-sampler' }, + { text: 'Sampler', link: '/guide/abstractions/sampler' }, + { text: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' }, + ], + }, + { + text: 'Controls', + items: [ + { text: 'OrbitControls', link: '/guide/controls/orbit-controls' }, + { text: 'CameraControls', link: '/guide/controls/camera-controls' }, + { text: 'TransformControls', link: '/guide/controls/transform-controls' }, + { text: 'PointerLockControls', link: '/guide/controls/pointer-lock-controls' }, + { text: 'KeyboardControls', link: '/guide/controls/keyboard-controls' }, + { text: 'ScrollControls', link: '/guide/controls/scroll-controls' }, + { text: 'MapControls', link: '/guide/controls/map-controls' }, + ], + }, + { + text: 'Loaders', + items: [ + { text: 'useProgress', link: '/guide/loaders/use-progress' }, + { text: 'useGLTF', link: '/guide/loaders/use-gltf' }, + { text: 'GLTFModel', link: '/guide/loaders/gltf-model' }, + { text: 'useFBX', link: '/guide/loaders/use-fbx' }, + { text: 'FBXModel', link: '/guide/loaders/fbx-model' }, + { text: 'useVideoTexture', link: '/guide/loaders/use-video-texture' }, + { text: 'SVG', link: '/guide/loaders/svg' }, + ], + }, + { + text: 'Materials', + collapsed: true, + items: [ + { text: 'WobbleMaterial', link: '/guide/materials/wobble-material' }, + { text: 'MeshGlassMaterial', link: '/guide/materials/glass-material' }, + { text: 'CustomShaderMaterial', link: '/guide/materials/custom-shader-material' }, + { text: 'MeshReflectionMaterial', link: '/guide/materials/mesh-reflection-material' }, + ], + }, + { + text: 'Shapes', + collapsed: true, + items: [ + { text: 'Box', link: '/guide/shapes/box' }, + { text: 'CatmullRomCurve3', link: '/guide/shapes/catmullromcurve3' }, + { text: 'Circle', link: '/guide/shapes/circle' }, + { text: 'Cone', link: '/guide/shapes/cone' }, + { text: 'Cylinder', link: '/guide/shapes/cylinder' }, + { text: 'Dodecahedron', link: '/guide/shapes/dodecahedron' }, + { text: 'Icosahedron', link: '/guide/shapes/icosahedron' }, + { text: 'Line2', link: '/guide/shapes/line2' }, + { text: 'Octahedron', link: '/guide/shapes/octahedron' }, + { text: 'Plane', link: '/guide/shapes/plane' }, + { text: 'Ring', link: '/guide/shapes/ring' }, + { text: 'RoundedBox', link: '/guide/shapes/rounded-box' }, + { text: 'Sphere', link: '/guide/shapes/sphere' }, + { text: 'Superformula', link: '/guide/shapes/superformula' }, + { text: 'Tetrahedron', link: '/guide/shapes/tetrahedron' }, + { text: 'Torus', link: '/guide/shapes/torus' }, + { text: 'TorusKnot', link: '/guide/shapes/torus-knot' }, + { text: 'Tube', link: '/guide/shapes/tube' }, + ], + }, + { + text: 'Staging', + items: [ + { text: 'Backdrop', link: '/guide/staging/backdrop' }, + { text: 'Environment', link: '/guide/staging/environment' }, + { text: 'useEnvironment', link: '/guide/staging/use-environment' }, + { text: 'Sky', link: '/guide/staging/sky' }, + { text: 'Stars', link: '/guide/staging/stars' }, + { text: 'Smoke', link: '/guide/staging/smoke' }, + { text: 'ContactShadows', link: '/guide/staging/contact-shadows' }, + { text: 'Precipitation', link: '/guide/staging/precipitation' }, + { text: 'Sparkles', link: '/guide/staging/sparkles' }, + { text: 'Ocean', link: '/guide/staging/ocean' }, + ], + }, + { + text: 'Misc', + collapsed: true, + items: [ + { text: 'Stats', link: '/guide/misc/stats' }, + { text: 'Html', link: '/guide/misc/html-component' }, + { text: 'StatsGl', link: '/guide/misc/stats-gl' }, + { text: 'useGLTFExporter', link: '/guide/misc/use-gltf-exporter' }, + { text: 'BakeShadows', link: '/guide/misc/bake-shadows' }, + ], + }, + ], socialLinks: [ { icon: 'github', link: 'https://github.com/tresjs/cientos' }, diff --git a/docs/.vitepress/theme/components/AnimatedSpriteCenterDemo.vue b/docs/.vitepress/theme/components/AnimatedSpriteCenterDemo.vue new file mode 100644 index 00000000..4fd22426 --- /dev/null +++ b/docs/.vitepress/theme/components/AnimatedSpriteCenterDemo.vue @@ -0,0 +1,113 @@ + + + diff --git a/docs/.vitepress/theme/components/AnimatedSpriteDefinitionsDemo.vue b/docs/.vitepress/theme/components/AnimatedSpriteDefinitionsDemo.vue new file mode 100644 index 00000000..c16760c0 --- /dev/null +++ b/docs/.vitepress/theme/components/AnimatedSpriteDefinitionsDemo.vue @@ -0,0 +1,25 @@ + + + diff --git a/docs/.vitepress/theme/components/AnimatedSpriteDemo.vue b/docs/.vitepress/theme/components/AnimatedSpriteDemo.vue new file mode 100644 index 00000000..04ce50ed --- /dev/null +++ b/docs/.vitepress/theme/components/AnimatedSpriteDemo.vue @@ -0,0 +1,22 @@ + + + diff --git a/docs/.vitepress/theme/components/AnimatedSpriteNamedAnimationDemo.vue b/docs/.vitepress/theme/components/AnimatedSpriteNamedAnimationDemo.vue new file mode 100644 index 00000000..69373371 --- /dev/null +++ b/docs/.vitepress/theme/components/AnimatedSpriteNamedAnimationDemo.vue @@ -0,0 +1,28 @@ + + + diff --git a/docs/.vitepress/theme/components/ContactShadowDemo.vue b/docs/.vitepress/theme/components/ContactShadowDemo.vue deleted file mode 100644 index 656d09bb..00000000 --- a/docs/.vitepress/theme/components/ContactShadowDemo.vue +++ /dev/null @@ -1,75 +0,0 @@ - - - diff --git a/docs/.vitepress/theme/components/ContactShadowsDemo.vue b/docs/.vitepress/theme/components/ContactShadowsDemo.vue new file mode 100644 index 00000000..840f6655 --- /dev/null +++ b/docs/.vitepress/theme/components/ContactShadowsDemo.vue @@ -0,0 +1,15 @@ + + + diff --git a/docs/.vitepress/theme/components/FboDemo.vue b/docs/.vitepress/theme/components/FboDemo.vue index 1823255d..f3416160 100644 --- a/docs/.vitepress/theme/components/FboDemo.vue +++ b/docs/.vitepress/theme/components/FboDemo.vue @@ -55,7 +55,7 @@ onMounted(async () => { diff --git a/docs/.vitepress/theme/components/KeyboardControlsDemo.vue b/docs/.vitepress/theme/components/KeyboardControlsDemo.vue new file mode 100644 index 00000000..ac20b564 --- /dev/null +++ b/docs/.vitepress/theme/components/KeyboardControlsDemo.vue @@ -0,0 +1,13 @@ + + + diff --git a/docs/.vitepress/theme/components/MeshReflectionMaterialDemo.vue b/docs/.vitepress/theme/components/MeshReflectionMaterialDemo.vue new file mode 100644 index 00000000..639b307f --- /dev/null +++ b/docs/.vitepress/theme/components/MeshReflectionMaterialDemo.vue @@ -0,0 +1,31 @@ + + + diff --git a/docs/.vitepress/theme/components/MouseParallaxDemo.vue b/docs/.vitepress/theme/components/MouseParallaxDemo.vue index 91a5f101..202d6402 100644 --- a/docs/.vitepress/theme/components/MouseParallaxDemo.vue +++ b/docs/.vitepress/theme/components/MouseParallaxDemo.vue @@ -14,7 +14,7 @@ import { MouseParallax, TorusKnot } from '@tresjs/cientos' diff --git a/docs/.vitepress/theme/components/ScrollControlsDemo.vue b/docs/.vitepress/theme/components/ScrollControlsDemo.vue index 34dc3f24..34097ea2 100644 --- a/docs/.vitepress/theme/components/ScrollControlsDemo.vue +++ b/docs/.vitepress/theme/components/ScrollControlsDemo.vue @@ -16,8 +16,8 @@ useControls({ const { onLoop } = useRenderLoop() onLoop(() => { if (boxRef.value) { - boxRef.value.value.rotation.x = progress.value * 10 - boxRef.value.value.rotation.y = progress.value * 2 + boxRef.value.instance.rotation.x = progress.value * 10 + boxRef.value.instance.rotation.y = progress.value * 2 } }) diff --git a/docs/.vitepress/theme/components/ScrollControlsProgressCameraDemo.vue b/docs/.vitepress/theme/components/ScrollControlsProgressCameraDemo.vue index 243994d3..49d1680b 100644 --- a/docs/.vitepress/theme/components/ScrollControlsProgressCameraDemo.vue +++ b/docs/.vitepress/theme/components/ScrollControlsProgressCameraDemo.vue @@ -9,9 +9,9 @@ const progress = ref(0) const { onLoop } = useRenderLoop() onLoop(() => { if (boxRef.value) { - boxRef.value.value.rotation.x = progress.value * 10 - boxRef.value.value.rotation.y = progress.value * 2 - boxRef.value.value.position.x = progress.value * 4.5 + boxRef.value.instance.rotation.x = progress.value * 10 + boxRef.value.instance.rotation.y = progress.value * 2 + boxRef.value.instance.position.x = progress.value * 4.5 } }) diff --git a/docs/.vitepress/theme/components/ScrollControlsProgressDemo.vue b/docs/.vitepress/theme/components/ScrollControlsProgressDemo.vue index 12d2db60..41b8ae4d 100644 --- a/docs/.vitepress/theme/components/ScrollControlsProgressDemo.vue +++ b/docs/.vitepress/theme/components/ScrollControlsProgressDemo.vue @@ -9,9 +9,9 @@ const progress = ref(0) const { onLoop } = useRenderLoop() onLoop(() => { if (boxRef.value) { - boxRef.value.value.rotation.x = progress.value * 10 - boxRef.value.value.rotation.y = progress.value * 2 - boxRef.value.value.position.x = progress.value * 4.5 + boxRef.value.instance.rotation.x = progress.value * 10 + boxRef.value.instance.rotation.y = progress.value * 2 + boxRef.value.instance.position.x = progress.value * 4.5 } }) diff --git a/docs/.vitepress/theme/components/ScrollControlsSlotsDemo.vue b/docs/.vitepress/theme/components/ScrollControlsSlotsDemo.vue index de420a20..2e06e6de 100644 --- a/docs/.vitepress/theme/components/ScrollControlsSlotsDemo.vue +++ b/docs/.vitepress/theme/components/ScrollControlsSlotsDemo.vue @@ -10,8 +10,8 @@ const progress = ref(0) const { onLoop } = useRenderLoop() onLoop(() => { if (boxRef.value) { - boxRef.value.value.rotation.x = progress.value * 10 - boxRef.value.value.rotation.y = progress.value * 2 + boxRef.value.instance.rotation.x = progress.value * 10 + boxRef.value.instance.rotation.y = progress.value * 2 } }) diff --git a/docs/component-list/components.ts b/docs/component-list/components.ts index 59f4f26c..ebc3cc8b 100644 --- a/docs/component-list/components.ts +++ b/docs/component-list/components.ts @@ -68,7 +68,7 @@ export default [ { text: 'CatmullRomCurve3', link: '/guide/shapes/catmullromcurve3' }, { text: 'Circle', link: '/guide/shapes/circle' }, { text: 'Cone', link: '/guide/shapes/cone' }, - { text: 'Cylinder', link: '/guide/shapes/cylinder' }, + { text: 'Cylinder', link: '/guide/shapes/cylinder' }, { text: 'Dodecahedron', link: '/guide/shapes/dodecahedron' }, { text: 'Icosahedron', link: '/guide/shapes/icosahedron' }, { text: 'Line2', link: '/guide/shapes/line2' }, @@ -93,7 +93,7 @@ export default [ { text: 'Sky', link: '/guide/staging/sky' }, { text: 'Stars', link: '/guide/staging/stars' }, { text: 'Smoke', link: '/guide/staging/smoke' }, - { text: 'Contact Shadows', link: '/guide/staging/contact-shadows' }, + { text: 'ContactShadows', link: '/guide/staging/contact-shadows' }, { text: 'Precipitation', link: '/guide/staging/precipitation' }, { text: 'Sparkles', link: '/guide/staging/sparkles' }, { text: 'Ocean', link: '/guide/staging/ocean' }, @@ -103,7 +103,6 @@ export default [ { text: 'Misc', items: [ - { text: 'useTweakpane', link: '/guide/misc/use-tweakpane' }, { text: 'Stats', link: '/guide/misc/stats' }, { text: 'Html', link: '/guide/misc/html-component' }, { text: 'StatsGl', link: '/guide/misc/stats-gl' }, diff --git a/docs/guide/abstractions/animated-sprite.md b/docs/guide/abstractions/animated-sprite.md new file mode 100644 index 00000000..f2d5e973 --- /dev/null +++ b/docs/guide/abstractions/animated-sprite.md @@ -0,0 +1,174 @@ +# AnimatedSprite + + + + + +`` displays 2D animations defined in a [texture atlas](https://en.wikipedia.org/wiki/Texture_atlas). A typical `` will use: + +* an image containing multiple sprites +* a JSON atlas containing the individual sprite coordinates in the image + +## Usage + +<<< @/.vitepress/theme/components/AnimatedSpriteDemo.vue{3,12-20} + +::: warning Suspense +`` loads resources asynchronously, so it must be wrapped in a ``. +::: + +## Compiling an atlas + +In typical usage, `` requires both the URL to a texture of compiled sprite images and a JSON atlas containing information about the sprites in the texture. + +* [example compiled texture](https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosTexture.png) +* [example JSON atlas](https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosAtlas.json) + +Compiling source images into a texture atlas is usually handled by third-party software. You may find [TexturePacker](https://www.codeandweb.com/texturepacker) useful. + +## Without an atlas + +There may be cases where you don't want to supply an atlas to the `atlas` prop. To do so: + +* Compile your source images into a single image texture. +* Space each sprite into equally sized columns and rows in the compiled image texture. +* Ensure no extra padding has been added to the compiled image texture. +* Set the `atlas` prop to number of columns, number of rows as `[number, number]`. + +## Spritesheets in the wild + +::: warning +In the wild, spritesheets are often distributed without atlases and the images are often compiled by hand. It can be difficult or impossible to use these resources directly with ``. In many cases, it's advisable to recompile the spritesheet. +::: + +### How to recompile an existing spritesheet image + +* Cut individual sprites from the spritesheet and paste them into separate layers in an image editing application, e.g., GIMP. +* Align the layers for animation. Toggling layer visibility on/off will show you how the animation will display, frame to frame. +* Export layers as individual images. +* Name the individual images according to the following pattern:
`[animation name][frame number].[extension]`
E.g., walk000.png, walk001.png, idle000.png, idle001.png +* Compile individual images into an image texture and atlas using a texture packing application, like TexturePacker. + +## Props + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault
imagestring – + URL of the image texture or an image dataURL. This prop is not reactive. +
atlasstring | Atlasish – +
    +
  • If string, the URL of the JSON atlas.
    • +
  • If number, the number of columns in the texture.
    • +
  • If [number, number], the number of columns/rows in the texture.
    • +
  • If AtlasData, the atlas as a JS object.
    • +
+

This prop is not reactive.

+
definitionsRecord<string, string> – Specify playback frame order and repeated frames (delays). definitions is a record where keys are atlas animation names and values are strings containing an animation definition.
+

A "animation definition" comma-separated string of frame numbers with optional parentheses-surrounded durations.

+

Here is how various definition strings convert to arrays of frames for playback:

+
    +
  • "0,2,1" - [0,2,1], i.e., play frame 0, 2, then 1.
    • +
  • "2(10)" - [2,2,2,2,2,2,2,2,2,2], i.e., play from 2 10 times.
    • +
  • "1-4" - [1,2,3,4]
    • +
  • "10-5(2)" - [10,10,9,9,8,8,7,7,6,6,5,5]
    • +
  • "1-4(3),10(2)" - [1,1,1,2,2,2,3,3,3,4,4,4,10,10]
    • +
+
fpsnumber – Desired frames per second of the animation.30
loopboolean – Whether or not the animation should loop.true
animationstring | [number, number] | number – If string, name of the animation to play. If [number, number], start and end frames of the animation. If number, frame number to display.0
pausedboolean – Whether the animation is paused.false
reversedboolean – Whether to play the animation in reverse.false
flipXboolean – Whether the sprite should be flipped, left to right.false
resetOnEndboolean – For a non-looping animation, when the animation ends, whether to display the zeroth frame.false
asSpriteboolean – Whether to display the object as a THREE.Sprite. See THREE.Spritetrue
centerTresVector2 – Anchor point of the object. A value of [0.5, 0.5] corresponds to the center. [0, 0] is left, bottom.[0.5, 0.5]
alphaTestnumber – Alpha test value for the material. See THREE.Material.alphaTest0.0
depthTestboolean – Depth test value for the material. See THREE.Material.depthTesttrue
depthWriteboolean – Depth write value for the material. See THREE.Material.depthWritetrue
+ +## Events + +| Event | Description | Argument | +| - | - | - | +| `frame` | Emitted when the displayed animation frame changes – at most once per tick, frames may be dropped | `string` – Name of the newly displayed frame | +| `end` | Emitted when the animation ends – `props.loop` must be set to `false` | `string` – Name of the ending frame | +| `loop` | Emitted when the animation loops – `props.loop` must be set to `true` | `string` – Name of the frame at the end of the loop | + +## `animation` + +The `:animation` prop holds either the name of the currently playing animation or a range of frames to play, or a frame number to display. + +### Using named animations as `animation` + +When individual files are converted to a spritesheet/atlas, typically the original images' filenames will be included in the atlas. + +`` uses those filenames to automatically group images into animations. + +Use either of the following naming conventions for your source images ... + +* `[animation name][frame number].[file_extension]` +* `[animation name]_[frame number].[file_extension]` + +... then `` will automatically make all `[animation name]` available for playback. Just pass `[animation name]` to the component's `:animation` prop. + +#### Example + +For our Cientos heart cartoon character animation, here's how the filenames map to animation names. + +| Filenames | Animation name | +| - | - | +| cientosIdle0000.png, cientosIdle0001.png, ... | cientosIdle | +| cientosIdleToWalkTransition0000.png | cientosIdleToWalkTransition | +| cientosWalk0000.png, cientosWalk0001.png, ... | cientosWalk | + +Try it out by clicking a few times on the character below: + + + + + +<<< @/.vitepress/theme/components/AnimatedSpriteNamedAnimationDemo.vue + +## `definitions` + +You can supply an object to the `:definitions` prop. Any [named animation](#animation) can be a key. The value is a string that specifies frame order and delays. + +### Demo + +In this demo, the 'idle' animation is comprised of six different images. By default, those images will play sequentially when the `:animation` prop is `'idle'`. + +But below, we've added a `:definitions` prop with this value for the `idle` key: + +``` +'0-5, 0(10), 1-2, 3(20), 4-5, 0-5(3)' +``` + +So, instead of playing images 0-5 sequentially, this animation will play instead: + +* `0-5` – Play all six images (`0-5`) of the animation normally. +* `0(10), 1-2, 3(20), 4-5` – Play all six images again with a delay of ten frames at the bottom of the bounce (`0(10)`) and a delay of twenty frames at the top of the bounce (`3(20)`). +* `0-5(3)` – Finally, play all six images of the animation with a delay of three frames each. + + + + + +<<< @/.vitepress/theme/components/AnimatedSpriteDefinitionsDemo.vue{17-19} + +## `center` + +In addition to being the sprite's anchor point, the `:center` prop also controls how differently sized source images will "grow" and "shrink". Namely, they "grow out from" and "shrink towards" the center. + +Below is a simple animation containing differently sized source images. The anchor is visible at world position `0, 0, 0`. + + + + diff --git a/docs/guide/abstractions/fbo.md b/docs/guide/abstractions/fbo.md index 27ffd352..37efbca6 100644 --- a/docs/guide/abstractions/fbo.md +++ b/docs/guide/abstractions/fbo.md @@ -20,3 +20,4 @@ Cientos provides an `` component make it easy to use FBOs in your applica | **`height`** | `number` - the height of the FBO | Height of the canvas | | **`depth`** | `boolean` - Whether or not the FBO should render the depth to a [`depthTexture`](https://threejs.org/docs/?q=webglre#api/en/renderers/WebGLRenderTarget.depthTexture). | `false` | | **`settings`** | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget) | `{}` | +| **`autoRender`** | `boolean` - Whether to automatically render the FBO on the default scene. | `true` | diff --git a/docs/guide/abstractions/mouse-parallax.md b/docs/guide/abstractions/mouse-parallax.md index 4af59899..f9d48393 100644 --- a/docs/guide/abstractions/mouse-parallax.md +++ b/docs/guide/abstractions/mouse-parallax.md @@ -10,9 +10,11 @@ You only need to import it and add it to your template as ``. Additionally, you can pass the following props: -`factor` is a number to increase the movement range of the camera. `ease` is a number that smoothes the movement. You can also disable the effect with the `disabled` prop. +`factor` is a number to increase the movement range of the camera. This could be an array of two values corresponding to the x and y values, in that order: `:factor=[x,y]`. -`local` is a boolean that enables movement based on the position of the mouse on the element rather than the window. +`ease` is a number that smooths the movement. This could be an array of two values corresponding to the x and y values, in that order: `:ease=[x,y]`. + +`local` is a boolean that enables movement based on the position of the mouse on the canvas rather than the window. <<< @/.vitepress/theme/components/MouseParallaxDemo.vue{3,15-18} diff --git a/docs/guide/controls/keyboard-controls.md b/docs/guide/controls/keyboard-controls.md index 16ee264f..ec883338 100644 --- a/docs/guide/controls/keyboard-controls.md +++ b/docs/guide/controls/keyboard-controls.md @@ -1,43 +1,31 @@ # KeyboardControls -KeyboardControls is a special type of controller that allows you to move using your keyboard. +KeyboardControls is a special type of controller that allows you to move through the scene using your keyboard, is based on the Unreal Engine Controls. -## Usage - -### In combination with PointerLockControls - -Here you need to use the PointerLockControls with make-default props, KeyboardControls will automatically adapt to it, creating a really good effect first player experiences. - -```vue{5} - -``` + + + -Just by doing this, works great but in addition the TresJs team give some special props (only available with this mode) to create more realistic sensation +::: info +:memo: KeyboardControls uses `PointerLockControls` under the hood, meaning you can use [all the props from ``](pointer-lock-controls#props) as well as it events. +::: -- headBobbing: To simulate the walk balance of the head -- Jump: to jump -- gravity: to control the gravity related to the jump +## Usage -### In combination with slots +You can use the ASDW or the arrows keys to move and your mouse to explore your scene. -Here you can move meshes by using your keyboard, by default you move through the X and Z axis, but you can change it with the is2D prop, to move your meshes on the X and Y axis +```vue{3,10} + -```vue{4-8} ``` @@ -48,14 +36,21 @@ Is really important that the Perspective camera is set first in the canvas. Othe ## Props -| Prop | Description | Default | -| :-------------- | :-------------------------------------------------------------------------------------------- | ---------- | -| **forward** | Keys to go forward. | ['w', 'W'] | -| **back** | Keys to go back. | ['s', 'S'] | -| **left** | Keys to go left. | ['a', 'A'] | -| **right** | Keys to go right. | ['d', 'D'] | -| **headBobbing** | Indicates if the forward movement is in the Z axis or Y axis. (only with PointerLockControls) | false | -| **jump** | Key to jump (only with PointerLockControls). | [' '] | -| **gravity** | Default gravity number for jump. | 9.8 | -| **moveSpeed** | Speed movement | 0.1 | -| **is2D** | Indicates if the forward movement is in the Z axis or Y axis. (only for meshes) | false | +| Prop | Description | Default | +| :---------------------- | :----------------------------------- | ------- | +| **moveSpeed** | Speed movement. | 0.2 | +| **makeDefault** | If `true`, the controls will be set as the default controls for the scene. | `true` | +| **camera** | The camera to control. | `undefined` | +| **domElement** | The dom element to listen to. | `undefined` | +| **selector** | Accept an id element as string, if it is set, the new element will be used as the trigger | `undefined` | + +## Events + +```vue + +``` + +| Event | Description | +| :--------- | :--------------------------------------------------------------- | +| **isLock** | Return `true` if "lock", `false` if "unlock" events are trigger. | +| **change** | Dispatched when the control changes. | diff --git a/docs/guide/directives/v-always-look-at.md b/docs/guide/directives/v-always-look-at.md deleted file mode 100644 index b13fdcae..00000000 --- a/docs/guide/directives/v-always-look-at.md +++ /dev/null @@ -1,61 +0,0 @@ -# v-always-look-at 👀 - -With the new directive v-always-look-at provided by **TresJS**, you can add easily command an [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) to always look at a specific position, this could be passed as a Vector3 or an Array. - -## Usage - -```vue{3,9} - - -``` -No matter where the Box move will always look-at the position [0,0,0] - -### Why not use the in built method look-at? - -You could ask, this is fine but I can use the :look-at method directly in the component, why should I need this? - -The answers is that with the method :look-at you will indicated to look at that position just once, when the instance is mounted, then if the object changes this will not get updated - -### You can look at other instance too! - -Another advantage is that you can look at an instance in movement, for example with the camera, like so: - -```vue{4,6,20,23} - - -``` diff --git a/docs/guide/directives/v-distance-to.md b/docs/guide/directives/v-distance-to.md deleted file mode 100644 index 86797d8c..00000000 --- a/docs/guide/directives/v-distance-to.md +++ /dev/null @@ -1,36 +0,0 @@ -# v-distance-to - -Have you tried to calculate the distance between two Object3Ds? - -With the new directive `v-distance-to` it's easier than ever, you should only indicate the target object to perform the measure and the result will appear in your console. - -In addition, an arrow will be created to indicate which objects you're measuring. - -```vue{2,8,13} - - -``` - -The use of `v-distance-to` is reactive, so it works perfectly with @tres/leches 🍰. - -::: warning -`v-distance-to` will not measure an object in movement within the renderLoop. -::: diff --git a/docs/guide/directives/v-light-helper.md b/docs/guide/directives/v-light-helper.md deleted file mode 100644 index bd16e2a1..00000000 --- a/docs/guide/directives/v-light-helper.md +++ /dev/null @@ -1,33 +0,0 @@ -# v-light-helper 🔆 - -With the new directive v-light-helper provided by **TresJS**, you can add fast the respective helper to your lights with just one line of code 😍. - -## Usage - -```vue{2,8,11,14,17} - - -``` - -::: warning -This directive just work with the following lights:DirectionalLight,PointLight, SpotLight, HemisphereLight. -By this way you can't tweaks the props for the helper if you need to do that, please use the normal helper instance -::: diff --git a/docs/guide/directives/v-log.md b/docs/guide/directives/v-log.md deleted file mode 100644 index ccfbbf29..00000000 --- a/docs/guide/directives/v-log.md +++ /dev/null @@ -1,57 +0,0 @@ -# v-log - -### Problem - -When you have to log your instance you have to use the template reference and then log them: - -```vue - - - -``` - -And is A LOT of code just for a simple log right? - -## Usage - -With the new directive v-log provided by **TresJS**, you can do this by just adding `v-log` to the instance. - -```vue{2,10,12} - - -``` - -Note that you can pass a modifier with the name of a property, for example `v-log:material`, and will log directly the `material` property 😍 - -::: warning -The component `` will not log the canvas or the scene. -::: diff --git a/docs/guide/materials/glass-material.md b/docs/guide/materials/glass-material.md index 9d1376e3..f39afe37 100644 --- a/docs/guide/materials/glass-material.md +++ b/docs/guide/materials/glass-material.md @@ -25,10 +25,10 @@ const boxRef = shallowRef() watch(glassMaterialRef, value => { // For good practice we dispose the old material - boxRef.value.value.material.dispose() + boxRef.value.instance.material.dispose() // We assign the new MeshGlassMaterialClass - boxRef.value.value.material = value.MeshGlassMaterialClass + boxRef.value.instance.material = value.MeshGlassMaterialClass })