mirror of
https://github.com/FabricMC/fabric.git
synced 2024-11-23 08:08:02 -05:00
c09be4c48a
* Original fluid API design * Rework the transaction system * First javadoc pass * Add a testmod, a base implementation for fluid storages and fix some little bugs * Fix checkstyle * Make Movement#move extract from the view and not the whole Storage * Document and update FluidPreconditions * Use for-each in CombinedStorage and document a little * Remove useless overrides in Insertion/ExtractionOnlyStorage * Move SnapshotParticipant#snapshots to the top of the class, and make updateSnapshots public * Fix garbage collection of unused CauldronWrappers * Use ArrayList directly * Remove locking, reorganize transaction implementation, and add outer close callback * Add more javadoc * Rework Storage#forEach into Storage#iterator * Add a few missing `transaction.addCloseCallback(iterator)` * Add anyView(), exactView(), capacity() and isEmpty() * Add Storage#iterable to make iteration friendlier to for loops * Storages may now have multiple open iterators Co-authored-by: Devan-Kerman <dev.sel20@gmail.com> * Make CombinedStorage#supportsInsertion/Extraction iterate through the parts * Block updates should be used when the supportsInsertion/Extraction status changes * Fluid -> FluidKey * Remove all references to ItemKey inside FluidKey, and other minor tweaks * Cache FluidKeys with a null tag inside Fluid directly * Fluid unit convention * Add FluidKeyRendering and RenderHandler * Bump version for more testing (also published to my maven) * Add SingleViewIterator, massively reduce code duplication! * Make API experimental, and add README * Bump version * Apparently Fluids.EMPTY is flowing * Add package info * Minor adjustements * 1.17 port, cauldron support, add ResourceKey * Checkstyle, gas rendering, use record for ResourceAmount * Add a few helpers, rename some stuff * Remove anyView, allow nullable in StorageUtil#find*, fix missing try block * Slight findStoredResource cleanup * Slightly improve implementation * Bump version * Fix wrong transaction * I wrote in a comment that this could happen... * Fix SingleFluidStorage bugs, add tests in the testmod, add testmod assets * Add extract stick * Rename a few things * `ResourceKey<T>` -> `TransferKey<O>` * `ResourceKey#getResource()` -> `TransferKey#getObject()` as resource is already widely used through the API for the keys themselves. * `tag` -> `nbt` * Add `get` prefixes to `StorageView` functions * Bump version * FluidKey -> FluidVariant * Bump version * Expand getVersion() documentation, make it thread-safe and use long. Co-authored-by: Player <player@player.to> * empty resource -> blank resource, and update SingleFluidStorage Co-authored-by: Player <player@player.to> * Make CauldronFluidContent a final class instead of a record. Co-authored-by: Player <player@player.to> * Get rid of CauldronFluidContent#minLevel (was always 1) * Fix nested commits. (Thanks @warjort!) * Separate Transaction and TransactionContext Co-authored-by: Devan-Kerman <dev.sel20@gmail.com> Co-authored-by: Player <player@player.to> * Change WorldLocation into a private record * Bump version * Guard against exceptions thrown in close callbacks * Make sure blank fluid variants don't have a tag * Add documentation, make CauldronStorage clearer Co-authored-by: frqnny <45723631+frqnny@users.noreply.github.com> * Allow null storages in StorageUtil#move, and clarify sidedness of FluidStorage * Add explicit hashCode and equals for transfer variants * Remove ugly equals and hashCode overrides, and add constant time hashcode spec Co-authored-by: Devan-Kerman <dev.sel20@gmail.com> Co-authored-by: liach <liach@users.noreply.github.com> Co-authored-by: Player <player@player.to> Co-authored-by: frqnny <45723631+frqnny@users.noreply.github.com>
36 lines
2.7 KiB
Markdown
36 lines
2.7 KiB
Markdown
# Fabric Transfer API (v1)
|
|
This module provides common facilities for the transfer of fluids and other game resources.
|
|
|
|
## Transactions
|
|
The [`Transaction`](src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/Transaction.java) system provides a
|
|
scope that can be used to simulate any number of transfer operations, and then cancel or validate all of them at once.
|
|
One can think of transactions as video game checkpoints. A more detailed explanation can be found in the class javadoc of `Transaction`.
|
|
Every transfer operation requires a `Transaction` parameter.
|
|
[`SnapshotParticipant`](src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/base/SnapshotParticipant.java)
|
|
is the reference implementation of a "participant", that is an object participating in a transaction.
|
|
|
|
## Storages
|
|
A [`Storage<T>`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/Storage.java) is any object that can store resources of type `T`.
|
|
Its contents can be read, and resources can be inserted into it or extracted from it.
|
|
[`StorageUtil`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/StorageUtil.java) provides a few helpful functions to work with `Storage`s,
|
|
for example to move resources between two `Storage`s.
|
|
The [`storage/base`](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/base) package provides a few helpers to accelerate
|
|
implementation of `Storage<T>`.
|
|
|
|
## Fluid transfer
|
|
A `Storage<FluidVariant>` is any object that can store fluids. It is just a `Storage<T>`, where `T` is
|
|
[`FluidVariant`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidVariant.java), the immutable combination of a `Fluid` and additional NBT data.
|
|
Instances can be accessed through the API lookups defined in [`FluidStorage`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidStorage.java).
|
|
|
|
Implementors of fluid inventories with a fixed number of "slots" or "tanks" can use
|
|
[`SingleFluidStorage`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/base/SingleFluidStorage.java),
|
|
and combine them with `CombinedStorage`.
|
|
|
|
The unit for fluid transfer is 1/81000ths of a bucket, also known as _droplets_.
|
|
[`FluidConstants`](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidConstants.java) contains a few helpful constants
|
|
to work with droplets.
|
|
|
|
Client-side [Fluid variant rendering](src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRendering.java) will use regular fluid rendering by default,
|
|
ignoring the additional NBT data.
|
|
`Fluid`s that wish to render differently depending on the stored NBT data can register a
|
|
[`FluidVariantRenderHandler`](src/main/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRenderHandler.java).
|