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 table (called Meta)
  5. Add fields
  6. Select Database tab and create data for tables (called Entities)
  7. Make sure to commit database file to your source control system or make regular backups to prevent the risk of data loss.


Which loader to choose?

  • Resources loader is a recommended loader to use
  • Choose StreamingAssets if you want to update database file without rebuilding your game
  • Choose custom loader if you want to load database from custom location and do not mind to write your own loader

You can switch between Resources/StreamingAssets loaders by simply moving your database file (bansheegz_database.bytes) between Resources/StreamingAssets folders (if you use localization addon, move all localization files as well- bansheegz_database*.bytes). Make sure to move corresponding meta files as well or move files inside Unity Editor.

Resources StreamingAssets Custom
File location Under one of Resources folders Under Assets/StreamingAssets folder Anywhere in your project
Pros Works everywhere without any extra effort You can update database file without rebuilding your game
  1. Database file can be put to any place under your project
  2. Database content can be loaded from any location at runtime
Cons If you store many assets under Resources folders (Unity does not recommend to do it), it may lead to slow database loading
  1. WEBGL platform requires custom loader
  1. you need to implement code, which loads database content.
  2. You need to load and assign database content using BGRepo.SetDefaultRepoContent method before accessing it
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

More details about database files

There are 2 different files BGDatabase operates with:

  1. file with database data
  2. file with user settings

More details about these files are available in the table below.

↓ 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 use GoogleSheets, make sure to not include bansheegz_database_settings.json into your build by using third-party tools or this package

Custom loader implementation guide

2 steps guide:
  1. Override database location in Unity Editor.
  2. Load database content manually at runtime and pass it to BGDatabase
Overriding database location inside Unity Editor
  1. Exit Unity
  2. Backup your database files
  3. Move all database files (bansheegz_database*.bytes* ) to any location in your project (except Resources and StreamingAssets folders)
  4. Open bansheegz_database.bytes.meta file in text editor and replace its guid with this value 3637ea689da0cff4b8d5c0fb5d609c15
  5. Open up Unity and click on Reload button in BGDatabase window.
  6. Select "Settings->Main>Database files" and make sure database is loaded from custom location and Loader is set to Custom. Also make sure all content is properly loaded.
Loading database content manually at runtime
  1. Load database content from whatever location you want and call BGRepo.SetDefaultRepoContent(byte[] content) method before accessing database followed by BGRepo.Load().
  2. If you use localization addon, you also need to load all localization files as well and use BGRepo.SetDefaultRepoContentModel(BGRepoCustomLoaderModel model) method instead.
    //content is database file content
    byte[] content = someContent; //todo load content
Example projects

There are 2 example projects, demonstrating how to load database file(s) from Addressables.

  1. For BGDatabase: download
  2. For BGDatabase + localization addon : download
What to read next:
  1. How to use
  2. GUI overview