Skip to content

Commit 6ecd840

Browse files
syntaxerror247syntaxerror247
committed
Add initial documentation
1 parent f77eff0 commit 6ecd840

File tree

5 files changed

+466
-0
lines changed

5 files changed

+466
-0
lines changed

‎docs/authentication.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Authentication
2+
3+
The Firebase Authentication module in **GodotFirebaseAndroid** supports anonymous login, email/password login, Google login, and account management. Each method emits signals to indicate success or failure.
4+
5+
## Signals
6+
7+
- `auth_success(current_user_data: Dictionary)`
8+
Emitted when a user successfully signs in. The dictionary contains user information such as UID, email, etc.
9+
10+
- `auth_failure(error_mplugin.emitGodotSignal("realtime_db_value_changed", path, data)essage: String)`
11+
Emitted when an authentication operation fails.
12+
13+
- `sign_out_success(success: bool)`
14+
Emitted after a sign-out operation. `true` indicates success.
15+
16+
- `password_reset_sent(success: bool)`
17+
Emitted after attempting to send a password reset email.
18+
19+
- `email_verification_sent(success: bool)`
20+
Emitted after attempting to send an email verification email.
21+
22+
- `user_deleted(success: bool)`
23+
Emitted after an attempt to delete the current user.
24+
25+
## Methods
26+
27+
### `sign_in_anonymously()`
28+
Signs in the user anonymously.
29+
**Emits:** `auth_success` or `auth_failure`.
30+
31+
```gdscript
32+
Firebase.auth.sign_in_anonymously()
33+
```
34+
35+
---
36+
37+
### `create_user_with_email_password(email: String, password: String)`
38+
Creates a new user with the given email and password.
39+
**Emits:** `auth_success` or `auth_failure`.
40+
41+
```gdscript
42+
Firebase.auth.create_user_with_email_password("testuser@email.com", "password123")
43+
```
44+
45+
---
46+
47+
### `sign_in_with_email_password(email: String, password: String)`
48+
Signs in a user using email and password credentials.
49+
**Emits:** `auth_success` or `auth_failure`.
50+
51+
```gdscript
52+
Firebase.auth.sign_in_with_email_password("testuser@email.com", "password123")
53+
```
54+
---
55+
56+
### `send_password_reset_email(email: String)`
57+
Sends a password reset email to the specified address.
58+
**Emits:** `password_reset_sent`. It also emits `auth_failure` on failure.
59+
60+
```gdscript
61+
Firebase.auth.send_password_reset_email("testuser@email.com")
62+
```
63+
---
64+
65+
### `send_email_verification()`
66+
Sends an email verification to the currently signed-in user.
67+
**Emits:** `email_verification_sent`. It also emits `auth_failure` on failure.
68+
69+
```gdscript
70+
Firebase.auth.send_email_verification()
71+
```
72+
---
73+
74+
### `sign_in_with_google()`
75+
Signs in the user using Google. Ensure Google Sign-In is properly configured in the Firebase console.
76+
**Emits:** `auth_success` or `auth_failure`.
77+
78+
```gdscript
79+
Firebase.auth.sign_in_with_google()
80+
```
81+
---
82+
83+
### `get_current_user_data() -> Dictionary`
84+
If no user is signed in, returns an dictionary with error.
85+
**Returns** a dictionary containing the currently signed-in user's data.
86+
87+
```gdscript
88+
Firebase.auth.get_current_user_data()
89+
```
90+
---
91+
92+
### `delete_current_user()`
93+
Deletes the currently signed-in user.
94+
**Emits:** `user_deleted`. It also emits `auth_failure` on failure.
95+
96+
```gdscript
97+
Firebase.auth.delete_current_user()
98+
```
99+
---
100+
101+
### `is_signed_in() -> bool`
102+
**Returns** `true` if a user is currently signed in, otherwise `false`.
103+
104+
```gdscript
105+
Firebase.auth.is_signed_in()
106+
```
107+
---
108+
109+
### `sign_out()`
110+
Signs out the current user.
111+
**Emits:** `sign_out_success`. It also emits `auth_failure` on failure.
112+
113+
```gdscript
114+
Firebase.auth.sign_out()
115+
```
116+
---

