Cardinal Components API

https://ladysnake.org/wiki/cardinal-components-api
Admin
Cardinal Components API is a Minecraft modding library developed by Ladysnake, providing an API for...
Tokens:12,596
Snippets:153
Trust Score:7.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Barebones Integer Component Example

Source: https://ladysnake.org/wiki/cardinal-components-api/implementing-component

Demonstrates a simple component that stores an integer, provides methods to get and increment its value, and handles NBT serialization. This component needs to be registered separately.

```java
// Your own component interface. You still need to register it!
public interface IntComponent extends Component {
    int getValue();
    void increment();
}

class RandomIntComponent implements IntComponent {
    private int value = (int) (Math.random() * 50); // random initial value because why not
    @Override public int getValue() { return this.value; }
    @Override public void increment() { this.value++; }
    @Override public void readFromNbt(NbtCompound tag) { this.value = tag.getInt("value"); }
    @Override public void writeToNbt(NbtCompound tag) { tag.putInt("value", this.value); }
}
```

--------------------------------

### Mod Metadata Entrypoint (Generic)

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Register component initializers in the mod's metadata file. This example uses a generic schema with a 'custom' field for components.

```json
{
    "schemaVersion": 1,
    "id": "mymod",

    "entrypoints": {
        "cardinal-components": [
            "a.b.c.MyComponents"
        ]
    },

    "custom": {
        "cardinal-components": [
            "mymod:magik"
        ]
    }
}
```

--------------------------------

### Mod Metadata Entrypoint (Quilt Loader)

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Register component initializers in the mod's metadata file under the 'quilt-loader' entrypoints. This example uses the Quilt Loader schema.

```json
{
    "schema_version": 1,

    "quilt-loader": {
        "id": "mymod",
        "entrypoints": {
            "cardinal-components": "a.b.c.MyComponents"
        },
    },

    "cardinal-components": [
        "mymod:magik"
    ]
}
```

--------------------------------

### Item Component Initialization Example

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Demonstrates correct and incorrect ways to initialize item stack components. Avoid random or volatile data in the constructor to prevent desynchronization. Initialization logic can be placed in an `init()` method called after construction.

```java
public MyItemStackComponent(ItemStack stack) {
    // Bad:
    this.bad0 = Math.random(); // DO NOT DO THIS, DESYNC WILL HAPPEN
    this.bad1 = stack.getCount(); // ALSO BAD, the stack's count may change before the component gets initialized on the server
    // Good:
    this.x = 3;  // Constant value
    this.y = Registry.ITEM.getId(stack.getItem); // cannot change
}

public void init() {
    this.r = Math.random(); // This is fine as long as init() is called outside of the constructor
}
```

--------------------------------

### Player Component with Client-to-Server Messaging

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/entity

Example of a player component implementing C2SSelfMessagingComponent for client-to-server communication. It demonstrates sending a power choice from the client and validating it on the server.

```java
public class MyPlayerComponent implements C2SSelfMessagingComponent, AutoSyncedComponent, ServerTickingComponent {
    private final PlayerEntity player;
    private List<String> powers; // String for the demo but this should store actual objects
    private int cooldown;
    
    public MyPlayerComponent(PlayerEntity player) {
        this.player = player;
        this.powers = List.of("fire", "water", "air", "earth");
        this.cooldown = 0;
    }

    /** Method to call clientside when a player uses a keybind or clicks in a GUI */
    public void usePower(int chosenPower) {
        sendC2SMessage(buf -> buf.writeVarInt(chosenPower));
    }

    @Override
    public void handleC2SMessage(RegistryByteBuf buf) {
        int chosenPower = buf.readVarInt();

        // ALWAYS MAKE SURE TO VALIDATE THE CLIENT'S INPUT IN THIS METHOD
        // regardless of your clientside checks, a malicious or buggy client can always send a bad packet

        // Obligatory check to avoid crashing the server
        if (chosenPower < 0 || chosenPower >= this.powers.size()) return;
        // Arbitrary check, let's assume our powers have a cooldown to avoid spamming them
        if (this.cooldown > 0) return;
        // Arbitrary check, let's assume players can't use fire in water
        if ("fire".equals(this.powers.get(chosenPower)) && this.player.isTouchingWater()) return;

        player.sendMessage("Used power " + powers.get(chosenPower));
        cooldown = 40;
    }

    // serialization and ticking methods elided for brevity
}

```

--------------------------------

### Global Trophy Component Example

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/scoreboard

An example of a global component that tracks player trophies, demonstrating how to store and retrieve player-specific data associated with the scoreboard. It includes synchronization logic.

```java
public class TrophyComponent implements AutoSyncedComponent {
    private final Map<UUID, TrophyCollection> data = new HashMap<>();
    private final Scoreboard provider;

    public TrophyComponent(Scoreboard provider, @Nullable MinecraftServer server) {
        this.provider = provider;
    }

    public void addTrophy(PlayerEntity player, Trophy trophy) {
        this.data.computeIfAbsent(playerId, i -> new TrophyCollection()).grant(trophy);
        KEY.sync(this.provider);
    }

    public List<Trophy> listTrophies(PlayerEntity player) {
        return this.listTrophies(player.getUuid());
    }

    public List<Trophy> listTrophies(UUID playerId) {
        TrophyCollection trophies = this.data.get(playerId);
        return trophies == null ? List.of() : trophies.toList();
    }
    
    // Sync implementation: only sync the players' own data
    // (in most cases that's what you want, but you could also sync the entirety of the map)
    
    @Override
    public boolean shouldSyncWith(ServerPlayerEntity player) {
        return data.containsKey(player.getUuid());
    }
    
    @Override
    public void writeSyncPacket(RegistryByteBuf buf, ServerPlayerEntity recipient) {
        buf.writeMap(
                Map.of(recipient.getUuid(), data.get(recipient.getUuid())),
                PacketByteBuf::writeUuid,
                TrophyCollection::writeToPacket
        );
    }
    
    @Override public void applySyncPacket(RegistryByteBuf buf) { /* ... */ }
}
```

--------------------------------

### Accessing Components from a Provider

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Retrieve component data using ComponentKey#get, ComponentKey#maybeGet, or ComponentKey#getNullable. Handles cases where the component might not be present.

```java
public static final ComponentKey<IntComponent> MAGIK = ...; // See the "Registering your component" section

public static void useMagik(Entity provider) { // anything will work, as long as a module allows it!
    // Retrieve a provided component
    int magik = MAGIK.get(provider).getValue();
    // Or, if the object is not guaranteed to provide that component:
    int magik = MAGIK.maybeGet(provider).map(IntComponent::getValue).orElse(0);
    // ...
}
```

--------------------------------

### Define a Compound Component for Fluid Containers

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/block

This Java code defines a compound component interface `FluidContainerCompound` that can be attached to any BlockEntity. It includes a component key for registration and a method to get a `FluidContainer` for a specific direction.

```java
public interface FluidContainerCompound extends Component {
      ComponentKey<FluidContainerCompound> KEY = ComponentRegistry.register(Identifier.of("mymod:fluid_container_compound"), FluidContainerCompound.class);

      FluidContainer get(Direction side);
 }
```

--------------------------------

### Implement and Use a Basic Integer Component

Source: https://ladysnake.org/wiki/cardinal-components-api

Demonstrates how to implement a simple integer component with NBT read/write functionality. This serves as a foundation for creating custom data components.

```java
public interface IntComponent extends Component {
    int getValue();
}

class RandomIntComponent implements IntComponent {
    private int value = (int) (Math.random() * 20);
    @Override public int getValue() { return this.value; }
    @Override public void readFromNbt(CompoundTag tag) { this.value = tag.getInt("value"); }
    @Override public void writeToNbt(CompoundTag tag) { tag.putInt("value", this.value); }
}

```

--------------------------------

### Registering Entity Components with Respawn Strategies

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/entity

Demonstrates how to register various entity components with different respawn copy strategies using EntityComponentFactoryRegistry. This includes registering components for specific entity types, players, and based on class assignability, along with setting custom respawn behaviors.

```java
public final class MyComponents implements EntityComponentInitializer {
    @Override
    public void registerEntityComponentFactories(EntityComponentFactoryRegistry registry) {
        // Scenario 1:
        // Add the component to every ZombieEntity instance, including husks and zombie villagers
        registry.registerFor(ZombieEntity.class, INFECTION, ZombieInfection::new);

        // Scenario 2:
        // Add the component to every instance of PlayerEntity, and ensure the component's data is always copied
        registry.registerForPlayers(MAGIK, player -> new RandomIntComponent(), RespawnCopyStrategy.ALWAYS_COPY);

        // Scenario 3:
        // Add the component to every living entity
        registry.registerFor(LivingEntity.class, BLUE, e -> new RandomIntComponent());
        // Ensure the component's data is copied when keepInventory is enabled (Optional)
        registry.setRespawnCopyStrategy(BLUE, RespawnCopyStrategy.INVENTORY);

        // Scenario 4:
        // Add the component to every entity with an inventory
        registry.registerFor(Inventory.class::isAssignableFrom, RED, e -> new RandomIntComponent());
        // Add a specialized component to every instance of PlayerEntity without specifying a strategy
        // The attached component can implement PlayerComponent to customize respawn copying
        registry.registerForPlayers(RED, PlayerIntComponent::new);
    }
}
```

--------------------------------

### Module-Specific Entrypoints

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Use module-specific entrypoints for registration, such as 'cardinal-components-entity' or 'cardinal-components-world'. This allows for method references as registration entrypoints.

```json
    "entrypoints": {
        "cardinal-components-entity": "a.b.c.MyComponents",
        "cardinal-components-world": "a.b.c.MyComponents::registerWorldComponents"
    },

```

--------------------------------

### Dynamic Component Registration with Entrypoints

Source: https://ladysnake.org/wiki/cardinal-components-api/advanced/custom-component-providers

Dynamically register components for a custom provider by iterating over entrypoints defined in FabricLoader.getInstance().

```java
    private static final ComponentContainer.Factory<MyCustomProvider> CONTAINER_FACTORY;

    static {
        ComponentContainer.Factory.Builder<MyCustomProvider> builder = ComponentContainer.Factory.builder(MyCustomProvider.class);
        for (CustomProviderComponentInitializer entrypoint : FabricLoader.getInstance().getEntrypoints("mymod:custom-provider-components", CustomProviderComponentInitializer.class)) {
            entrypoint.registerComponents(builder);
        }
        CONTAINER_FACTORY = builder.build();
    }

    public interface CustomProviderComponentInitializer {
        void registerComponents(ComponentContainer.Factory.Builder<MyCustomProvider> builder);
    }
```

--------------------------------

### Making a Component Client-Optional

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

Override `isRequiredOnClient` to return false to prevent players without your mod from being disconnected. This is useful for components that are not essential for gameplay.

```java
public class MyClientOptionalComponent implements AutoSyncedComponent {
    @Override
    public boolean isRequiredOnClient() {
        return false;
    }

    // ...
}
```

--------------------------------

### Version Catalog for CCA Dependencies

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Define versions and libraries for Cardinal Components API in your libs.versions.toml file for centralized management.

```toml
[versions]
cca = '8.0.0'

[libraries]
cca-base = { module = "org.ladysnake.cardinal-components-api:cardinal-components-base", version.ref = "cca" }
cca-<MODULE> = { module = "org.ladysnake.cardinal-components-api:cardinal-components-<MODULE>", version.ref = "cca" }

[bundles]
cca = [ "cca-base", "cca-<MODULE>" ]

```

--------------------------------

### Item Stack Component Initialization Best Practices

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Illustrates correct and incorrect methods for initializing item stack components to prevent client-server desynchronization. Lazy initialization must use constant values.

```java
private void tryInit() { // Lazy init method
    // Bad:
    this.putDouble("bad0", Math.random()); // DO NOT DO THIS, DESYNC WILL HAPPEN
    this.putInt(stack.getCount()); // ALSO BAD, the stack's count may change before the component gets initialized on the server
    // Good:
    this.putInt("x", 3);  // Constant value
    this.putString("y", Registry.ITEM.getId(stack.getItem).toString()); // cannot change
}

public void init() { // explicit init method
    this.putDouble("r", Math.random()); // This is fine as long as init() is called only on the server
}
```

--------------------------------

### Registering Component Factories

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Implement XComponentInitializer to register component factories. Use constructor references or lambda expressions for initialization.

```java
public final class MyComponents implements XComponentInitializer[, YComponentInitializer...] {
    public static final ComponentKey<IntComponent> MAGIK = ...;

    @Override
    public void registerXComponentFactories(XComponentFactoryRegistry registry) {
        registry.register(MAGIK, XIntComponent::new);
    }
}
```

--------------------------------

### Barebones Custom Component Provider Implementation

Source: https://ladysnake.org/wiki/cardinal-components-api/advanced/custom-component-providers

Implement a basic custom component provider by extending ComponentProvider and defining components using ComponentContainer.Factory.builder.

```java
public class MyCustomProvider implements ComponentProvider {
    private static final ComponentContainer.Factory<MyCustomProvider> CONTAINER_FACTORY =
        ComponentContainer.Factory.builder(MyCustomProvider.class)
            .component(MyComponents.KEY1, MyComponent1::new)
            .component(MyComponents.KEY2, MyComponent2::new)
            .build();

    private final ComponentContainer components = CONTAINER_FACTORY.createContainer(this);

    @Override
    public ComponentContainer getComponentContainer() {
        return this.components;
    }
}
```

--------------------------------

### Add Jitpack Maven Repository

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Configure your build script to use Jitpack as a maven repository. This allows fetching versions directly from GitHub repositories. Note that Jitpack builds can sometimes be slow or time out on the first attempt.

```gradle
repositories {
    maven {
        name = "Jitpack"
        url = "https://jitpack.io"
    }
}

```

--------------------------------

### Gradle Buildscript Dependencies using Version Catalog (Groovy/Kotlin)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Configure your build script to use the defined bundles from libs.versions.toml for Cardinal Components API.

```groovy
repositories {
    maven {
        name = "Ladysnake Mods"
        url = "https://maven.ladysnake.org/releases"
    }
}

dependencies {
    // Replace modImplementation with modApi if you expose components in your own API
    modImplementation(libs.bundles.cca)
    // Copy the following only if you want to bundle Cardinal Components API as a Jar-in-Jar dependency
    // (otherwise, you should configure the dependency on Modrinth/Curseforge)
    include(libs.bundles.cca)
}

```

--------------------------------

### Lazy Data Initialization for Item Component

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Demonstrates lazy initialization of component data, ensuring that default values are set only when the component is first accessed, optimizing memory usage.

```Java
    @Override
    public int getValue() {
        if (!this.hasTag("value", NbtType.INT)) this.putInt("value", 10);
        return this.getInt("value");
    }

    @Override
    public void increment() {
        this.putInt("value", this.getValue() + 1); // performs initialization through getValue()
    }
```

--------------------------------

### Expose Fluid Container API on Blocks

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/block

This Java code demonstrates how to use `BlockComponents#exposeApi` to expose the `FLUID_CONTAINER` API on any block. This is typically done within the `onInitialize` method of a mod.

```java
@Override
 public void onInitialize() {
     BlockComponents.exposeApi(
         FluidContainerCompound.KEY,
         MyApi.FLUID_CONTAINER,
         FluidContainerCompound::get
     );
 }
```

--------------------------------

### Add OnyxStudios Maven Repository (Historical)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

This former official maven repository contained versions up to 2.3.0. It is no longer available.

```gradle
repositories {
    maven {
        name = "OnyxStudios"
        url = "https://maven.abusedmaster.xyz"
    }
}

```

--------------------------------

### Gradle Buildscript Dependencies (Kotlin DSL)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Configure your build.gradle.kts file to include Cardinal Components API. Use `modImplementation` for direct dependency and `include` for Jar-in-Jar.

```kotlin
repositories {
    maven {
        name = "Ladysnake Mods"
        url = "https://maven.ladysnake.org/releases"
    }
}

dependencies {
    val ccaVersion = property("cca_version") as String
    // Replace modImplementation with modApi if you expose components in your own API
    modImplementation("org.ladysnake.cardinal-components-api:cardinal-components-base:$ccaVersion")
    modImplementation("org.ladysnake.cardinal-components-api:cardinal-components-<MODULE>:$ccaVersion")
    // Copy the following only if you want to bundle Cardinal Components API as a Jar-in-Jar dependency
    // (otherwise, you should configure the dependency on Modrinth/Curseforge)
    include("org.ladysnake.cardinal-components-api:cardinal-components-base:$ccaVersion")
    include("org.ladysnake.cardinal-components-api:cardinal-components-<MODULE>:$ccaVersion")
}

```

--------------------------------

### Gradle Buildscript Dependencies (Groovy)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Configure your build.gradle file to include Cardinal Components API. Use `modImplementation` for direct dependency and `include` for Jar-in-Jar.

```groovy
repositories {
    maven {
        name = "Ladysnake Mods"
        url = 'https://maven.ladysnake.org/releases'
    }
}

dependencies {
    // Replace modImplementation with modApi if you expose components in your own API
    modImplementation "org.ladysnake.cardinal-components-api:cardinal-components-base:${project.cca_version}"
    modImplementation "org.ladysnake.cardinal-components-api:cardinal-components-<MODULE>:${project.cca_version}"
    // Copy the following only if you want to bundle Cardinal Components API as a Jar-in-Jar dependency
    // (otherwise, you should configure the dependency on Modrinth/Curseforge)
    include "org.ladysnake.cardinal-components-api:cardinal-components-base:${project.cca_version}"
    include "org.ladysnake.cardinal-components-api:cardinal-components-<MODULE>:${project.cca_version}"
}

```

--------------------------------

### Add Ladysnake Bintray Maven Repository (Historical)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

This historical maven repository contained binaries for versions between 2.3.5 (MC 1.15) and 2.7.11 (MC 1.16). It is now unavailable due to Bintray shutting down.

```gradle
repositories {
    maven {
        name = "Ladysnake Libs"
        url = 'https://dl.bintray.com/ladysnake/libs'
    }
}

```

--------------------------------

### Registering Old and New Component IDs (Java)

Source: https://ladysnake.org/wiki/cardinal-components-api/migrating-components

When changing a component's ID, register both the old and new component keys, specifying that the new component registration should occur after the old one. This ensures deterministic data loading.

```java
@Override
    public void registerEntityComponentFactories(EntityComponentFactoryRegistry registry) {
        registry.registerFor(entityClass, OLD_INT_COMPONENT_KEY, OldIntComponent::new);
        registry.beginRegistration(entityClass, NEW_INT_COMPONENT_KEY).after(OLD_INT_COMPONENT_KEY).end(IntComponent::new);
    }
```

--------------------------------

### Register Scoreboard and Team Components

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/scoreboard

Register custom components for scoreboards and teams using a ScoreboardComponentInitializer. This allows the component to be available on all relevant instances.

```java
public final class MyComponents implements ScoreboardComponentInitializer {
    @Override
    public void registerScoreboardComponentFactories(ScoreboardComponentFactoryRegistry registry) {
        // Global data component
        registry.registerScoreboardComponent(TrophyComponent.KEY, TrophyComponent::new);
        // Team-specific component, useful for minigames
        registry.registerTeamComponent(TrophyComponent.KEY, (scoreboard, team, server) -> new TeamTrophyComponent(team));
    }
}
```

--------------------------------

### Implement ItemIntComponent

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Re-implements the IntComponent interface as an ItemComponent, demonstrating how to store and retrieve integer values within an item's NBT.

```Java
public class ItemIntComponent extends ItemComponent implements IntComponent {
    @Override public int getValue() { return this.getInt("value"); }
    @Override public void increment() { this.putInt("value", this.getValue() + 1); }
}
```

--------------------------------

### Implement AutoSyncedComponent

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

Implement the AutoSyncedComponent interface to enable automatic synchronization of component data. This is the first step for any component that needs to be synchronized.

```java
public class SyncedIntComponent implements IntComponent, AutoSyncedComponent {
    private int value;

    // getters, setters, and serialization methods omitted for brevity
}
```

--------------------------------

### Implementing AutoSyncedComponent Synchronization

Source: https://ladysnake.org/wiki/cardinal-components-api/advanced/custom-component-providers

Implement synchronization for AutoSyncedComponent by providing recipients and packet data. This includes a temporary kludge for packet writer support.

```java
    @Override
    public Iterator<ServerPlayerEntity> getRecipientsForComponentSync() {
        // TODO return an iterator over the list of players watching this provider, eg. world.getPlayers().iterator()
    }

    @Nullable
    @Override
    public <C extends AutoSyncedComponent> CustomPayloadS2CPacket toComponentPacket(PacketByteBuf buf, ComponentKey<? super C> key, ComponentPacketWriter writer, ServerPlayerEntity recipient) {
        // TODO write here the information needed to uniquely identify this provider on the client
        buf.writeInt(myId);
        // Write the component data
        buf.writeIdentifier(key.getId());
        writer.writeSyncPacket(buf, recipient);
        // Finally, construct the packet with your own channel ID
        return new CustomPayloadS2CPacket(MY_PACKET_ID, buf);
    }

    @Override
    public boolean supportsCustomComponentPacketWriters() {
        return true;  // temporary required kludge, will be gone in 1.17
    }
```

--------------------------------

### Batch Sync for Frequent Updates

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

For components updated multiple times per tick, batch synchronization calls using ComponentKey#sync after all updates are complete to avoid excessive network traffic.

```java
FluidComponent component = BikeshedComponents.FLUID.get(provider);
component.setPressure(5);
component.drain(dest, 2);
component.setPressure(0);
BikeshedComponents.FLUID.sync(provider);
```

--------------------------------

### Customizing Sync Packet for SyncedIntComponent

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

This snippet demonstrates how to pass a custom packet writer to the sync method to selectively sync data and trigger client-side effects. Use this when you need more control over the synchronization payload than a full sync provides.

```java
public class SyncedIntComponent implements IntComponent, AutoSyncedComponent {
    public static final int INCREASE_VALUE = 1;
    private int value;

    @Override // overrides a hypothetical method in IntComponent
    public void increment() {
        this.value++;
        // Pass a custom packet writer to sync
        MyComponents.MAGIK.sync(this.provider, (buf, p) -> writeSyncPacket(buf, player, true));
    }

    @Override
    public void writeSyncPacket(PacketByteBuf buf, ServerPlayerEntity player) {
        this.writeSyncPacket(buf, player, false);
    }

    private void writeSyncPacket(PacketByteBuf buf, ServerPlayerEntity player, boolean increaseValue) {
        buf.writeVarInt(this.value);
        // Write different information to the packet based on the extra parameters
        buf.writeBoolean(increaseValue);
    }

    @Override
    public void applySyncPacket(PacketByteBuf buf) {
        this.value = buf.readVarInt();

        // Only play particle effects if the synchronization was triggered by increment()
        if (buf.readBoolean()) {
            MinecraftClient.getInstance().particleManager.addEmitter(entity, ParticleTypes.TOTEM_OF_UNDYING, 20);
        }
    }
}
```

--------------------------------

### Ladysnake Maven Repository Configuration

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Add the Ladysnake maven repository to your Gradle build scripts to access Cardinal Components API releases.

```groovy
repositories {
    maven {
        name = "Ladysnake Mods"
        url = 'https://maven.ladysnake.org/releases'
    }
}

```

--------------------------------

### Optimize Sync Packet Data

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

Override writeSyncPacket and applySyncPacket to selectively synchronize only the necessary data, reducing packet size and network load.

```java
@Override
public void writeSyncPacket(PacketByteBuf buf, ServerPlayerEntity player) {
    buf.writeVarInt(this.value); // only synchronize the information you need!
}
```

```java
@Override
public void applySyncPacket(PacketByteBuf buf) {
    this.value = buf.readVarInt();
}
```

--------------------------------

### Sync Component on Value Update

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

Call ComponentKey#sync within the method that updates the component's value to notify tracked players. This is suitable for components updated atomically.

```java
private final Object provider;

public IntComponent(Object provider) {
    this.provider = provider;
}

public void setValue(int value) {
    this.value = value;
    MyComponents.MAGIK.sync(this.provider); // assuming MAGIK is the right key for this component
}
```

--------------------------------

### Gradle Properties for CCA Version

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

Define the version of Cardinal Components API to be used in your project.

```properties
cca_version = 8.0.0

```

--------------------------------

### Marking Chunk Components for Saving

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/chunk

Components must call `Chunk#setShouldSave(true)` in their setter methods to ensure they are saved correctly after a change.

```java
public class MyComponent implements Component {
    private final Chunk chunk;
    private Thing thingy;

    public void setThingy(Thing thingy) {
        this.thingy = thingy;
        this.chunk.setShouldSave(true);
    }
}
```

--------------------------------

### Client-Side Packet Listener for Component Synchronization

Source: https://ladysnake.org/wiki/cardinal-components-api/advanced/custom-component-providers

Register a client-side packet listener to receive and apply synchronization packets for AutoSyncedComponents. Ensure proper handling of packet data and task queuing.

