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. Flaggable objects (like item stacks and fluid stacks) either do or do not possess a given Flag. A key feature of these Flags is that they are preserved when crafting.

Tags vs Flags

Vanilla Minecraft already has a system of tags, which are easily confused but differ in several key ways:

	Tags	Flags
Origin	Vanilla Minecraft	This Library
Scope	Any registered "definition" object, e.g. Item and Fluid	Some "instance" objects. Built-in implementations are for ItemStack, FluidStack and certain BlockEntitys
Modification	Modifiable only by datapacks, requiring a reload to update	Modifiable at runtime (in code, by commands, in loot tables, etc.)
Perpetuation	ItemStacks of Items (for example) have the same tags, regardless of how they were obtained	While some Items (for example) have intrinsic Flags and so their ItemStacks are always flagged, generally Flags propagate through crafting and depend on how the ItemStack is obtained
Appearance	Generally not shown to the player except in advanced tooltips and JEI. It is possible but not mandatory to define a name (which is separate from the internal ID)	Shown in the tooltips of item stacks and names of fluid stacks. A defined name and color are encouraged

Definitions

When these words are capitalized in this Wiki and in the JavaDocs, they refer to these definitions:

• 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 Flaggables: 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, which has the necessary serialization functions.

If you are making 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 (the full path is .../data/petrolpark/tags/block_entity_type/contaminable_kinetic).

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);

(There are slightly different versions of this method available in the IFlagPole class, including for mixtures of items and fluids).

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 which are encouraged 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 self-explanatory, but are explained in more detail in the javadocs:

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:

Checking Flags:

• Ingredient TODO
• ItemPredicate TODO

Modifying Flags:

• LootItemFunction TODO
• GlobalLootModifier TODO
• The /petrolpark flag <entities> <flag> command adds the Flag to the item held in the main hand of targeted entities, similarly to the /enchant command

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. There still has to be at least one---it won't just apply to every item crafted.

• 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 includes the Flag in the item data map petrolpark:shown_if_absent_flags.

• 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"

Intrinsic Flags

It may be your wish that all stacks of a particular item (or all fluid stacks of a particular fluid, etc.) have a certain Flag. This is only useful in crafting items that do not intrinsically have that Flag; otherwise you should use a tag instead of a Flag. You can define intrinsic Flags for items and fluids in the corresponding data maps, both with ID petrolpark:intrinsic_flags.

Datapack Structure

data
├── examplemod
|   └── petrolpark
|       └── flag
|           ├── my_flag_1.json
|           └── my_flag_2.json
└── petrolpark
    ├── data_maps
    |   ├── fluid
    |   |
    |   └── item
    |
    └── tags
        ├── fluid
        |   └── flaggable.json
        └── item
            └── flaggable.json