mirror of
https://github.com/FabricMC/fabric.git
synced 2024-11-26 17:46:25 -05:00
f995ab4233
# Fabric API Lookup API v1
## Introduction
This module allows Api instances to be associated with game objects without specifying how the association is implemented. This is useful when the same Api could be implemented more than once or implemented in different ways.
Many thanks to @Grondag for providing the original concept (#1072).
Thanks also go to @i509VCB, @Pyrofab, @sfPlayer1 and the others who were involved with the design of this module.
This is the foundation upon which can be built for example a fluid transfer api (#1166). Closes #1199.
## Flexible Api Querying
## Block Api Usage example
## Building blocks
This PR was changed a lot, please have a look at the README, the package info, and the javadoc for `BlockApiLookup` and `ApiLookupMap` for up-to-date documentation.
## More usage examples
FastTransferLib (https://github.com/Technici4n/FastTransferLib) is an experiment to build an item, fluid and energy transfer api on top of this module. (Which was until recently called `fabric-provider-api-v1`.)
## Missing things?
~~I could add an overload of `BlockApiLookup#find` with nullable `BlockState` and `BlockEntity` parameters, so that the caller can directly provide them if they are available for some reason.~~ Added in later commits.
There is no module to retrieve apis from items or entities yet because there were unsolved issues with those. The community can use the provided building blocks to experiment with their own implementations of `ItemStackApiLookup` and `EntityApiLookup` until the way forward becomes clear, but let's please not delay the `BlockApiLookup` because of that.
Co-authored-by: i509VCB <git@i509.me>
Co-authored-by: PepperBell <44146161+PepperCode1@users.noreply.github.com>
(cherry picked from commit dc716ea167)
30 lines
2 KiB
Markdown
30 lines
2 KiB
Markdown
# Fabric API Lookup API (v1)
|
|
This module allows API instances to be associated with game objects without specifying how the association is implemented.
|
|
This is useful when the same API could be implemented more than once or implemented in different ways.
|
|
See also the [package-info.java file](src/main/java/net/fabricmc/fabric/api/lookup/v1/package-info.java).
|
|
|
|
* What we call an API is any object that can be offered or queried, possibly by different mods, to be used in an agreed-upon manner.
|
|
* This module allows flexible retrieving of such APIs from blocks in the world, represented by the generic type `A`.
|
|
* It also provides building blocks for defining custom ways of retrieving APIs from other game objects.
|
|
|
|
# Retrieving APIs from blocks
|
|
See the javadoc of `BlockApiLookup` for a full usage example.
|
|
|
|
## [`BlockApiLookup`](src/main/java/net/fabricmc/fabric/api/lookup/v1/block/BlockApiLookup.java)
|
|
The primary way of querying API instances for blocks in the world.
|
|
It exposes a `find` function to retrieve an API instance, and multiple `register*` functions to register Apis for blocks and block entities.
|
|
|
|
Instances can be obtained using the `get` function.
|
|
|
|
## [`BlockApiCache`](src/main/java/net/fabricmc/fabric/api/lookup/v1/block/BlockApiCache.java)
|
|
A `BlockApiLookup` bound to a position and a server world, allowing much faster repeated API queries.
|
|
|
|
# Retrieving APIs from custom objects
|
|
The subpackage `custom` provides helper classes to accelerate implementations of `ApiLookup`s for custom objects,
|
|
similar to the existing `BlockApiLookup`, but with different query parameters.
|
|
|
|
## [`ApiLookupMap`](src/main/java/net/fabricmc/fabric/api/lookup/v1/custom/ApiLookupMap.java)
|
|
A map meant to be used as the backing storage for custom `ApiLookup` instances, to implement a custom equivalent of `BlockApiLookup#get`.
|
|
|
|
## [`ApiProviderMap`](src/main/java/net/fabricmc/fabric/api/lookup/v1/custom/ApiProviderMap.java)
|
|
A fast thread-safe copy-on-write map meant to be used as the backing storage for registered providers.
|