1. Server

Install the Recipe Item Sync JAR matching your Minecraft version in the server's mods folder.

2. Client

Install the matching Recipe Item Sync build and at least one supported recipe viewer. The client does not need a copy of the datapack itself.

3. Datapack

Keep the datapack installed on the server as normal. Recipe Item Sync discovers supported content from the server and synchronizes the relevant ItemStacks and metadata.

4. Resource pack

5. First test

1. Start the server.
2. Join with a client containing Recipe Item Sync and a supported recipe viewer.
3. Search for one of the custom datapack items.
4. If it does not appear, run /recipeitemsync status.

Configuration file

The v3 configuration is stored at:

config/recipeitemsync/recipeitemsync.json

If this file does not exist but the older config/recipeitemsync/server/recipeitemsync.json file is present, v3 migrates it automatically.

Default configuration

{
  "viewerPreference": "auto",
  "namespaces": [],
  "manualVirtualItems": []
}

viewerPreference

Controls which supported recipe viewer receives Recipe Item Sync content.

Blank or invalid values fall back to auto.

namespaces

The namespace list acts as an optional allow-list. Leave it empty to allow every eligible namespace.

{
  "viewerPreference": "auto",
  "namespaces": [
    "stellarity",
    "my_datapack"
  ],
  "manualVirtualItems": []
}

Wildcard-style entries such as stellarity:* are also accepted.

When should I use resync?

A resync is useful after modifying datapack content or the Recipe Item Sync configuration when you want to immediately rebuild the current snapshot for connected players.

Diagnostic dump

If an item or recipe is missing, /recipeitemsync dump is the most useful command to run before making a bug report.

Manual virtual items

Automatic discovery should be preferred. manualVirtualItems can expose a specific virtual ItemStack when the normal datapack source cannot be discovered.

{
  "viewerPreference": "auto",
  "namespaces": [],
  "manualVirtualItems": [
    {
      "virtualId": "my_pack:ancient_relic",
      "hostItem": "minecraft:paper",
      "customModelData": 1001,
      "displayName": "Ancient Relic",
      "tooltip": [
        "A manually exposed datapack item"
      ]
    }
  ]
}

Datapack author recommendations

• Use stable recipe and loot-table identifiers.
• Keep output ItemStacks deterministic whenever possible.
• Use standard data components for names, lore, CustomModelData, and custom data.
• Keep visual assets in a separate client resource pack.

Custom item-entity crafting

Static item-entity crafting systems can be exposed when Recipe Item Sync can safely determine the required inputs, exact dropped-item counts, and a deterministic output.

Recipe viewer differences

What cannot always be represented?

Arbitrary mcfunction systems may depend on scoreboards, random state, entity state, command chains, or other runtime logic. Recipe Item Sync only exposes a custom system when its inputs and outputs can be represented safely and deterministically.

My custom item does not appear

1. Confirm that server and client use the correct Recipe Item Sync build.
2. Confirm that the client has a supported recipe viewer installed.
3. Run /recipeitemsync status.
4. Run /recipeitemsync dump.
5. Check that namespaces is not filtering the datapack out.
6. Run /recipeitemsync resync all.
7. Check both server and client logs for Recipe Item Sync messages.

The item appears with the wrong texture

This is normally a resource-pack issue. Recipe Item Sync transfers ItemStacks and recipe metadata, not textures or models.

The datapack uses commands or functions

Command-driven systems are only supported when the required input and deterministic output can be inferred safely. Highly dynamic mcfunction logic may not produce a displayable recipe.

After /reload

Recipe Item Sync is designed to rebuild supported datapack content after reloads without leaving stale duplicate entries. If the viewer does not refresh correctly, run /recipeitemsync resync all and inspect the logs and dump.

Known limitations

• Virtual datapack items are not registered as normal registry items.
• Resource-pack assets are not synchronized.
• Highly custom modded recipe types may expose an output without a safe recipe layout.
• Dedicated custom categories are not identical across JEI, REI, and EMI.

Bug reports

Please include:

• Minecraft version.
• NeoForge version.
• Recipe Item Sync version.
• Recipe viewer and version.
• Server and client logs.
• The output generated by /recipeitemsync dump, if possible.