Merge branch 'main' into feat/lensflare

.eslintignore

@@ -3,4 +3,6 @@ dist
 **.test.ts
 **.test.js
 **.cy.js
-**/cypress/**
+**/cypress/**
+docs/.vitepress/cache
+docs/.vitepress/dist

.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@tresjs/eslint-config-vue",
+  "rules": {
+    "@typescript-eslint/no-use-before-define": "off"
+  }
+}

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-![repository-banner.png](/public/github-banner.png)
+![repository-banner.png](https://res.cloudinary.com/alvarosaburido/image/upload/v1683452574/repo-banner_d2xeem.png)
 
 # Tres Contributing Guide
 
@@ -8,9 +8,25 @@ No contribution is too small, whether it is a typo in the docs, a bug report or
 
 Thanks from the heart 💚 for taking the time to help out. This guide will help you to get started with the project.
 
+## Ecosystem
+- [@tresjs/core](https://github.com/Tresjs/tres) - The core package.
+- [@tresjs/cientos](https://github.com/Tresjs/cientos) - The abstractions package.
+- [@tresjs/postprocessing](https://github.com/Tresjs/post-processing) - The post-processing package.
+
 ## Setup
 
-Tresjs is a monorepo using [pnpm workspaces](https://pnpm.io/workspaces). Pnpm is a package manager that is faster than npm and yarn, and it also uses symlinks to avoid code duplication.
+All the packages in the ecosystem use [pnpm workspaces](https://pnpm.io/workspaces). PnPM is a package manager that is faster than npm and yarn. It also uses symlinks to avoid code duplication.
+
+The `workspace` has the following structure:
+
+
+```
+.
+├── docs // The documentation
+├── playground // The playground to test the package
+├── src // The source code
+
+```
 
 Make sure you are using [Node.js](https://nodejs.org/en/) version 14 or higher.
 
@@ -28,21 +44,24 @@ If you have the package manager installed, you can install pnpm using the follow
 brew install pnpm
 ```
 
-To develop Tres core or any of the packages, run `pnpm install` in the root of the project. This will install all the dependencies and link the packages together. There is also a `postinstall` script that will build all the packages.
 
 ## Development
 
-TresJS is an ecosystem of packages, each one of them has its own purpose. The main package is `@tresjs/core` which is the core of the library. The other packages are plugins that extend the core functionality, like `@tresjs/cientos` which is a plugin that adds a bunch abstractions and composables to make it easier to create 3D scenes.
+To start developing, you can run `pnpm playground` in the root folder.
+
+This will start the dev server for the playground at `http://localhost:5173/` where you can test the changes you are making in the `src` folder. 
+
+
+> **Important**
+> There is no need to run anything in the `src` folder or in the root, the `playground` will take care of it
 
-### Core
 
-You can go to the `packages/tres` folder and run `pnpm dev` to start the dev server. This will start a vite server that will watch for changes in the code and rebuild the package.
+Whenever you are working on a new feature or fixing a bug, make sure to add a demo under `playground/src/pages` and create a route in the `playground/src/router.ts` to test the changes you are making.
 
-This is only a playground to test the core package, to keep the `App.vue` clean create a new component with your scene and import it in the `App.vue` file.
+> **Warning**
+> Make sure to check if there is already a demo for the feature you are working on. If so, feel free to add your changes to the existing demo.
 
-### Cientos
 
-You can go to the `packages/cientos` folder and run `pnpm build --watch` to build the package and watch for changes. That way you can test the changes in the playground on the `packages/tres` folder.
 
 ### Docs
 
@@ -64,14 +83,14 @@ Before opening a pull request, make sure to run `pnpm lint` to make sure the cod
 - Please follow the [commit message conventions](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) when committing your changes. This is important because the release notes will be automatically generated from these messages. Small scoped commits are always preferred, as it is easier to review them.
 - If adding new feature:
   - Provide convincing reason to add this feature. Ideally you should open a suggestion issue first and have it greenlighted before working on it. We would reject feature PRs that are not first opened as suggestions except for trivial changes.
-  - Create a `feature/{issue-number}-add-test-to-core` branch for this feature. Make the name meaningful.
-  - PR title must start with `feat(pkg): Descriptive title`. For example: `feat(core): added unit test to composables`.
+  - Create a `feature/{issue-number}-add-test-to-cientos` branch for this feature. Make the name meaningful.
+  - PR title must start with `feat(pkg): Descriptive title`. For example: `feat(cientos): added unit test to composables`.
 - If fixing a bug 🐛:
 
   - Provide detailed description of the bug in the PR. Live demo preferred.
   - Create a `fix/{issue-number}-fix-test-in-core` branch for this bug fix.
   - If you are resolving a special issue, add `(fix #xxx[,#xxx])` (#xxx is the issue id) in your PR title for a better release log, e.g. `update entities encoding/decoding (fix #3899)`.
 
-## Keep core small
+## Third Party Libraries
 
-The core package should be as small as possible, it should only contain the core functionality of the library. If you are adding a new feature, please consider adding it as a plugin instead, for example, if you want to add support for [Effect Composer](https://threejs.org/examples/?q=compo#webgl_postprocessing_effectcomposer) you should create a new package called `@tresjs/postprocessing` and add it as a plugin. If it's a smaller scope you can always add it to `cientos` package.
+Adding a new third party library is generally discouraged, unless it is absolutely necessary. If you want to add a new library, please open an issue first to discuss the best approach.

docs/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@tresjs/eslint-config-vue"
+}

docs/.vitepress/config.ts

@@ -60,6 +60,7 @@ export default defineConfig({
           { 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' },
         ],
       },
       {
@@ -96,7 +97,10 @@ export default defineConfig({
       },
       {
         text: 'Misc',
-        items: [{ text: 'useTweakpane', link: '/guide/misc/use-tweakpane' }],
+        items: [
+          { text: 'useTweakpane', link: '/guide/misc/use-tweakpane' },
+          { text: 'Stats', link: '/guide/misc/stats' },
+        ],
       },
     ],
 

docs/.vitepress/theme/components/BackdropDemo.vue

@@ -3,9 +3,7 @@ import { TresCanvas } from '@tresjs/core'
 import { PCFSoftShadowMap, SRGBColorSpace, NoToneMapping } from 'three'
 
 import { useProgress, Backdrop, GLTFModel } from '@tresjs/cientos'
-import { ref } from 'vue'
-import { watch } from 'vue'
-import { watchEffect } from 'vue'
+import { ref, watch, watchEffect } from 'vue'
 
 const gl = {
   clearColor: 'pink',
@@ -18,14 +16,15 @@ const gl = {
 const model = ref(null)
 
 watch(model, ({ value }) => {
-  value.traverse(child => {
+  value.traverse((child) => {
     if (child.isMesh) {
       child.castShadow = true
     }
   })
 })
 
 function onCameraChange(e) {
+  // eslint-disable-next-line no-console
   console.log('camera changed', e)
 }
 
@@ -51,30 +50,46 @@ const { hasFinishLoading, progress, items } = await useProgress()
         v-show="!hasFinishLoading"
         class="absolute bg-grey-600 t-0 l-0 w-full h-full z-20 flex justify-center items-center text-black font-mono"
       >
-        <div class="w-200px">Loading... {{ progress }} %</div>
+        <div class="w-200px">
+          Loading... {{ progress }} %
+        </div>
       </div>
     </Transition>
     <TresCanvas v-bind="gl">
       <TresPerspectiveCamera
-        ref="camerRef"
         :position="[0.07224002153117198, 0.5245876539770153, 2.9469498522622626]"
         :rotation="[-0.04419077275543715, 0.025561987075415186, 0.0011302162688196786]"
         :fov="35"
       />
       <Suspense>
-        <GLTFModel ref="model" cast-shadow :path="'/card-bo-bot/CardBoBotv3.glb'" draco :rotation="[0, 0.5, 0]" />
+        <GLTFModel
+          ref="model"
+          cast-shadow
+          path="/card-bo-bot/CardBoBotv3.glb"
+          draco
+          :rotation="[0, 0.5, 0]"
+        />
       </Suspense>
-      <Backdrop :floor="1.5" :scale="[10, 3, 3]" :position="[0, 0, -3]" receive-shadow>
-        <TresMeshPhysicalMaterial :roughness="1" color="pink" :side="2" />
+      <Backdrop
+        :floor="1.5"
+        :scale="[10, 3, 3]"
+        :position="[0, 0, -3]"
+        receive-shadow
+      >
+        <TresMeshPhysicalMaterial
+          :roughness="1"
+          color="pink"
+          :side="2"
+        />
       </Backdrop>
       <TresAmbientLight :intensity="0.5" />
       <TresDirectionalLight
         :args="['white', 2]"
         cast-shadow
         :position="[3, 4, 4]"
         :look-at="[0, 0, 0]"
-        :shadow-mapSize-width="256"
-        :shadow-mapSize-height="256"
+        :shadow-map-size-width="256"
+        :shadow-map-size-height="256"
         :shadow-camera-near="0.5"
         :shadow-camera-left="-10"
       />
@@ -83,8 +98,8 @@ const { hasFinishLoading, progress, items } = await useProgress()
         cast-shadow
         :position="[-3, 2, 4]"
         :look-at="[0, 0, 0]"
-        :shadow-mapSize-width="256"
-        :shadow-mapSize-height="256"
+        :shadow-map-size-width="256"
+        :shadow-map-size-height="256"
         :shadow-camera-near="0.5"
         :shadow-camera-left="-10"
       />

docs/.vitepress/theme/components/Feather.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { useGLTF, Levioso } from '@tresjs/cientos'
-import { shallowRef } from 'vue'
-import { watchEffect } from 'vue'
+import { shallowRef, watchEffect } from 'vue'
+
 const { scene: feather, nodes } = await useGLTF('/feather.glb')
 
 /* const feather = computed(() => nodes.Sketchfab_model)
@@ -11,6 +11,7 @@ const featherRef = shallowRef()
 
 watchEffect(() => {
   if (featherRef.value) {
+    // eslint-disable-next-line no-console
     console.log(featherRef.value)
     featherRef.value.rotation.y = -Math.PI / 4
     featherRef.value.updateMatrixWorld()
@@ -19,9 +20,16 @@ watchEffect(() => {
   }
 })
 </script>
+
 <template>
-  <Levioso ref="groupRef" :speed="4">
-    <primitive ref="featherRef" :object="nodes.Sketchfab_model" :position-y="-Math.PI / 4" />
+  <Levioso
+    :speed="4"
+  >
+    <primitive
+      ref="featherRef"
+      :object="nodes.Sketchfab_model"
+      :position-y="-Math.PI / 4"
+    />
   </Levioso>
   <!--  <TresMesh ref="featherRef" v-bind="feather"></TresMesh> -->
 </template>

docs/.vitepress/theme/components/LeviosoDemo.vue

@@ -15,13 +15,18 @@ const gl = {
 </script>
 
 <template>
-  <TresCanvas v-bind="gl" ref="context">
+  <TresCanvas
+    v-bind="gl"
+  >
     <TresPerspectiveCamera :position="[1, 2, 1]" />
     <Suspense>
       <Feather />
     </Suspense>
     <TresAmbientLight :intensity="1" />
-    <TresDirectionalLight :intensity="1" :position="[2, 2, 2]" />
+    <TresDirectionalLight
+      :intensity="1"
+      :position="[2, 2, 2]"
+    />
     <OrbitControls />
   </TresCanvas>
 </template>

docs/.vitepress/theme/components/LoveVueThreeJS.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
 ///<reference types="vite-svg-loader" />
+import { gsap } from 'gsap'
+import { onMounted, ref } from 'vue'
 import Triangle from '../assets/triangle.svg'
 import SecondRow from '../assets/second-row.svg'
 import ThirdRow from '../assets/third-row.svg'
-import { gsap } from 'gsap'
-import { onMounted, ref } from 'vue'
 
 const triangleRef = ref()
 const secondRowRef = ref()

docs/.vitepress/theme/components/WobbleMaterialDemo.vue

@@ -14,14 +14,23 @@ const gl = {
 </script>
 
 <template>
-  <TresCanvas v-bind="gl" ref="context">
+  <TresCanvas
+    v-bind="gl"
+  >
     <TresPerspectiveCamera :position="[3, 3, 3]" />
     <TresMesh>
       <TresTorusGeometry />
-      <MeshWobbleMaterial color="orange" :speed="1" :factor="2" />
+      <MeshWobbleMaterial
+        color="orange"
+        :speed="1"
+        :factor="2"
+      />
     </TresMesh>
     <TresAmbientLight :intensity="1" />
-    <TresDirectionalLight :intensity="1" :position="[2, 2, 2]" />
+    <TresDirectionalLight
+      :intensity="1"
+      :position="[2, 2, 2]"
+    />
     <OrbitControls />
   </TresCanvas>
 </template>

docs/guide/controls/camera-controls.md

@@ -36,6 +36,7 @@ Certainly! Here's the properties of the object in raw markdown table format:
 | **maxPolarAngle**         | Maximum vertical angle in radians.                                                                                                                                                        | `Math.PI`        |
 | **minAzimuthAngle**       | Minimum horizontal angle in radians.                                                                                                                                                      | `-Infinity`      |
 | **maxAzimuthAngle**       | Maximum horizontal angle in radians.                                                                                                                                                      | `Infinity`       |
+| **distance**              | Current distance.                                                                                                                                       | `8`              |
 | **minDistance**           | Minimum distance for dolly. PerspectiveCamera only.                                                                                                                                       | `Number.EPSILON` |
 | **maxDistance**           | Maximum distance for dolly. PerspectiveCamera only.                                                                                                                                       | `Infinity`       |
 | **infinityDolly**         | `true` to enable Infinity Dolly for wheel and pinch.                                                                                                                                      | `false`          |