Skip to content

Firestore Examples

This section demonstrates practical usage of Firebase Firestore in Unreal Engine projects.

Firestore is a document-based database designed for structured, strongly typed data. It is commonly used to store player profiles, progression data, game state, leaderboards, and other persistent content that needs to be queried or synchronized across devices.

All examples below are shown using Blueprint nodes. Firebase is assumed to be already initialized.

Firestore Documents and Values

Before working with Firestore operations such as Set, Update, Add, or Query, it is important to understand how FirestoreDocument and FirestoreValue are used in this plugin.
These two structures form the foundation of all Firestore interactions.

FirestoreDocument

A FirestoreDocument represents a Firestore document as a collection of typed fields.

Key characteristics:

  • a document is built locally before being sent to Firestore
  • each field is identified by a string key
  • fields are strongly typed and stored explicitly
  • documents are immutable on the Firestore side, but mutable while being built locally

To construct a document, you typically:

  • create an empty document
  • add fields using typed setter nodes (Set Int, Set String, Set Bool, etc.)
  • pass the completed document to a Firestore operation

To read a document, you typically:

  • request the document from Firestore using its path
  • receive the document asynchronously in the success callback
  • extract individual fields using typed getter nodes (Get Int, Get String, Get Bool, etc.)

This approach avoids raw JSON strings and ensures predictable data structure.

FirestoreValue

A FirestoreValue represents a single typed value stored inside a document.

Firestore values are required when working with:

  • arrays
  • nested objects
  • dynamic or mixed-type data

FirestoreValue supports common Firestore types such as:

  • integers
  • booleans
  • doubles
  • strings
  • arrays
  • objects
  • null

Values are created explicitly using value maker nodes and can later be inspected using typed getters.

When to Use Document and Value

In this plugin, FirestoreDocument is the primary container used in all Firestore operations.
A document always consists of one or more FirestoreValue entries internally.

Key points:

  • FirestoreDocument is used as the main data container when calling Firestore operations (Set, Update, Add, Batch, etc.). Simple fields (int, string, bool, double) are typically added to the document directly using document setter nodes
  • FirestoreValue is mainly required when constructing: arrays, nested objects, complex or dynamic field structures

In practice:

  • use document setters for most common, flat fields
  • use FirestoreValue to build arrays and objects, then attach them to the document
  • combine both to create structured, strongly typed Firestore documents

This separation keeps document construction explicit and predictable, while still allowing complex data layouts when needed.

Creating and Writing Documents

Writing data to Firestore is most commonly done using Set Document. This approach gives you full control over the document path and is ideal for data that belongs to a specific user or entity.

Using Set Document

Set Document writes a document at a specific path, including the document ID.

This is the recommended approach when:

  • the document has a well-defined owner (for example, a player)
  • the document ID is known in advance
  • the data should be replaced or updated over time

A typical example is storing a player profile using the authenticated user ID as the document ID.
Calling Set Document again at the same path will overwrite the existing document with the new data.

Important notes:

  • the document path includes the document ID
  • existing data at the same path is replaced
  • this is the most common pattern for profiles, settings, and persistent state

Using Add Document

Add Document is an alternative approach used for append-only data.

Instead of targeting a specific document path, you provide a collection path, and Firestore automatically generates a unique document ID.

This approach is useful when:

  • each entry should be stored as a separate record
  • document IDs do not need to be known in advance
  • existing documents must never be overwritten

Typical use cases include:

  • event logs
  • match history
  • activity feeds
  • analytics-style records

When using Add Document, the generated document ID is returned in the success callback and can be stored if you need to reference the entry later.

Choosing Between Set and Add

  • Use Set Document when you control the document ID and want to replace or update a specific document
  • Use Add Document when you want to append new records and let Firestore generate unique IDs
  • Set targets a document path, Add targets a collection
  • Set can overwrite data, Add never overwrites existing documents

In most game projects, Set Document is used for core user data, while Add Document is used for logs and history-style data.

Reading Documents

Documents can be read asynchronously from Firestore.

Typical use cases:

  • loading player profiles
  • restoring progression
  • reading configuration or state

Important notes:

  • reading is asynchronous
  • returned data is provided as a FirestoreDocument
  • fields can be accessed using typed getters
  • fields may be missing depending on document state

Helper functions allow you to:

  • check if a field exists
  • determine the type of a stored field

Updating Existing Data

Firestore supports updating only specific fields of an existing document.

Important differences:

  • Set Document replaces the entire document
  • Update Document modifies only the specified fields

Typical use cases for updates:

  • incrementing progression values
  • toggling feature flags
  • modifying a subset of player data

Using updates avoids overwriting unrelated fields.

Running Queries

Queries allow retrieving multiple documents that match specific conditions.

Typical use cases:

  • leaderboards
  • filtered lists
  • recent activity feeds

This example retrieves leaderboard entries from the leaderboard collection.

The query:

  • filters out entries with a score greater than 50
  • orders results by score in descending order
  • runs asynchronously and returns an array of documents

After the query succeeds, the returned documents are iterated and individual fields (such as player_name) are read using Firestore document getters.
Once processing is complete, the query handle is released to free internal resources.

Important notes:

  • queries return arrays of documents
  • query handles must be released explicitly
  • ordering and filtering rules must match Firestore indexing requirements

Listening for Changes

Firestore supports real-time listeners for documents and collections.

When a listener is attached:

  • updates are delivered automatically when data changes
  • a listener handle is returned and must be stored
  • the listener must be stopped explicitly when no longer needed

Typical use cases:

  • live player state updates
  • synchronized UI elements
  • multiplayer or social features

Listeners are efficient but should be used carefully to avoid unnecessary updates.

Batch Operations Overview

Batch operations allow multiple write actions to be grouped and committed atomically.

Key characteristics:

  • all operations succeed or fail together
  • useful for complex state updates
  • reduces the number of network round-trips

Typical use cases include saving multiple related documents in a single operation.

Summary

Firestore provides a powerful, structured data model suitable for most game backend needs.

By combining documents, queries, listeners, and typed values, you can build scalable and maintainable data-driven systems while keeping Blueprint logic clear and predictable.