Skip to content

Commit 8cafbb5

Browse files
sascha245sascha245
authored
Merge pull request #4 from sascha245/feature/docs
add first version of vuepress docs
2 parents 0acff8b + ab4237a commit 8cafbb5

17 files changed

+559
-207
lines changed

‎.npmignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
/build/tests
77
/src
88
/tests
9+
README.md
910

1011
.prettierignore
1112
.editorconfig

‎README.md

Lines changed: 30 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -4,245 +4,70 @@ Build beautiful and interactive scenes in the easy way.
44

55
## What?
66

7-
This library focuses on managing your THREE.js assets and objects, but nothing more. As such, it won't include any basic geometries, materials, as you can easily implement custom ones yourself as we will see later.
7+
Today there are already a few libraries out there to create scenes in Vue with Three.js:
8+
9+
- [vue-gl](https://github.com/vue-gl/vue-gl)
10+
- [vue-threejs](https://github.com/fritx/vue-threejs)
11+
12+
These libraries are good for creating simple scenes, as they allow us to easily create basic 3D content.
13+
14+
For more complex ones however, they aren’t enough, as integrating custom components can’t be done with ease. Managing and tracking the loading progress of your assets also becomes more difficult the more assets you use.
15+
16+
This library tries to solve these problems.
817

918
## Features
1019

11-
This library's strong points:
20+
This library focuses on **managing** your Three.js assets, scenes and objects.
21+
22+
As such, it won’t include any basic geometries, materials and so on, as you can implement them yourself very easily.
1223

13-
1. Core features to easily register assets and create objects in your scenes.
24+
But rather than speaking about what this library doesn’t handle, here the main strong points:
1425

15-
2. Asset bundles to efficiently (pre)load and unload your assets when you don't need them anymore
26+
1. Asset bundles to (pre)load your assets
1627

17-
3. Easily load 3D models and assign their materials
28+
2. Easily create and organize objects in your scenes.
1829

19-
4. Easily create custom geometries and materials with dedicated factory functions.
30+
3. Helpers for loading 3D models and automatically assigning their materials
2031

32+
4. You write your THREE.js objects, we manage them for you: Practically all objects are customizable and accept factory functions.
2133

22-
## Usage
2334

24-
### Installation
35+
## Installation
2536

26-
1. Install THREE.js:
37+
Install THREE.js:
2738
`npm install three --save`
2839

29-
2. Optionally, install THREE.js typings:
40+
Optionally, install THREE.js typings:
3041
`npm install @types/three --save-dev`
3142

32-
3. Install this package:
43+
Install this package:
3344
`npm install vue-threejs-composer --save`
3445

3546

36-
### Samples
47+
## Samples
3748

3849
If you want to test out our samples, you can clone our repository and launch our samples with the following commands:
3950

40-
1. Install dependencies
51+
Install dependencies
4152
`npm install`
4253

43-
2. Launch development server
54+
Launch development server
4455
`npm run serve`
4556

46-
3. Play around with the files in */samples*. The demo scene is situated at */samples/views/Demo.vue*
47-
48-
#### Define your scenes
49-
50-
```html
51-
<div>
52-
53-
<canvas ref="canvas"></canvas>
54-
<div v-if="canvas">
55-
<three>
56-
<renderer :canvas="canvas" :camera="activeCamera" :scene="activeScene" antialias shadows/>
57-
58-
<asset-bundle name="PolygonMini" preload>
59-
<texture name="PolygonMini_Tex" src="/assets/textures/PolygonMinis_Texture_01.png"/>
60-
61-
<standard-material name="PolygonMini_Mat" map="PolygonMini_Tex"/>
62-
63-
<model name="PM_column" src="/assets/models/SM_Tile_Hex_Column_02.fbx" materials="PolygonMini_Mat"/>
64-
<model name="PM_flat" src="/assets/models/SM_Tile_Hex_Flat_01.fbx" materials="PolygonMini_Mat"/>
65-
</asset-bundle>
66-
67-
<asset-bundle name="Forms">
68-
<geometry name="cube" :factory="cubeFactory"/>
69-
<geometry name="plane" :factory="planeFactory"/>
70-
</asset-bundle>
71-
72-
<asset-bundle dependencies="Forms" name="Water" preload>
73-
<standard-material name="waterMat" color="#9c9cff"/>
74-
</asset-bundle>
75-
76-
<scene name="scene1" assets="PolygonMini, Water">
77-
78-
<fog exp2/>
79-
80-
<camera name="main" :factory="cameraFactory">
81-
<position :value="scene1.camera.position"/>
82-
<rotation :value="scene1.camera.rotation" rad/>
83-
<orbit-behaviour :data="scene1.camera"/>
84-
</camera>
85-
86-
<light name="sun" :factory="lightFactory">
87-
<position :value="{x: -5, y: 10, z: -5}"/>
88-
<shadows cast/>
89-
</light>
90-
91-
<mesh geometry="plane" material="waterMat">
92-
<rotation :value="{ x: -90, y: 0, z: 0 }"/>
93-
<shadows receive/>
94-
</mesh>
95-
96-
<group>
97-
<position :value="{ x: 10, y: 3, z: 10 }"/>
98-
<scale :value="{ x: 0.01, y: 0.01, z: 0.01 }"/>
99-
<shadows cast receive/>
100-
101-
<mesh model="PM_column">
102-
<shadows cast receive deep/>
103-
</mesh>
104-
<mesh model="PM_flat">
105-
<shadows cast receive deep/>
106-
</mesh>
107-
</group>
108-
109-
</scene>
110-
111-
</three>
112-
</div>
113-
</div>
114-
```
57+
Play around with the files in */samples*. The demo scene is situated at */samples/views/Demo.vue*
11558

116-
**Note**: The *OrbitBehaviour*, as well as the *StandardMaterial* components are not included in the library. You may however look them up in the samples if you wish.
117-
118-
119-
#### Define custom materials
120-
121-
```html
122-
<template>
123-
<material :factory="factory" :name="name"/>
124-
</template>
125-
```
126-
127-
```ts
128-
import { MeshStandardMaterial, Texture } from "three";
129-
import { Component, Prop, Vue } from "vue-property-decorator";
130-
131-
import { Application, components } from "../../../src";
132-
133-
const { Material } = components;
134-
135-
@Component({
136-
components: {
137-
Material
138-
}
139-
})
140-
export default class StandardMaterial extends Vue {
141-
@Prop({ required: true, type: String })
142-
public name!: string;
143-
144-
@Prop({ type: String })
145-
public map!: string;
146-
147-
@Prop({ type: String, default: "#ffffff" })
148-
public color!: string;
149-
150-
@Prop({ type: Number, default: 0.01 })
151-
public metalness!: number;
152-
153-
public async factory(app: Application) {
154-
let texture;
155-
if (this.map) {
156-
texture = await app.assets.textures.get(this.map);
157-
}
158-
159-
const mat = new MeshStandardMaterial({
160-
color: this.color,
161-
metalness: this.metalness
162-
});
163-
mat.map = texture as Texture;
164-
return mat;
165-
}
166-
}
167-
```
168-
169-
**Note**: You can also create custom geometries in a very similar way with factory functions.
170-
171-
#### Define custom behaviours
172-
173-
```ts
174-
import { Component, Mixins, Prop } from "vue-property-decorator";
175-
176-
import { BehaviourComponent } from "vue-threejs-composer";
177-
178-
@Component
179-
export class HoverBehaviour extends Mixins(BehaviourComponent) {
180-
@Prop({ required: true, type: Object })
181-
public position!: { x: number, y: number, z: number };
182-
183-
@Prop({ type: Number, default: 1 })
184-
public distance!: number;
185-
186-
@Prop({ type: Number, default: 1 })
187-
public speed!: number;
188-
189-
private m_moveUp = true;
190-
private m_originalY = 0;
191-
192-
public created() {
193-
// access app
194-
const app = this.app();
195-
// access scene handler if behaviour is placed in a scene
196-
const scene = this.scene();
197-
// access object if behaviour is placed in an object
198-
const object = this.object();
199-
200-
this.m_originalY = this.position.y;
201-
202-
// once your component is ready
203-
this.ready();
204-
}
205-
206-
// lifecycle function called on each frame (optional)
207-
public update(deltaTime: number) {
208-
this.position.y += deltaTime * (this.m_moveUp ? 1 : -1) * this.speed;
209-
210-
const min = this.m_originalY - this.distance;
211-
const max = this.m_originalY + this.distance;
212-
if (this.position.y > max) {
213-
this.m_moveUp = false;
214-
} else if (this.position.y < min) {
215-
this.m_moveUp = true;
216-
}
217-
}
218-
219-
public destroyed() {
220-
// dispose everything that needs to be disposed here
221-
}
222-
223-
public render(h: any) {
224-
return h("div");
225-
}
226-
}
227-
```
22859

22960
## Documentation
23061

231-
As this module has only been recently released, there is no official documentation available yet.
232-
233-
For now, I added some samples to show how to use and implement your geometries, materials and prefabs.
234-
235-
If you have any questions, don't hesitate to open up a ticket.
236-
237-
## Bugs
62+
The writing of the documentation is still in progress.
63+
Here however the link to the official documentation: [vue-threejs-composer.netlify.com](https://vue-threejs-composer.netlify.com/)
23864

239-
The core features presented should be stable.
240-
But as this module is still young, it will probably still have some bugs here and there.
65+
If you can't find what you are looking for in the documentation, you can also open a new ticket describing your issue.
24166

24267
## License
24368

24469
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) for details
24570

24671
## Acknowledgments
24772

248-
- Handling of multiple renderer inspired by [vue-gl](https://github.com/vue-gl/vue-gl)
73+
- Inspired in some ways by [vue-gl](https://github.com/vue-gl/vue-gl)

‎docs/.vuepress/config.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
module.exports = {
2+
title: "Vue Threejs Composer",
3+
description: "Compose beautiful 3D scenes in a flash",
4+
themeConfig: {
5+
search: true,
6+
lastUpdated: true,
7+
nav: [
8+
{ text: "Home", link: "/" },
9+
{ text: "Guide", link: "/guide/" },
10+
{
11+
text: "Github",
12+
link: "https://github.com/sascha245/vue-threejs-composer"
13+
}
14+
],
15+
sidebar: {
16+
"/guide/": [
17+
{
18+
title: "Guide",
19+
collapsable: false,
20+
children: [
21+
["", "Introduction"],
22+
["getting-started", "Getting started"]
23+
// ["assets", "Assets"],
24+
// ["objects", "Scene objects"]
25+
]
26+
}
27+
]
28+
}
29+
}
30+
};

‎docs/.vuepress/public/hero.png

34.3 KB
Loading

‎docs/.vuepress/public/webgl-cube-texture.png

11.2 KB
Loading

‎docs/.vuepress/public/webgl-cube.png

5.61 KB
Loading

‎docs/README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
home: true
3+
heroImage: /hero.png
4+
actionText: Get Started →
5+
actionLink: /guide/
6+
features:
7+
- title: Setup
8+
details: Easily setup all your assets and preload them without a hassle.
9+
- title: Create
10+
details: Create your own materials, geometries, prefabs and even more
11+
- title: Enjoy
12+
details: Just enjoy working with WebGl in a clear and readable way.
13+
footer: MIT Licensed | Copyright © 2018-present Sascha Braun
14+
---

‎docs/guide/README.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Guide
2+
3+
4+
## What?
5+
6+
Today there are already a few libraries out there to create scenes in Vue with Three.js:
7+
8+
- [vue-gl](https://github.com/vue-gl/vue-gl)
9+
- [vue-threejs](https://github.com/fritx/vue-threejs)
10+
11+
These libraries are good for creating simple scenes, as they allow us to easily create basic 3D content.
12+
13+
For more complex ones however, they aren’t enough, as integrating custom components can’t be done with ease. Managing and tracking the loading progress of your assets also becomes more difficult the more assets you use.
14+
15+
This library tries to solve these problems.
16+
17+
## Features
18+
19+
This library focuses on **managing** your Three.js assets, scenes and objects.
20+
21+
As such, it won’t include any basic geometries, materials and so on, as you can implement them yourself very easily.
22+
23+
But rather than speaking about what this library doesn’t handle, here the main strong points:
24+
25+
1. Asset bundles to (pre)load your assets
26+
27+
2. Easily create and organize objects in your scenes.
28+
29+
3. Helpers for loading 3D models and automatically assigning their materials
30+
31+
4. You write your THREE.js objects, we manage them for you: Practically all objects are customizable and accept factory functions.
32+
33+
## Installation
34+
35+
Install THREE.js:
36+
`npm install three --save`
37+
38+
Optionally, install THREE.js typings:
39+
`npm install @types/three --save-dev`
40+
41+
Install this package:
42+
`npm install vue-threejs-composer --save`
43+
44+
45+
## Samples
46+
47+
If you want to test out our samples, you can clone our repository and launch our samples with the following commands:
48+
49+
Install dependencies
50+
`npm install`
51+
52+
Launch development server
53+
`npm run serve`
54+
55+
Play around with the files in */samples*. The demo scene is situated at */samples/views/Demo.vue*

0 commit comments

Comments
 (0)