> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/edmortars/reference/custom-textures.md). # Custom Textures & Resource-Pack Menus The unlock and upgrades menus are PinnaPrison GUI files (`plugins/PinnaPrison/guis/EdMortars/`), so they can look like anything your resource pack can draw: a full picture as the background, your own icons on every button, custom tooltip frames and values drawn with your own art. This page shows how. You only edit the menu files and your pack; EdMortars needs no extra setting. ## How it fits together A resource-pack menu is still a normal chest menu, built from three layers that you set in the menu file: 1. **The background**: a picture from your pack, placed in the menu **title**. 2. **The buttons**: menu items that wear your pack's models and tooltip frames. 3. **Live values**: text, glyphs or models that change with the player's data. The server only sends the title and the items. The pack on the player's game does the drawing, so every player needs your pack loaded. Players without it see vanilla items and unreadable characters in the title. ## 1. The background picture A menu title is text, and text can show font images ("glyphs") from your pack. A glyph as large as the chest window covers the vanilla texture and becomes the background. ```yaml # plugins/PinnaPrison/guis/EdMortars/mortar-upgrades.yml title: '&f:offset_-18::mortar_upgrades:' rows: 6 ``` | Part | What it does | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `&f` | Makes the title white. Title text is dark grey by default and glyphs take the colour of the text, so without `&f` the picture looks dark. | | `:offset_-18:` | Moves the text cursor 18 pixels to the left. The title starts 8 pixels in from the left edge of the window, so the picture needs a negative offset to start at the edge. The right number depends on how your picture was drawn: change it one pixel at a time until the picture lines up with the slots. | | `:mortar_upgrades:` | The picture itself (here an ItemsAdder font image called `mortar_upgrades`). | Set `rows` to the menu height your picture was made for. ### Writing glyphs for your pack plugin | Pack made with | Picture | Offset | | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | ItemsAdder | `:name:`, or `%img_name%` through PlaceholderAPI | `:offset_-18:` (or `%img_offset_-18%`) | | Nexo or Oraxen | the glyph's PlaceholderAPI placeholder (for example `%nexo_%` or `%oraxen_%`), or the glyph's own character | the plugin's shift placeholder or character (see its docs) | | Your own pack | the character you gave the picture in your font file | a character of a `space` provider with a negative width | Menu titles use `&` colour codes, not MiniMessage, so tags such as `` or `` are shown as plain text. Use the PlaceholderAPI form or the raw character instead (PlaceholderAPI must be installed for `%...%`). ### Using your own font If you make the pack yourself, add the picture and a few negative spaces to a font, for example `assets/minecraft/font/default.json`. Use characters from Unicode's private use area, which no language uses: here U+E000 for the picture and U+F801, U+F808 and U+F810 for spaces of -1, -8 and -16 pixels. In the examples below, `` stands for that one character. In the JSON file write it as a JSON escape (a backslash, the letter `u` and the four hex digits `E000`), or paste the character itself. ```json { "providers": [ { "type": "space", "advances": { "": -1, "": -8, "": -16 } }, { "type": "bitmap", "file": "mypack:gui/mortar_upgrades.png", "ascent": 13, "height": 222, "chars": [""] } ] } ``` The picture goes in `assets/mypack/textures/gui/mortar_upgrades.png`. `height` is the height the picture is drawn at (222 = a 6-row chest window) and `ascent` how far it reaches above the title line (13 puts its top at the top of the window). `ascent` must never be larger than `height`, or the game ignores the whole font. In the menu file, write the same escapes inside a double-quoted YAML string (YAML only reads escapes between double quotes), or paste the characters. -16, -1 and -1 make the same 18 pixel offset as `:offset_-18:`: ```yaml title: "&f" ``` ### Text on top of the picture After the picture the cursor stands at its right edge, and anything written after it is drawn over the picture. Move back with another negative offset first, then write your text with a normal colour: ```yaml title: '&f:offset_-18::mortar_upgrades::offset_-150:&8{mortar}' ``` The title takes the EdMortars tokens (`{mortar}`, `{status}`...) and PlaceholderAPI placeholders. It is filled in when the menu opens and again when the menu redraws after a purchase. ## 2. Button textures Menu items use PinnaPrison's item format. These are the keys that matter for a pack: | Key | Use | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `material` | A vanilla material (`PAPER`...) or an item of your pack plugin: `itemsadder::`, `nexo:`, `oraxen:`. Pack plugin items bring their own model, so they need no `custom-model-data`. `texture-` makes a custom head and `head-` / `head-{player}` a player's head. An unknown material shows as a barrier. | | `custom-model-data` | The model number your pack gives that material, e.g. `20001`. Tokens and placeholders work here too. `-1` or empty means none. | | `tooltip-style` | A tooltip frame from your pack, `namespace:id` (Minecraft 1.21.2+). | | `hide-tooltip` | `true` shows no tooltip at all on hover (1.20.5+). The item can still be clicked. | | `glow` | The enchant shimmer, without a visible enchant. | | `color` | Tint for leather armour and potions: `'#RRGGBB'` or `'R,G,B'`. | PinnaPrison menus have no `item-model` key: choose the model with `custom-model-data`, or use an item of your pack plugin as `material`. ### Custom model data The number is read by the material's model in your pack. On Minecraft 1.21.4+ that is the item definition (for paper: `assets/minecraft/items/paper.json`, usually a `range_dispatch` on `custom_model_data`); older versions use `overrides` in `assets/minecraft/models/item/paper.json`. ItemsAdder, Nexo and Oraxen write these files for you: look up the number they gave your item, or use the item's id as `material`. ### Tooltip frames `tooltip-style: 'mypack:gold'` uses `assets/mypack/textures/gui/sprites/tooltip/gold_background.png` and `gold_frame.png` from your pack (with `.png.mcmeta` files that set nine-slice scaling, like the vanilla tooltip). Placeholders work here too, so one item can change its frame with the player's data. ### Invisible items A common trick is to draw the buttons into the background picture and put an invisible item on each button slot. Give those items a model with a fully transparent texture (a `custom-model-data` number your pack maps to an empty model). Add `hide-tooltip: true` to slots that should show nothing on hover, like the filler, and leave it out on buttons so players can still read their name and lore. ### A full button An upgrade button with its own icon and frame for each state: it can be bought, it can't be afforded, and it is maxed. ```yaml upgrade-chance: custom-item: type: 'edmortars-upgrade' upgrade: chance # the next level can't be afforded: a greyed icon and a plain frame unmet-item: material: PAPER custom-model-data: 20002 tooltip-style: 'mypack:locked' name: '&7{upgrade} &8(Lv. {level}/{max-level})' lore: - '&7Cost: &c{cost} {currency}' - '&7You need &c{needed} &7more.' # max level: a golden icon, the shimmer and a gold frame maxed-item: material: PAPER custom-model-data: 20003 glow: true tooltip-style: 'mypack:gold' name: '&6{upgrade} &8(&a&lMAXED&8)' lore: - '&7Chance: &6{value}%' slot: '20' # the normal look: the next level can be bought material: PAPER custom-model-data: 20001 tooltip-style: 'mypack:rare' click-sound: 'UI_BUTTON_CLICK' name: '&b{upgrade} &8(Lv. {level}/{max-level})' lore: - '&7Chance: &6{value}% &8→ &a{next-value}%' - '{progress-bar} &7{percent}%' - '&7Cost: &e{cost} {currency}' - '' - '&bClick to upgrade' ``` The `unmet-item` and `maxed-item` sections take every item key above. The same pattern works for `edmortars-requirement` and `edmortars-unlock` (`unmet-item`). For an item of your pack plugin, replace `material` and `custom-model-data` with one line, for example `material: 'itemsadder:mypack:mortar_upgrade'`. ## 3. Numbers drawn with textures EdMortars has no option that turns its numbers into pictures by itself: its tokens (`{level}`, `{cost}`, `{cooldown}`...) are plain text in the menu's font. You can still get a fully textured look with what is there. ### A model per value `custom-model-data` accepts tokens and PlaceholderAPI placeholders, so a button can change its model with a number: ```yaml material: KNOWLEDGE_BOOK custom-model-data: '{level}' ``` The button then has model data 0, 1, 2... by level, and your pack can show a different icon for each value, for example a badge with the level painted on it. Use a material that no other item of your menus uses, because these low numbers would clash with your other models, and map the values in that material's item definition, here `assets/minecraft/items/knowledge_book.json` (Minecraft 1.21.4+): ```json { "model": { "type": "minecraft:range_dispatch", "property": "minecraft:custom_model_data", "index": 0, "entries": [ { "threshold": 1, "model": { "type": "minecraft:model", "model": "mypack:item/level_1" } }, { "threshold": 2, "model": { "type": "minecraft:model", "model": "mypack:item/level_2" } }, { "threshold": 3, "model": { "type": "minecraft:model", "model": "mypack:item/level_3" } } ], "fallback": { "type": "minecraft:model", "model": "minecraft:item/knowledge_book" } } } ``` Each entry is used from its threshold up to the next one, and 0 falls back to the normal book. A PlaceholderAPI number works the same way, e.g. `custom-model-data: '%edmortars_level_chance_default%'`. ### A progress bar made of glyphs `{progress-bar}` writes `length` symbols: the filled part in the `filled` colour, the rest in the `empty` colour. The symbol is plain text, so it can be a glyph of your pack: ```yaml # plugins/EdMortars/config.yml menus: progress-bar: length: 10 symbol: "" filled: '&a' empty: '&8' ``` Here `` stands for a bar piece from your font and `` for a 1 pixel negative space, so the pieces touch (written as escapes inside double quotes, or pasted). Draw the piece in white: glyphs take the colour in front of them. Filled and empty pieces always use the same symbol; only their colour differs. ### Glyphs from PlaceholderAPI Titles, names and lore parse PlaceholderAPI, so a placeholder of another plugin that returns glyphs (for example a number written with your pack's digits) can be used anywhere in these menus. EdMortars' own placeholders (`%edmortars_level__%`...) return plain numbers. ## Checklist * Every player has your pack loaded (the server resource pack, or the hosting of your pack plugin), and it loads without errors. * `&f` is the first thing in the title, and the offset lines the picture up with the slots. * `tooltip-style` needs Minecraft 1.21.2+ and `hide-tooltip` 1.20.5+, on the server and on the player's game. Item definitions in `assets//items/` (such as `range_dispatch`) need 1.21.4+. * A barrier instead of your item means the `material` is misspelled, or its pack plugin isn't installed or doesn't know that id. * After editing the menu files run `/pinna reload`; after editing `config.yml` (`menus.progress-bar`) run `/edmortars reload`. After changing the pack, rebuild it with your pack plugin and rejoin so the game loads the new version.