‎docs/firestore.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Cloud Firestore
2+
3+
The Cloud Firestore module in **GodotFirebaseAndroid** supports adding, retrieving, updating, and deleting documents, as well as listening for document changes.
4+
5+
## Signals
6+
7+
-`write_task_completed(result: Dictionary)`
8+
Emitted after adding or setting a document.
9+
10+
-`get_task_completed(result: Dictionary)`
11+
Emitted after retrieving a document or a list of documents.
12+
13+
-`update_task_completed(result: Dictionary)`
14+
Emitted after updating a document.
15+
16+
-`delete_task_completed(result: Dictionary)`
17+
Emitted after deleting a document.
18+
19+
-`document_changed(document_path: String, data: Dictionary)`
20+
Emitted when a listened document is changed.
21+
22+
**Note**: All signal result dictionaries contain the following keys:
23+
24+
- status (bool): true if the operation succeeded, false otherwise.
25+
26+
- docID (String): The Firestore document ID related to the operation.
27+
28+
- data (optional Dictionary): The data returned in the operation (if applicable).
29+
30+
- error (optional String): The error message if the operation failed.
31+
32+
## Methods
33+
34+
### `add_document(collection: String, data: Dictionary)`
35+
36+
Adds a new document to the specified collection with an auto-generated ID.
37+
**Emits:** `write_task_completed`
38+
39+
```gdscript
40+
Firebase.firestore.add_document("players", {"name": "Alice", "score": 100})
41+
```
42+
43+
---
44+
45+
### `set_document(collection: String, documentId: String, data: Dictionary, merge: bool = false)`
46+
47+
Sets data for a document. If the document exists, it will be overwritten unless `merge` is `true`.
48+
**Emits:** `write_task_completed`
49+
50+
```gdscript
51+
Firebase.firestore.set_document("players", "user_123", {"score": 150}, true)
52+
```
53+
54+
---
55+
56+
### `get_document(collection: String, documentId: String)`
57+
58+
Retrieves a single document from the specified collection.
59+
**Emits:** `get_task_completed`
60+
61+
```gdscript
62+
Firebase.firestore.get_document("players", "user_123")
63+
```
64+
65+
---
66+
67+
### `get_documents_in_collection(collection: String)`
68+
69+
Retrieves all documents in a given collection.
70+
**Emits:** `get_task_completed`
71+
72+
```gdscript
73+
Firebase.firestore.get_documents_in_collection("players")
74+
```
75+
76+
---
77+
78+
### `update_document(collection: String, documentId: String, data: Dictionary)`
79+
80+
Updates fields in a document without overwriting the entire document.
81+
**Emits:** `update_task_completed`
82+
83+
```gdscript
84+
Firebase.firestore.update_document("players", "user_123", {"score": 200})
85+
```
86+
87+
---
88+
89+
### `delete_document(collection: String, documentId: String)`
90+
91+
Deletes a document from the specified collection.
92+
**Emits:** `delete_task_completed`
93+
94+
```gdscript
95+
Firebase.firestore.delete_document("players", "user_123")
96+
```
97+
98+
---
99+
100+
### `listen_to_document(documentPath: String)`
101+
102+
Starts listening to changes on a specific document path.
103+
**Emits:** `document_changed`
104+
105+
```gdscript
106+
Firebase.firestore.listen_to_document("players/user_123")
107+
```
108+
109+
---
110+
111+
### `stop_listening_to_document(documentPath: String)`
112+
113+
Stops listening to changes for a document path.
114+
115+
```gdscript
116+
Firebase.firestore.stop_listening_to_document("players/user_123")
117+
```
118+
119+
---

