AeThex-Connect/PHASE5-QUICK-START.md

# PHASE 5: NEXUS INTEGRATION - Quick Start Guide

Get AeThex Connect working with Nexus Engine in 5 minutes.

## Prerequisites

- Node.js 18+
- PostgreSQL database
- AeThex Passport account
- Nexus API key

## Step 1: Database Migration

Run the Nexus integration migration:

```bash
cd /workspaces/AeThex-Connect
npm run migrate
```

Or manually:
```bash
psql -d aethex_connect -f src/backend/database/migrations/005_nexus_cross_platform.sql
```

## Step 2: Environment Setup

Add to `.env`:
```env
NEXUS_API_KEY=your-nexus-api-key-here
NEXUS_ENGINE_URL=https://nexus.aethex.cloud
```

## Step 3: Start Server

```bash
npm start
```

Server will run on `http://localhost:5000`

## Step 4: Integrate SDK in Your Game

### Install Plugin

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

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

### Initialize in Game

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

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

// Initialize Connect Plugin
const connect = new AeThexConnectPlugin(nexus, {
  apiUrl: 'http://localhost:5000/api', // Dev server
  apiKey: process.env.NEXUS_API_KEY,
  enableOverlay: true,
  overlayPosition: 'top-right'
});

// Start when game loads
await connect.initialize();
```

### Emit Game Events

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

// When match ends
nexus.emit('match:end', {
  score: 150,
  won: true,
  duration: 1234
});

// When game exits
nexus.emit('game:exit');
```

## Step 5: Test

### Test Session Start

```bash
curl -X POST http://localhost:5000/api/nexus/sessions/start \
  -H "X-Nexus-API-Key: your-key" \
  -H "X-Nexus-Player-ID: test-player-1" \
  -H "Content-Type: application/json" \
  -d '{
    "nexusPlayerId": "test-player-1",
    "gameId": "test-game",
    "gameName": "Test Game",
    "metadata": {
      "platform": "PC"
    }
  }'
```

Expected response:
```json
{
  "success": true,
  "session": {
    "id": "session-uuid",
    "game_id": "test-game",
    "started_at": "2026-01-10T12:00:00Z"
  },
  "overlayConfig": {
    "enabled": true,
    "position": "top-right",
    "opacity": 0.9,
    "notifications": true,
    "autoMute": true
  }
}
```

### Test Friends

First, create test users and send friend request:

```bash
# Send friend request
curl -X POST http://localhost:5000/api/friends/request \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetIdentifier": "friend@nexus.aethex.cloud"
  }'

# Get friends list
curl http://localhost:5000/api/friends \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Step 6: View Overlay

Open in browser:
```
http://localhost:5173/overlay?session=test-session
```

You should see:
- Friends list
- Minimize button
- Message notifications (when triggered)

## Troubleshooting

### Overlay Not Appearing

Check:
1. `enableOverlay: true` in config
2. Browser console for errors
3. CORS settings allow your game domain

### Session Start Fails

Check:
1. `NEXUS_API_KEY` is set in `.env`
2. Database migration ran successfully
3. API key matches server expectation

### Friends Not Loading

Check:
1. User is authenticated (has valid token)
2. Friend relationships exist in database
3. WebSocket connection is established

## API Endpoints Reference

### Game Sessions
- `POST /api/nexus/sessions/start` - Start session
- `POST /api/nexus/sessions/:id/update` - Update state
- `POST /api/nexus/sessions/:id/end` - End session

### Friends
- `GET /api/friends` - Get friends list
- `POST /api/friends/request` - Send request
- `POST /api/friends/requests/:id/respond` - Accept/reject
- `DELETE /api/friends/:userId` - Remove friend

### Lobbies
- `POST /api/nexus/lobbies` - Create lobby
- `POST /api/nexus/lobbies/:id/join` - Join lobby
- `POST /api/nexus/lobbies/:id/ready` - Toggle ready
- `POST /api/nexus/lobbies/:id/start` - Start game

## Example: Full Game Integration

```javascript
class MyGame {
  async init() {
    // Setup Nexus
    this.nexus = new NexusEngine({
      gameId: 'my-awesome-game',
      gameName: 'My Awesome Game'
    });

    // Setup Connect
    this.connect = new AeThexConnectPlugin(this.nexus, {
      apiKey: process.env.NEXUS_API_KEY,
      enableOverlay: true,
      autoMute: true
    });

    await this.connect.initialize();
  }

  startMatch(matchData) {
    this.nexus.emit('match:start', matchData);
  }

  endMatch(results) {
    this.nexus.emit('match:end', results);
    
    // Optional: Show notification
    this.connect.showNotification({
      icon: '🏆',
      title: 'Match Complete',
      body: `Score: ${results.score}`
    });
  }

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

## Next Steps

1. Read full documentation: `PHASE5-COMPLETE.md`
2. Explore SDK features: `nexus-sdk/README.md`
3. Join Discord: `#nexus-integration`
4. Report issues: GitHub Issues

## Need Help?

- Discord: discord.gg/aethex
- Email: support@aethex.app
- Docs: docs.aethex.app/nexus

---

**You're all set! Your game now has cross-platform communication! 🎮**