Setup

Create your own database

  1. Import the package
  2. Open Window->BGDatabase. Click on Create new database file. Chose the loader (Resources or StreamingAssets), fill in fields and press Create button
  3. Go to Configuration and create table (called Meta)
  4. Add fields
  5. Go to Database and create data for tables (called Entities)
  6. 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 chose?

  • Chose Resources loader, if you do not use Resources folders to store assets (Unity does not recommend to do it)
  • Chose StreamingAssets if you have a lot of assets in the Resources folders or if you want to update database file without rebuilding the game
  • Chose 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).

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 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
  3. Not supported by Localization addon
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 bansheegz_database_settings.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 No restrictions
How to change location Move (not copy) database file along with it's meta file Go to Settings -> Main -> "Settings file" to set/change its path.
How file is resolved Naming convention is used (bansheegz_database.bytes) File location is stored in EditorPrefs and bound to database asset GUID

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.
  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. Switch to 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.
  2. If you use localization addon, you also need to load all localization files as well and use BGRepo.SetDefaultRepoContentModel(BGRepoCustomLoaderModel model). We have created an example project with custom loader implementation, which can be downloaded here
What to read next:
  1. How to use
  2. GUI overview