# Firebase Backend v1.5 > **Scope** ‑ This document explains how to integrate the BulletHell Elemental Template v1.4 with Firebase Authentication and Cloud Firestore. It covers both a **Quick Start** for experienced users and a **Step‑by‑Step** walkthrough with screenshots for newcomers. *** Read the offline backend page first *** ### 1. Quick Start (Experienced Users) **Unity** * Unity Version: **2022.3 LTS (or newer)** **Unity Packages (via Package Manager)** * Input System * AI Navigation * In-App Purchasing * 2D Sprite * TextMeshPro (TMP) **Firebase SDK** Import the following Firebase SDK packages (same major/minor, recommended): * **FirebaseAuth 12.10.1** * **FirebaseFirestore 12.10.1** * **FirebaseDatabase (Realtime Database) 12.10.1** Project setup: * In **Project Settings → Player → Scripting Define Symbols**, add: * `FIREBASE` * Import the **BulletHell Elemental Template**. * Add scenes to **Build Settings** in this order: 1. `Login` 2. `Home` 3. Other gameplay/maps scenes * Tags / Layers: * Ensure the **Monster** tag exists and is assigned to all enemy prefabs. * `google-services.json`: * Download from Firebase Console. * Place in: `Assets/StreamingAssets/` (create the folder if missing). * File name must remain **google-services.json**. *** ### 2. Firebase Console Setup #### 2.1 Authentication In **Authentication → Sign-in method**: * Enable: * **Email/Password** * **Anonymous** No special action needed here for user IDs; they are handled by the game code using Firebase Auth UID + Firestore metadata. *** #### 2.2 Firestore Database Create a **Cloud Firestore** database in **Production mode** (or test mode during development, but with the rules below). **Required Collections & Documents** 1. **Players** * Will be created automatically by the game on first login/registration. * No manual documents required. 2. **BattlePass / SeasonInfo** Create: * Collection: `BattlePass` * Document ID: `SeasonInfo` * Fields: * `Season` — **Number**, e.g. `1` * `StartSeason` — **Timestamp**, season start date * (Optional) `DurationDays` — **Number**, total days for the season 3. **Admin / Admin** Create: * Collection: `Admin` * Document ID: `Admin` * Fields: * `gm` — **Array of string** * Each entry is a **Firebase Auth UID** of a GM user. * `support` — **Array of string** * Each entry is a **Firebase Auth UID** of a support user. These arrays control who can use GM tools (Events, Mailbox, Global Message, Ban, etc). 4. **Admin / Events** Create: * Collection: `Admin` * Document ID: `Events` * You can leave it empty or add fields according to your tooling. * Used by the in-game GM tools for map events (must exist for writes under provided rules). 5. **Admin / GlobalMessage** Create: * Collection: `Admin` * Document ID: `GlobalMessage` * Used for global announcements. 6. **Admin / Mailbox** Create: * Collection: `Admin` * Document ID: `Mailbox` * Can start empty. * Used by GM tools to send reward mails. 7. **Friendships** * Create a **root-level collection**: `Friendships`. * Add **one placeholder document** (for example `placeholder`), so the collection exists. * Any shape is fine when created via Console (rules don’t block console writes). * Actual friendship documents are created and managed by the game code using the rules below. 8. **Meta / UserCounters** Used to assign incremental numeric `userId` values. * Create collection: `Meta` * Create document: `UserCounters` * Add field: * `lastUserId` — **Number** * Example: `1000` (or `0`, or any starting point you prefer) * The game will atomically increment this value when new users are provisioned. #### 2.3 Firestore Security Rules Paste the following into **Firestore → Rules**: ```javascript rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { /* Helpers */ function isSignedIn() { return request.auth != null; } function isOwner(uid) { return isSignedIn() && request.auth.uid == uid; } function hasRole(list, uid) { return list is list && uid in list; } /** * Returns true if the current user UID is listed as GM or Support * inside Admin/Admin document ("gm" or "support" string arrays). */ function isGmOrSupport() { return isSignedIn() && ( hasRole( get(/databases/$(database)/documents/Admin/Admin).data.gm, request.auth.uid ) || hasRole( get(/databases/$(database)/documents/Admin/Admin).data.support, request.auth.uid ) ); } /* PLAYERS */ match /Players/{uid} { allow get, list: if isSignedIn(); allow create: if isOwner(uid); allow delete: if isOwner(uid); // Owner can update anything. // GM/Support can only change "isBanned". allow update: if isOwner(uid) || ( isGmOrSupport() && resource.data.diff(request.resource.data).changedKeys().hasOnly(['isBanned']) ); match /PurchasedItems/Items/List/{itemId} { allow get, list, create, update, delete: if isOwner(uid); } match /{document=**} { allow get, list, create, update, delete: if isOwner(uid); } } /* PLAYER NAMES */ match /PlayerNames/{nameLower} { allow get: if true; allow list: if false; allow create: if isSignedIn() && request.resource.data.keys().hasOnly(['ownerUid', 'createdAt']) && request.resource.data.ownerUid == request.auth.uid; allow update, delete: if isSignedIn() && resource.data.ownerUid == request.auth.uid && request.resource.data == resource.data; } /* CURRENCIES */ match /Players/{uid}/Currencies/{coinId} { allow get: if isOwner(uid); allow list: if false; allow delete: if false; allow create: if isOwner(uid) && request.resource.data.keys().hasOnly(['initialAmount', 'amount']) && request.resource.data.initialAmount is int && request.resource.data.amount is int && request.resource.data.initialAmount >= 0 && request.resource.data.amount >= 0; allow update: if isOwner(uid) && request.resource.data.keys().hasOnly(['amount']) && request.resource.data.amount is int && request.resource.data.amount >= 0; } /* BATTLE PASS META */ match /BattlePass/{docId} { allow get: if isSignedIn() && docId == "SeasonInfo"; allow list: if false; allow create, update, delete: if false; } /* ADMIN / ROLES */ match /Admin/Admin { allow get: if isSignedIn(); allow list: if false; allow create, update, delete: if false; } /* ADMIN MAP EVENTS */ match /Admin/Events { allow get: if isSignedIn(); allow list: if false; allow create, update, delete: if isGmOrSupport(); } /* ADMIN MAILBOX */ match /Admin/Mailbox { allow get, list, create, update, delete: if isGmOrSupport(); } /* ADMIN GLOBAL MESSAGE */ match /Admin/GlobalMessage { allow get: if isSignedIn(); allow list: if false; allow create, update, delete: if isGmOrSupport(); } /* OTHER ADMIN DOCS DEFAULT */ match /Admin/{other} { allow get: if isSignedIn(); allow list, create, update, delete: if false; } /* FRIENDSHIPS */ match /Friendships/{fid} { function validUsersArray(data) { return data.users is list && data.users.size() == 2 && data.users[0] is string && data.users[1] is string && data.users[0] != data.users[1]; } function sortedIdFor(data) { let a = data.users[0]; let b = data.users[1]; return (a < b) ? (a + "_" + b) : (b + "_" + a); } function isParticipant(uid) { return uid in resource.data.users; } function userIndex(uid) { return resource.data.users[0] == uid ? 0 : (resource.data.users[1] == uid ? 1 : -1); } function isRequester(uid) { return resource.data.requestedBy == uid; } function friendshipTransitionAllowed() { let before = resource.data.state; let after = request.resource.data.state; let uid = request.auth.uid; let idx = userIndex(uid); return ( (before == "PENDING" && after == "ACCEPTED" && !isRequester(uid)) || (before == "PENDING" && after == "PENDING" && isRequester(uid)) || (after == "BLOCKED_0" && idx == 0) || (after == "BLOCKED_1" && idx == 1) ); } // Read: only participants. allow get, list: if isSignedIn() && isParticipant(request.auth.uid); // Create: send friend request (PENDING). allow create: if isSignedIn() && validUsersArray(request.resource.data) && sortedIdFor(request.resource.data) == fid && request.auth.uid in request.resource.data.users && request.resource.data.requestedBy == request.auth.uid && request.resource.data.state == "PENDING" && request.resource.data.createdAt is timestamp && request.resource.data.updatedAt is timestamp; // Update: accept, block, or refresh pending. allow update: if isSignedIn() && isParticipant(request.auth.uid) && validUsersArray(request.resource.data) && request.resource.data.users == resource.data.users && request.resource.data.requestedBy == resource.data.requestedBy && request.resource.data.createdAt == resource.data.createdAt && request.resource.data.updatedAt is timestamp && friendshipTransitionAllowed(); // Delete: // - requester can cancel pending // - other user can reject pending // - either can unfriend (ACCEPTED) // - blocker can unblock (BLOCKED_x) allow delete: if isSignedIn() && isParticipant(request.auth.uid) && ( (resource.data.state == "PENDING") || (resource.data.state == "ACCEPTED") || (resource.data.state == "BLOCKED_0" && request.auth.uid == resource.data.users[0]) || (resource.data.state == "BLOCKED_1" && request.auth.uid == resource.data.users[1]) ); } match /Meta/UserCounters { allow get: if isSignedIn(); allow create, update: if isSignedIn() && request.resource.data.keys().hasOnly(['lastUserId']) && request.resource.data.lastUserId is int && ( !resource.exists() || (request.resource.data.lastUserId > resource.data.lastUserId) ); allow delete: if false; } } } ``` ### 3. Realtime Database Setup #### 3.1 Create Realtime Database In **Firebase Console → Realtime Database**: 1. Create a new database in the same project. 2. Choose a location (any supported region). 3. You can start in locked mode and then paste the rules below. #### 3.2 Base Structure The game will create nodes automatically when presence & invites are used, but you may create them upfront (empty) for clarity: * Root-level: * `status` (empty object) * `invites` (empty object) * `chat` is created automatically when global chat is used. Example initial JSON: ```json { "status": {}, "invites": {} } ``` #### 3.3 Realtime Database Rules Paste the following into **Realtime Database → Rules**: ```javascript { "rules": { "status": { "$uid": { ".read": "auth != null && auth.uid == $uid", ".write": "auth != null && auth.uid == $uid" } }, "invites": { "$targetUid": { ".read": "auth != null && auth.uid == $targetUid", "$inviteId": { ".write": "auth != null && newData.child('fromUid').val() === auth.uid" } } }, "chat": { ".read": "auth != null", ".write": "false", ".indexOn": ["timestamp"], "$messageId": { ".write": "auth != null && !data.exists()", ".validate": "newData.hasChildren(['playerId', 'playerName', 'iconId', 'frameId', 'message', 'timestamp', 'isHighlighted'])", "playerId": { ".validate": "newData.isString() && newData.val() === auth.uid" }, "playerName": { ".validate": "newData.isString() && newData.val().length > 0 && newData.val().length <= 50" }, "iconId": { ".validate": "newData.isString() && newData.val().length > 0" }, "frameId": { ".validate": "newData.isString() && newData.val().length > 0" }, "message": { ".validate": "newData.isString() && newData.val().length > 0 && newData.val().length <= 500" }, "timestamp": { ".validate": "newData.isNumber() && newData.val() <= now" }, "isHighlighted": { ".validate": "newData.isBoolean()" } } } } } ``` ### **For developers who have not yet set up a project with Firebase or who have any questions, below is a detailed step-by-step guide with images:** #### 2. Step‑by‑Step Guide (With Images) **2.1 Create a URP Project** 1. Open **Unity Hub → New Project**. 2. Select **Universal 3D (URP)** template. 3. Name your project and click **Create**. *Optional* – HDRP/Built‑in pipelines work, but demo textures may need conversion.
**2.2 Install Required Unity Packages** *Window → Package Manager → Unity Registry*. Add *Input System*, *AI Navigation*, *In‑App Purchasing*, *2D Sprite*, *TextMeshPro*.
**2.3 Import Firebase SDK** 1. Download lastest `FirebaseAuth.unitypackage` , `FirebaseFirestore.unitypackage` and `FirebaseDatabase.unitypackage` from the [Firebase Unity SDK Archive](https://developers.google.com/unity/archive). 2. Double‑click each package to import. 3. When prompted, allow **ExternalDependancyManager** to resolve libraries. 4. add FIREBASE in Scripting Define Symbols in Build Settings > Player
**2.4 Import the Template** Drag the *BulletHell Elemental Template* `.unitypackage` into the Editor or install via **Package Manager → My Assets**. **2.5 Configure Project Settings** * **Player Settings → Identification → Package Name** must match the *Android/iOS* package names you register in Firebase. * Switch Platform to PC, **Android** or **iOS** before building (Editor → File → Build Settings). **2.6 Firebase Console Configuration** 1. **Create Project** → add Android and/or iOS app with the correct package name. 2. Download **google‑services.json** (Android) or **GoogleService‑Info.plist** (iOS). 3. Place *json* file in **Assets/StreamingAssets/**. *If Unity cannot locate the file, verify the folder name and that the filename has no suffix (e.g., (1)).*
1. **Firestore Database → Start in production mode**. 2. See the step-by-step instructions and rules at the beginning regarding which fields to create in Firestore. 3. Apply the security rules (see Quick Start above). **2.8 Prepare Cloud Firestore** * **Authentication → Sign‑in method**: enable **Email/Password** and **Anonymous**. **2.7 Enable Authentication**
### 3. Realtime Database Setup #### 3.1 Create Realtime Database In **Firebase Console → Realtime Database**: 1. Create a new database in the same project. 2. Choose a location (any supported region). 3. You can start in locked mode and then paste the rules below. #### 3.2 Base Structure The game will create nodes automatically when presence & invites are used, but you may create them upfront (empty) for clarity: * Root-level: * `status` (empty object) * `invites` (empty object) * `chat` is created automatically when global chat is used. Example initial JSON (optional): ```json { "status": {}, "invites": {} } ```
**2.9 Verify Tags, Layers & Scenes** If you imported the template into an existing project: * Add **Monster** tag in **Edit → Project Settings → Tags & Layers**. * Assign it to enemy prefabs in `BulletHellTemplate/Resources/Monsters/`. * Ensure scene order in **Build Settings**: `Login`, `Home`, *others*. **2.10 Test in Editor** 1. Open `Login` scene. 2. Press **Play** – the template auto‑creates a local account, syncs with Firebase, and loads initial data. 3. Check **Console** for Firebase initialization logs. #### 3. Common Issues & Fixes | Issue | Cause | Fix | | ------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | `google‑services.json` not found | File in wrong location | Place inside **Assets/StreamingAssets/**. Refresh project. | | "Unknown error" on account creation | Weak password | Use at least 8 chars, 1 number, 1 special char. | | Android/iOS build fails on "Validate References" | Unused platform DLLs | *Edit → Project Settings → Player → Other Settings*, disable **Validate References** for unsupported platform. | *** #### 4. Next Steps * Customize Battle Pass seasons by updating `Season` and `StartSeason` fields. * Harden security with **App Check** or move save logic to **Cloud Functions** (requires paid Firebase plan). * Join our community for support and feature requests. **Discord** – **Email** –