SurtlingFuel ItemHopper Fix 1.2.1

• Feeds Surtling Cores, Black Cores, and configured core-like items through ItemHopper correctly.
• Preserves SurtlingFuel's multi-unit fuel value, speed boost, capacity checks, and coal/core no-mixing rule.
• Restricts every SurtlingFuel path to the vanilla smelter and blastfurnace prefabs.
• Protects Eitr Refineries and other Smelter-based machines with an owner-side RPC guard.
• Updates SurtlingFuel messages/effects and ItemHopper fuel/filter/pickup paths for Valheim 1.0.12.

1.2.1 startup hotfix

Fixes IL Compile Error / Unexpected null / Character::Message during server or client startup. Version 1.2.0's raw-IL adapters ran too late for this dependency-loading path. This release bypasses the affected legacy method bodies and preserves the existing configs. Replace 1.2.0 on the server and every client, then restart.

What it fixes

ItemHopper 2.0.0 normally accepts only the machine's vanilla fuel item and calls Valheim's RPC_AddFuel. SurtlingFuel 1.4.0 uses a different RPC and tracks how much of the current fuel came from cores. Changing only ItemHopper's item filter would therefore give the wrong fuel value and could mix coal with core fuel.

This add-on patches both ItemHopper checks:

Hopper item	Empty machine	Coal active	Core fuel active
Coal	Loads normally	Loads normally	Waits in hopper
Surtling Core	Loads	Waits in hopper	Loads
Black Core	Loads by default	Waits in hopper	Loads by default
Configured extra prefab	Loads	Waits in hopper	Loads

While core fuel is active, coal waits in the hopper. While coal is active, configured core items wait in the hopper. This preserves SurtlingFuel's no-mixed-fuel behavior. A full machine also leaves the item in the hopper.

Only the exact vanilla prefab names smelter and blastfurnace are allowed. Fuel type is not used as a substitute for machine identity.

Machine safety boundary

SurtlingFuel 1.4.0 attaches its logic to Valheim's shared Smelter class. The Eitr Refinery also uses that class, so checking only the class or ordinary fuel item is too broad.

This add-on replaces SurtlingFuel's five dynamic Smelter patches with allowlist-guarded equivalents and registers its own guarded core-fuel RPC receiver. The allowlist is deliberately fixed:

Internal prefab name	Core fuel allowed?
smelter	Yes
blastfurnace	Yes
eitrrefinery	No
Any other or unknown Smelter prefab	No

The restriction covers:

• manual E-key fuel selection and explicit-item fueling;
• owner-side/network RPC_SurtlingFuel_AddCoreFuel handling;
• Surtling Core additions to hover text;
• speed multiplier and core-fuel state maintenance;
• SurtlingFuel's fuel-per-core lookup;
• ItemHopper acceptance and transfer.

During machine initialization, any existing core-fuel RPC registration is removed. Only allowed machines receive the replacement handler, which rechecks machine identity, network ownership, capacity, and coal/core separation before changing fuel. Direct calls to the replacement handler receive the same checks.

If an older release already left a SurtlingFuel core-state marker on a disallowed machine, this release clears that marker on the network owner. It preserves Valheim's generic stored fuel amount; any remaining fuel runs without SurtlingFuel's core speed/state behavior.

Valheim 1.0 compatibility

Version 1.2.1 was compiled and inspected against supplied Valheim 1.0.12 game assemblies and the matching BepInEx core. It repairs these concrete dependency changes:

• SurtlingFuel 1.4.0 calls removed message and effect overloads. Manual fueling and the core-fuel receiver now use code compiled against the current methods, without patching or executing those broken dependency bodies.
• ItemHopper's filter icons used the removed InventoryGrid.Element type. Its filter display now uses the current InventoryElement API.
• ItemHopper's pickup dispatch routes honey and dropped items through current inventory methods. Failed insertion leaves the source intact; a refused dropped-item removal rolls back its insertion.
• Hopper fuel checks and transfers use cached access to the private network view. Both coal and cores use the current RPC signatures.
• Hopper ore delivery now sends the new required provenance flag from the actual source item and checks successful removal before sending.
• Receiving owners recheck coal/core separation and reject nonpositive core-fuel requests.

These are runtime compatibility patches. The package does not contain altered game or dependency DLLs. It does not change achievement settings or clear item metadata. The inspected game's fuel RPC has no cheated argument; the bridge preserves that actual API.

Black Core behavior

SurtlingFuel 1.4.0 itself recognizes only SurtlingCore. This add-on deliberately includes BlackCore in its server-synced hopper list, because that was part of the requested behavior.

