Skip to main content

Unity Example

This example shows the YooAsset + HybridCLR hot update table solution. Also, there is a solution for customizing the buffer loading logic.

Unity Project Dependencies​

Example Unity Project Structure:​

Asset/
├── HotUpdate/       
│   └── Configs/        
│   │   └── Xls/           # Binaries generated by x2f     
│   └── Scripts/
│       ├── GameLogic/     # Game logic
│       └── Xls/           # Code generated by x2f
└── Plugins/        
    ├── FlatBuffers/       # FlatBuffers library
    └── UniTask/

Data Standards​

  • Must configure id field for data indexing, and the type must be int.

Table Generation Commands​

tip

The following commands use macOS/Linux/WSL as examples, using backslash \ as line continuation
For Windows PowerShell, use ` as line continuation
CMD doesn't support line continuation, you can write a bat script and use ^ for line continuation.

  • Incremental Table Generation

    x2f ./example/batchConvert \
    -o "/Path/To/Output" \
    --output-bin "/UnityProject/Assets/HotUpdate/Configs/Xls" \ 
    --output-csharp "/UnityProject/Assets/HotUpdate/Scripts" \
    -n Xls \
    --binary-extension bytes \ 
    --data-class-suffix DataInfo \
    --csharp \
    --csharp-unity-loader \
    --csharp-unity-loader-suffix "" \
    --table-class-suffix Table

  • Full Table Generation

    x2f ./example/batchConvert \
    -o "/Path/To/Output" \
    --output-bin "/UnityProject/Assets/HotUpdate/Configs/Xls" \ 
    --output-csharp "/UnityProject/Assets/HotUpdate/Scripts" \
    -n Xls \
    --binary-extension bytes \ 
    --data-class-suffix DataInfo \
    --csharp \
    --csharp-unity-loader \
    --csharp-unity-loader-suffix "" \
    --table-class-suffix Table \
    --disable-incremental
info

Above, we swapped the default values of tableClassSuffix and csharpUnityLoaderSuffix to make the interface code more concise.

Using YooAsset to Package Binaries​

  • Create a resource package named TablePackage.

AssetBundle Collector:

  • Enable Enable Addressable
  • Use AddressByFileName addressing mode

Coding Example​

async void Start()
{
    // Use your own encapsulated method to load TablePackage
    await AssetLoader.DownloadPackageAsync("TablePackage");

    // Load single tables
    await Xls.Item.Instance.LoadAsync();
    await Xls.Module.Instance.LoadAsync();

    // Load tables configured with merge field in $tables.xlsx through merge table interface
    await Xls.MergeTableLoader.LoadAllAsync();  
    // This line is equivalent to the two lines above that separately load item and module, see implementation in MergeTableLoader.cs

    // Get single row data
    var item = Xls.Item.Instance.Get(101);
    Debug.Log(item.HasValue ? item.Value.Name : "Nope");

    Debug.Log($"name: {Xls.Item.Instance.Get(101)?.Name}");
    Debug.Log($"name: {Xls.Item.Instance.Get(1)?.Name}");

    // Get all data
    var items = Xls.Item.Instance.GetAll();
    foreach (var itemDataInfo in items)
    {
        Debug.Log($"id: {itemDataInfo.Id} name: {itemDataInfo.Name}");
    }

    // Get data pointed to by constant definition
    if (Xls.Module.Instance.TryGet(Xls.ModuleConst.CHAT_PANEL, out var module))
    {
        Debug.Log(module.Name);
    }
    else
    {
        Debug.LogError("Cant find chat panel");
    }

    await Xls.Domain.Instance.LoadAsync();
    // Expose FlatBuffers Root for directly calling Root object interfaces
    var google = Xls.Domain.Instance.Root.DomainDataInfosByKey("google");
    Debug.Log(google.HasValue ? google.Value.Ip + google.Value.Port : "Nope");
}

Strict Verification Identifier STRICT_VERIFICATION​

  • When STRICT_VERIFICATION is set, it will strictly verify file_identifier and buffer structure during LoadAsync/LoadAllAsync, throwing an exception if there's a mismatch, otherwise only printing errors to the console.

About Assembly Definition References​

  • You can create asmdef files for FlatBuffers and Xls, and add references to FlatBuffers and Xls in your project.

Hot Update Suggestions​

  • When packaging, use LZ4 compression to significantly reduce binary size.
  • Only hot update the code generated by x2f, such as Xls.dll. Do not hot update FlatBuffers.dll, otherwise performance will decrease.

Custom buffer loading logic​

If you want to customize the way table data is loaded, you can modify these two code templates under template/unity.

  • Import dependencies

    // 👇 Remove or replace with your own dependencies
    using YooAsset;

  • TableLoaderBase template

    template/unity/unityTableLoaderBaseTemplate.cs
    private async UniTask<bool> InternalLoadAsync()
    {
        // Modify the code that gets the binary data
        var package = YooAssets.TryGetPackage("TablePackage");
        // (...)
        try
        {
            // (...) 
            // 👇 Assign your binary data to buffer
            var buffer = new ByteBuffer(textAsset.bytes);
        
            if (!TableValidator.Validate(
                    () => VerifyIdentifier(buffer),
                    () => VerifyBuffer(buffer),
                    AssetPath))
            {
                return false;
            }
        
            _root = GetTableRoot(buffer);
            LoadDataFromTableRoot(_root);
            return true;
        }
        finally
        {
            // Release resources
            _loadingTask = null;
        }
    }

  • MergeTableLoader template

    template/unity/unityMergeTableTemplate.cs
    public static async UniTask<bool> LoadAllAsync()
    {   
        // (...)
        // Modify the code that gets the binary data
        var package = YooAssets.TryGetPackage("TablePackage");
        // (...)
        
        // 👇 Assign your binary data to buffer
        var buffer = new ByteBuffer(textAsset.bytes);

        // (...)
    }