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:

cd /workspaces/AeThex-Connect
npm run migrate

Or manually:

psql -d aethex_connect -f src/backend/database/migrations/005_nexus_cross_platform.sql

Step 2: Environment Setup

Add to .env:

NEXUS_API_KEY=your-nexus-api-key-here
NEXUS_ENGINE_URL=https://nexus.aethex.cloud

Step 3: Start Server

npm start

Server will run on http://localhost:5000

Step 4: Integrate SDK in Your Game

Install Plugin

npm install @aethex/connect-nexus-plugin

Or use CDN:

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

Initialize in Game

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

// 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

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:

{
  "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:

# 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

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! 🎮