AeThex-Connect/nexus-sdk/README.md

# AeThex Connect - Nexus SDK Plugin

Integrate AeThex Connect communication into your games using the Nexus Engine.

## Installation

```bash
npm install @aethex/connect-nexus-plugin
```

Or include directly in your game:

```html
<script src="https://cdn.aethex.app/nexus-sdk/connect-plugin.js"></script>
```

## Quick Start

```javascript
// Initialize Nexus Engine
const nexus = new NexusEngine({
  gameId: 'your-game-id',
  gameName: 'Your Awesome Game'
});

// Initialize AeThex Connect Plugin
const connectPlugin = new AeThexConnectPlugin(nexus, {
  apiUrl: 'https://connect.aethex.app/api',
  apiKey: 'your-nexus-api-key',
  enableOverlay: true,
  enableNotifications: true,
  overlayPosition: 'top-right',
  autoMute: true
});

// Initialize on game start
await connectPlugin.initialize();
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | string | `https://connect.aethex.app/api` | AeThex Connect API URL |
| `apiKey` | string | **required** | Your Nexus API key |
| `enableOverlay` | boolean | `true` | Show in-game overlay |
| `enableNotifications` | boolean | `true` | Show in-game notifications |
| `overlayPosition` | string | `'top-right'` | Overlay position: `'top-right'`, `'top-left'`, `'bottom-right'`, `'bottom-left'` |
| `autoMute` | boolean | `true` | Auto-mute voice chat during matches |

## Features

### In-Game Overlay

The plugin automatically creates an in-game overlay that shows:
- Friends list with online status
- Current game they're playing
- Quick message access
- Unread message notifications

### Auto-Mute

Voice chat automatically mutes when players enter a match and unmutes when returning to menu. Configure with `autoMute: false` to disable.

### Cross-Game Presence

Friends can see what game you're playing in real-time, with states:
- `in-menu` - In main menu
- `in-match` - Currently playing
- `paused` - Game paused

## Events

The plugin listens to these Nexus Engine events:

### `match:start`
```javascript
nexus.emit('match:start', {
  map: 'Forest Arena',
  mode: 'Team Deathmatch',
  teamId: 'team-red'
});
```

### `match:end`
```javascript
nexus.emit('match:end', {
  score: 150,
  won: true,
  duration: 1234
});
```

### `game:pause`
```javascript
nexus.emit('game:pause');
```

### `game:resume`
```javascript
nexus.emit('game:resume');
```

### `game:exit`
```javascript
nexus.emit('game:exit');
```

## Methods

### `initialize()`
Initialize the plugin and start game session.

```javascript
const success = await connectPlugin.initialize();
if (success) {
  console.log('AeThex Connect ready!');
}
```

### `updateSessionState(state, metadata)`
Manually update game session state.

```javascript
await connectPlugin.updateSessionState('in-match', {
  mapName: 'Desert Storm',
  gameMode: 'Capture the Flag'
});
```

### `showNotification(notification)`
Show a custom in-game notification.

```javascript
connectPlugin.showNotification({
  icon: '🎉',
  title: 'Achievement Unlocked',
  body: 'You earned the "Victory" badge!'
});
```

### `endSession()`
End the game session (called automatically on game exit).

```javascript
await connectPlugin.endSession();
```

### `destroy()`
Cleanup and remove plugin.

```javascript
connectPlugin.destroy();
```

## Example: Full Integration

```javascript
import NexusEngine from '@aethex/nexus-engine';
import AeThexConnectPlugin from '@aethex/connect-nexus-plugin';

class MyGame {
  async initialize() {
    // Initialize Nexus
    this.nexus = new NexusEngine({
      gameId: 'hide-and-seek-extreme',
      gameName: 'Hide and Seek Extreme',
      platform: 'PC'
    });

    // Initialize Connect Plugin
    this.connect = new AeThexConnectPlugin(this.nexus, {
      apiKey: process.env.NEXUS_API_KEY,
      enableOverlay: true,
      overlayPosition: 'top-right',
      autoMute: true
    });

    await this.connect.initialize();
  }

  startMatch(matchData) {
    // Notify Nexus (Connect plugin listens)
    this.nexus.emit('match:start', {
      map: matchData.map,
      mode: matchData.mode,
      teamId: matchData.teamId
    });

    // Your game logic...
  }

  endMatch(results) {
    // Notify Nexus
    this.nexus.emit('match:end', {
      score: results.score,
      won: results.won,
      duration: results.duration
    });

    // Show custom notification
    this.connect.showNotification({
      icon: '🏆',
      title: 'Match Complete',
      body: `Final Score: ${results.score}`
    });
  }

  cleanup() {
    this.connect.destroy();
  }
}
```

## Testing

Test the plugin in development mode:

```javascript
const connectPlugin = new AeThexConnectPlugin(nexus, {
  apiUrl: 'http://localhost:5000/api', // Local dev server
  apiKey: 'test-key',
  enableOverlay: true
});
```

## Troubleshooting

### Overlay not appearing
- Check that `enableOverlay: true` in config
- Ensure API key is valid
- Check browser console for errors

### Auto-mute not working
- Verify you're emitting `match:start` and `match:end` events
- Check that `autoMute: true` in config

### Friends not showing
- Ensure player is logged into AeThex Connect
- Check network connectivity
- Verify API URL is correct

## Support

For issues or questions:
- GitHub: [github.com/AeThex-Corporation/AeThex-Connect](https://github.com/AeThex-Corporation/AeThex-Connect)
- Discord: [discord.gg/aethex](https://discord.gg/aethex)
- Email: support@aethex.app

## License

MIT License - See LICENSE file for details