Skip to content

Commit

Permalink
Expanded documentation with info about TagPrefixes and ChemicalHelper. (
Browse files Browse the repository at this point in the history
#41)

* Update Custom-Machines.md

-Added correction to simple machine builder regarding defining pollution amount
-Added comment to multiblock machine builder regarding how to define tooltips.

* Update Custom-Recipe-Types.md

-Added comment explaining recipeModifers
-Added comment explaining where to find additional GuiTextures and FillDirections.

* Update v1.2.1.md

Added note mentioning how to supply recipe modifiers correctly.

* Update Custom-Machines.md

- Corrected comment on how to define simple electric machine to include pollution in the method.
- Added comment detailing how to add tooltips to multiblock machines.

* Update Custom-Machines.md

Formatting corrections

* Update v1.2.1.md

-Corrected capitalization.

* Update Adding-and-Removing-Recipes.md

Expanded documentation regarding RecipeBuilder functionality.

* Create TagPrefixes-and-the-power-of-.setIgnored().md

Expands documentation on TagPrefixes and how to use .setIgnored() to treat items not native to GTCEu Modern as belonging to a GTCEu Modern Material.

* Create The-ChemicalHelper-class.md

Expanded docs to include info about the ChemicalHelper class

* Update Adding-and-Removing-Recipes.md

Made corrections to the description of some energy calls.

* Update TagPrefixes-and-the-power-of-.setIgnored().md

Made corrections to information concerning .setIgnored().

* Update The-ChemicalHelper-class.md

Corrected minor punctuation error.

* Update The-ChemicalHelper-class.md

Minor correction to description of .get() method.

* Update TagPrefixes-and-the-power-of-.setIgnored().md

Minor spelling corrections and additional details.

* Update Adding-and-Removing-Recipes.md

Minor punctuation corrections and clarifications.
  • Loading branch information
AncientShotgun authored Nov 12, 2024
1 parent c7b1d67 commit bfaec43
Show file tree
Hide file tree
Showing 3 changed files with 101 additions and 5 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
title: TagPrefixes and the power of .setIgnored()
---
## What is a TagPrefix?
TagPrefixes are GTCEu Modern's way of streamlining applying item and block tags to Materials, along with some other functions. The `TagPrefix` class,
available for use in startup and server scripts, contains a number of predefined TagPrefixes that
associate potentially everything from drill heads to flawless gemstones with a material. A common and easy-to-understand example is `TagPrefix.ingot`,
which associates with all Materials that have an IngotProperty and thus an associated ingot item, including custom ones defined via KubeJS.
TagPrefixes provide localization, item and block tagging, and influence many crafting recipes, and are integral to the functioning of GTCEu's material definition system.

!!! tip "What TagPrefixes are there?"
A list of all availabe TagPrefixes can be found in GTCEu Modern's GitHub or in the .JAR file, in the class `TagPrefix`.

## What is .setIgnored()?

While trawling thorugh GTCEu Modern's codebase, or simply by playing Minecraft, you may have noticed that GTCEu Modern treats some vanilla materials differently.
For example, iron ingots are a vanilla item, yet GTCEu Modern does not create a duplicate iron ingot, as its Material definition would suggest it is meant to do.
Instead, the GTCEu Modern Material entry for iron treats the vanilla iron ingot as the material's ingot, and thus produces no duplicates.
This functionality is governed by TagPrefixes, and can also be harnessed by packmakers for their own custom items, or when writing compatibility between GTCEu Modern and another mod.

## Okay, but how do I use this?

This functionality can be leveraged in the material modification event, which is a startup event.
The material modification event occurs in Minecraft's boot sequence after Material registration is finalized, but before the Material registry is closed; you won't be able to define any new Materials using it.
The following calls are available for each TagPrefix:
- `.setIgnored()` with one input parameter: Takes a `Material` as input and prevents GTCEu from associating that specific TagPrefix with that Material.
- `.setIgnored()` with two input parameters: Takes a `Material` and an `Item` or `Block` (or any class that that implements the `ItemLike` interface) as input; causes GTCEu to treat the passed `ItemLike` as whatever item the TagPrefix would have originally generated for the Material. An `ItemLike...` varargs in the form of a JS array may also be passed to perform the action on multiple blocks and/or items at once.
- `.removeIgnored()`: takes a `Material` as input and re-enables generation of the item associated with the TagPrefix for that material.

!!! caution "Beware of `Item.of()`!" The classic way to retrieve an `Item` in KubeJS, namely the `Item.of()` wrapper, doesn't work here. You will need to directly pass an `ItemLike` from a Java class for `.setIgnored()` to work correctly.

A more illustrative example, using some Applied Energistics 2 items:

```js title="setignored_usage_example.js"
GTCEuStartupEvents.materialModification(event => { // (1)
TagPrefix.gemChipped.setIgnored(GTMaterialRegistry.getMaterial("fluix_crystal")) // (2)
TagPrefix.rock.setIgnored(GTMaterialRegistry.getMaterial("sky_stone"), AEBlocks.SKY_STONE_BLOCK) // (3)
TagPrefix.ingot.removeIgnored(GTMaterials.Iron) // (4)
})
```
1. This event has no methods such as `event.create()`, as it is not intended to be used to create anything, only tweak pre-existing Material associations. In fact, this event has no accessible methods whatsoever.
2. This call prevents GTCEu Modern from creating a chipped gem variant of the custom 'fluix_crystal' Material.
3. This call makes GTCEu Modern associate AE2's Sky Stone block as a rock type (like vanilla stone is associated with the GTCEu Modern stone `Material`) with the custom 'sky_stone' Material. It may be necessary to manually load whatever data definition class contains the `ItemLike` you wish to associate with your `Material`, depending on how the mod's author has provided KubeJS access to the modn's classes.
4. This call makes GTCEu Modern de-associate vanilla iron ingots from GTCEu Modern's iron Material entry, causing it to generate a duplicate iron ingot.

The `Material` for which you are adjusting the TagPrefix must be registered in GTCEu Modern's material registry; if this material is custom, this is done using `GTCEuStartupEvents.registry()`, as depicted in these docs.
44 changes: 44 additions & 0 deletions docs/Modpacks/Materials-and-Elements/The-ChemicalHelper-class.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: The ChemicalHelper class
---

It may behoove a packmaker working with GTCEu Modern to learn about the ChemicalHelper class. This class, available for use in server scripts,
contains a number of useful methods that can ease working with GTCEu Materials in contexts where it might not be possible, or it might be unsafe, to work with item or block tags.

## Useful functions that ChemicalHelper offers
The following functions are available for use by packmakers:
- `.getMaterial()`: can take almost any form of item reference (`Item`, `ItemStack`, `Ingredient` and so on) and will return the `Material` entry associated with it.
If there is no associated Material, the method returns `null`. A `Fluid` may also be passed as input.
- `.getPrefix()`: Takes an item reference as input and will return the TagPrefix it is associated with it. If there is non associated, the method will return `null`.
- `.getIngot()`
- `.getDust()`
- These two methods take two parameters each as input: a `Material`, and a number representing a material amount, and will return an ItemStack representation of the respective Material's dust or ingot form, if it has one.
The material amount is usually very large; it is generally an integer multiple or fraction of the predefined value `GTValues.M`, which is the commonly agreed-upon material amount of one (1) ingot or regular dust.
Depending on the amount passed, the functions will return different items: `.getIngot()`, for example, will return
an ItemStack representation of a block or nugget of the associated Material if the passed amount is large or small enough.
`.getDust()`, in similar fashion, will return regular, small or tiny dust ItemStack representations depending on the material amount passed.
- `.getTag()`
- `.getBlockTag()`
- `.getTags()`
- `.getBlockTags()`
- Takes a `TagPrefix` and a non-`null` `Material` as input and returns the first item or block tag
(or a Java array of all item or block tags if the plural functions are used) possessed by the item represented by that `TagPrefix`-`Material` combination.
- `.get()`: Takes a `TagPrefix`, a `Material` and optionally an item count that otherwise defaults to 1, and returns an ItemStack representing that `TagPrefix`-`Material` combination with the specified item count.

Some usage examples:

```js title="chemicalhelper_example_script.js"
var ironMaterial = ChemicalHelper.getMaterial(Item.of("gtceu:double_iron_plate").asItem()) // (1)
var rawOrePrefix = ChemicalHelper.getPrefix(Item.of("gtceu:raw_platinum").asItem()) // (2)
var cobaltIngotStack = ChemicalHelper.get(TagPrefix.ingot, GTMaterials.Cobalt, 32) // (3)

var goldNugget = ChemicalHelper.getIngot(GTMaterials.Gold, GTValues.M / 9)// (4)
var steelBlock = ChemicalHelper.getIngot(GTMaterials.Steel, GTValues.M * 9)

var ashSmallDust = ChemicalHelper.getDust(GTMaterials.Ash, GTValues.M / 4)// (5)
```
1. `ironMaterial` is now a reference to `GTMaterials.Iron`.
2. `rawOrePrefix` is now a reference to `TagPrefix.rawOre`.
3. `cobaltIngotStack` is now an ItemStack representing half a stack of cobalt ingots.
4. `goldNugget` is now an ItemStack representing one gold nugget.
5. `ashSmallDust` is now an ItemStack representing a small ash pile.
16 changes: 11 additions & 5 deletions docs/Modpacks/Other-Topics/Adding-and-Removing-Recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,10 @@ ServerEvents.recipes(event => {
})
```

### Event Addons

### Event calls for adding inputs and outputs
- Basic calls:
- `.input()`: The most basic input definition available. Takes two parameters: one RecipeCapability that defines what input type this call is supposed to be (usually an item, a fluid or energy, but can also be, for example, Create Stress Units), and an Object that defines the input itself. Available RecipeCapabilities can be found in the GTCEu Modern GitHub or the mod's .JAR file, but the class containing all of GTCEu Modern's native RecipeCapabilities, `GTRecipeCapabilites`, must be manually loaded in your scripts. This method is unwieldy to use in Javascript; it is more user-friendly to use the ones below that clearly tell you what input type they call.
- `.output()`: As above, but defines an output instead. Takes the exact same parameters. This method is likewise unwieldy to use; it is more user-friendly to use the ones below that clearly tell you what output type they call.
- Inputs:
- Items:
- `.itemInput()`
Expand All @@ -76,6 +78,7 @@ ServerEvents.recipes(event => {
- Fluids:
- `.inputFluids()`
- `.chancedFluidInput()`
- `.notConsumableFluid()`
- Misc:
- `.circuit()`
- Outputs:
Expand All @@ -87,10 +90,13 @@ ServerEvents.recipes(event => {
- `.outputFluids()`
- `.chancedFluidOutput()`
- Energy:
- `.EUt()`

### Research
- `.inputEU()`: Makes the recipe consume a lump sum of EU to start the recipe. Most often seen in fusion reactor recipes.
- `.outputEU()`: Makes the recipe produce a lump sum of EU upon recipe completion.
- `.EUt()`: Takes a numerical value represesnting an EU amount. Positive values will make the recipe consume energy per tick, negative ones will make it generate energy per tick.
- More granular functionality:
- `.perTick()`: Using this will enable you to control whether a recipe input/output is consumed/produced per tick the recipe is running or all at once at recipe start/end. Set to true with `.perTick(true)` to make the recipe builder consider any following input/output calls as per-tick. Remember to set the value to false with `.perTick(false)` after the calls you intend to be per-tick, to prevent behaviour you don't want!

### The Research System
GTCEu has Research System which allows for adding extra requirements to recipes such as: Scanner Research, Station Research and Computation.

```js title="scanner_research.js"
Expand Down

0 comments on commit bfaec43

Please sign in to comment.