BG BGDatabase Home Setup How To Use Video guides Example Breakdown Fields Export Import Data Binding Events Code Generation Addons

Setup

Setup guide

  1. Import the package
  2. Starting with Unity version 2022, API updater window should pop up. Make sure to press "Yes".
  3. Open Window->BGDatabase. Click on Create new database file. Choose the loader (Resources or StreamingAssets) and press Create button
  4. Select Configuration tab and create a table (meta)
  5. Add fields
  6. Select Database tab and create rows (entities) for tables. Save the database.
  7. To prevent data loss, commit the database file to your source control system or create regular backups.

Video guide

Which loader should you choose?

  • Resources loader: this is the recommended option.
  • StreamingAssets loader: use it if you need to update the database file without rebuilding your game.
  • Custom loader: select this option if you need to load the database from a custom location and are comfortable implementing your own loading logic.

You can switch between the Resources and StreamingAssets loaders by moving your database file (bansheegz_database.bytes) between the Resources and StreamingAssets folders. If you're using the localization or partition addon, move all other files (bansheegz_database*.bytes) as well. Ensure you move the corresponding .meta files as well or move the files directly within the Unity Editor.

Resources (recommended) StreamingAssets Custom
File location Under one of Resources folders Under Assets/StreamingAssets folder Anywhere in your project
Pros Works seamlessly everywhere Update the database file without rebuilding your game.
  1. You can place the database file anywhere within your project.
  2. Load database content from any location at runtime.
Cons Storing many assets under the Resources folders (which Unity doesn't recommend) may slow down database loading.
  1. The WEBGL platform requires a custom loader.
  2. Additional code may be executed on Android to load the database.
  1. You need to implement code to load database content and then pass it to database using BGRepo.SetDefaultRepoContent method before accessing database
How to enable File bansheegz_database.bytes should be placed under one of Resources folders File bansheegz_database.bytes should be placed under Assets/StreamingAssets folder Read the guide below

Database file details

BGDatabase operates with two different file types:

  1. Database data file
  2. User settings file

See the table below for more details.

↓ Feature\File → Database file Settings file
Purpose Database file User settings file
Default name bansheegz_database.bytes BGS_{database asset GUID}.json
Format Binary Json
Available at runtime Yes No
Shared between developers Yes No, each developer has a separate file
Location Under Resources / StreamingAssets folders Under Documents folder
How to change location Move (not copy) database file along with its meta file N/A
How file is resolved Naming convention is used (bansheegz_database.bytes) File location is resolved using database asset GUID

You can create a single, shared settings file for all team members by placing bansheegz_database_settings.json file next to database file (only resources loader is currently supported). If you're using both Google Sheets and a shared settings file, exclude bansheegz_database_settings.json from your build using third-party tools or this package, because settings file can contain sensitive data.

Custom loader implementation guide

Follow these steps:
  1. Override the database location in the Unity Editor.
  2. Load the database content manually at runtime and pass it to BGDatabase.
Step 1: Overriding the database location in the Unity Editor
  1. Exit Unity
  2. Back up your database files
  3. Move all database files (e.g., bansheegz_database*.bytes* ) to any location within your project (except Resources and StreamingAssets folders)
  4. Open bansheegz_database.bytes.meta file in a text editor and replace its guid with the following value 3637ea689da0cff4b8d5c0fb5d609c15
  5. Open Unity and click on Reload button in the BGDatabase window.
  6. Select "Settings->Main>Database files" and ensure the database is loaded from the custom location and the Loader is set to Custom. Verify that all content is properly loaded.
Step 2: Loading database content manually at runtime
  1. Load database content from your desired location and call BGRepo.SetDefaultRepoContent(byte[] content) method followed by BGRepo.Load() before accessing database.
  2. If you're using localization/partition add-ons, you also need to load all localization/partition files as well and use BGRepo.SetDefaultRepoContentModel(BGRepoCustomLoaderModel model) method instead. 
    //content is database file content
    byte[] content = someContent; //todo load content
    BGRepo.SetDefaultRepoContent(content);
    BGRepo.Load();
Example projects

Two example projects demonstrate loading the database file(s) from Addressables.

  1. For BGDatabase: download
  2. For BGDatabase + localization addon : download