Flags

This Library introduces an API for Flags. This allows various objects (most prevalently Items, but also Fluids, Entities and some Block Entities) to have things called Flags. These are simple things that these flaggable objects either do or do not possess. A key feature of these Contaminants is that they are preserved when crafting with Items.

Definitions as used in the API

• Flag - A property a flaggable object can have. These are of the class Flag.
• FlagPole - The set of all Flags possessed by an Item (or other object). Every Item Stack has a unique FlagPole, but they can share Flags. These implement the interface IFlagPole.
• Flaggable - The whole class of objects that can have FlagPoles. This library supplies two main FlagPoles: Items and Fluids.

Flagged Items

The primary use of Flags are with Item Stacks, as these are the things Players craft with the most. By default, the only items marked as flaggable are most vanilla non-BlockItems, but the system is abstract and can be applied to any item. Items which can be placed as blocks cannot be flagged (easily) as FlagPoles are stored in Item Stacks' Components and these are not preserved when blocks are placed.

You can make an item flaggable by adding it to the Item Tag petrolpark:flaggable. But if you are applying this to BlockItems, getting them to actually remember their FlagPoles when placed must be done in code, usually by storing the FlagPole in a Block Entity associated with the Block. You can use the class GenericFlagPole for this.

If you are a Create add-on, add a FlagPoleBehaviour to the Block Entity Behaviours. This is done automatically for any Blocks implementing Create's KineticBlock and whose Block Entity Types are in the Tag petrolpark:contaminable_kinetic, if you are looking for a code example.

Recipes

By default, Flags are propagated according to each Contaminant's preservation_proportion for a variety of vanilla and Create processes like Crafting, Smelting, Brewing, Milling and Mixing (to name a few). These can be configured more or less individually in the Library's per-world configs.

It is strongly recommended that if you are developing a mod with this Library as a strict dependent that you propagate Flags in your mod's Recipes whenever they are crafted. This can be as simple as calling the following:

ItemFlagPole.propagate(streamOfMyInputStacks, outputStack);

This exact thing is done numerous times in the Library's code. See CraftingMenuMixin and AbstractCookingRecipeMixin for examples. You should also trigger Item Decay at these points.

Using Flags in Code

You can obtain the FlagPole of an object with the static method:

IFlagPole.get(Object);

However, there are faster methods for if you know the type of the object:

ItemFlagPole.get(ItemStack);

FluidFlagPole.get(FluidStack);

Once you have a FlagPole, the methods to add and remove Flags are fairly obvious:

IFlagPole<?, ?> contamination = ItemFlagPole.get(stack); // Get the FlagPole of some ItemStack

flagPole.flag(myFlag);

flagPole.unflag(myFlag);

Using Flags in Datapacks

FlagPoles can also be accessed in data-driven resources like Loot Tables, Advancements and Recipes.

TODO

Defining Flags

Flags (as defined above) are data-driven objects, meaning they can be added by datapacks (and any datapack-modifying programs like KubeJS). Flaggables are not.

Flags belong to the petrolpark:flag data Registry and can be registered in the usual way by adding a file data/yourmodid/petrolpark/flag/your_flag.json with the following structure:

{
 "preservation_proportion": 0.5,
 "color": 5635925,
 "absent_color": 16733525,
 "children": [
  "yourmodid:other_flag"
 ]
}

• preservation_proportion is the required proportion of total input Items (or total millibuckets of input Fluid etc.) which must have this Flag in order for the result to also be given the Flag. It must be a number between 0.0 and 1.0 inclusive.

  For example, if the preservation proportion is 0.5, then crafting an Iron Ingot out of 4 flagged and 5 unflagged Iron Nuggets will produce an unflagged Ingot, but 5 flagged Nuggets (or greater) will produce a flagged Ingot. This count only includes flaggable items (e.g. not BlockItems), and does not care about the individual input items, only the total number.

  preservation_proportion: 0.0 will mean any flagged inputs at all will produce a flagged output.

• color is the color (as a 6-digit hexadecimal color code converted to denary) of the tooltip that renders when an Item Stack has the Flag.

• absent_color is the color of the tooltip that renders when an Item Stack does not have a Flag. Note you will only see this tooltip if the Item belongs to the Tag yourmodid:flag/your_flag/show_if_absent.

• children is a list of Child Flags IDs. It can be empty.

You must also add the following entries to your language files (unless your Flag is Tagged petrolpark:hidden):

 "contaminant.yourmodid.your_flag": "Has my Flag",
 "contaminant.yourmodid.your_flag.absent": "Doesn't have my Flag"

TODO absent and intrinsic flags