myroom-react-private/README.md

React components for MyRoom 3D scene integration with Babylon.js

# @petarainsoft/myroom-react

React components for MyRoom 3D scene integration with Babylon.js. This package provides a complete set of React components and hooks for creating interactive 3D virtual environments with avatar support, room management, and item manipulation.

## Features

- 🎮 **Interactive 3D Scenes** - Full Babylon.js integration with React
- 👤 **Avatar System** - Customizable avatars with animation support
- 🏠 **Room Management** - Load and manage 3D room environments
- 🎯 **Item Manipulation** - Drag, drop, and transform 3D objects
- 🎨 **Post-processing Effects** - Built-in visual enhancements
- 📱 **Touch Support** - Mobile-friendly controls
- 🔧 **TypeScript Support** - Full type definitions included

## Installation

```bash
npm install @petarainsoft/myroom-react
```

## Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install react react-dom @babylonjs/core @babylonjs/loaders
```

## Quick Start

```tsx
import React from 'react';
import { IntegratedBabylonScene } from '@petarainsoft/myroom-react';

function App() {
  const avatarConfig = {
    gender: 'male' as const,
    parts: {
      body: 'male_body_001',
      hair: 'male_hair_001',
      top: 'male_top_001',
      bottom: 'male_bottom_001',
      shoes: 'male_shoes_001'
    }
  };

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <IntegratedBabylonScene
        avatarConfig={avatarConfig}
        roomPath="/models/rooms/cate001/MR_KHROOM_0001.glb"
        onSceneReady={(scene) => {
          console.log('Scene is ready!', scene);
        }}
      />
    </div>
  );
}

export default App;
```

## Components

### IntegratedBabylonScene

The main component that provides a complete 3D scene with avatar, room, and interaction capabilities.

```tsx
import { IntegratedBabylonScene } from '@petarainsoft/myroom-react';

<IntegratedBabylonScene
  // Avatar configuration
  avatarConfig={{
    gender: 'male',
    parts: {
      body: 'male_body_001',
      hair: 'male_hair_001',
      // ... other parts
    }
  }}
  
  // Room configuration
  roomPath="/models/rooms/room001.glb"
  
  // Movement controls
  activeMovement="idle"
  touchMovement={{ x: 0, y: 0 }}
  
  // Items to load
  loadedItems={[
    {
      id: 'item1',
      modelPath: '/models/items/chair.glb',
      position: { x: 0, y: 0, z: 0 }
    }
  ]}
  
  // Callbacks
  onSceneReady={(scene) => console.log('Scene ready')}
  onItemTransformChange={(itemId, transform) => {
    console.log('Item moved:', itemId, transform);
  }}
/>
```

### BabylonScene

A basic Babylon.js scene component for custom implementations.

```tsx
import { BabylonScene } from '@petarainsoft/myroom-react';

<BabylonScene
  onSceneReady={(scene) => {
    // Custom scene setup
  }}
/>
```

## Hooks

### useAvatarLoader

Manages avatar part loading and animation.

```tsx
import { useAvatarLoader } from '@petarainsoft/myroom-react';

const {
  isAnimationReady,
  loadedAvatarPartsRef
} = useAvatarLoader({
  sceneRef,
  avatarConfig,
  domainConfig,
  // ... other props
});
```

### useAvatarMovement

Handles avatar movement and camera following.

```tsx
import { useAvatarMovement } from '@petarainsoft/myroom-react';

const {
  moveAvatarToPosition,
  resetAvatarMovement,
  AVATAR_BOUNDARY_LIMIT
} = useAvatarMovement({
  sceneRef,
  cameraRef,
  avatarRef,
  touchMovement,
  isSceneReady
});
```

### usePostProcessing

Manages visual effects and post-processing.

```tsx
import { usePostProcessing } from '@petarainsoft/myroom-react';

usePostProcessing({
  scene,
  camera,
  isSceneReady,
  options: {
    enableFXAA: true,
    enableBloom: true,
    enableSSAO: true,
    contrast: 1.1,
    exposure: 1.0
  }
});
```

## Types

### AvatarConfig

```tsx
interface AvatarConfig {
  gender: 'male' | 'female';
  parts: {
    body?: string;
    hair?: string;
    top?: string;
    bottom?: string;
    shoes?: string;
    acc?: string;
  };
}
```

### LoadedItem

```tsx
interface LoadedItem {
  id: string;
  modelPath: string;
  position?: { x: number; y: number; z: number };
  rotation?: { x: number; y: number; z: number };
  scale?: { x: number; y: number; z: number };
}
```

## Configuration

### Domain Configuration

The package uses a domain configuration system for asset loading:

```tsx
// In your app config
const domainConfig = {
  baseDomain: 'https://your-domain.com',
  paths: {
    models: {
      rooms: '/models/rooms',
      items: '/models/items',
      avatars: '/models/avatars'
    }
  }
};
```

## Examples

### Basic Scene with Avatar

```tsx
import React from 'react';
import { IntegratedBabylonScene } from '@petarainsoft/myroom-react';

function BasicExample() {
  return (
    <IntegratedBabylonScene
      avatarConfig={{
        gender: 'female',
        parts: {
          body: 'female_body_001',
          hair: 'female_hair_001'
        }
      }}
    />
  );
}
```

### Interactive Scene with Items

```tsx
import React, { useState } from 'react';
import { IntegratedBabylonScene } from '@petarainsoft/myroom-react';

function InteractiveExample() {
  const [selectedItem, setSelectedItem] = useState(null);
  const [gizmoMode, setGizmoMode] = useState('position');

  return (
    <IntegratedBabylonScene
      avatarConfig={{ gender: 'male', parts: {} }}
      loadedItems={[
        { id: 'chair1', modelPath: '/models/items/chair.glb' },
        { id: 'table1', modelPath: '/models/items/table.glb' }
      ]}
      selectedItem={selectedItem}
      onSelectItem={setSelectedItem}
      gizmoMode={gizmoMode}
      onGizmoModeChange={setGizmoMode}
    />
  );
}
```

## Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

## License

MIT © PetarainSoft

## Support

For support and questions, please open an issue on our [GitHub repository](https://github.com/petarainsoft/myroom-system/issues).