Fabric Transfer API: "fluid only" edition (#1356)
* 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>
2021-07-12 13:28:33 -04:00
# 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>` .
Fabric Transfer API: item transfer and fluid-containing items. (#1553)
* Add item and "fluid item" APIs
* Rework ContainerItemContext javadoc
* Rework the Inventory wrapper API
* Cleanup inventory wrapper implementation, add < 64 max stack count test, separate tests better
* Fix Inventory wrapper not limiting the stack count correctly (thanks @lilybeevee!)
* Rewrite inventory wrapper, add SingleStackStorage base implementation
* Composters
* SingleStackStorage adjustements
* Bump version
* Move icon to correct location. Closes #1565
* Bump version
* Remove composter implementation (it's broken), slight renames
* Fix SidedInventory extract
* Bump version
* Don't use MAVEN_USERNAME if it's not specified
* Add comparator output, add missing markDirty calls, fix tests
* Bump version
* Add SingleVariantStorage, deprecate SingleFluidStorage, definalize a few things, make sure markDirty() is only called once per successful outer transaction in inventory wrappers
* Add composter support
* Move EmptyFluidView to BlankVariantView, update README and package-info
* Bump version
* Key -> variant
* Add Transaction#openNested(@Nullable TransactionContext)
* Add SingleSlotContainerItemContext
* Bump prerelease version
* Remove useless comment
* Remove ContainerItemContext#getWorld
* Bump prerelease version
* Add StorageUtil#findExtractableContent and ContainerItemContext#withInitial
* Bump prerelease version
2021-08-17 14:08:09 -04:00
Implementors of inventories with a fixed number of "slots" or "tanks" can use
2024-04-10 17:14:36 -04:00
[`SingleVariantStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/base/SingleVariantStorage.java ),
and combine them with [`CombinedStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/storage/base/CombinedStorage.java ).
Fabric Transfer API: item transfer and fluid-containing items. (#1553)
* Add item and "fluid item" APIs
* Rework ContainerItemContext javadoc
* Rework the Inventory wrapper API
* Cleanup inventory wrapper implementation, add < 64 max stack count test, separate tests better
* Fix Inventory wrapper not limiting the stack count correctly (thanks @lilybeevee!)
* Rewrite inventory wrapper, add SingleStackStorage base implementation
* Composters
* SingleStackStorage adjustements
* Bump version
* Move icon to correct location. Closes #1565
* Bump version
* Remove composter implementation (it's broken), slight renames
* Fix SidedInventory extract
* Bump version
* Don't use MAVEN_USERNAME if it's not specified
* Add comparator output, add missing markDirty calls, fix tests
* Bump version
* Add SingleVariantStorage, deprecate SingleFluidStorage, definalize a few things, make sure markDirty() is only called once per successful outer transaction in inventory wrappers
* Add composter support
* Move EmptyFluidView to BlankVariantView, update README and package-info
* Bump version
* Key -> variant
* Add Transaction#openNested(@Nullable TransactionContext)
* Add SingleSlotContainerItemContext
* Bump prerelease version
* Remove useless comment
* Remove ContainerItemContext#getWorld
* Bump prerelease version
* Add StorageUtil#findExtractableContent and ContainerItemContext#withInitial
* Bump prerelease version
2021-08-17 14:08:09 -04:00
Fabric Transfer API: "fluid only" edition (#1356)
* 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>
2021-07-12 13:28:33 -04:00
## Fluid transfer
A `Storage<FluidVariant>` is any object that can store fluids. It is just a `Storage<T>` , where `T` is
2024-03-12 05:22:55 -04:00
[`FluidVariant` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidVariant.java ), the immutable combination of a `Fluid` and additional components.
Fabric Transfer API: "fluid only" edition (#1356)
* 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>
2021-07-12 13:28:33 -04:00
Instances can be accessed through the API lookups defined in [`FluidStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/fluid/FluidStorage.java ).
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.
2024-04-10 17:14:36 -04:00
Client-side [Fluid variant rendering ](src/client/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRendering.java ) will use regular fluid rendering by default,
2024-03-12 05:22:55 -04:00
ignoring the additional components.
`Fluid` s that wish to render differently depending on the stored components can register a
2024-04-10 17:14:36 -04:00
[`FluidVariantRenderHandler` ](src/client/java/net/fabricmc/fabric/api/transfer/v1/client/fluid/FluidVariantRenderHandler.java ).
Fabric Transfer API: item transfer and fluid-containing items. (#1553)
* Add item and "fluid item" APIs
* Rework ContainerItemContext javadoc
* Rework the Inventory wrapper API
* Cleanup inventory wrapper implementation, add < 64 max stack count test, separate tests better
* Fix Inventory wrapper not limiting the stack count correctly (thanks @lilybeevee!)
* Rewrite inventory wrapper, add SingleStackStorage base implementation
* Composters
* SingleStackStorage adjustements
* Bump version
* Move icon to correct location. Closes #1565
* Bump version
* Remove composter implementation (it's broken), slight renames
* Fix SidedInventory extract
* Bump version
* Don't use MAVEN_USERNAME if it's not specified
* Add comparator output, add missing markDirty calls, fix tests
* Bump version
* Add SingleVariantStorage, deprecate SingleFluidStorage, definalize a few things, make sure markDirty() is only called once per successful outer transaction in inventory wrappers
* Add composter support
* Move EmptyFluidView to BlankVariantView, update README and package-info
* Bump version
* Key -> variant
* Add Transaction#openNested(@Nullable TransactionContext)
* Add SingleSlotContainerItemContext
* Bump prerelease version
* Remove useless comment
* Remove ContainerItemContext#getWorld
* Bump prerelease version
* Add StorageUtil#findExtractableContent and ContainerItemContext#withInitial
* Bump prerelease version
2021-08-17 14:08:09 -04:00
## Item transfer
A `Storage<ItemVariant>` is any object that can store items.
Instances can be accessed through the API lookup defined in [`ItemStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/item/ItemStorage.java ).
The lookup already provides compatibility with vanilla inventories, however it may sometimes be interesting to use
[`InventoryStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/item/InventoryStorage.java ) or
[`PlayerInventoryStorage` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/item/PlayerInventoryStorage.java ) when interaction with
`Inventory` -based APIs is required.
## `ContainerItemContext`
[`ContainerItemContext` ](src/main/java/net/fabricmc/fabric/api/transfer/v1/context/ContainerItemContext.java ) is a context designed for `ItemApiLookup` queries
that allows the returned APIs to interact with the containing inventory.
Notably, it is used by the `FluidStorage.ITEM` lookup for fluid-containing items.
