FabricMC/fabric
1
0
Fork 1
mirror of https://github.com/FabricMC/fabric.git synced 2024-11-23 16:18:29 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
fabric/fabric-api-lookup-api-v1/README.md

45 lines
2.7 KiB
Markdown
Raw Permalink Normal View History

Fabric API Lookup (#1234) # 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 dc716ea1674642c756cb030eed411f0f4919e0e8)
2021-03-08 15:32:36 -05:00
# 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.
Add ItemApiLookup (#1352) * Initial version of Item API API * Use an ItemStack parameter instead of an Item parameter for API queries * Add ItemStack modification note * Kindly ask providers not to modify the stack * Expose the API and context types * Bump version to 1.2.0
2021-06-20 10:45:46 -04:00
* This module allows flexible retrieving of such APIs, represented by the generic type `A`, from blocks in the world or from item stacks.
Fabric API Lookup (#1234) # 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 dc716ea1674642c756cb030eed411f0f4919e0e8)
2021-03-08 15:32:36 -05:00
* 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.
Add ItemApiLookup (#1352) * Initial version of Item API API * Use an ItemStack parameter instead of an Item parameter for API queries * Add ItemStack modification note * Kindly ask providers not to modify the stack * Expose the API and context types * Bump version to 1.2.0
2021-06-20 10:45:46 -04:00
It exposes a `find` function to retrieve an API instance, and multiple `register*` functions to register APIs for blocks and block entities.
Fabric API Lookup (#1234) # 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 dc716ea1674642c756cb030eed411f0f4919e0e8)
2021-03-08 15:32:36 -05:00
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.
Add ItemApiLookup (#1352) * Initial version of Item API API * Use an ItemStack parameter instead of an Item parameter for API queries * Add ItemStack modification note * Kindly ask providers not to modify the stack * Expose the API and context types * Bump version to 1.2.0
2021-06-20 10:45:46 -04:00
# Retrieving APIs from items
See the javadoc of `ItemApiLookup` for a full usage example.
## [`ItemApiLookup`](src/main/java/net/fabricmc/fabric/api/lookup/v1/item/ItemApiLookup.java)
The way to query API instances from item stacks.
It exposes a `find` function to retrieve an API instance, and multiple `register*` functions to register APIs for items.
Entity API Lookup (#1836) * Entity API Lookup * Update fabric-api-lookup-api-v1/src/main/java/net/fabricmc/fabric/api/lookup/v1/entity/EntityApiLookup.java Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com> * Update according to review * Check for valid entity * Use synchronized block on REGISTERED_SELVES accesses Co-authored-by: Juuxel <6596629+Juuxel@users.noreply.github.com>
2021-12-03 08:34:42 -05:00
# Retrieving APIs from entities
See the javadoc of `EntityApiLookup` for a full usage example.
## [`EntityApiLookup`](src/main/java/net/fabricmc/fabric/api/lookup/v1/entity/EntityApiLookup.java)
The way to query API instances from entities.
Exposes a `find` function to retrieve an API instance, and multiple `register*` functions to register APIs for entity types.
Fabric API Lookup (#1234) # 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 dc716ea1674642c756cb030eed411f0f4919e0e8)
2021-03-08 15:32:36 -05:00
# 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.
Reference in a new issue Copy permalink