💬 UnityLink Chat

Production-grade, WhatsApp-style real-time chat for Unity

---

Drop-in chat plugin 1-to-1 messaging, groups, media, reactions, E2E encryption. Built on Firebase. Works on Android, iOS, and Desktop.

---

✨ Features

💬 Core Messaging 1-to-1 chat with persistent history Real-time sync via Firestore listeners Delivery & read receipts (✓ / ✓✓ / 🔵) Typing indicators with animated dots Offline-first with auto sync Push notifications via FCM Unread badges & pagination	📎 Media Support Image messages with thumbnails & tap-to-enlarge File attachments with download progress Voice notes — record, play, seek Upload progress bar with cancel Media picker — gallery, camera, file browser
👥 Group Chat Create groups with name, description & members Role system — Owner / Admin / Member Member management — add, remove, promote @mention and @everyone with priority push System messages for join/leave/promote events	⚡ Advanced Features 😀 Emoji reactions with quick-picker Long-press context menu (Reply · Copy · Edit · Delete · Forward) Edit & delete messages (for everyone or self) Forward messages to any conversation Debounced chat search with context snippets
🔒 End-to-End Encryption AES-256-CBC + HMAC-SHA256 · Per-conversation keys · Secure key exchange · Firebase Storage & Firestore security rules

---

🚀 Quick Start

1. Install Firebase SDK

Import these packages from the Firebase Unity SDK:

Package	Purpose
FirebaseAuth	User authentication
FirebaseFirestore	Real-time database
FirebaseMessaging	Push notifications
FirebaseStorage	Media uploads

2. Import UnityLink Chat

# Option A — Package Manager
Window → Package Manager → + → Add package from disk → select package.json

# Option B — Manual
Copy this folder into your project's Packages/ directory

3. Set Up Your Scene

Use the Setup Wizard: UnityLink → Chat Setup Wizard in the menu bar.

Or manually:

1. Create a ChatManager GameObject → add the ChatManager component
2. Create a ChatTheme: Assets → Create → UnityLink → Chat Theme
3. Wire up UI panels — ChatListView, MessageWindow, etc.

4. Deploy Cloud Functions

cd CloudFunctions
npm install -g firebase-tools
firebase login
firebase init         # Select Functions, Firestore, Storage
npm install
firebase deploy       # Deploys functions + rules

5. Run the Demo

💡 Try the built-in demo scene to see everything in action!

UnityLink → Testing → Create Dual Chat Scene → Press Play

Two test users (Alice & Bob) will sign in automatically and chat side-by-side.
See Demo Scene below for details.

---

🎮 Demo Scene

The plugin includes a fully self-contained dual-user chat demo in Samples~/DemoScene/.

File	Description
DualChatTest.unity	Pre-built scene — just press Play
ChatManager.prefab	Reference prefab with default settings
DefaultChatTheme.asset	WhatsApp-style theme configuration

How to Use

Option A — Import via Package Manager:

Window → Package Manager → UnityLink Chat → Samples → Import "Demo Scene"

Option B — Generate a fresh scene:

UnityLink → Testing → Create Dual Chat Scene

The DualChatTest component builds the entire UI at runtime — no prefabs or manual wiring needed:

• Creates a split-screen with two chat panels
• Signs in Alice & Bob via Firebase Auth
• Both can send/receive messages in real-time

⚠️ Note: Ensure Firebase is configured before running. See SETUP_GUIDE.md for detailed instructions.

---

🏗️ Architecture

UnityLink Chat/
│
├── Runtime/
│   ├── Core/           → ChatManager orchestrator
│   ├── Models/         → UserData, ConversationData, MessageData, GroupData
│   ├── Services/       → FirebaseChatService, GroupChatService, StorageService
│   ├── Sync/           → ChatSyncEngine, ConversationRepository
│   ├── Events/         → Static ChatEvents hub
│   ├── UI/             → MessageBubble, MediaPicker, ReactionView, SearchView...
│   ├── Theme/          → ChatTheme ScriptableObject
│   └── Testing/        → DualChatTest (self-contained demo)
│
├── Editor/             → Custom inspectors, Setup Wizard, Scene Generator
├── CloudFunctions/     → Firebase Cloud Functions + Security Rules
├── Samples~/           → Importable demo scene & assets
└── package.json

---

📖 API Reference

Authentication

await ChatManager.Instance.SignIn("email", "password");
await ChatManager.Instance.CreateAccount("email", "password", "Display Name");
await ChatManager.Instance.SignOut();

Conversations & Messaging

// Start a 1-to-1 chat
await ChatManager.Instance.StartConversation("otherUserId");

// Create a group
var group = await ChatManager.Instance.CreateGroup("Team Chat", "description", memberIds);

// Send media
await ChatManager.Instance.SendMediaMessage(convoId, filePath, MessageType.Image, "caption");

// Edit, Delete & Forward
await ChatManager.Instance.EditMessage(convoId, msgId, "updated text");
await ChatManager.Instance.DeleteMessage(convoId, msgId, forEveryone: true);
var results = await ChatManager.Instance.SearchMessages("query");

Events (Reactive UI)

ChatEvents.OnMessageReceived      += (convoId, msg)  => { /* new message      */ };
ChatEvents.OnConversationsUpdated += (conversations)  => { /* list changed     */ };
ChatEvents.OnTypingStateChanged   += (convoId, uid, t)=> { /* typing indicator */ };
ChatEvents.OnConnectionStateChanged += (state)        => { /* online / offline */ };
ChatEvents.OnUnreadCountChanged   += (convoId, uid, n)=> { /* badge count      */ };

Services

// Group management
ChatManager.Instance.GroupService.AddMember(groupId, adminId, newMemberId);
ChatManager.Instance.GroupService.PromoteMember(groupId, adminId, targetId, MemberRole.Admin);

// Media
ChatManager.Instance.StorageService.UploadImage(convoId, userId, path, onProgress);
ChatManager.Instance.StorageService.DownloadFile(url, localPath, onProgress);

// Encryption
ChatManager.Instance.EncryptionService.Encrypt("hello", convoId);
ChatManager.Instance.EncryptionService.Decrypt(ciphertext, convoId);

---

🎨 Customization

Area	How
Colors & Fonts	Edit the ChatTheme ScriptableObject
Custom Backend	Implement IChatService for your own server
Custom UI	Extend or replace any UI MonoBehaviour
Encryption	Toggle _enableEncryption on ChatManager

---

🔧 Troubleshooting

Issue	Solution
Scripts don't compile	Import all 4 Firebase packages (Auth, Firestore, Messaging, Storage)
FirebaseApp not initialized	Verify google-services.json / GoogleService-Info.plist in Assets/
Push notifications not working	Check FCM token in user document & Cloud Functions logs
Messages not syncing	Deploy Firestore rules; check Console for permission errors
Media upload fails	Enable Firebase Storage & deploy storage.rules
Group creation fails	Ensure Firestore rules allow isGroup documents

---

📋 Requirements

Requirement	Version
Unity	2021.3+
Firebase Unity SDK	11.x+
Node.js	18+ (for Cloud Functions)
Platforms	Android · iOS · Desktop

---

Built with ❤️ by UnityLink