hello-player

Embeddable Hello 3D player runtime for the web. Renders scenes exported from the Hello 3D editor directly in your React app or via a plain <script> tag.

Installation

npm install hello-player

Peer dependencies

npm install react react-dom three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing protobufjs

Usage

React component

import HelloPlayerApp from 'hello-player';

function App() {
  return (
    <HelloPlayerApp
      sceneUrl="./scene/scene.json"
      style={{ width: '100%', height: '100vh' }}
    />
  );
}

Pass a pre-loaded scene object instead of a URL:

import HelloPlayerApp from 'hello-player';
import sceneData from './scene.json';

<HelloPlayerApp sceneData={sceneData} />

Imperative API

import { mountHelloPlayer } from 'hello-player';

const player = mountHelloPlayer('#app', { sceneUrl: './scene/scene.json' });

player.unmount();

CDN / IIFE

<script src="https://unpkg.com/hello-player/dist/hello-player.iife.js"></script>
<script>
  HelloPlayer.mountHelloPlayer('#app', { sceneUrl: './scene/scene.json' });
</script>

API

HelloPlayerApp (default export)

React component that renders a Hello 3D scene.

| Prop | Type | Description | |------|------|-------------| | sceneUrl | string | URL to a scene.json file. Defaults to ./scene/scene.json. | | sceneData | object | Raw scene data object (alternative to sceneUrl). | | canvasProps | object | Extra props forwarded to the underlying <Canvas>. | | onError | (error: Error) => void | Called when a fatal error occurs. | | className | string | CSS class applied to the root container. |

createHelloPlayerRoot(target, props?)

Creates a player root attached to target (CSS selector, DOM element, or DocumentFragment). Returns a HelloPlayerRoot with:

• render(nextProps?) — re-render with new props
• unmount() — unmount and clean up
• container — the resolved DOM element

mountHelloPlayer(target, props?)

Shorthand for createHelloPlayerRoot.

License

MIT