Merge pull request #44 from Tresjs/feature/2-docs-for-cientos

feat(docs): docs for cientos

docs/.vitepress/config.ts

@@ -39,6 +39,7 @@ export default defineConfig({
           { text: 'Basic Animations', link: '/examples/basic-animations' },
           { text: 'Load Textures', link: '/examples/load-textures' },
           { text: 'Load Models', link: '/examples/load-models' },
+          { text: 'Load Text', link: '/examples/text-3d' },
         ],
       },
       {
@@ -52,6 +53,32 @@ export default defineConfig({
           },
         ],
       },
+      {
+        text: 'Cientos ⚡️',
+        collapsible: true,
+        items: [
+          { text: 'Introduction', link: '/cientos/' },
+          {
+            text: 'Abstractions',
+            items: [{ text: 'Text3D', link: '/cientos/abstractions/text-3d' }],
+          },
+          {
+            text: 'Controls',
+            items: [{ text: 'OrbitControls', link: '/cientos/controls/orbit-controls' }],
+          },
+          {
+            text: 'Loaders',
+            items: [
+              { text: 'useGLTF', link: '/cientos/loaders/use-gltf' },
+              { text: 'GLTFModel', link: '/cientos/loaders/gltf-model' },
+            ],
+          },
+          {
+            text: 'Misc',
+            items: [{ text: 'useTweakpane', link: '/cientos/misc/use-tweakpane' }],
+          },
+        ],
+      },
     ],
     nav: [
       { text: 'Guide', link: '/guide/' },

docs/api/instances-arguments-and-props.md

@@ -73,7 +73,7 @@ This is the same as doing this:
 const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
 ```
 
-## rops
+## Props
 
 You can also pass props to the component, for example, the `TresAmbientLight` has a `intensity` property, so you can pass it to the component like this:
 

docs/api/renderer.md

@@ -16,7 +16,7 @@ The `Renderer` component is the main component of Tres. It's the one that create
 ## Props
 
 | Prop                        | Description                                                                                                                                                     | Default            |
-| --------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
 | **shadows**                 | Enable shadows in the Renderer                                                                                                                                  | `false`            |
 | **shadowMapType**           | Set the shadow map type                                                                                                                                         | `PCFSoftShadowMap` |
 | **physicallyCorrectLights** | Whether to use physically correct lighting mode. See the [lights / physical example](https://threejs.org/examples/#webgl_lights_physical).                      | `false`            |

docs/cientos/abstractions/text-3d.md

@@ -0,0 +1,56 @@
+# Text3D <Badge type="warning" text="^1.1.0" />
+
+`<Text3D />` is a component that renders a 3D text. It is a wrapper around the [TextGeometry](https://threejs.org/docs/#api/en/geometries/TextGeometry) class.
+
+<StackBlitzEmbed projectId="tresjs-text3d-cientos" />
+
+## Usage
+
+To use the `<Text3D />` component you need to pass the `font` prop with the URL of the font JSON file you want to use. TextGeometry uses `typeface`.json generated fonts, you can generate yours [here](http://gero3.github.io/facetype.js/)
+
+```vue
+<template>
+  <TresCanvas>
+    <TresScene>
+      <Text3D text="TresJS" font="/fonts/FiraCodeRegular.json">
+        <TresMeshNormalMaterial />
+      </Text3D>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+Notice that you need to pass the `<TresMeshNormalMaterial />` component as a child of the `<Text3D />` component. This is because `<Text3D />` is a `Mesh` component, so it needs a material. The geometry is created automatically. Also you can pass the text as a slot or as a prop like this:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresScene>
+      <Text3D font="/fonts/FiraCodeRegular.json">
+        TresJS
+        <TresMeshNormalMaterial />
+      </Text3D>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## Props [[1]](#1)
+
+| Prop               | Description                                                            | Default |
+| :----------------- | :--------------------------------------------------------------------- | ------- |
+| **font**           | The font data or font name to use for the text.                        |         |
+| **text**           | The text to display.                                                   |         |
+| **size**           | The size of the text.                                                  | 0.5     |
+| **height**         | The height of the text.                                                | 0.2     |
+| **curveSegments**  | The number of curve segments to use when generating the text geometry. | 5       |
+| **bevelEnabled**   | A flag indicating whether beveling should be enabled for the text.     | true    |
+| **bevelThickness** | The thickness of the beveled edge on the text.                         | 0.05    |
+| **bevelSize**      | The size of the beveled edge on the text.                              | 0.02    |
+| **bevelOffset**    | The offset of the beveled edge on the text.                            | 0       |
+| **bevelSegments**  | The number of bevel segments to use when generating the text geometry. | 4       |
+
+## References
+
+<a id="1">[1]</a>
+This table was generated by [ChatGPT](https://chat.openai.com/chat) based on the Vue component props.

docs/cientos/controls/orbit-controls.md

@@ -0,0 +1,30 @@
+# OrbitControls
+
+[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) is a camera controller that allows you to orbit around a target. It's a great way to explore your scene.
+
+However, it is not part of the core of ThreeJS. So to use it you would need to import it from the `three/examples/jsm/controls/OrbitControls` module.
+
+Here is where the fancy part begins. ✨  
+The `cientos` package provides a component called `<OrbitControls />` that is a wrapper of the `OrbitControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+
+The nicest part? You don't need to extend the catalog or pass any arguments.  
+It just works. 💯
+
+```vue{3}
+<template>
+  <TresCanvas shadows alpha>
+    <OrbitControls />
+    <TresScene> ... </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## Props
+
+| Prop              | Description                                                                                                      | Default     |
+| :---------------- | :--------------------------------------------------------------------------------------------------------------- | ----------- |
+| **makeDefault**   | If `true`, the controls will be set as the default controls for the scene.                                       | `false`     |
+| **camera**        | The camera to control.                                                                                           | `undefined` |
+| **domElement**    | The dom element to listen to.                                                                                    | `undefined` |
+| **target**        | The target to orbit around.                                                                                      | `undefined` |
+| **enableDamping** | If `true`, the controls will use damping (inertia), which can be used to give a sense of weight to the controls. | `false`     |

docs/cientos/index.md

@@ -0,0 +1,44 @@
+<script setup>
+    import cientos from '../../packages/cientos/package.json'
+</script>
+
+# Cientos <Badge :text="`v${cientos.version}`" type="warning" vertical="middle" />
+
+![Cientos banner](/cientos-banner.png)
+
+> Cientos (Spanish word for "hundreds", pronounced `/θjentos/` ) is is a collection of useful ready-to-go helpers and components that are not part of the [core](/docs/guide/index.md) package. The name uses the word uses in spanish to multiply by 100, to refer to the potential reach of the package to hold a amazing abstractions.
+
+The `cientos` package uses [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module under the hood instead of the `three/examples/jsm` module. This means that you don't need to extend the catalogue of components using the `extend` method of the [useCatalogue](/composables/use-catalog) composable, `cientos` does it for you.
+
+It just works. 💯
+
+::: info
+This package is not required to use the core library, but they can make your DX way better, specially for complex scenes.
+:::
+
+## Installation
+
+```bash
+npm install @tresjs/cientos -D
+```
+
+## Basic Usage
+
+```ts
+import { OrbitControls } from '@tresjs/cientos'
+```
+
+Now you can use the `OrbitControls` component in your scene.
+
+```html
+<template>
+  <TresCanvas shadows alpha>
+    <OrbitControls />
+    <TresScene> ... </TresScene>
+  </TresCanvas>
+</template>
+```
+
+::: warning
+Notice that you don't need to write the prefix `Tres` such as `<TresOrbitControl />` to use the component
+:::

docs/cientos/loaders/gltf-model.md

@@ -0,0 +1,29 @@
+# Using `GLTFModel`
+
+The `GLTFModel` component is a wrapper around [`useGLTF`](./use-gltf.md) composable and accepts the same options as props.
+
+```vue{2,10}
+<script setup lang="ts">
+import { OrbitControls, GLTFModel } from '@tresjs/cientos'
+</script>
+<template>
+  <Suspense>
+    <TresCanvas clear-color="#82DBC5" shadows alpha>
+      <TresPerspectiveCamera :position="[11, 11, 11]" />
+      <OrbitControls />
+      <TresScene>
+        <GLTFModel path="/models/AkuAku.gltf" draco />
+        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+      </TresScene>
+    </TresCanvas>
+  </Suspense>
+</template>
+```
+
+## Props
+
+| Prop          | Description                                                                                                           | Default     |
+| :------------ | :-------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `path`        | Path to the model file.                                                                                               | `undefined` |
+| `draco`       | Enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) for the model. | `false`     |
+| `decoderPath` | Path to a local Draco decoder.                                                                                        | `undefined` |

docs/cientos/loaders/use-gltf.md

@@ -0,0 +1,38 @@
+# useGLTF
+
+A composable that allows you to easily load glTF models into your **TresJS** scene.
+
+## Usage
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene } = await useGLTF('/models/AkuAku.gltf')
+```
+
+Then is as straightforward as adding the scene to your scene:
+
+```html{4}
+<Suspense>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresMesh v-bind="scene" />
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```
+
+An advantage of using `useGLTF`is that you can pass a `draco` prop to enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) for the model. This will reduce the size of the model and improve performance.
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+```
+
+## Options
+
+| Name            | Type      | Default     | Description                          |
+| :-------------- | --------- | ----------- | ------------------------------------ |
+| **draco**       | `boolean` | `false`     | Whether to enable Draco compression. |
+| **decoderPath** | `string`  | `undefined` | Local path to the Draco decoder.     |

docs/cientos/misc/use-tweakpane.md

@@ -0,0 +1,40 @@
+# useTweakPane
+
+[TweakPane](https://cocopon.github.io/tweakpane/) is a JavaScript library for creating a user interface for tweaking values of JavaScript variables. It's a great tool for fine-tuning parameters and monitoring value changes on your three.js applications.
+
+**TresJS** provides a composables called `useTweakPane` that creates a Tweakpane panel to your container so you can add tweaks to it. By default, the panel is created on the top right corner of the canvas and includes a FPS graph monitor to keep and eye on the performance of your scene.
+
+::: info
+You can change the container of the panel by passing the `selector` option to the `useTweakPane` function.
+:::
+
+## Basic usage
+
+```ts
+import { useTweakPane } from '@tresjs/cientos'
+
+const { pane } = useTweakPane()
+
+const experiment = reactive({
+  clearColor: '#000000',
+  alpha: true,
+  shadow: true,
+})
+
+pane.addInput(experiment, 'clearColor', {
+  label: 'Clear Color',
+  colorMode: 'hex',
+})
+
+pane.addInput(experiment, 'alpha')
+```
+
+The result will be something like this:
+
+![](/use-tweakpane.png)
+
+## Options
+
+| Name         | Type     | Default     | Description                                                    |
+| :----------- | -------- | ----------- | -------------------------------------------------------------- |
+| **selector** | `string` | `undefined` | The selector of the container where the panel will be created. |

docs/examples/text-3d.md

@@ -0,0 +1,180 @@
+# Text3D
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) is one of the ways we can add 3D text in our scene.
+
+<StackBlitzEmbed projectId="tresjs-text3d-cientos" />
+
+However, it is not part of the core of ThreeJS. So to use it you would need to import it from the `three/examples/jsm/controls/TextGeometry` module.
+
+This creates a problem because **TresJS** automatically creates a catalog of the core of Three so you can use them as components.
+
+Fortunately, **TresJS** provides a way to extend the catalog of components. You can do it by using the `extend` method using the [useCatalogue](/api/composables#usecatalog) composable.
+
+For more information about extending your TresJS catalog, refer to the [extending](/advanced/extending.md) section.
+
+## Using TextGeometry
+
+To use `TextGeometry` you need to import it from the `three/examples/jsm/geometries/TextGeometry` module.
+
+```js
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
+```
+
+Then you need to extend the catalogue of components using the `extend` method of the [useCatalogue](/api/composables#usecatalog) composable.
+
+```js
+import { useCatalogue } from '@tresjs/core'
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
+
+const { extend } = useCatalogue()
+
+extend({ TextGeometry: TextGeometry })
+```
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) needs a only one required argument the font, you can see an example below.
+
+```js
+const fontPath = 'https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json'
+
+const loader = new FontLoader()
+
+const font = await new Promise((resolve, reject) => {
+  try {
+    loader.load(fontPath, font => {
+      resolve(font)
+    })
+  } catch (error) {
+    reject(console.error('cientos', error))
+  }
+})
+```
+
+Now you can use the `TresTextGeometry` component inside a TresMesh in your scene
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresMesh>
+        <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+      </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+then as in the example you can pass an object with the desired configurations.
+
+```ts
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+```
+
+We can also pass a matcapTexture to add final details, using the TresMeshNormalMaterial inside the TresMesh
+
+```ts
+const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
+
+  <TresMesh>
+    <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+    <TresMeshNormalMaterial :matcap="matcapTexture" />
+  </TresMesh>
+```
+
+So the final code would be something like this:
+
+```vue
+<script setup lang="ts">
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
+import { FontLoader } from 'three/examples/jsm/loaders/FontLoader'
+import { useCatalogue, useTexture } from '/@/core'
+const { extend } = useCatalogue()
+
+extend({ TextGeometry: TextGeometry })
+
+const fontPath = 'https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json'
+
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+
+const loader = new FontLoader()
+
+const font = await new Promise((resolve, reject) => {
+  try {
+    loader.load(fontPath, font => {
+      resolve(font)
+    })
+  } catch (error) {
+    reject(console.error('cientos', error))
+  }
+})
+
+const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
+</script>
+<template>
+  <TresMesh>
+    <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+    <TresMeshNormalMaterial :matcap="matcapTexture" />
+  </TresMesh>
+</template>
+```
+
+I know seems like a lot of work, but good news there is a much more simple way
+
+## TextGeometry from `cientos`
+
+The `cientos` package provides a component called `<Text3D />` that is a wrapper of the `TextGeometry` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+
+The nicest part? You don't need to extend the catalog and just pass the font argument.
+It just works. 💯 (if not text is provided, the text will be TresJS)
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <Text3D :font="fontPath" />
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+We can pass the options as props
+
+```html
+<Text3D :font="fontPath" :text="my 3d text" :size="0.8" />
+```
+
+in case the options are not provided the default values are:
+
+```js
+size: 0.5,
+height: 0.2,
+curveSegments: 5,
+bevelEnabled: true,
+bevelThickness: 0.05,
+bevelSize: 0.02,
+bevelOffset: 0,
+bevelSegments: 4,
+```
+
+By default text in ThreeJS starts at the mesh initial position, so it's [0,0,0] the text will start there but we can center it by just passing the flag "center"
+
+```js
+<Text3D :font="fontPath" :text="my 3d text" center  />
+```

packages/cientos/src/core/useGLTF/index.ts

@@ -1,5 +1,4 @@
 import { GLTFLoader, DRACOLoader } from 'three-stdlib'
-/* import { useLoader } from '../../../../tres/src/core' */
 import { useLoader } from '@tresjs/core'
 import { Object3D } from 'three'
 

packages/tres/src/App.vue

@@ -4,6 +4,7 @@ import TheExperience from '/@/components/TheExperience.vue'
 
 useTweakPane()
 </script>
+
 <template>
   <Suspense>
     <TheExperience />