Skip to main content

Unity Example

Unity Project Dependencies​

  • YooAsset 2.3.x: Configure according to the official tutorial.
  • UniTask: Install into the project via UPM.
  • FlatBuffers: Copy the .cs files from the net/FlatBuffers folder into the project.

Example Unity Project Structure:​

Asset/
├── HotUpdate/       
│   └── Configs/        
│   │   └── Xls/           # Place binaries generated by x2f     
│   └── Scripts/
│       ├── GameLogic/      # Game logic
│       └── Xls/           # Place code generated by x2f
└── Plugins/        
    ├── FlatBuffers/        # Place 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

Example Code​

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 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.

Custom Unity Template Code​

  • Refer to modifying .cs files under template/unity.

Hot Update Suggestions​

  • When packaging, use LZ4 compression to significantly reduce binary size.