Skip to content

Commit 3c55437

Browse files
committed
docs: start working on docs
1 parent d9d3120 commit 3c55437

23 files changed

+444
-672
lines changed
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
id: first-scene
3+
title: Our first scene
4+
sidebar_label: First Scene
5+
---
6+
7+
This tutorial will help us setup our first NGT scene and introduce us to some of its core concepts.
8+
9+
## Set up the Canvas
10+
11+
The scene graph in NGT starts with `<ngt-canvas>`. Let's start by rendering `<ngt-canvas>` on our `app.component.ts`.
12+
Make sure to import `NgtCanvas` from `angular-three`
13+
14+
:::note
15+
16+
We are using Inline Template syntax for this tutorial
17+
18+
:::
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
id: installation
3+
title: Installation
4+
sidebar_label: Installation
5+
---
6+
7+
## Automatic
8+
9+
For Angular CLI projects, run the following command:
10+
11+
```shell
12+
ng add angular-three
13+
```
14+
15+
For [Nx](https://nx.dev) users, run the following commands:
16+
17+
```shell
18+
npm i angular-three
19+
npx nx g angular-three:init
20+
```
21+
22+
The generator (schematic) does the following:
23+
24+
- Installs `three`, `@types/three`, and `angular-three` (in the case of Angular CLI)
25+
- Turns on `skipLibCheck: true`
26+
27+
## Manual
28+
29+
```shell
30+
npm i angular-three three
31+
npm i -D @types/three
32+
```
33+
34+
Next, open `tsconfig.json` (or `tsconfig.base.json` in an Nx Workspace) and add `skipLibCheck: true` to `compilerOptions`
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
id: introduction
3+
title: Introduction
4+
sidebar_label: Introduction
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
## What is Angular Three (NGT)?
11+
12+
NGT is a custom **Renderer** that renders [THREE.js](https://threejs.org) entities instead of DOM elements.
13+
Developers can leverage their [Angular](https://angular.io) skills to build 3D scenes declaratively by tapping into
14+
Angular features.
15+
16+
:::tip
17+
It is recommended that developers should get familiar with both Angular and THREE.js before starting with NGT
18+
:::
19+
20+
## What is the difference between NGT and React Three Fiber (R3F)?
21+
22+
Fundamentally, NGT and [R3F](https://docs.pmnd.rs/react-three-fiber/getting-started/introduction) are both custom renderers.
23+
Technically, there are differences between Angular Renderer and React Reconciler. That said, R3F is a huge inspiration for NGT.
24+
Many code from R3F are brought over to NGT and adjusted to work with Angular. NGT APIs are intentionally left similar to those from R3F
25+
so that developers who have experience with R3F can also work with NGT without much friction.
26+
27+
## Why a Renderer?
28+
29+
In the past, Angular Three was a **Component Library** via the name `@angular-three/core`. However, a **Component Library** suffers greatly
30+
from frequent THREE.js updates. There are trade-offs but Angular Three decides to take the approach of a **Renderer** to ensure optimal compatibilities
31+
with THREE.js as well as maintenance cost over the time.
32+
33+
## What does the code look like?
34+
35+
:::info
36+
Play with a Scene with a re-useable component which has its own states, events, and inputs
37+
38+
<iframe
39+
class="code-demo"
40+
src="https://stackblitz.com/edit/angular-three-demo-template-zgmtpe?ctl=1&embed=1&file=src/app/scene.component.ts&hideExplorer=1&hideNavigation=1&view=previewsjj"
41+
title="first-scene-first-cube"
42+
></iframe>
43+
:::
44+
45+
<Tabs>
46+
47+
<TabItem value="appComponentTs" label="app.component.ts" default>
48+
49+
```ts
50+
import { Component } from '@angular/core';
51+
import { Scene } from './scene.component';
52+
import { NgtCanvas } from 'angular-three';
53+
54+
@Component({
55+
selector: 'my-app',
56+
standalone: true,
57+
template: `<ngt-canvas [scene]="Scene" />`,
58+
imports: [NgtCanvas],
59+
})
60+
export class AppComponent {
61+
readonly Scene = Scene;
62+
}
63+
```
64+
65+
</TabItem>
66+
67+
<TabItem value="sceneComponentTs" label="scene.component.ts">
68+
69+
```ts
70+
import { Component, CUSTOM_ELEMENTS_SCHEMA, Input } from '@angular/core';
71+
import { extend } from 'angular-three';
72+
import { AmbientLight, BoxGeometry, Mesh, MeshStandardMaterial, PointLight } from 'three';
73+
74+
extend({ Mesh, MeshStandardMaterial, BoxGeometry, AmbientLight, PointLight });
75+
76+
@Component({
77+
selector: 'demo-cube',
78+
standalone: true,
79+
template: `
80+
<ngt-mesh
81+
[position]="position"
82+
[scale]="active ? 1.5 : 1"
83+
(click)="active = !active"
84+
(pointerover)="hovered = true"
85+
(pointerout)="hovered = false"
86+
(beforeRender)="onBeforeRender($any($event).object)"
87+
>
88+
<ngt-box-geometry />
89+
<ngt-mesh-standard-material [color]="hovered ? 'darkred' : 'orange'" />
90+
</ngt-mesh>
91+
`,
92+
schemas: [CUSTOM_ELEMENTS_SCHEMA],
93+
})
94+
export class Cube {
95+
@Input() position = [0, 0, 0];
96+
97+
hovered = false;
98+
active = false;
99+
100+
onBeforeRender(cube: Mesh) {
101+
cube.rotation.x += 0.01;
102+
cube.rotation.y += 0.01;
103+
}
104+
}
105+
106+
@Component({
107+
standalone: true,
108+
template: `
109+
<ngt-ambient-light />
110+
<ngt-point-light position="10" />
111+
<demo-cube [position]="[1.5, 0, 0]" />
112+
<demo-cube [position]="[-1.5, 0, 0]" />
113+
`,
114+
imports: [Cube],
115+
schemas: [CUSTOM_ELEMENTS_SCHEMA],
116+
})
117+
export class Scene {}
118+
```
119+
120+
</TabItem>
121+
122+
</Tabs>
123+
124+
:::note
125+
126+
- NGT requires Angular 14+ for Standalone APIs
127+
- All examples will be written with Standalone APIs and `inject()`
128+
129+
:::

apps/documentation/docs/intro.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,15 @@ sidebar_position: 1
44

55
# Tutorial Intro
66

7-
Let's discover **Docusaurus in less than 5 minutes**.
7+
Let's discover Docusaurus as a documentation framework.
8+
9+
<iframe
10+
class="code-demo"
11+
src="https://stackblitz.com/edit/angular-three-demo-template-zgmtpe?ctl=1&embed=1&file=src/app/scene.component.ts&hideExplorer=1&hideNavigation=1&view=preview"
12+
title="first-scene-first-cube"
13+
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
14+
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
15+
></iframe>
816
917
## Getting Started
1018

@@ -14,8 +22,8 @@ Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new
1422

1523
### What you'll need
1624

17-
- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
18-
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
25+
- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
26+
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
1927

2028
## Generate a new site
2129

apps/documentation/docs/tutorial-basics/markdown-features.mdx

Lines changed: 16 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -39,20 +39,6 @@ Let's see how to [Create a page](./create-a-page.md).
3939

4040
**Result:** Let's see how to [Create a page](./create-a-page.md).
4141

42-
## Images
43-
44-
Regular Markdown images are supported.
45-
46-
You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
47-
48-
```md
49-
![Docusaurus logo](/img/docusaurus.png)
50-
```
51-
52-
![Docusaurus logo](/img/docusaurus.png)
53-
54-
You can reference images relative to the current file as well, as shown in [the extra guides](../tutorial-extras/manage-docs-versions.md).
55-
5642
## Code Blocks
5743

5844
Markdown code blocks are supported with Syntax highlighting.
@@ -67,7 +53,7 @@ Markdown code blocks are supported with Syntax highlighting.
6753

6854
```jsx title="src/components/HelloDocusaurus.js"
6955
function HelloDocusaurus() {
70-
return <h1>Hello, Docusaurus!</h1>;
56+
return <h1>Hello, Docusaurus!</h1>;
7157
}
7258
```
7359

@@ -125,20 +111,21 @@ This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
125111
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
126112
```
127113

128-
export const Highlight = ({children, color}) => (
129-
<span
130-
style={{
131-
backgroundColor: color,
132-
borderRadius: '20px',
133-
color: '#fff',
134-
padding: '10px',
135-
cursor: 'pointer',
136-
}}
137-
onClick={() => {
138-
alert(`You clicked the color ${color} with label ${children}`);
139-
}}>
140-
{children}
141-
</span>
114+
export const Highlight = ({ children, color }) => (
115+
<span
116+
style={{
117+
backgroundColor: color,
118+
borderRadius: '20px',
119+
color: '#fff',
120+
padding: '10px',
121+
cursor: 'pointer',
122+
}}
123+
onClick={() => {
124+
alert(`You clicked the color ${color} with label ${children}`);
125+
}}
126+
>
127+
{children}
128+
</span>
142129
);
143130

144131
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

0 commit comments

Comments
 (0)