diff options
Diffstat (limited to 'web/src/pages/docs')
| -rw-r--r-- | web/src/pages/docs/texture-pack-format.astro | 15 | ||||
| -rw-r--r-- | web/src/pages/docs/texture-pack-format.md | 583 |
2 files changed, 598 insertions, 0 deletions
diff --git a/web/src/pages/docs/texture-pack-format.astro b/web/src/pages/docs/texture-pack-format.astro new file mode 100644 index 0000000..f04188f --- /dev/null +++ b/web/src/pages/docs/texture-pack-format.astro @@ -0,0 +1,15 @@ +--- +import Base from "../../layouts/Base.astro"; +import NavBar from "../../components/NavBar.astro"; +import Content from "../../layouts/Content.astro"; +import MarkDown from './texture-pack-format.md'; +--- + +<Base title="Firmament Texture Packs"> + <NavBar></NavBar> + <Content> + <MarkDown/> + </Content> +</Base> + + diff --git a/web/src/pages/docs/texture-pack-format.md b/web/src/pages/docs/texture-pack-format.md new file mode 100644 index 0000000..da66043 --- /dev/null +++ b/web/src/pages/docs/texture-pack-format.md @@ -0,0 +1,583 @@ +<!-- +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" +``` + +#### Extra attributes + +Filter by extra attribute NBT data: + +Specify a `path` 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" + } +} +``` + +#### 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 either side independently. + +Specifying round parenthesis `()` means the number is exclusive, so not including this number. For example `(50,100)` +would not match just the number `50` or `100`, but would match `51`. + +Specifying square brackets `[]` means the number is inclusive. For example `[50,100]` would match both `50` and `100`. + +You can mix and match parenthesis and brackets, they only ever affect the number next to it. + +For more information in intervals check out [Wikipedia](https://en.wikipedia.org/wiki/Interval_(mathematics)). + +#### Operators + +If instead of specifying a range you just need to specify one boundary you can also use the standard operators to +compare your number: + +```json5 +"firmament:pet": { + "level": "<50" +} +``` + +This example would match if the level is less than fifty. The available operators are `<`, `>`, `<=` and `>=`. The +operator needs to be specified on the left. The versions of the operator with `=` also allow the number to be equal. + +### Nbt Matcher + +This matches a single nbt element. + +Have the type of the nbt element as json key. Can be `string`, `int`, `float`, `double`, `long`, `short` and `byte`. + +The `string` type matches like a regular [string matcher](#string-matcher): + +```json +"string": { + "color": "strip", + "regex": "^aaa bbb$" +} +``` + +The other (numeric) types can either be matched directly against a number: + +```json +"int": 10 +``` + +Or as a range: + +```json +"long": { + "min": 0, + "max": 1000 +} +``` + +Min and max are both optional, but you need to specify at least one. By default `min` is inclusive and `max` is exclusive. +You can override that like so: + +```json +"short": { + "min": 0, + "max": 1000, + "minExclusive": true, + "maxExclusive": false +} +``` + + +> [!WARNING] +> This syntax for numbers is *just* for **NBT values**. This is also why specifying the type of the number is necessary. +> For other number matchers, use [the number matchers](#number-matchers) + +## Armor textures + +You can re-*texture* armors, but not re-*model* them with firmament. + +To retexture a piece of armor place a json file at `assets/firmskyblock/overrides/armor_models/*.json`. + +```json +{ + "item_ids": [ + "TARANTULA_BOOTS", + "TARANTULA_LEGGINGS", + // ETC + ], + "layers": [ + { + "identifier": "firmskyblock:tarantula" + } + ] +} +``` + +Only one such file can exist per item id, but multiple item ids can share one texture file this way. + +The `item_ids` is the items to which this override will apply when worn. Those are neu repo ids (so what will be shown +in game as the regular SkyBlock id, not the resource pack identifier). + +### Layers + +The `layers` specify the multiple texture layers that will be used when rendering. For non leather armor, or armor +ignoring the leather armor tint just one layer is enough. + +If you want to apply armor tint to the texture you will usually want two layers. The first layer has a tint applied: + +```json +{ + "identifier": "firmskyblock:angler", + "tint": true +} +``` + +This will tint the texture before it is being rendered. + +The second layer will have no tint applied, but will have a suffix: + +```json +{ + "identifier": "firmskyblock:angler", + "suffix": "_overlay" +} +``` + +This second layer is used for the countours of the armor. + +The layer identifier will resolve to a texture file path according to vanilla armor texture rules like so: + +`assets/{identifier.namespace}/textures/models/armor/{identifier.path}_layer_{isLegs ? 2 : 1}{suffix}.png` + +Note that there is no automatic underscore insertion for suffix, so you will need to manually specify it if you want. + +The leg armor piece uses a different texture, same as with vanilla. + +### Overrides + +You can also apply overrides to these layers. These work similar to item predicate overrides, but only the custom +Firmament predicates will work. You will also just directly specify new layers instead of delegating to another file. + +```json +{ + "item_ids": [ + "TARANTULA_BOOTS", + "TARANTULA_LEGGINGS", + // ETC + ], + "layers": [ + { + "identifier": "firmskyblock:tarantula" + } + ], + "overrides": [ + { + "layers": [ + { + "identifier": "firmskyblock:tarantula_maxed" + } + ], + "predicate": { + "firmament:lore": { + "regex": "Piece Bonus: +285.*" + } + } + } + ] +} +``` + +## UI Text Color Replacement + +This allows you to replace the color of text in your inventory. This includes inventory UIs like chests and anvils, but +not screens from other mods. You can also target specific texts via a [string matcher](#string-matcher). + +```json +// This file is at assets/firmskyblock/overrides/text_colors.json +{ + "defaultColor": -10496, + "overrides": [ + { + "predicate": "Crafting", + "override": -16711936 + } + ] +} +``` + +| Field | Required | Description | +|-----------------------|----------|----------------------------------------------------------------------------------------------------| +| `defaultColor` | true | The default color to use in case no override matches | +| `overrides` | false | Allows you to replace colors for specific strings. Is an array. | +| `overrides.predicate` | true | This is a [string matcher](#string-matcher) that allows you to match on the text you are replacing | +| `overrides.override` | true | This is the replacement color that will be used if the predicate matches. | + +## Global Item Texture Replacement + +Most texture replacement is done based on the SkyBlock id of the item. However, some items you might want to re-texture +do not have an id. The next best alternative you had before was just to replace the vanilla item and add a bunch of +predicates. This tries to fix this problem, at the cost of being more performance intensive than the other re-texturing +methods. + +The entrypoint to global overrides is `firmskyblock:overrides/item`. Put your overrides into that folder, with one file +per override. + +```json5 +{ + "screen": "testrp:chocolate_factory", + "model": "testrp:time_tower", + "predicate": { + "firmament:display_name": { + "regex": "Time Tower.*" + } + } +} +``` + +There are three parts to the override. + +The `model` is an *item id* that the item will be replaced with. This means the +model will be loaded from `assets/<namespace>/models/item/<id>.json`. Make sure to use your own namespace to +avoid collisions with other texture packs that might use the same id for a gui. + +The `predicate` is just a normal [predicate](#predicates). This one does not support the vanilla predicates. You can +still use vanilla predicates in the resolved model, but this will not allow you to fall back to other global overrides. + +The `screen` specifies which screens your override will work on. This is purely for performance reasons, your filter +should work purely based on predicates if possible. You can specify multiply screens by using a json array. + +### Global item texture Screens + +In order to improve performance not all overrides are tested all the time. Instead you can prefilter by the screen that +is open. First the gui is resolved to `assets/<namespace>/filters/screen/<id>.json`. Make sure to use your own namespace +to avoid collisions with other texture packs that might use the same id for a screen. + +```json +{ + "title": "Chocolate Factory" +} +``` + +Currently, the only supported filter is `title`, which accepts a [string matcher](#string-matcher). You can also use +`firmament:always` as an always on filter (this is the recommended way). + +## Block Model Replacements + +Firmament adds the ability to retexture block models. Supported renderers are vanilla, indigo (fabric), sodium (and +anything sodium based). Firmament performs gentle world reloading so that even when the world data gets updated very +late by the server there should be no flicker. + +If you want to replace block textures in the world you can do so using block overrides. Those are stored in +`assets/firmskyblock/overrides/blocks/<id>.json`. The id does not matter, all overrides are loaded. This file specifies +which block models are replaced under which conditions: + +```json +{ + "modes": [ + "mining_3" + ], + "area": [ + { + "min": [ + -31, + 200, + -117 + ], + "max": [ + 12, + 223, + -95 + ] + } + ], + "replacements": { + "minecraft:blue_wool": "firmskyblock:mithril_deep", + "minecraft:light_blue_wool": { + "block": "firmskyblock:mithril_deep", + "sound": "minecraft:block.wet_sponge.hit" + } + } +} +``` + +| Field | Required | Description | +|-------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `modes` | yes | A list of `/locraw` mode names. | +| `area` | no | A list of areas. Blocks outside of the coordinate range will be ignored. If the block is in *any* range it will be considered inside | +| `area.min` | yes | The lowest coordinate in the area. Is included in the area. | +| `area.max` | yes | The highest coordinate in the area. Is included in the area. | +| `replacements` | yes | A map of block id to replacement mappings | +| `replacements` (string) | yes | You can directly specify a string. Equivalent to just setting `replacements.block`. | +| `replacements.block` | yes | You can specify a block model to be used instead of the regular one. The model will be loaded from `assets/<namespace>/models/block/<path>.json` like regular block models. | +| `replacements.sound` | no | You can also specify a sound override. This is only used for the "hit" sound effect that repeats while the block is mined. The "break" sound effect played after a block was finished mining is sadly sent by hypixel directly and cannot be replaced reliably. | + +> A quick note about optimization: Not specifying an area (by just omitting the `area` field) is quicker than having an +> area encompass the entire map. +> +> If you need to use multiple `area`s for unrelated sections of the world it might be a performance improvement to move +> unrelated models to different files to reduce the amount of area checks being done for each block. |