Skip to content

[Architecture] Add semantic content tags for cross-mod compatibility #55

@yunnwi

Description

@yunnwi

Summary

Add semantic tags for registered content so mods can reason about other mods' blocks and systems without hardcoding exact block keys.

Problem / Motivation

Cross-mod systems need to identify content by meaning rather than by specific IDs.

Examples:

  • ecology mods need logs, leaves, saplings, organic blocks
  • gas mods need porous blocks, sealed blocks, vents
  • machinery mods need conductors, containers, inputs/outputs
  • survival mods need flammable, harvestable, edible, organic

Without tags, compatibility requires hardcoding block keys from other mods or replacing whole systems.

Current state

Blocks can be registered with BlockDescriptor and resolved by key/runtime id. This is enough for direct usage, but not enough for generic compatibility between unrelated mods.

There is no generic semantic grouping layer like "this block is a log", "this block is gas-permeable", or "this block is flammable.

Proposed direction

Support semantic tags on registered content.

Example tags:

  • freven:logs
  • freven:leaves
  • freven:saplings
  • freven:organic
  • freven:flammable
  • modid:gas_permeable
  • modid:sealed

Tags should be:

  • declared by content providers
  • queryable by worldgen/runtime APIs
  • namespaced
  • composable across vanilla and mods
  • not tied to hardcoded engine gameplay concepts

Alternatives considered

Mods can hardcode specific block keys, but this does not scale for compatibility.
Another workaround is to make compatibility patches per mod pair, but that becomes fragile as the ecosystem grows.

Ownership / boundary impact

  • SDK vs engine: tag declaration/query contracts probably belong in SDK-facing public contracts
  • vanilla vs engine: vanilla may declare common tags, but engine should not hardcode tree/gas/ecology concepts
  • mods: mods can define their own tags or consume vanilla/common tags

Non-goals

  • Hardcoding trees, gases, crops, ores, or ecology into engine core
  • Defining all possible gameplay tags upfront
  • Replacing existing block runtime IDs

Open questions

  • Should there be a small set of recommended common tags?
  • Should tags be available during worldgen, runtime, or both?
  • How should tag conflicts or aliases be handled?

Expected follow-up work

  • tag declaration syntax
  • tag query APIs
  • docs for common vanilla tags and mod-defined tags

Metadata

Metadata

Assignees

No one assigned

    Labels

    status:triageNew / untriaged. Needs initial review and classification.type:architectureLong-term structural / contract / system design work, not just isolated implementation.

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions