Skip to content

Commit

Permalink
Update CCA migration instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
Pyrofab committed Apr 19, 2024
1 parent 89e48e0 commit f032c29
Show file tree
Hide file tree
Showing 13 changed files with 91 additions and 39 deletions.
2 changes: 1 addition & 1 deletion public/wiki/blabber/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -428,7 +428,7 @@ dependencies {


You can find the current version of Blabber in the [releases](https://github.com/Ladysnake/Blabber/releases) tab of the repository on Github,
and the latest CCA version in the [appropriate repository](https://github.com/OnyxStudios/Cardinal-Components-API/releases).
and the latest CCA version in the [appropriate repository](https://github.com/Ladysnake/Cardinal-Components-API/releases).

### API

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@ class RandomIntComponent implements IntComponent {

## Extensions

A `Component` implementation can also implement some extended interfaces to help with tasks such as [server-client synchronization](synchronization), [data transfers](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/CopyableComponent.java) or [ticking](ticking). More information on those interfaces is available in the javadoc and in the documentation for each module.
A `Component` implementation can also implement some extended interfaces to help with tasks such as [server-client synchronization](synchronization), [data transfers](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/CopyableComponent.java) or [ticking](ticking). More information on those interfaces is available in the javadoc and in the documentation for each module.

**[Next up: Registering and using a component](registration)**
2 changes: 1 addition & 1 deletion public/wiki/cardinal-components-api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Just download the version that works for you - Cardinal Components API does not

If you are a developer, **detailed information is available in the [developer wiki](landing)** *(check the sidebar)*.
The information below is a condensed form of the latter. You can also find a short description and associated examples
in the repository's [README](https://github.com/OnyxStudios/Cardinal-Components-API#readme).
in the repository's [README](https://github.com/Ladysnake/Cardinal-Components-API#readme).

## An example

Expand Down
2 changes: 1 addition & 1 deletion public/wiki/cardinal-components-api/landing.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ layout: default

Cardinal Components API is a Quilt and Fabric library that allows Minecraft mods to attach custom data to game objects in the form of components. Its goals are to offer an accessible API that is just as fast as direct mixins attachments, as well as to promote interoperability between mods using it.

For a short description and associated examples, see the repository's [README](https://github.com/OnyxStudios/Cardinal-Components-API#readme).
For a short description and associated examples, see the repository's [README](https://github.com/Ladysnake/Cardinal-Components-API#readme).

<div id="search-bar" hidden="">
<form class="search-form" action="/wiki/cardinal-components-api/search" method="get">
Expand Down
8 changes: 4 additions & 4 deletions public/wiki/cardinal-components-api/modules/block.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@ This module has two purposes, allowing mods to attach components to `BlockEntity
**Warning: BlockEntity components currently require their holder to call both `super.readNbt(nbt)` and `super.writeNbt(nbt)`.** (Modded) block entities that do not fulfill this criteria will not get their components properly saved.

### Registration
Entity components are registered by a [`BlockComponentInitializer`](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-block/src/main/java/dev/onyxstudios/cca/api/v3/block/BlockComponentInitializer.java), exposed as `cardinal-components-block` in the mod json (more information on the [component registration page](../registration#2-attaching-your-component)).
Entity components are registered by a [`BlockComponentInitializer`](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-block/src/main/java/org/ladysnake/cca/api/v3/block/BlockComponentInitializer.java), exposed as `cardinal-components-block` in the mod json (more information on the [component registration page](../registration#2-attaching-your-component)).

Component factories are registered per block entity class, thereby attaching components to all instances of that class and of its subclasses.
Registering a factory to both a class and its subclass will cause the latter factory to override the former, letting you eg. use a different implementation for trapped chests than for generic containers.

Instead of a specific class, you can also register a component factory with a `Predicate<Class<? extends BlockEntity>>`. This lets you use your own criteria like "implements a specific interface".

### Synchronization
BlockEntity components can be automatically synchronized by implementing [`AutoSyncedComponent`](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/sync/AutoSyncedComponent.java) - more information is available on [the component synchronization page](../synchronization).
BlockEntity components can be automatically synchronized by implementing [`AutoSyncedComponent`](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/sync/AutoSyncedComponent.java) - more information is available on [the component synchronization page](../synchronization).

### Ticking
BlockEntity components also support both [server](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/tick/ServerTickingComponent.java) and [client](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/tick/ClientTickingComponent.java) ticking. Components get ticked right after the block entity they are attached to, provided the latter gets ticked through `World#tickBlockEntities`. **This means that only block entities that implement `Tickable` are currently supported.**
BlockEntity components also support both [server](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/tick/ServerTickingComponent.java) and [client](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/tick/ClientTickingComponent.java) ticking. Components get ticked right after the block entity they are attached to, provided the latter gets ticked through `World#tickBlockEntities`. **This means that only block entities that implement `Tickable` are currently supported.**

### API Lookup integration

Expand Down Expand Up @@ -52,7 +52,7 @@ This component could be then used to expose the `FLUID_CONTAINER` API on any blo
```

## V1/V2 API (legacy)
Blocks implement the `BlockComponentProvider` interface instead of the regular `ComponentProvider`. Custom blocks may re-implement that interface themselves to provide components independently of the presence of a BlockEntity. Usually the block simply proxies its Block Entity, however the Block Entity does not need to implement `BlockComponentProvider` if the block already has a custom implementation. The module also includes [several utility classes](https://github.com/OnyxStudios/Cardinal-Components-API/tree/master/cardinal-components-block/src/main/java/nerdhub/cardinal/components/api/util/sided) to help with providing block components.
Blocks implement the `BlockComponentProvider` interface instead of the regular `ComponentProvider`. Custom blocks may re-implement that interface themselves to provide components independently of the presence of a BlockEntity. Usually the block simply proxies its Block Entity, however the Block Entity does not need to implement `BlockComponentProvider` if the block already has a custom implementation. The module also includes [several utility classes](https://github.com/Ladysnake/Cardinal-Components-API/tree/master/cardinal-components-block/src/main/java/nerdhub/cardinal/components/api/util/sided) to help with providing block components.

Components are entirely compatible with [LibBlockAttributes](https://github.com/AlexIIL/LibBlockAttributes)' attributes.
Since `Component` is an interface, any attribute instance can easily implement it. Conversely, making an `Attribute`
Expand Down
8 changes: 4 additions & 4 deletions public/wiki/cardinal-components-api/modules/chunk.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This module allows mods to attach components to Chunk objects. Chunk components

## Usage
### Registration
Chunk components are registered by a [`ChunkComponentInitializer`](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-chunk/src/main/java/dev/onyxstudios/cca/api/v3/chunk/ChunkComponentInitializer.java), exposed as `cardinal-components-chunk` in the mod json (more information on the [component registration page](../registration#2-attaching-your-component)). Once a component factory is registered, its associated component will be available on every `Chunk` instance, on both clients and servers.
Chunk components are registered by a [`ChunkComponentInitializer`](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-chunk/src/main/java/org/ladysnake/cca/api/v3/chunk/ChunkComponentInitializer.java), exposed as `cardinal-components-chunk` in the mod json (more information on the [component registration page](../registration#2-attaching-your-component)). Once a component factory is registered, its associated component will be available on every `Chunk` instance, on both clients and servers.

### Saving
As chunks only save when necessary, components must call the `Chunk#setShouldSave` method to ensure they get saved correctly after a change.
Expand All @@ -29,10 +29,10 @@ public class MyComponent implements Component {
```

### Synchronization
Chunk components can be automatically synchronized from the server to the client by implementing [`AutoSyncedComponent`](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/sync/AutoSyncedComponent.java) - more information is available on [the component synchronization page](../synchronization).
Chunk components can be automatically synchronized from the server to the client by implementing [`AutoSyncedComponent`](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/sync/AutoSyncedComponent.java) - more information is available on [the component synchronization page](../synchronization).

### Ticking
Chunk components support [server](https://github.com/OnyxStudios/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/dev/onyxstudios/cca/api/v3/component/tick/ServerTickingComponent.java) (not client) ticking. Components get ticked right after the chunk they are attached to.
Chunk components support [server](https://github.com/Ladysnake/Cardinal-Components-API/blob/master/cardinal-components-base/src/main/java/org/ladysnake/cca/api/v3/component/tick/ServerTickingComponent.java) (not client) ticking. Components get ticked right after the chunk they are attached to.

### `EmptyChunk` guarantees
Empty chunks never expose any components, no matter what was originally attached to them. As such, when chunk components are queried on the client, one should make sure the chunk is loaded, or use `ComponentType#maybeGet` to retrieve a component.
Expand All @@ -46,4 +46,4 @@ Instead of components attached to chunks, one can use a `PersistentState` storin
- Requires some boilerplate
- Only exists on ServerWorld - cannot be synchronized, requires casting to use, not available from other chunk views
```
To solve the latter 2 issues while keeping control over the data structure, one can also replace the `PersistentState` with a [`World` component](https://github.com/OnyxStudios/Cardinal-Components-API/wiki/Cardinal-Components-World).
To solve the latter 2 issues while keeping control over the data structure, one can also replace the `PersistentState` with a [`World` component](https://github.com/Ladysnake/Cardinal-Components-API/wiki/Cardinal-Components-World).
Loading

0 comments on commit f032c29

Please sign in to comment.