Asset bundles

Warning

This section is out of date. For now, you should only use it for reference.

A bundle of assets allows to package assets into a single archive that can be downloaded into the game at a specific time.

It allows creation of Downloadable Content (DLC).

Basic rules:

  • A project can generate several bundle.
  • A bundle is created from several assets selectors (Currently, only the PathSelector and TagSelector are supported)
  • A bundle can have dependencies to others bundles
  • Every bundle implicitly references default bundle, where every asset which shouldn't go in a specific bundle will be packaged
  • Once a bundle is deployed into the game, all assets from this bundle and all its dependencies are accessible
  • Bundle resolution is done through an asynchronous callback that allows you to download bundle, and will be called once per dependency (similar to AssemblyResolve event).

Create a bundle

Note

Creating currently requires some manual steps (i.e. editing sdpkg by hand).

Open the sdprj file of the game executable and add the following configuration:

Example:

  • A bundle named MyBundleName will embed assets with tags MyTag1 and MyTag2
  • A bundle named MyBundleName2 will embed assets with tags MyTag3 and MyTag4. This bundle has a dependency to MyBundleName
  • There is also a PathSelector which follow the .gitignore filtering convention.
Bundles:
 - Name: MyBundleName
   Selectors:
    - !TagSelector
      Tags: 
        - MyTag1
        - MyTag2
 - Name: MyBundleName2
   Dependencies:
    - MyBundleName
   Selectors:
    - !TagSelector
      Tags: 
        - MyTag3
        - MyTag4
    - !PathSelector
      Paths:
        - folder1/
        - /folder2/
        - *.bin
        - folder3/*.xml
Note

Asset dependencies are automatically placed in the most appropriate bundle.

Current process works that way:

  • Find assets that matches specific Tag Selectors ("roots" of bundle assets).
  • Enumerate assets that are dependent on those "roots" bundle assets and put them in the same bundle than their "roots" asset.
    • Except if already accessible through one of package dependencies (i.e. a shared dependent package or default package).
  • Place everything else in default bundle.

Note that:

  • Shared assets might be duplicated if not specifically placed in common or default package, but that is intended (i.e. if user wishes to distribute 2 separate DLC that need common assets but need to be self-contained).
  • Every bundle implicitly depends on default bundle.

Load a bundle at runtime

Loading bundle is done through ObjectDatabase.LoadBundle(string bundleName) (ref:{Stride.Core.Storage.ObjectDatabase.LoadBundle}):

// Load bundle
Assets.DatabaseFileProvider.ObjectDatabase.LoadBundle("MyBundleName2");

// Load specified asset
var texture = Assets.Load<Texture2D>("AssetContainedInMyBundleName2");

Selectors

Selectors help deciding which assets are stored in a specific bundle.

Tag selector

Select assets based on a list of tag attached on each asset.

Properties:

  • Tags: List of Tags. Any asset that contains at least one of the tag will be included.

Path selector

Select assets based on their path.

Standard .gitignore patterns are supported (except ! (negate), # (comments) and [0-9] (groups)).

Properties:

  • Paths: List of filters. Any asset whose URL matches one of the filter will be included.