myroom-react/README.md

React component wrapper for MyRoom 3D scene

# MyRoom React Component

A React component wrapper for the MyRoom 3D scene system, providing an easy-to-use interface for integrating 3D avatar and room management into React applications.

## Features

- 🎮 **3D Scene Management**: Full Babylon.js 3D scene with avatar and room support
- 👤 **Avatar System**: Customizable avatars with gender, parts, and colors
- 🏠 **Room Management**: Load and manage 3D rooms and furniture items
- 🎯 **Interactive Controls**: Camera controls, item selection, and manipulation
- 📱 **Responsive Design**: Works on desktop and mobile devices
- 🔧 **TypeScript Support**: Full TypeScript definitions included

## Installation

```bash
npm install myroom-react
```

## Quick Start

```tsx
import React from 'react';
import { MyRoomScene } from 'myroom-react';

function App() {
  return (
    <MyRoomScene
      roomPath="/models/rooms/cate001/MR_KHROOM_0001.glb"
      gender="male"
      width="100%"
      height="600px"
      onSceneReady={(scene) => console.log('Scene ready:', scene)}
    />
  );
}
```

## Props

### Basic Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `roomPath` | `string` | `"/models/rooms/cate001/MR_KHROOM_0001.glb"` | Path to the 3D room model |
| `gender` | `'male' \| 'female'` | `'female'` | Avatar gender |
| `width` | `string` | `'800px'` | Component width |
| `height` | `string` | `'600px'` | Component height |
| `autoplay` | `boolean` | `false` | Auto-start animations |

### Avatar Configuration

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `avatarConfig` | `AvatarConfig` | Auto-generated | Complete avatar configuration |
| `enableControls` | `boolean` | `true` | Enable UI controls |
| `cameraControls` | `boolean` | `true` | Enable camera controls |

### Items Management

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `loadedItems` | `LoadedItem[]` | `[]` | Array of items to load in the scene |
| `gizmoMode` | `'position' \| 'rotation' \| 'scale'` | `'position'` | Current gizmo mode for item manipulation |

### Event Handlers

| Prop | Type | Description |
|------|------|-------------|
| `onSceneReady` | `(scene: Scene, engine: Engine) => void` | Called when the 3D scene is ready |
| `onAvatarChanged` | `(config: AvatarConfig) => void` | Called when avatar configuration changes |
| `onItemSelected` | `(item: any) => void` | Called when an item is selected |
| `onCameraMoved` | `(position: any, target: any) => void` | Called when camera moves |
| `onError` | `(error: any) => void` | Called when an error occurs |

## Advanced Usage

### Custom Avatar Configuration

```tsx
import { AvatarConfig } from 'myroom-react';

const customAvatarConfig: AvatarConfig = {
  gender: 'female',
  parts: {
    body: '/models/female/female_body/female_body.glb',
    hair: '/models/female/female_hair/female_hair_001.glb',
    top: '/models/female/female_top/female_top_001.glb',
    bottom: '/models/female/female_bottom/female_bottom_001.glb',
    shoes: '/models/female/female_shoes/female_shoes_001.glb'
  },
  colors: {
    hair: '#8B4513',
    top: '#FF6B6B',
    bottom: '#4ECDC4',
    shoes: '#45B7D1'
  }
};

<MyRoomScene
  avatarConfig={customAvatarConfig}
  roomPath="/models/rooms/cate001/MR_KHROOM_0001.glb"
/>
```

### Loading Items

```tsx
import { LoadedItem } from 'myroom-react';

const items: LoadedItem[] = [
  {
    id: 'chair-1',
    name: 'Comfortable Chair',
    path: '/models/items/catelv1_01/catelv2_01/catelv3_01/MR_CHAIR_0001.glb',
    position: { x: 0, y: 0, z: 2 },
    rotation: { x: 0, y: Math.PI / 4, z: 0 },
    scale: { x: 1, y: 1, z: 1 }
  }
];

<MyRoomScene
  loadedItems={items}
  onItemSelected={(item) => console.log('Selected:', item)}
/>
```

### Using the Component Ref

```tsx
import React, { useRef } from 'react';
import { MyRoomScene, MyRoomSceneRef } from 'myroom-react';

function App() {
  const sceneRef = useRef<MyRoomSceneRef>(null);

  const handleResetCamera = () => {
    sceneRef.current?.resetCamera();
  };

  const handleChangeAvatar = async (config: AvatarConfig) => {
    await sceneRef.current?.changeAvatar(config);
  };

  return (
    <div>
      <button onClick={handleResetCamera}>Reset Camera</button>
      <MyRoomScene
        ref={sceneRef}
        roomPath="/models/rooms/cate001/MR_KHROOM_0001.glb"
        onSceneReady={(scene) => console.log('Scene ready')}
      />
    </div>
  );
}
```

## Available Rooms

- **Living Room**: `/models/rooms/cate001/MR_KHROOM_0001.glb`
- **Exercise Room**: `/models/rooms/cate001/MR_KHROOM_0002.glb`
- **Lounge Room**: `/models/rooms/cate002/MR_KHROOM_0003.glb`

## Available Items

- **Chair**: `/models/items/catelv1_01/catelv2_01/catelv3_01/MR_CHAIR_0001.glb`
- **Light Stand**: `/models/items/catelv1_01/catelv2_01/catelv3_02/MR_LIGHTSTAND_0002.glb`
- **Board**: `/models/items/catelv1_02/catelv2_02/catelv3_02/MR_KH_BOARD_0001.glb`
- **Mirror**: `/models/items/catelv1_02/catelv2_03/catelv3_02/MR_MIRROR_0001.glb`

## Styling

The component uses CSS modules for styling. You can customize the appearance by overriding CSS classes:

```css
.myroom-scene {
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

.myroom-scene canvas {
  border-radius: 8px;
}
```

## Browser Support

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## License

MIT License - see LICENSE file for details.