PlayCanvas React

If you are using Tailwind CSS, you must import the @playcanvas/blocks styles and configure the content source so Tailwind can scan the package for utility classes. Add the following to your CSS file:

@import "@playcanvas/blocks";
@source "../../node_modules/@playcanvas/blocks";

To use high-level 3D primitives in your React project, install @playcanvas/blocks along with the core playcanvas engine.

npm install @playcanvas/blocks playcanvas

To start using the library, install both @playcanvas/react and the core playcanvas engine using your preferred package manager.

npm install @playcanvas/react playcanvas

To improve IDE support in Cursor, you can install the PlayCanvas React rules by downloading the .mdc rule file into your .cursor/rules directory.

mkdir -p .cursor/rules && curl -s https://raw.githubusercontent.com/playcanvas/react/main/packages/lib/.playcanvas-react.mdc -o .cursor/rules/playcanvas-react.mdc

The library is organized into three main layers to build 3D content:

1. Core: Provides fundamental building blocks like Application and Entity.
2. Components: Provides behaviors that you attach to Entity nodes (e.g., Light, Camera, Render, Collision).
3. Hooks: Provides logic and asset management (e.g., useModel, useSplat, useApp).

// Core 
import { Application, Entity } from '@playcanvas/react'
// Components add behaviors to Entities
import { Light, Camera, Render, Gsplat, Screen, Collision, RigidBody, Anim } from '@playcanvas/react/components'
// Hooks add functionality
import { useModel, useSplat, useAppEvent, useParent, useApp } from '@playcanvas/react/hooks'

The SplatViewer ecosystem provides several sub-components for managing the viewer UI:

Controls Wrapper

• Controls: A wrapper for layout that provides a container for UI elements. It supports an autoHide prop which causes the controls to fade out when not in use.

UI Buttons

These components should be placed inside the <SplatViewer /> component (typically within <Controls />) to function as overlays:

• FullScreenButton: Toggles full-screen mode.
• DownloadButton: Triggers a download of the asset.
• MenuButton: Opens the viewer menu.
• CameraModeToggle: Switches between different camera control modes.
• HelpButton: Displays help information.

The SplatViewer supports two camera modes:

• orbit: An orbit camera that follows the splat.
• fly: A fly camera that follows the splat.

To control the mode from a parent component, pass the mode prop. To let the component manage its own state, use defaultMode and listen to changes via onTypeChange.

The Entity component is the fundamental building block of a PlayCanvas scene. It represents a node in the scene graph and can have components attached to it via its children. You can control its transform properties (name, position, scale, rotation) and attach pointer event listeners directly through props.

To use Entity, wrap other components (like Render) inside it. The Entity component also provides a ParentContext so that child components can access the underlying PlayCanvas Entity instance.

// Basic usage
<Entity name="myEntity" position={[0, 1, 0]}>
  <Render type="box" />
</Entity>

// With pointer events
<Entity 
  position={[0, 1, 0]}
  onPointerDown={(e) => console.log('Clicked!')}
  onClick={(e) => console.log('Mouse clicked!')}
>
  <Render type="sphere" />
</Entity>

The SplatViewer component is added to your project using the shadcn CLI. Run the following command to install it:

npx shadcn@latest add https://playcanvas-react.vercel.app/r/splat-viewer.json

When building 3D scenes, adhere to these architectural rules:

• Initialization: Always wrap your root components in an <Application /> component to initialize the PlayCanvas engine.
• Transformations: Use the <Entity /> component to define a transform node. It handles position, rotation, and scale but does not render anything by itself.
• Functionality: Attach behaviors to entities using components from @playcanvas/react/components (e.g., <Camera />, <Light />, <Render />).
• Asset Loading: Use specialized hooks like useModel(src) or useSplat(src) to load assets.
• Materials: Create materials using the useMaterial() hook.
• Data Formats: Use numeric arrays for colors and vectors:
  • Colors: [1, 0, 0]
  • Position/rotation/scale: [0, 0, 0]

You can render 3D objects by composing <Application>, <Entity>, and component-based elements like <Camera /> and <Render />. The <Application> component serves as the root for the PlayCanvas engine within your React tree.

import { Application, Entity } from '@playcanvas/react';
import { Camera, Render } from '@playcanvas/react/components';
import { OrbitControls } from '@playcanvas/react/scripts';

export function AssetViewer() {
  return (
    <Application>
      <Entity position={[0, 2, 0]}>
        <Camera />
        <OrbitControls />
      </Entity>
      <Render type="sphere"/>
    </Application>
  );
}