Installation

Use Paper 26.3, Java 25, Packforge and a current Geyser build supporting custom items and spear components. No extra gameplay plugin or datapack is needed.

Locate egw_gems in the Complete ZIP and install that content folder in Packforge. The mapping and Bedrock pack are under the bundle’s Geyser/ folder.

Updating from 1.0.1 or 1.0.2

Install the current gem configs and run /pf reload or restart Paper. Grant pf.recipe.gems to the players who should be able to craft the set.

Updating from 1.0.0

Replace the matching gem configs, rebuild with /pf zip, and update the Geyser mapping and Bedrock pack. Remove the previous copy of this Bedrock pack, restart Geyser, and reconnect clients. Check fresh gear as well as existing items after the update.

Packforge and Java

Install the egw_gems content folder in plugins/Packforge/contents/. Keep configs/emerald.yml, configs/amethyst.yml and the adjacent item, model, texture and equipment folders together.
Run /pf zip from the server, let it finish, and publish/serve the resulting combined resource pack through your existing hosting setup. Check the console for errors about egw_gems.
Java players accept the combined pack. The separate Java ZIP contains these same assets for manual testing or pack stacking; it does not need to replace your existing combined pack.

Items use item_model: egw_gems:<item>. There are no custom model data numbers to allocate. The supplied definitions include stats, repairs, equipment assets and mining rules.

Allow regular players to craft

The current pack’s recipes use the gems permission suffix. Grant regular players pf.recipe.gems, for example with LuckPerms:

/lp group default permission set pf.recipe.gems true

Omit the slash in the console. If your regular-player group does not inherit default, grant it the same node. This allows all 20 gem equipment recipes for Java and Bedrock players without granting admin commands. Test with a non-op account. See the crafting correction (included in the release package).

Geyser and Bedrock

Put egw_gems.json into Geyser's custom_mappings directory. For Geyser-Spigot, this is normally plugins/Geyser-Spigot/custom_mappings/.
Put GrimsGemEquipment-Bedrock-1.0.3.mcpack into the same Geyser instance's packs directory. Keep only one copy of this pack/version there.
Merge these settings into the existing Geyser config:
```
gameplay:
  enable-custom-content: true
  force-resource-packs: true
```
Do not create a second gameplay section. The second setting requires pack acceptance; it can be omitted if pack downloads are intentionally optional.
Fully restart Geyser (restart Paper too when Geyser runs as its plugin). Bedrock clients must reconnect and accept the pack. If Geyser runs on a proxy, put the mappings and pack on the proxy's Geyser instance.

The mappings register all 20 items, their durability, armor display points, repair materials, mining rules, and spear charge overrides. The Bedrock pack supplies 20 inventory icons, eight worn armor attachables, and two spear attachables. Crafting recipes come from Paper/Packforge through Geyser. No Bedrock behavior pack is used.

Getting test items

Use /pf give <player> egw_gems:emerald_helmet or /pf give <player> egw_gems:amethyst_pickaxe as an administrator. Available suffixes for both materials:

helmet chestplate leggings boots pickaxe axe shovel hoe sword spear

Place vanilla emeralds or amethyst shards and sticks in a crafting table. Players need pf.recipe.gems. Test with a non-op account as well as an administrator.

Server acceptance checks

Static validation is included in VALIDATION.md. These checks still need real clients:

Confirm /pf zip loads 20 items and all recipes with no errors. Join with Java 26.3 and a supported Bedrock client; check all inventory icons, tools in hand, and worn armor on yourself and another player. Check both normal and slim skins.
Craft both armor sets and all tools with an ordinary player. Check shifted helmet/boot recipes, mirrored axes/hoes/spears, shift-click crafting, ingredient consumption, and Bedrock recipe-book output.
Equip a complete set. On Java, /attribute @s minecraft:armor get should report 18 and /attribute @s minecraft:armor_toughness get should report 4 when no other modifiers apply. A mixed emerald/amethyst set must give the same results. Unequipping a piece must remove its contribution.
Check a fresh item's durability against STATS.md, damage it, and verify normal breakage at zero. Test gem/shard anvil repair, combining two damaged matching items, enchanting, Unbreaking, and Mending. Repeat repairs from Bedrock.
Check the pickaxe harvests diamond ore but not obsidian/ancient debris; check matching tool mining, log stripping, path making, and tilling. Compare Java and Bedrock mining completion.
Check spear first/third person appearance, jab, hold/charge, and mounted use on both editions. Geyser's custom spear behavior and animations depend on the installed Geyser/client versions.
Rejoin after damage, enchantment, and repair: each item must retain its gem texture and durability.

Visual limits

Version 1.0.2 declares pbr in the Bedrock manifest, following Microsoft's Vibrant Visuals requirements. The earlier pack omitted this compatibility declaration. This pack supplies no global lighting, fog, water, or color-grading overrides, and adds no custom PBR material maps. Verify Vibrant Visuals remains selectable after joining and that worn armor, held tools, and enchantment glint render correctly. A supported device and compatible full pack stack are still required; this has not been tested in a live Bedrock client.

Java keeps the source armor trim item models and equipment layers. The Bedrock armor attachables currently render the base gem texture and enchantment glint; matching custom trim overlays are not implemented. Basic protection and durability are server-side and unaffected. Horse and nautilus armor are outside this release's scope.

Troubleshooting

Java shows iron or missing textures: verify Packforge loaded the egw_gems folder, rebuild with /pf zip, and refresh the served combined pack. While holding a test item, inspect /data get entity @s SelectedItem.components; minecraft:item_model should be egw_gems:<item>, and worn armor should have the correct minecraft:equippable.asset_id.
Bedrock shows iron: check that mappings loaded at Geyser startup and custom content is enabled. Item models must match the mapping exactly. Remove old duplicate mappings for these identifiers.
Bedrock icons work but worn armor does not: verify the Bedrock pack was accepted and attachable identifiers match egw_gems:<item>. Refresh the cached pack and reconnect.
For wrong protection or repair behaviour, inspect minecraft:attribute_modifiers, minecraft:max_damage and minecraft:repairable on a fresh item. Another item or stat plugin may be replacing these components.

Regular-player crafting correction: 1.0.3

All 20 recipes in the current pack are covered by pf.recipe.gems.

Install the correction

Install the current emerald.yml and amethyst.yml together with the matching pack assets.
Run /pf reload or restart Paper to reload the recipe definitions.
Run /lp group default permission set pf.recipe.gems true as an administrator. Omit the slash in the console. If players use another group, grant that group the permission. This grants crafting, not admin item-give commands.
Test manual crafting and the recipe book on Java and Bedrock with a non-op account. Check the grant with /lp user PLAYER permission check pf.recipe.gems.

If upgrading from 1.0.2, no Java/Bedrock texture or Geyser mapping update is needed for this correction. Item stats, durability, ingredients, recipe patterns, and Vibrant Visuals compatibility are unchanged. Existing gear does not need replacement.

Verification and limits

The generated files are checked for all 20 explicit suffixes and unchanged gameplay/texture data. No live server permissions were changed; the grant above is a required installation step. Actual non-op crafting still requires testing on the server.

If crafting still fails, confirm the current configs loaded, recipes are enabled, and no protection or recipe plugin cancels the action. Seeing a recipe and being permitted to take its result are separate checks.

Grims Gem Equipment