path: root/web/src/pages/docs/_texture-pack-format.md

<!--
SPDX-FileCopyrightText: 2023 Linnea Gräf <nea@nea.moe>

SPDX-License-Identifier: CC0-1.0
-->

# Custom SkyBlock Items Texture Pack Format

## Items by internal id (ExtraAttributes)

Find the internal id of the item. This is usually stored in the ExtraAttributes tag (Check the Power User Config for 
keybinds). Once you found it, create an item model in a resource pack like you would for
a vanilla item model, but at the coordinate `firmskyblock:<internalid>`. So for an aspect of the end, this would be 
`firmskyblock:models/item/aspect_of_the_end.json` (or `assets/firmskyblock/models/item/aspect_of_the_end.json`). Then,
just use a normal minecraft item model. See https://github.com/nea89o/BadSkyblockTP/blob/master/assets/firmskyblock/models/item/magma_rod.json
as an example. The id is first turned to lower case, then gets `:` replaced with `___`, `;` with `__` and all other 
characters that cannot be used in a minecraft resource location with `__XXXX` where `XXXX` is the 4 digit hex code for 
the character.

## (Placed) Skulls by texture id

Find the texture id of a skull. This is the hash part of an url like
`https://textures.minecraft.net/texture/bc8ea1f51f253ff5142ca11ae45193a4ad8c3ab5e9c6eec8ba7a4fcb7bac40` (so after the
/texture/). You can find it in game for placed skulls using the keybinding in the Power User Config. Then place the
replacement texture at `firmskyblock:textures/placedskulls/<thathash>.png`. Keep in mind that you will probably replace
the texture with another skin texture, meaning that skin texture has its own hash. Do not mix those up, you need to use
the hash of the old skin.

## Armor Skull Models

