docs: improved docs with more info

docs/.vitepress/config.ts

@@ -70,6 +70,8 @@ export default defineConfig({
             items: [
               { text: 'Text3D', link: '/cientos/abstractions/text-3d' },
               { text: 'useAnimations', link: '/cientos/abstractions/use-animations' },
+              { text: 'Environment', link: '/cientos/abstractions/environment' },
+              { text: 'useEnvironment', link: '/cientos/abstractions/use-environment' },
             ],
           },
           {

docs/cientos/abstractions/environment.md

@@ -0,0 +1,67 @@
+# Environment <Badge type="warning" text="^1.7.0" />
+
+![Environment](/cientos/environment.png)
+
+Is a component abstraction that automatically sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`,
+
+It uses the composable [useEnvironment](/cientos/abstractions/use-environment) under the hood to load the cubemap.
+
+## Usage
+
+```html
+<Environment
+  :files="[
+    '/px.jpg',
+    '/nx.jpg',
+    '/py.jpg',
+    '/ny.jpg',
+    '/pz.jpg',
+    '/nz.jpg'
+]"
+/>
+```
+
+You can also pass the `.hdr` file directly:
+
+```html
+<Environment files="/sunset.hdr" />
+```
+
+![Environment](/cientos/envmaps.png)
+
+## Texture reference
+
+You can access the model reference by pasing a `ref` to the `<Environment />` prop and then using the method `getTexture()` to get the object.
+
+```vue{4,6,9,14,17}
+<script setup lang="ts">
+import { Environment } from '@tresjs/cientos'
+
+let envMap = null
+
+const environmentTexture = shallowRef()
+
+watch(environmentTexture, ({ getTexture }) => {
+  envMap = getTexture()
+})
+</script>
+
+<template>
+  <Environment ref="environmentTexture" />
+  <TresMesh>
+    <TresSphereGeometry />
+    <TresMeshStandardMaterial :env-map="envMap" />
+  </TresMesh>
+</template>
+```
+
+## Props
+
+| Prop         | Description                                                          | Default                                                                        |
+| :----------- | :------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `files`      | Array of 6 urls to images, one for each side of the CubeTexture.     | `undefined`                                                                    |
+| `path`       | Path to the environment map files.                                   | `undefined`                                                                    |
+| `encoding`   | Encoding of the environment map.                                     | `sRGBEncoding` for an array of files and `LinearEncoding` for a single texture |
+| `background` | If `true`, the environment map will be used as the scene background. | `false`                                                                        |
+| `blur`       | Blur factor between 0 and 1. (only works with three 0.146 and up)    | 0                                                                              |
+| `preset`     | Preset environment map.                                              | `undefined`                                                                    |

docs/cientos/abstractions/use-environment.md

@@ -0,0 +1,44 @@
+# UseEnvironment <Badge type="warning" text="^1.7.0" />
+
+`useEnvironment` composable that automatically sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`.
+
+It uses the [CubeTextureLoader](https://threejs.org/docs/#api/en/loaders/CubeTextureLoader) to load the cubemap
+
+## Usage
+
+```ts
+import { useEnvironment } from '@tresjs/cientos'
+
+const texture = await useEnvironment({
+  files: [
+    '/textures/environmentMaps/0/px.jpg',
+    '/textures/environmentMaps/0/nx.jpg',
+    '/textures/environmentMaps/0/py.jpg',
+    '/textures/environmentMaps/0/ny.jpg',
+    '/textures/environmentMaps/0/pz.jpg',
+    '/textures/environmentMaps/0/nz.jpg',
+  ],
+  path: '',
+  encoding: sRGBEncoding,
+})
+```
+
+Then you can use the `texture` in your scene:
+
+```html{3}
+<TresMesh>
+    <TresSphereGeometry />
+    <TresMeshStandardMaterial :map="texture" />
+</TresMesh>
+```
+
+## Options
+
+| Name           | Type       | Default                                                                        | Description                                                       |
+| :------------- | ---------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| **files**      | `Array`    | `undefined`                                                                    | Array of 6 urls to images, one for each side of the CubeTexture.  |
+| **path**       | `boolean`  | `false`                                                                        | Path to the environment map files.                                |
+| **encoding**   | `Encoding` | `sRGBEncoding` for an array of files and `LinearEncoding` for a single texture | Encoding of the environment map.                                  |
+| **background** | `boolean`  | `false`                                                                        | If `true` the texture will be used as the scene background.       |
+| **blur**       | `number`   | `0`                                                                            | Blur factor between 0 and 1. (only works with three 0.146 and up) |
+| **preset**     | `string`   | `undefined`                                                                    | Preset environment map.                                           |

packages/cientos/src/core/useEnvironment/component.ts

@@ -17,7 +17,6 @@ export const Environment = defineComponent({
     },
     files: {
       type: [String, Array],
-      required: true,
     },
     encoding: Object as PropType<TextureEncoding>,
     path: String,

packages/cientos/src/core/useEnvironment/const.ts

@@ -10,7 +10,7 @@ export type EnvironmentOptions = {
 }
 
 export const environmentPresets = {
-  sunset: 'venice/venice_sunset_1k.hdr',
+  sunset: 'venice/venice_sunset_4k.hdr',
 }
 
 export type EnvironmentPresetsType = keyof typeof environmentPresets

packages/tres/src/components/TheEnvironment.vue

@@ -14,7 +14,7 @@ import {
   CustomToneMapping,
 } from 'three'
 import { reactive, ref, shallowRef, watch } from 'vue'
-import { OrbitControls, useTweakPane, TransformControls, Environment } from '../../../cientos/src'
+import { OrbitControls, useTweakPane, Environment } from '../../../cientos/src'
 import { TresCanvas } from '../core/useRenderer/component'
 /* import { OrbitControls, GLTFModel } from '@tresjs/cientos' */
 
@@ -111,13 +111,13 @@ pane
     <TresPerspectiveCamera :position="[8, 8, 8]" :fov="45" :near="0.1" :far="1000" :look-at="[-8, 3, -3]" />
     <OrbitControls make-default />
     <TresScene>
-      <!-- <Environment
+      <Environment
         ref="environmentTexture"
         background
         :files="environmentFiles"
         :path="'https://raw.githubusercontent.com/Tresjs/assets/main/textures/environmentMap'"
-      /> -->
-      <Environment ref="environmentTexture" background preset="sunset" />
+      />
+      <!--  <Environment ref="environmentTexture" background preset="sunset" /> -->
       <TresAmbientLight :intensity="0.5" />
 
       <TresMesh ref="sphereRef" :position="[0, 4, 0]" cast-shadow>

pnpm-lock.yaml

@@ -104,7 +104,6 @@ importers:
     dependencies:
       '@alvarosabu/utils': 2.3.0
       '@vueuse/core': 9.12.0
-      three: 0.149.0
     devDependencies:
       '@tresjs/cientos': link:../cientos
       '@types/three': 0.149.0
@@ -118,6 +117,7 @@ importers:
       release-it: 15.6.0
       rollup-plugin-analyzer: 4.0.0
       rollup-plugin-visualizer: 5.9.0
+      three: 0.149.0
       unplugin-vue-components: 0.23.0
       vite: 4.1.1
       vite-plugin-banner: 0.7.0
@@ -7035,7 +7035,7 @@ packages:
 
   /three/0.149.0:
     resolution: {integrity: sha512-tohpUxPDht0qExRLDTM8sjRLc5d9STURNrdnK3w9A+V4pxaTBfKWWT/IqtiLfg23Vfc3Z+ImNfvRw1/0CtxrkQ==}
-    dev: false
+    dev: true
 
   /through/2.3.8:
     resolution: {integrity: sha512-w89qg7PI8wAdvX60bMDP+bFoD5Dvhm9oLheFp5O4a2QF0cSBGsBX4qZmadPMvVqlLJBBci+WqGGOAPvcDeNSVg==}