‎docs/index.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# GodotFirebaseAndroid
2+
3+
**GodotFirebaseAndroid** is an Android plugin for the Godot Engine that integrates Firebase services in Godot Android games and apps.
4+
5+
## Features
6+
7+
- ✅ Firebase Authentication (Email/Password, Google Sign-In)
8+
- ✅ Cloud Firestore
9+
- ✅ Realtime Database
10+
- ✅ Cloud Storage
11+
- 🔜 Cloud Messaging (Coming Soon)
12+
13+
## Getting Started
14+
15+
1. **Download & Install Plugin**
16+
- Download the latest release from [Releases](https://github.com/syntaxerror247/GodotFirebaseAndroid/releases)
17+
- Extract and copy the `GodotFirebaseAndroid` folder to your project's `addons/` directory: `your_project/addons GodotFirebaseAndroid/`
18+
- Enable the plugin via **Project > Project Settings > Plugins**.
19+
20+
2. **Set Up Firebase**
21+
- Go to the [Firebase Console](https://console.firebase.google.com/)
22+
- Create a Firebase project and register your Android app.
23+
- Enable the necessary Firebase features (Auth, Firestore, etc.)
24+
- Download `google-services.json` and place it in: `android/build/`
25+
26+
3. **Enable Gradle Build**
27+
- Open **Project > Export**
28+
- Enable `gradle_build/use_gradle_build` in Android preset.
29+
30+
## Documentation
31+
32+
- [Authentication](authentication.md)
33+
- [Cloud Firestore](firestore.md)
34+
- [Realtime Database](realtime_database.md)
35+
- [Cloud Storage](storage.md)
36+
- [Cloud Messaging](messaging.md)
37+
38+
## License
39+
40+
MIT License
41+
42+
Copyright (c) 2025 Anish Mishra (syntaxerror247)
43+
44+
Permission is hereby granted, free of charge, to any person obtaining a copy
45+
of this software and associated documentation files (the "Software"), to deal
46+
in the Software without restriction, including without limitation the rights
47+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
48+
copies of the Software, and to permit persons to whom the Software is
49+
furnished to do so, subject to the following conditions:
50+
51+
The above copyright notice and this permission notice shall be included in all
52+
copies or substantial portions of the Software.
53+
54+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
55+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
56+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
57+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
58+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
59+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
60+
SOFTWARE.

‎docs/realtime_database.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Realtime Database
2+
3+
The Realtime Database module in **GodotFirebaseAndroid** supports reading, writing, and listening to changes in the Firebase Realtime Database.
4+
5+
## Signals
6+
7+
-`write_task_completed(result: Dictionary)`
8+
Emitted after a write (set) operation completes. The dictionary contains a `success` boolean and optionally a `message`.
9+
10+
-`get_task_completed(result: Dictionary)`
11+
Emitted after a get (read) operation completes. Contains either the fetched data or an error.
12+
13+
-`update_task_completed(result: Dictionary)`
14+
Emitted after an update operation. Indicates success or failure.
15+
16+
-`delete_task_completed(result: Dictionary)`
17+
Emitted after a delete operation. Indicates success or failure.
18+
19+
-`db_value_changed(path: String, data: Dictionary)`
20+
Emitted when a value at a listened path changes.
21+
22+
**Note**: All signal result dictionaries contain the following keys:
23+
24+
- status (bool): true if the operation succeeded, false otherwise.
25+
26+
- path (String): The Realtime Database path related to the operation.
27+
28+
- data (optional Dictionary): The data returned in the operation (if applicable).
29+
30+
- error (optional String): The error message if the operation failed.
31+
32+
## Methods
33+
34+
### `set_value(path: String, data: Dictionary)`
35+
36+
Sets data at the specified path.
37+
**Emits:** `write_task_completed`.
38+
39+
```gdscript
40+
Firebase.realtimeDB.set_value("/users/user1", {"name": "Alice", "score": 10})
41+
```
42+
43+
---
44+
45+
### `get_value(path: String)`
46+
47+
Retrieves data from the specified path.
48+
**Emits:** `get_task_completed`.
49+
50+
```gdscript
51+
Firebase.realtimeDB.get_value("/users/user1")
52+
```
53+
54+
---
55+
56+
### `update_value(path: String, data: Dictionary)`
57+
58+
Updates specific fields at the given path.
59+
**Emits:** `update_task_completed`.
60+
61+
```gdscript
62+
Firebase.realtimeDB.update_value("/users/user1", {"score": 15})
63+
```
64+
65+
---
66+
67+
### `delete_value(path: String)`
68+
69+
Deletes data at the given path.
70+
**Emits:** `delete_task_completed`.
71+
72+
```gdscript
73+
Firebase.realtimeDB.delete_value("/users/user1")
74+
```
75+
76+
---
77+
78+
### `listen_to_path(path: String)`
79+
80+
Listens to realtime changes at the specified path.
81+
**Emits:** `db_value_changed` on every update.
82+
83+
```gdscript
84+
Firebase.realtimeDB.listen_to_path("/users/user1")
85+
```
86+
87+
---
88+
89+
### `stop_listening(path: String)`
90+
91+
Stops listening for changes at the specified path.
92+
93+
```gdscript
94+
Firebase.realtimeDB.stop_listening("/users/user1")
95+
```
96+
97+
---

0 commit comments

Comments
 (0)