```java
            ClientSidePacketRegistry.INSTANCE.register(PACKET_ID, (context, buffer) -> {
                try {
                    // TODO read here the information you wrote in toComponentPacket
                    int myId = buffer.readInt();
                    Identifier componentKeyId = buffer.readIdentifier();
                    ComponentKey<?> componentKey = ComponentRegistry.get(componentKeyId);
                    if (componentKey == null) {
                        return;
                    }
                    PacketByteBuf copy = new PacketByteBuf(buffer.copy());
                    context.getTaskQueue().execute(() -> {
                        try {
                            componentKey.maybeGet(/* TODO get your clientside provider here */)
                                .ifPresent(c -> {
                                    if (c instanceof AutoSyncedComponent) {
                                        ((AutoSyncedComponent) c).applySyncPacket(copy);
                                    }
                                });
                        } finally {
                            copy.release();
                        }
                    });
                } catch (Exception e) {
                    LOGGER.error("Error while reading components from network", e);
                    throw e;
                }
            });
```

--------------------------------

### Create and Retrieve ComponentKey

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Retrieve a ComponentKey for your custom component using its identifier and class. The class should be the superclass or superinterface of all implementations.

```java
// retrieving a type for my component or for a required dependency's
public static final ComponentKey<IntComponent> MAGIK = 
        ComponentRegistry.getOrCreate(Identifier.of("mymod", "magik"), IntComponent.class);
```

--------------------------------

### Component Interface Definition

Source: https://ladysnake.org/wiki/cardinal-components-api/implementing-component

The core Component interface requires methods for reading from and writing to NbtCompound tags, essential for data persistence.

```java
public interface Component {
    void readFromNbt(NbtCompound tag);
    void writeToNbt(NbtCompound tag);
}
```

--------------------------------

### Add Ladysnake Artifactory Maven Repository (Historical)

Source: https://ladysnake.org/wiki/cardinal-components-api/dev-install

This historical maven repository was used for versions between 3.0.0-21w06a and 5.2.1. It is no longer available due to JFrog Artifactory's free tier shutdown.

```gradle
repositories {
    maven {
        name = "Ladysnake Mods"
        url = 'https://ladysnake.jfrog.io/artifactory/mods'
    }
}

```

--------------------------------

### Item Component with Live Mutable Color Data

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Demonstrates an item component that associates identifiers with mutable color objects, managing their state through NBT. Lazy initialization is used for the color map.

```java
public class ItemColorComponent {
    private @Nullable Map<Identifier, MutableColor> colors;

    public MutableColor getColor(Identifier identifier) {
        if (this.colors == null) { // Lazy initialization
            this.colors = new HashMap<>();

            // Load existing data from the stack's NBT
            CompoundTag colorsNbt = this.getCompound("colors");
            for (String id : colorsNbt.getKeys()) {
                if (colorsNbt.contains(id, NbtType.COMPOUND)) {
                    this.colors.put(Identifier.tryParse(id), new MutableColor(colorsNbt.getCompound(id)));
                } else {
                    colorsNbt.remove(id); // clear corrupted data
                    this.putCompound("colors", colorsNbt); // will clean up the stack's NBT if empty
                }
            }
        }
        if (this.colors.containsKey(identifier)) {
            // Return existing color
            return this.colors.get(identifier);
        }
        if (!this.colors.containsKey(identifier)) {
            // Create a new color and bind it to the stack's NBT
            CompoundTag tag = this.getCompound("colors");
            MutableColor color = new MutableColor(new CompoundTag());
            this.colors.put(identifier, color.tag);
            tag.put(identifier.toString(), color.tag);
            this.putCompound("colors", tag); // the tag returned by getCompound may just have been created
            return color;
        }
    }

    public void removeColor(Identifier identifier) {
        if (this.colors != null && this.colors.remove(identifier) != null) {
            CompoundTag tag = this.getCompound("colors");
            tag.remove(identifier.toString());
            this.putCompound("colors", tag); // will clean up the stack's NBT if tag is empty
        }
    }

    @Override
    public onTagInvalidated() {
       super.onTagInvalidated(); // Must call super!
       this.colors = null;
    }

    public static class MutableColor {
        private final CompoundTag tag;
        private byte red, green, blue;

        Color(CompoundTag tag) {
            this.tag = tag;
            this.red = tag.getByte("red");
            this.green = tag.getByte("green");
            this.blue = tag.getByte("blue");
        }

        public int getRed() {
            return this.red;
        }

        public void setRed(int red) {
            this.red = red;
            this.tag.putByte("red", red);
        }
        // etc.
    }
}
```