You can replace the models of skull items (or other items) by specifying the `firmament:head_model` property on your
model. Note that this is resolved *after* all [overrides](#predicates) and further predicates are not resolved on the
head model.

```json5
{
    "parent": "minecraft:item/generated",
    "textures": {
        "layer0": "firmskyblock:item/regular_texture"
    },
    "firmament:head_model": "minecraft:block/diamond_block" // when wearing on the head render a diamond block instead (can be any item model, including custom ones)
}
```

## Tint Overrides

Some items get naturally tinted by Minecraft's rendering. Examples include leather armour, spawn eggs, potions and more.
If you want to avoid your textures getting tinted, one thing you can do is use a higher texture layer:

```json
{
    "parent": "minecraft:item/generated",
    "textures": {
		// Notice the layer1 instead of layer0 here
        "layer1": "firmskyblock:item/regular_texture"
    }
}
```

Some items, however, tint *all* layers. For those items you can instead specify a tint override:

```json
{
    "parent": "minecraft:item/generated",
    "textures": {
        "layer0": "firmskyblock:item/regular_texture"
    },
    "firmament:tint_overrides": {
        "0": -1
    }
}
```

This forces layer 0 to be tinted with the color `-1` (pure white, aka no tint). This property is inherited, so if you
attach it to one of your root models that you `"parent"` other models to, all those models will have their tints
overridden. When the property is inherited, only layers specified in the child actually overwrite the parent layers.
You can use `"0": null` to remove the tint override in a child, which will cause a fallback to the vanilla tinting
behaviour.

## Predicates

Firmament adds the ability for more complex [item model predicates](https://minecraft.wiki/w/Tutorials/Models#Item_predicates).
Those predicates work on any model, including models for vanilla items, but they don't mix very well with vanilla model overrides.
Vanilla predicates only ever get parsed at the top level, so including a vanilla predicate inside of a more complex
firmament parser will result in an ignored predicate.

### Example usage

```json
{
    "parent": "minecraft:item/handheld",
    "textures": {
        "layer0": "firmskyblock:item/bat_wand"
    },
    "overrides": [
        {
            "predicate": {
                "firmament:display_name": {
                    "regex": ".*§d.*",
                    "color": "preserve"
                }
            },
            "model": "firmskyblock:item/recombobulated_bat_wand"
        }
    ]
}
```

You specify an override like normally, with a `model` that will replace the current model and a list of `predicate`s
that must match before that override takes place.

At the top level `predicate` you can still use all the normal vanilla predicates, as well as the custom ones, which are
all prefixed with `firmament:`.

#### Display Name

Matches the display name against a [string matcher](#string-matcher)

```json
"firmament:display_name": "Display Name Test"
```

#### Lore

Tries to find at least one lore line that matches the given [string matcher](#string-matcher).

```json
"firmament:lore": {
  "regex": "Mode: Red Mushrooms",
  "color": "strip"
}
```

#### Item type

Filter by item type:

```json
"firmament:item": "minecraft:clock"
```

#### Skulls

You can match skulls using the skull textures and other properties using the skull predicate. If there are no properties specified this is equivalent to checking if the item is a `minecraft:player_head`.

```json
"firmament:skull": {
	"profileId": "cca2d452-c6d3-39cb-b695-5ec92b2d6729",
	"textureProfileId": "1d5233d388624bafb00e3150a7aa3a89",
	"skinUrl": "http://textures.minecraft.net/texture/7bf01c198f6e16965e230235cd22a5a9f4a40e40941234478948ff9a56e51775",
	"textureValue": "ewogICJ0aW1lc3RhbXAiIDogMTYxODUyMTY2MzY1NCwKICAicHJvZmlsZUlkIiA6ICIxZDUyMzNkMzg4NjI0YmFmYjAwZTMxNTBhN2FhM2E4OSIsCiAgInByb2ZpbGVOYW1lIiA6ICIwMDAwMDAwMDAwMDAwMDBKIiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzdiZjAxYzE5OGY2ZTE2OTY1ZTIzMDIzNWNkMjJhNWE5ZjRhNDBlNDA5NDEyMzQ0Nzg5NDhmZjlhNTZlNTE3NzUiLAogICAgICAibWV0YWRhdGEiIDogewogICAgICAgICJtb2RlbCIgOiAic2xpbSIKICAgICAgfQogICAgfQogIH0KfQ"
}
```

| Name               | Type                      | Description                                                                                                                                                                                                                                         |
|--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `profileId`        | UUID                      | Match the uuid of the profile component directly.                                                                                                                                                                                                   |
| `textureProfileId` | UUID                      | Match the uuid of the skin owner in the encoded texture value. This is more expensive, but can deviate from the profile id of the profile owner.                                                                                                    |
| `skinUrl`          | [string](#string-matcher) | Match the texture url of the skin. This starts with `http://`, not with `https:/` in most cases.                                                                                                                                                    |
| `textureValue`     | [string](#string-matcher) | Match the texture value. This is the encoded base64 string of the texture url along with metadata. It is faster to query than the `skinUrl`, but it can out of changed without causing any semantic changes, and is less readable than the skinUrl. |

#### Extra attributes

Filter by extra attribute NBT data:

Specify a `path` (using an [nbt prism](#nbt-prism)) to look at, separating sub elements with a `.`. You can use a `*` to check any child.

Then either specify a `match` sub-object or directly inline that object in the format of an [nbt matcher](#nbt-matcher).

Inlined match:

```json5
"firmament:extra_attributes": {
    "path": "gems.JADE_0",
    "string": "PERFECT"
}
```

Sub object match:

```json5
"firmament:extra_attributes": {
    "path": "gems.JADE_0",
    "match": {
        "string": "PERFECT"
    }    
}
```

#### Components

You can match generic components similarly to [extra attributes](#extra-attributes). If you want to match an extra
attribute match directly using that, for better performance.

You can specify a `path` (using an [nbt prism](#nbt-prism)) and match similar to extra attributes, but in addition you can also specify a `component`. This
variable is the identifier of a component type that will then be encoded to nbt and matched according to the `match`
using a [nbt matcher](#nbt-matcher).

```json5
"firmament:component": {
    "path": "rgb",
	"component": "minecraft:dyed_color",
	"int": 255
}
// Alternatively
"firmament:component": {
	"path": "rgb",
	"component": "minecraft:dyed_color",
	"match": {
		"int": 255
	}
}
```


#### Pet Data

Filter by pet information. While you can already filter by the skyblock id for pet type and tier, this allows you to
further filter by level and some other pet info.

```json5
"firmament:pet" {
    "id": "WOLF",
    "exp": ">=25353230",
    "tier": "[RARE,LEGENDARY]",
    "level": "[50,)",
    "candyUsed": 0
}
```

| Name        | Type                                                                   | Description                                                                                                                          |
|-------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `id`        | [String](#string-matcher)                                              | The id of the pet                                                                                                                    |
| `exp`       | [Number](#number-matcher)                                              | The total experience of the pet                                                                                                      |
| `tier`      | Rarity (like [Number](#number-matcher), but with rarity names instead) | The total experience of the pet                                                                                                      |
| `level`     | [Number](#number-matcher)                                              | The current level of the pet                                                                                                         |
| `candyUsed` | [Number](#number-matcher)                                              | The number of pet candies used on the pet. This is present even if they are not shown in game (such as on a level 100 legendary pet) |

Every part of this matcher is optional.


#### Logic Operators

Logic operators allow to combine other firmament predicates into one. This is done by building boolean operators:

```json5
"firmament:any": [
  {
    "firmament:display_name": "SkyBlock Menu (Click)"
  },
  {
    "firmament:display_name": "SkyBlock",
    "firmament:lore": "Some Lore Requirement"
  }    
]
```

This `firmament:any` test if the display name is either "SkyBlock Menu (Click)" or "SkyBlock" (aka any of the child predicates match).

Similarly, there is `firmament:all`, which requires all of its children to match.

There is also `firmament:not`, which requires none of its children to match. Unlike `any` or `all`, however, `not`
only takes in one predicate `{}` directly, not an array of predicates `[{}]`.

Note also that by default all predicate dictionaries require all predicates in it to match, so you can imagine that all
things are wrapped in an implicit `firmament:all` element.

### String Matcher

A string matcher allows you to match almost any string. Whenever a string matcher is expected, you can use any of these
styles of creating one.

#### Direct

```json
"firmament:display_name": "Test"
```

Directly specifying a raw string value expects the string to be *exactly* equal, after removing all formatting codes.

#### Complex

A complex string matcher allows you to specify whether the string will get its color codes removed or not before matching


```json5
"firmament:display_name": {
  "color": "strip",
  "color": "preserve", 
  // When omitting the color property alltogether, you will fall back to "strip"
}
```
In that same object you can then also specify how the string will be matched using another property. You can only ever
specify one of these other matchers and one color preserving property.

```json5
"firmament:display_name": {
  "color": "strip",
  // You can use a "regex" property to use a java.util.Pattern regex. It will try to match the entire string.
  "regex": "So[me] Regex",
  // You can use an "equals" property to test if the entire string is equal to some value. 
  // Equals is faster than regex, but also more limited.  
  "equals": "Some Text"    
}
```

### Number Matchers

This matches a number against either a range or a specific number.

#### Direct number

You can directly specify a number using that value directly:
```json5
"firmament:pet": {
    "level": 100
}
```

This is best for whole numbers, since decimal numbers can be really close together but still be different.

#### Intervals

For ranges you can instead use an interval. This uses the standard mathematical notation for those as a string:


```json5
"firmament:pet": {
    "level": "(50,100]"
}
```

This is in the format of `(min,max)` or `[min,max]`. Either min or max can be omitted, which results in that boundary
being ignored (so `[50,)` would be 50 until infinity). You can also vary the parenthesis on