Skip to content

Commit 3a9dd1b

Browse files
marklundinCopilot
marklundin
and
Copilot
authored
Adds @playcanvas/react docs (#768)
* Initial commit of PlayCanvas/React docs * broken link fix * Update src/css/custom.scss Co-authored-by: Copilot <[email protected]> * Add lazy loading for PlayCanvas React example and update documentation - Introduced lazy loading for the PlayCanvas React example component to improve performance. - Updated the documentation to reflect the changes, including the use of BrowserOnly for the demo tab. - Removed the GitHub icon image as it is no longer needed. - Added external dependency for canvas-confetti in the Docusaurus config. * Refactor PlayCanvas React documentation and configuration - Removed unused path import from docusaurus.config.js. - Updated building-a-scene.md to include a link to Web Components for clarity. - Enhanced index.mdx by specifying that PlayCanvas React provides built-in powerful features without third-party libraries, and updated links for better navigation. * Remove sidebar position from building-a-scene.md for cleaner documentation structure. * Refactor PlayCanvas React configuration and update dependencies - Removed custom Webpack configuration from docusaurus.config.js. - Updated @playcanvas/react to version 0.5.0 and added canvas-confetti as a dependency. - Adjusted import statement in playcanvas-react-example.jsx to use canvas-confetti from npm instead of ESM. - Modified building-a-scene.md to use a function for rendering LazyInteractive component. --------- Co-authored-by: Copilot <[email protected]>
1 parent 36c231b commit 3a9dd1b

File tree

11 files changed

+784
-1
lines changed

11 files changed

+784
-1
lines changed

‎docs/user-manual/playcanvas-react/building-a-scene.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Building a Scene
3+
---
4+
5+
import { Application, Entity } from '@playcanvas/react';
6+
import { Camera, Render, Light, Collision } from '@playcanvas/react/components';
7+
import { useState, lazy } from 'react';
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
import InteractiveSource from '!!raw-loader!@site/src/components/playcanvas-react-example';
11+
import CodeBlock from '@theme/CodeBlock';
12+
import BrowserOnly from '@docusaurus/BrowserOnly';
13+
14+
export const LazyInteractive = lazy(() => import('@site/src/components/playcanvas-react-example'));
15+
16+
Let's build a simple 3D scene step by step using PlayCanvas React. We'll create a basic scene with a lit sphere and see it running live in your browser.
17+
18+
## Starting Point
19+
20+
First, let's create the basic structure of our application using the `Application` component:
21+
22+
```jsx
23+
import { Application } from '@playcanvas/react'
24+
25+
export default function App() {
26+
return (
27+
<Application>
28+
{/* Your 3D scene will go here */}
29+
</Application>
30+
)
31+
}
32+
```
33+
34+
This creates an empty 3D scene. However, we can't see anything rendered yet. We need a camera and some content.
35+
36+
## Adding a Camera
37+
38+
To view our scene, we need a camera. In PlayCanvas React, we use `Entity` components as containers and attach component behaviors like `Camera`:
39+
40+
```jsx
41+
import { Application, Entity } from '@playcanvas/react'
42+
import { Camera } from '@playcanvas/react/components'
43+
44+
export default function App() {
45+
return (
46+
<Application>
47+
<Entity name="camera" position={[0, 0, 5]}>
48+
<Camera />
49+
</Entity>
50+
</Application>
51+
)
52+
}
53+
```
54+
55+
We've added a camera entity positioned 5 units down the positive Z axis. By default, a camera looks down the negative Z axis so our camera is now looking at the origin. The rendered scene shows a solid grey color (the clear color of the camera).
56+
57+
## Adding a Light
58+
59+
Let's add a directional light to illuminate our scene:
60+
61+
```jsx
62+
import { Application, Entity } from '@playcanvas/react'
63+
import { Camera, Light } from '@playcanvas/react/components'
64+
65+
export default function App() {
66+
return (
67+
<Application>
68+
<Entity name="camera" position={[0, 0, 5]}>
69+
<Camera />
70+
</Entity>
71+
<Entity name="light" rotation={[45, 45, 0]}>
72+
<Light type="directional" />
73+
</Entity>
74+
</Application>
75+
)
76+
}
77+
```
78+
79+
The light is rotated to shine at an angle, which will create more interesting shading on our objects.
80+
81+
## Adding an Object
82+
83+
Now let's add a sphere to our scene using the `Render` component:
84+
85+
<Tabs>
86+
<TabItem value="code" label="Code">
87+
88+
```jsx
89+
import { Application, Entity } from '@playcanvas/react'
90+
import { Camera, Light, Render } from '@playcanvas/react/components'
91+
92+
export default function App() {
93+
return (
94+
<Application>
95+
<Entity name="camera" position={[0, 0, 5]}>
96+
<Camera />
97+
</Entity>
98+
<Entity name="light" rotation={[45, 45, 0]}>
99+
<Light type="directional" />
100+
</Entity>
101+
<Entity name="sphere">
102+
<Render type="sphere" />
103+
</Entity>
104+
</Application>
105+
)
106+
}
107+
```
108+
109+
</TabItem>
110+
<TabItem value="demo" label="Live Demo">
111+
112+
export const CompleteScene = () => {
113+
return (
114+
<div style={{height: '400px', width: '100%', position: 'relative'}}>
115+
<Application>
116+
<Entity name="camera" position={[0, 0, 5]}>
117+
<Camera clearColor="#1a1a1a" />
118+
</Entity>
119+
<Entity name="light" rotation={[45, 45, 0]}>
120+
<Light type="directional" intensity={1} />
121+
</Entity>
122+
<Entity name="sphere">
123+
<Render type="sphere" />
124+
</Entity>
125+
</Application>
126+
</div>
127+
);
128+
};
129+
130+
<CompleteScene />
131+
132+
</TabItem>
133+
</Tabs>
134+
135+
You should now see a white sphere in the center of your screen!
136+
137+
## Making it Interactive
138+
139+
One of the great advantages of using React is how easy it is to add interactivity. Let's make our sphere respond to clicks.
140+
141+
**Click on the Demo Tab to view the results.**
142+
143+
<Tabs>
144+
<TabItem default value="code" label="Code">
145+
<CodeBlock language="jsx">{InteractiveSource}</CodeBlock>
146+
</TabItem>
147+
<TabItem value="demo" label="Demo" className='example-demo'>
148+
<BrowserOnly>
149+
{() => <LazyInteractive/>}
150+
</BrowserOnly>
151+
</TabItem>
152+
</Tabs>
153+
154+
## Key Differences from Web Components
155+
156+
When building scenes with PlayCanvas React compared to [Web Components](/user-manual/web-components/):
157+
158+
1. **Component Structure**: Instead of HTML tags like `<pc-app>`, we use React components like `<Application>`
159+
2. **Props vs Attributes**: We use React props with camelCase (e.g., `clearColor`) instead of HTML attributes
160+
3. **Event Handling**: We can use React's event system directly (e.g., `onClick`)
161+
4. **State Management**: We can leverage React hooks like `useState` for dynamic behavior
162+
5. **Type Safety**: Full TypeScript support with type safety.
163+
164+
## Next Steps
165+
166+
Now that you've built your first scene, try:
167+
168+
- Adding more objects with different shapes (`box`, `cylinder`, `cone`, etc.)
169+
- Experimenting with different light types (`point`, `spot`)
170+
- Adding movement with the `OrbitControls` script
171+
- Exploring physics by adding `RigidBody` and `Collision` components
172+
173+
Now you have the basics, see the [documentation](https://playcanvas-react.vercel.app/docs) for more examples.

‎docs/user-manual/playcanvas-react/index.mdx

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: PlayCanvas React
3+
sidebar_position: 5.6
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
[PlayCanvas React](https://github.com/playcanvas/react) is a modern library that brings the power of the PlayCanvas 3D engine into the React ecosystem. It provides a declarative, component-based approach to building interactive 3D applications using familiar React patterns.
10+
11+
Explore the [official documentation](https://playcanvas-react.vercel.app/docs) or browse the [GitHub repository](https://github.com/playcanvas/react) for more.
12+
13+
<div className='flex py-1 font-bold mb-2'>
14+
<a href="#quick-start">
15+
<div className='tablet'>
16+
<span>Getting Started →</span>
17+
</div>
18+
</a>
19+
<a href="https://github.com/playcanvas/react" className='foreground underline' target="_blank">View on GitHub ↗</a>
20+
</div>
21+
22+
<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '20px', marginBottom: '40px' }}>
23+
<a href="https://playcanvas-react.vercel.app/examples/splats">
24+
<img
25+
src="/img/user-manual/react/splats.jpg"
26+
alt="Gaussian Splats Example"
27+
style={{ width: '100%', height: '200px', objectFit: 'cover', borderRadius: '8px', transition: 'transform 0.2s', cursor: 'pointer' }}
28+
/>
29+
</a>
30+
<a href="https://playcanvas-react.vercel.app/examples/model-viewer">
31+
<img
32+
src="/img/user-manual/react/render.png"
33+
alt="3D Model Viewer Example"
34+
style={{ width: '100%', height: '200px', objectFit: 'cover', borderRadius: '8px', transition: 'transform 0.2s', cursor: 'pointer' }}
35+
/>
36+
</a>
37+
<a href="https://playcanvas-react.vercel.app/examples/physics">
38+
<img
39+
src="/img/user-manual/react/physics.png"
40+
alt="Physics Example"
41+
style={{ width: '100%', height: '200px', objectFit: 'cover', borderRadius: '8px', transition: 'transform 0.2s', cursor: 'pointer' }}
42+
/>
43+
</a>
44+
<a href="https://stackblitz.com/edit/pc-react-tick-tock?file=src%2FScene.tsx">
45+
<img
46+
src="/img/user-manual/react/clock.png"
47+
alt="Clock Example"
48+
style={{ width: '100%', height: '200px', objectFit: 'cover', borderRadius: '8px', transition: 'transform 0.2s', cursor: 'pointer' }}
49+
/>
50+
</a>
51+
</div>
52+
53+
## Why React?
54+
55+
React is at the heart of modern web development, and 3D content is no longer just for games. **PlayCanvas React** brings real-time 3D into the React ecosystem, enabling developers to build immersive experiences using the same tools and patterns they already use. With support for hooks, context, and component composition, it’s 3D — the React way.
56+
57+
Explore more in the [example gallery](https://playcanvas-react.vercel.app/examples).
58+
59+
### Full Engine Power, React Simplicity
60+
61+
PlayCanvas React gives you access to the **entire** PlayCanvas engine via intuitive React components, with all its powerful features built-in without needing third-party libraries:
62+
63+
- **Physics** – Full Ammo.js integration
64+
- **Gaussian Splats** – Cutting-edge 3D point cloud rendering
65+
- **Pointer Events** – React-style event propagation and bubbling
66+
- **Asset System** – Declarative and imperative loading of assets
67+
- **Scripts** – Escape hatches for custom logic when needed
68+
69+
## Quick Start
70+
71+
**The fastest way to get started is with the [StackBlitz template](https://playcanvas-react.vercel.app/new)**. It's a one-click experience that launches a basic scene with a camera and a cube. Fork, edit, or clone the code to make it your own.
72+
73+
Alternatively, follow the [Getting Started guide](https://playcanvas-react.vercel.app/docs/getting-started) or install it directly in your project:
74+
75+
```bash
76+
npm install @playcanvas/react
77+
78+
Then follow the [first scene walkthrough](./building-a-scene) to learn how to compose a scene using PlayCanvas React components and APIs.
79+
80+
## Learn More
81+
82+
- [Getting Started Guide](https://playcanvas-react.vercel.app/docs/guide/getting-started) - Set up your first project
83+
- [Features Showcase](https://playcanvas-react.vercel.app/docs#features) - Explore all capabilities
84+
- [Interactive Playground](https://playcanvas-react.vercel.app/examples) - Learn by doing
85+
- [API Reference](https://playcanvas-react.vercel.app/docs/api) - Complete component documentation
86+
87+
Join the growing community of developers building the next generation of 3D web experiences with **PlayCanvas React**!

‎docusaurus.config.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ const config = {
9999
return redirects;
100100
}
101101
}],
102-
'docusaurus-plugin-sass',
102+
'docusaurus-plugin-sass'
103103
],
104104

105105
presets: [

0 commit comments

Comments
 (0)