--------------------------------

### Temporary Component for ID Change (Java)

Source: https://ladysnake.org/wiki/cardinal-components-api/migrating-components

Use this pattern to register a temporary component that reads old data and transfers it to the new component when changing a component's ID. This ensures data is preserved across saves.

```java
public class OldIntComponent implements Component {
    private final Object owner;

    public OldIntComponent(Object owner) {
        this.owner = owner;
    }

    @Override
    default void readFromNbt(NbtCompound tag) {
        NEW_INT_COMPONENT_KEY.get(this.owner).readFromNbt(tag); // makes the new component read the old data if it exists
    }

    @Override
    default void writeToNbt(NbtCompound tag) {
        // Nothing to write, the new component should write its own data
    }
}
```

--------------------------------

### Register Item Component Factory

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Registers an ItemIntComponent factory for specific item types or using a predicate. This allows components to be attached to item stacks based on defined criteria.

```Java
    @Override
    public void registerItemComponentFactories(ItemComponentFactoryRegistry registry) {
        // Attach an ItemIntComponent to all armor items
        registry.register(item -> item instanceof ArmorItem, MAGIK, ItemIntComponent::new);
        // Attach an ItemIntComponent to leather chestplates specifically
        registry.register(Items.LEATHER_CHESTPLATE, MAGIK, ItemIntComponent::new);
    }
```

--------------------------------

### Register Ticking Component

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

When registering a component that implements TickingComponent, use a dedicated registration method on the factory to ensure it is ticked.

```java
factory.beginRegistration(TargetClass.class, MyNonTickingComponent.KEY).impl(MyTickingImpl.class).end(MyTickingImpl::new);
```

```java
factory.register(MyNonTickingComponent.KEY, MyTickingImpl.class, MyTickingImpl::new);
```

--------------------------------

### Declare Component ID in quilt.mod.json

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Declare your component's identifier in your mod's metadata file. This is required for static component registration.

```json
{
    "schema_version": 1,
    "quilt_loader": {
        "id": "mymod"
    },
    "cardinal-components": [
        "mymod:magik"
    ]
}
```

--------------------------------

### Retrieve an Existing ComponentKey

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Retrieve a ComponentKey registered by another mod using its identifier. Returns null if the component is not registered. No metadata declaration is needed for this.

```java
// retrieving a component type registered by an optional dependency
public static final Lazy<@Nullable ComponentKey<?>> BLUE = 
        new Lazy<>(() -> ComponentRegistry.get(Identifier.of("theirmod:blue")));
```

--------------------------------

### Control Sync Recipient

Source: https://ladysnake.org/wiki/cardinal-components-api/synchronization

Override the shouldSyncWith method to specify which players should receive synchronization packets for a component, preventing unnecessary data transfer and potential exploits.

```java
@Override
public boolean shouldSyncWith(ServerPlayerEntity player) {
    return player == this.provider; // only sync with the provider itself
}
```

--------------------------------

### Item Component Caching and Invalidation

Source: https://ladysnake.org/wiki/cardinal-components-api/modules/item

Implements caching for item component data to optimize read operations. The cache is invalidated in the onTagInvalidated method to ensure data consistency.

```Java
    private static final int DEFAULT_VALUE = 10;

    private boolean initialized;
    private int cachedValue;

    @Override
    public int getValue() {
        if (!this.initialized) {
             if (!this.hasKey("value", NbtType.INT)) this.putInt("value", DEFAULT_VALUE);
             this.cachedValue = this.getInt("value");
             this.initialized = true;
        }
        return this.cachedValue;
    }

    @Override
    public void increment() {
        this.putInt("value", this.getValue() + 1); // performs initialization through getValue()
    }

    @Override
    public onTagInvalidated() {
       super.onTagInvalidated(); // Must call super!
       this.initialized = false;
    }
```

--------------------------------

### Declare Component ID in fabric.mod.json

Source: https://ladysnake.org/wiki/cardinal-components-api/registration

Declare your component's identifier in your mod's custom properties. This is required for static component registration.

```json
{
    "schemaVersion": 1,
    "id": "mymod",

    "custom": {
        "cardinal-components": [
            "mymod:magik"
        ]
    }
}
```
Tokens:
Raw