A Black Core loaded by a hopper receives the same fuel amount and speed boost as a Surtling Core. This add-on does not change manual E-key fueling, so Black Cores are hopper-only unless another installed mod also supports them manually. Remove BlackCore from the config if you do not want hoppers to consume them.

Multiplayer requirement

Install 1.2.1 on the dedicated server and every client. A hopper can update on the current network owner. Jötunn now checks the patch version too, preventing a broken 1.2.0 client from taking over machine processing.

Additional Fuel Prefabs is server-synced and admin-only. SurtlingFuel 1.4.0 does not synchronize its own balance settings, so keep its SmelterFuelPerCore, BlastFurnaceFuelPerCore, and SpeedMultiplier values identical on the server and clients.

Requirements and checked versions

• Valheim 1.0.12
• BepInExPack Valheim 5.4.2350
• Jötunn 2.30.0
• ItemHopper 2.0.0
• SurtlingFuel 1.4.0

The DLL compiles against the supplied game and core files. Version 1.2.0's exact startup error was reproduced under standalone Mono. Version 1.2.1 passes Harmony wrapper generation for all 16 patched targets and 12 fuel-validation cases. Full Unity/Valheim detour installation, gameplay, and multiplayer still need an in-game test. Run the copied-profile checks below before publishing or updating the main world. ItemHopper also requires MultiUserChest through its own dependency manifest; keep that dependency installed and current. See VALIDATION.md for exact checked versions and remaining limits.

Install with Thunderstore Mod Manager or r2modman

1. Download this ZIP without extracting it.
2. Open the Valheim profile that contains ItemHopper and SurtlingFuel.
3. Open Settings and choose Import local mod.
4. Select SurtlingFuelItemHopperFix-1.2.1.zip.
5. Put the same version on every client and the dedicated server.
6. Launch once to generate the config.

For a manual installation, place SurtlingFuelItemHopperFix.dll in BepInEx/plugins/SurtlingFuelItemHopperFix/ on the server and every client.

Config

Generated at:

BepInEx/config/local.valheim.surtlingfuelitemhopperfix.cfg

Setting	Default	Purpose
Fuel / Additional Fuel Prefabs	BlackCore	Server-synced prefab-name list. SurtlingCore is always enabled; Coal is always ignored.

Separate entries with commas, semicolons, or new lines. Example:

BlackCore, MyCustomCore

Use internal prefab names, not localized display names. Every extra item uses SurtlingFuel's core fuel value; there is no separate multiplier per item.

Copied-profile test

1. Aim an ItemHopper output at an empty smelter. Put one Surtling Core in the hopper.
2. Confirm the core leaves the hopper and the smelter gains the configured SurtlingFuel amount, not one vanilla coal unit.
3. Repeat steps 1–2 with a blast furnace, then repeat with one Black Core in each allowed machine.
4. While core fuel remains, put coal in the hopper. Confirm the coal waits and is not deleted; then reverse the order and confirm the core waits for coal to reach zero.
5. Fill an allowed machine, then put a core in the hopper. Confirm it remains in the hopper.
6. Aim a hopper at an Eitr Refinery and insert a Surtling Core and Black Core. Confirm both stay in the hopper.
7. Try to add a Surtling Core to the Eitr Refinery manually. Confirm it is rejected and its hover text does not advertise Surtling Cores.
8. Confirm an operating Eitr Refinery has no SurtlingFuel speed boost or core-fuel state, while smelter/blast-furnace core fuel still receives the configured boost.
9. Repeat on a dedicated server with a non-admin client and check both client and server BepInEx logs for red errors.
10. Open a hopper with filtering enabled and verify ghost icons display in the correct slots. Test picking up one dropped item and one honey item into an available hopper slot.
11. Test two nearby players with changing machine ownership. The existing remove-then-RPC transfer protocol is not an acknowledged transaction; simultaneous requests or a disconnect during transfer still require a live check.
12. Feed an ordinary ore through a hopper. Confirm it enters the smelter/blast-furnace queue and smelts normally. Test on a copied world that existing cheated-item flags remain preserved rather than being reset.

Uninstall

Remove this package from the server and every client, then restart. It creates no items, recipes, or pieces. Removing it also removes these Valheim 1.0 compatibility patches; the inspected upstream releases then regain their original API errors and unguarded shared-Smelter behavior. SurtlingFuel's own stored core marker belongs to SurtlingFuel.

Source is included under src/ and released under the MIT License. See CONFIG_REFERENCE.md, SOURCE_RESEARCH.md, and THUNDERSTORE_LISTING.md for the complete details.