From a4c8785ccd5c1d107e86bc746fc64f54ab74f485 Mon Sep 17 00:00:00 2001
From: Alvaro Saburido <alvaro.saburido@gmail.com>
Date: Mon, 18 Sep 2023 10:02:54 +0200
Subject: [PATCH] docs: added primitive (#398)

* docs: added primitive

* docs: fix grammar

* docs: fix grammar

* docs: fix grammar abstraction

* docs: fix grammar
---
 docs/.vitepress/config.ts    |  1 +
 docs/advanced/primitive.md   | 47 ++++++++++++++++++++++++++++++++++++
 docs/examples/load-models.md | 19 +++++++++------
 3 files changed, 60 insertions(+), 7 deletions(-)
 create mode 100644 docs/advanced/primitive.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index f7fce7398..9b338c183 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -80,6 +80,7 @@ export default defineConfig({
 
         items: [
           { text: 'Extending', link: '/advanced/extending' },
+          { text: 'primitive', link: '/advanced/primitive' },
           {
             text: 'Caveats',
             link: '/advanced/caveats',
diff --git a/docs/advanced/primitive.md b/docs/advanced/primitive.md
new file mode 100644
index 000000000..6dbcd95a2
--- /dev/null
+++ b/docs/advanced/primitive.md
@@ -0,0 +1,47 @@
+# Primitives
+
+The `<primitive />` component is a versatile low-level component in TresJS that allows you to directly use any Three.js object within your Vue application without an abstraction. It acts as a bridge between Vue's reactivity system and Three.js's scene graph.
+
+## Usage
+
+```html
+<script setup lang="ts">
+  // Import necessary Three.js classes
+  import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';
+
+  // Create a box geometry and a basic material
+  const geometry = new BoxGeometry(1, 1, 1);
+  const material = new MeshBasicMaterial({ color: 0x00ff00 });
+
+  // Create a mesh with the geometry and material
+  const meshWithMaterial = new Mesh(geometry, material);
+</script>
+
+<template>
+  <TresCanvas>
+    <primitive :object="meshWithMaterial" />
+  </TresCanvas>  
+</template>
+```
+
+## Props
+
+`object`: This prop expects a Three.js Object3D or any of its derived classes. It is the primary object that the `<primitive />` component will render. In the updated example, a `Mesh` object with an associated `Material` is passed to this prop.
+
+## Usage with Models 
+
+The `<primitive />` component is especially useful for rendering complex objects like models loaded from external sources. The following example shows how to load a model from a GLTF file and render it using the `<primitive />` component.
+
+```html
+<script lang="ts" setup>
+import { useGLTF } from '@tresjs/cientos'
+
+const { nodes } = await useGLTF('/models/AkuAku.gltf')
+</script>
+
+<TresCanvas>
+  <Suspense>
+    <primitive :object="nodes.AkuAku" />
+  </Suspense>
+</TresCanvas>
+```
diff --git a/docs/examples/load-models.md b/docs/examples/load-models.md
index e78a24084..5d5b61966 100644
--- a/docs/examples/load-models.md
+++ b/docs/examples/load-models.md
@@ -23,7 +23,7 @@ import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
 const { scene } = await useLoader(GLTFLoader, '/models/AkuAku.gltf')
 ```
 
-Then you can pass the model scene to a TresJS `primitive`:
+Then you can pass the model scene to a TresJS [`primitive`](/advanced/primitive) component to render it:
 
 ```html{3}
 <TresCanvas>
@@ -39,7 +39,7 @@ Notice in the example above that we are using the `Suspense` component to wrap t
 
 ## Using `useGLTF`
 
-A more convenient way of loading models is using the `useGLTF` composable available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+A more convenient way of loading models is using the `useGLTF` composable available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
 
 ```ts
 import { useGLTF } from '@tresjs/cientos'
@@ -63,8 +63,13 @@ import { useGLTF } from '@tresjs/cientos'
 
 const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
 </script>
+
 <template>
-  <TresCanvas clear-color="#82DBC5" shadows alpha>
+  <TresCanvas
+    clear-color="#82DBC5"
+    shadows
+    alpha
+  >
     <TresPerspectiveCamera :position="[11, 11, 11]" />
     <OrbitControls />
     <Suspense>
@@ -76,7 +81,7 @@ const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gl
 
 ## Using `GLTFModel`
 
-The `GLTFModel` component is a wrapper around `useGLTF` that's available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+The `GLTFModel` component is a wrapper around `useGLTF` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
 
 ```vue{2,9}
 <script setup lang="ts">
@@ -96,9 +101,9 @@ import { OrbitControls, GLTFModel } from '@tresjs/cientos'
 
 This particular approach is more straightforward but gives you less control over the model.
 
-## useFBX
+## useFBX
 
-The `useFBX` composable is available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+The `useFBX` composable is available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
 
 ```ts
 import { useFBX } from '@tresjs/cientos'
@@ -118,7 +123,7 @@ Then is as straightforward as adding the scene to your scene:
 
 ## FBXModel
 
-The `FBXModel` component is a wrapper around `useFBX` that's available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar usage to `GLTFModel`:
+The `FBXModel` component is a wrapper around `useFBX` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar usage to `GLTFModel`:
 
 ```vue{2,9}
 <script setup lang="ts">