Stratkit Content Items Model

This package provides a comprehensive system for managing Content Items in Unity, offering a 1-to-1 mirroring of Java Content Items with support for both managed and unmanaged workflows. It serves as a centralized abstraction layer for accessing Content Items, supporting both backend-imported and frontend-authored content.

Workflow

Runtime

The runtime workflow is composed of the following steps:

---
title: Initializing the Content Items Database
---
flowchart TD
A["Load and register Content Items binaries"]
B["Load and register frontend-authored data"]
C(["(OPTIONAL) Load and register map specific data"])
D["Initialize the Content Items database"]
E["Initialize the ECS mappings of the database elements"]

A --> B --> C --> D --> E

Frontend-authored data is loaded from the PropertiesCollectionScriptable instances assigned to the ContentItemsVersioned.

Map specific data is loaded from the PropertiesCollectionScriptable instances assigned to the current map.

After that is done, the Content Items Database will be ready for use. Each ECS World (Persistent World, Map World) will have its own instance of the database, as well as its own ECS mappings.

Accessing Content Items - Managed

// Get managed database instance
IContentItemsDbManaged db = SystemAPI.GetSingleton<ContentItemsVersioned>();

// Access by Content Item type
IContentItemsTable unitsTable = db[ContentItemsTableId.Units];

// Access specific Content Item types
UnitContent unitContent = db.GetContent<UnitContent>(contentItemId);
PremiumContent premiumContent = db.GetContent<PremiumContent>(contentItemId);

// Access frontend authored components
bool hasIcon = db.HasValue<IconAtlasedProperty>(contentItemId);
IconAtlasedProperty icon = db.GetValue<IconAtlasedProperty>(contentItemId);

Accessing Content Items - Unmanaged

// Get unmanaged database instance
ContentItemDatabase db = SystemAPI.GetSingleton<ContentItemDatabase>();

// Access by Content Item type
UnitContentDots unitContent = db.GetUnitContent(contentItemId);

Accessing Content Items - Editor

Utilities for accessing the Content Items catalog in the Unity Editor are provided in ContentItemsCatalogEditorUtils. Since entities are not available during edit mode, only the managed workflow is supported.

Content Items Spaces

The Content Items database also includes elements that are not formally part of the Content Items, but have close relationships with it, such as UnitClass or DamageType. These elements are grouped into spaces, which are defined in ContentItemsIdSpace. Since those elements might share ids with Content Items or each other, they have to be grouped into different spaces. The default space for most operations is ContentItemsIdSpace.Backend, which is the space used by the backend-imported Content Items.

Registering new ECS components

Components can be added for each Content Item entity type to make it possible to access the Content Items data using the ECS workflow. Every Content Item type has a corresponding DOTS counterpart, which is responsible for initializing the ECS components for each entity of that type.

The following example shows how to add a new component to the "Unit" Content Item:

// Define a new component
public struct UnitExpirableSecondsComponent : IComponentData {
    public int Value;
}

// In UnitContentDots.Initialize, add the new component
entityManager.AddComponentData(
    Entity,
    new UnitExpirableSecondsComponent {
        Value = (int)content.Expirable.Value.TotalSeconds,
    }
);

Editor

Importing Content Items JSONs

To update the balancing data, we import the JSONs directly from the backend. To import the JSONs, follow these steps:

1. Clone the sup-server repository or update your local copy.
2. Copy the JSONs from the sup-server/content-items/PROJECT_ID
3. In Unity, replace the JSONs in the Content Items directory in your project
4. Execute import process: Tools -> Stratkit -> Content Items -> Import Setup

Stratkit also provides a GitHub workflow to automate this process.

Workflow: https://github.com/bytro/stratkit/actions/workflows/stratkit-content-items-generate.yml

Generating Content Items classes

To manipulate the Content Items, we generate the C# classes from the Content Items definitions in the Java game server. To update the generated classes, follow these steps:

1. Clone the sup-server repository or update your local copy.
2. Execute the content-item-csharp-generator:contentCsharpGenerator gradlew task (check sup-server documentation for additional details)
3. In Unity, replace the generated classes in the Content Items directory in your project
4. Execute import process: Tools -> Stratkit -> Content Items -> Generate

Stratkit also provides a GitHub workflow to automate this process.

WHS Workflow: https://github.com/bytro/stratkit/actions/workflows/whs-content-items-update.yml

S1914 Workflow: https://github.com/bytro/s1914-unity/actions/workflows/s1914-content-items-update.yml

Import process

During the import process, Stratkit will execute a set of post-import steps. Here are some of the key steps:

• Binary Generation All JSONs will be imported into the ContentItemsBackendCollectionScriptable objects in the ContentItemsCatalog ScriptableObject. Right after, those JSONs will be serialized into a binary format, which will also be stored in the ContentItemsBackendCollectionScriptable objects. For performance reasons, the JSONs are not referenced during runtime by this object, only the binary data.

• DataId Updates All DataIdScriptable linked in the ContentItemsCatalog will be updated to match the latest imported balancing data.

• Custom post import hooks Custom hooks can be added to each version of the Content Items, which are represented by the ContentItemsVersioned ScriptableObject. They can be freely added by adding them to the OnPostImport event of this ScriptableObject.