Cardinal Components API Mod Wiki

Cardinal Components API (CCA) is a specialized library mod designed for the Fabric and Quilt ecosystems. It provides a standardized, modular, and extremely fast way for mods to attach arbitrary data (known as "components") to various Minecraft objects. Unlike traditional NBT-based data storage, CCA uses ASM-generated extensions to ensure that data access is nearly as fast as native field access.

For players, this mod is a silent dependency required by many popular gameplay mods to handle complex mechanics like mana systems, leveling, custom energy types, or persistent player statistics. For developers, it eliminates the need for manual packet handling, complex mixins, or redundant storage logic.

The API operates on three primary pillars that define how data is handled within the game engine:

1. Components

A Component is a piece of data that can be attached to a provider. It must implement the Component interface, which requires defining how the data is read from and written to NBT (Named Binary Tag) for saving to the disk.

2. Component Keys

Every component type is identified by a unique ComponentKey. This key acts as a registry entry and is used to retrieve specific data from an object. For example, a mod adding "Mana" would register a MANA key to access mana values on players.

3. Component Providers

Providers are vanilla Minecraft classes that have been modified by CCA to hold components. Through ASM (Abstract Syntax Tree) manipulation, CCA injects a ComponentContainer into these classes, allowing them to store any number of registered components without conflicting with other mods.

Cardinal Components API allows data attachment to almost every major object in the Minecraft world. Each type of provider has specific behaviors regarding persistence and synchronization.

Entity Components

Entity components are the most common use case. They allow mods to track data on players (like "Class" or "Experience") or mobs (like "Affixes" or "Scaling Difficulty"). These components are automatically saved when the entity is unloaded and reloaded.

Item Components

Components attached to ItemStack objects are unique because they follow the item as it moves through inventories, is dropped on the ground, or is placed in containers. CCA ensures that item equality checks (isEqualIgnoreDamage) correctly account for these custom components.

World & Level Components

World components are ideal for dimension-specific data, such as a "Corruption Level" in a specific biome or dimension. Level components (often replaced by Scoreboard components in newer versions) are used for truly global data that persists even if the player changes dimensions.

Beyond simple data storage, Cardinal Components API provides high-level utilities to automate common modding tasks.

Synchronization (S2C)

CCA simplifies the process of sending data from the server to the client. By implementing the AutoSyncedComponent interface, a component can automatically sync its data to players whenever it changes. This is essential for UI elements like mana bars or custom health displays that need to reflect real-time server data.

Ticking Components

If a component needs to update every game tick (e.g., regenerating mana over time), it can implement ServerTickingComponent or ClientTickingComponent. CCA will then automatically call the tick method on the component alongside the provider's own tick cycle, ensuring high performance without the need for global tick listeners.

Player Respawn Handling

When a player dies and respawns, Minecraft typically wipes their data. CCA provides a RespawnCopyStrategy to define how components should behave during this transition:

• ALWAYS_COPY: Data is always preserved (e.g., a player's Level or Quest progress).
• NEVER_COPY: Data is reset on death (e.g., a temporary combat buff).
• CHARACTER: Data is preserved only if the player is not starting a "new life" (used in hardcore or specific gameplay modes).

For developers using version 1.20.1, the implementation follows a standard pattern of registration and usage.

Component Interface Example

public interface ManaComponent extends Component {
 int getMana;
 void setMana(int value);
}

Registration

Components must be registered in the mod's entry point using the ComponentRegistryV3. This ensures that the API can generate the necessary ASM code to attach the component to the desired providers.

Usage

Once registered, components can be accessed directly from any provider:

// Retrieve mana from a player
ManaComponent mana = MANA_KEY.get(player);
mana.setMana(100);

This direct access is optimized by the API to be nearly instantaneous, making it suitable for high-frequency calls in rendering or physics logic.