Hytale Tag System

Hytale Tag System

This skill documents Hytale's hierarchical tag system and how Hyforged integrates with it for stats, items, blocks, and other assets.

Overview

Hytale uses a hierarchical tag system where tags are defined as a map of categories to value arrays. This creates a rich, queryable tag structure that enables flexible asset lookups.

Key Concepts

JSON Format

Tags in Hytale assets use a map structure, not a flat array:

{
  "Tags": {
    "Category1": ["value1", "value2"],
    "Category2": ["value3"]
  }
}

Example: Item Tags

{
  "Id": "hytale:adamantite_axe",
  "Tags": {
    "Type": ["Weapon"],
    "Family": ["Axe"]
  }
}

Example: Stat Tags

{
  "Id": "hyforged:fire-resistance-bps",
  "Tags": {
    "Domain": ["defense"],
    "Type": ["resistance"],
    "Element": ["fire", "elemental"],
    "Modifier": ["percent"],
    "Source": ["derived"]
  }
}

Tag Expansion

When tags are loaded, Hytale's AssetExtraInfo.Data.putTags() expands each entry into multiple searchable tags:

Expansion Rules

For each entry "Category": ["val1", "val2", ...]:

1. The category key becomes a tag: Category
2. Each value becomes a tag: val1, val2
3. Each category=value combination becomes a tag: Category=val1, Category=val2

This enables flexible querying:

• hasTag("fire") - matches any asset with "fire" in ANY category
• hasTag("Element=fire") - matches only assets with "Element": ["fire"]
• hasTag("Element") - matches any asset with an Element category

AssetRegistry API

Hytale's AssetRegistry provides the global tag index system:

Core Methods

// Get existing tag index (returns Integer.MIN_VALUE if not found)
int tagIndex = AssetRegistry.getTagIndex("fire");

// Get or create tag index (creates if not existing)
int tagIndex = AssetRegistry.getOrCreateTagIndex("fire");

Integer Indices

Tags are stored as integer indices for O(1) lookups:

// Fast membership test
IntSet entityTags = entity.getData().getExpandedTagIndexes();
int fireIndex = AssetRegistry.getTagIndex("fire");
if (entityTags.contains(fireIndex)) {
    // Entity has fire tag
}

StatDefinitionRegistry Tag API

The Hyforged stat system provides convenience methods for tag queries:

Basic Tag Methods

StatDefinitionRegistry registry = StatDefinitionRegistry.get();

// Check if any stat has a tag
boolean exists = registry.hasTag("fire");

// Get stats by tag (any expanded tag)
Collection<StatDefinition> stats = registry.getStatsForTag("fire");
Set<Integer> indices = registry.getStatIndicesForTag("fire");
List<StatId> statIds = registry.getStatIdsForTag("fire");

Category-Based Methods (Recommended)

For hierarchical tags, use the explicit category-based API:

// Check if any stat has Type=resistance
boolean exists = registry.hasTagValue("Type", "resistance");

// Get all resistance stats
Collection<StatDefinition> resistances = registry.getStatsForTagValue("Type", "resistance");

// Get fire elemental stats
Set<Integer> fireStats = registry.getStatIndicesForTagValue("Element", "fire");

// Get all ability score stat IDs
List<StatId> abilityScores = registry.getStatIdsForTagValue("Type", "ability-score");

Integer Index Methods (Performance)

For hot paths, use pre-resolved integer indices:

// Resolve once, use many times
int fireTagIndex = registry.getOrCreateTagIndex("Element=fire");

// Fast O(1) lookup
IntSet stats = registry.getStatIndicesForTagIndex(fireTagIndex);

Standard Tag Categories

Stats

Items (Hytale Native)

Implementing Tags in New Assets

1. Define JSON Schema with Map Codec

// In your asset class
public static final AssetBuilderCodec<String, MyAsset> CODEC = AssetBuilderCodec
    .builder(MyAsset.class, MyAsset::new, ...)
    .appendInherited(
        new KeyedCodec<>("Tags", new MapCodec<>(Codec.STRING_ARRAY, HashMap::new)),
        (asset, value) -> asset.rawTags = value != null ? value : new HashMap<>(),
        asset -> asset.rawTags,
        (asset, parent) -> asset.rawTags = new HashMap<>(parent.rawTags)
    )
    .add()
    .build();

private Map<String, String[]> rawTags = new HashMap<>();

2. Expand Tags on Load

public Set<String> getExpandedTags() {
    Set<String> expanded = new HashSet<>();
    for (Map.Entry<String, String[]> entry : rawTags.entrySet()) {
        String category = entry.getKey();
        expanded.add(category);
        for (String value : entry.getValue()) {
            expanded.add(value);
            expanded.add(category + "=" + value);
        }
    }
    return expanded;
}

3. Register Tags with AssetRegistry

// During asset registration
for (String tag : asset.getExpandedTags()) {
    int tagIndex = AssetRegistry.getOrCreateTagIndex(tag);
    tagToAssetIndices.computeIfAbsent(tagIndex, k -> new IntOpenHashSet()).add(assetIndex);
}

Best Practices

DO

• ✅ Use category-based API (getStatsForTagValue("Type", "resistance")) for explicit queries
• ✅ Pre-resolve tag indices for hot paths
• ✅ Use consistent category names across asset types
• ✅ Document your tag categories in the asset schema
• ✅ Use IntSet for efficient tag membership tests

DON'T

• ❌ Use flat tag arrays ("Tags": ["fire", "damage"]) - use hierarchical format
• ❌ Create duplicate tags across different categories with same meaning
• ❌ Store tag strings at runtime - resolve to indices
• ❌ Assume tag order matters - it doesn't

Related Files

• AssetRegistry - Hytale's global tag index registry
• AssetExtraInfo.Data.putTags() - Tag expansion logic
• StatDefinitionRegistry - Stat-specific tag queries
• StatDefinitionAsset - JSON codec for stat tags
• TagSet / TagSetLookupTable - Advanced tag grouping (like NPCGroup)

ADR Reference

See ADR-0008 in .memory_bank/ADRs.md for the decision rationale behind adopting Hytale's tag system.