Valheim.Testing.Bindings.Tool 0.1.0

Valheim.Testing.Bindings

API reference. This page covers the library and its valheim-bindings tool.

Check offline that a built mod's references into the game still bind.

Purpose

A game update can remove, rename or retype a member your mod uses. The mod then throws MissingFieldException, MissingMethodException or TypeLoadException. It throws only when the runtime first compiles a method that uses the member, possibly hours into play.

This check reads your mod DLL with Mono.Cecil. It resolves every type, field and method the mod references in the game assemblies you supply. For each reference that no longer binds, it names the mod methods that use it. It loads and runs nothing, and needs no game process.

• Valheim.Testing.Bindings (netstandard2.0) is the library. BindingCheck.Check(modPath, options) returns a BindingReport.
• Valheim.Testing.Bindings.Tool (net10.0) is the valheim-bindings .NET tool for CI.

Install

Install the tool into .tools. Then point it at your built mod and the game's Managed directory:

dotnet tool install Valheim.Testing.Bindings.Tool --version 0.1.0-rc.1 --tool-path .tools
.tools/valheim-bindings MyMod/bin/Release/MyMod.dll --game-dir "path/to/valheim_Data/Managed"

The tool prints one report per mod. Each report's last line starts with PASS:, FAIL: or INCOMPLETE:. The tool then exits with one of the exit codes.

Options

valheim-bindings <mod.dll>... (--game-dir <dir> | --game-file <file>)... [options]

Name one or more mod DLLs. Supply at least one --game-dir or --game-file.

The client's valheim_Data/Managed holds assembly_valheim, assembly_utils, the Unity modules and the framework the game runs on. Add BepInEx/core for BepInEx and Harmony. assembly_valheim is always required when the mod references it. If your path is wrong, the check therefore fails instead of checking nothing.

Exit codes

A mod that cannot be read gives exit 2 with the reason, never an unhandled crash. The tool still checks the other mods. With several mods, the tool exits with the highest code among them.

What is checked

The check looks up references the way the runtime binds them:

References come from method bodies, signatures, locals and catch clauses. They also come from base types, interfaces, generic constraints and explicit overrides. Attributes count, including typeof(...) arguments, as do the module's reference tables. Byref, arrays and their rank, pointers, generic instances and modifiers must match exactly.

Each missing reference appears once, with every mod member that uses it. When it helps, the finding also shows what the assembly has instead: other overloads, the field's new type, or a property that became a field. Suppose a lookup reaches a base type in an assembly you did not supply, such as a game type's MonoBehaviour base. The member is then still reported missing, with a note that it was not searched there.

Publicized assemblies and access

Mods often compile against publicized game assemblies, where every member is public. Checked against the real assemblies, each private reference is an access finding. So access findings never fail the check by default. An access finding is info if the mod carries [assembly: IgnoresAccessChecksTo("<assembly>")] for that assembly, and a warning otherwise. --fail-on-access fails on warnings only.

If you check against the publicized copy you built with, the check still finds removals. It reports no access findings.

A mod compiled against a publicized assembly that reads a private game member at run time needs AllowUnsafeBlocks=true in its project. [assembly: IgnoresAccessChecksTo("assembly_valheim")] alone passes --fail-on-access but throws FieldAccessException at run time. --fail-on-access can also warn on a mod whose private access works:

The check classifies metadata and does not test run-time permissions. Before you rely on private access, make a real call against the original game assembly.

From a test

var options = new BindingCheckOptions();
options.GameDirectories.Add(managedDirectory);
BindingReport report = BindingCheck.Check(modDll, options);
Assert.Empty(report.MissingRequired);
Assert.True(report.Binds, string.Join("\n", report.Missing.Select(f => $"{f.Member}: {string.Join(", ", f.UsedBy)}")));

To get the tool's exit code and report text instead, call BindingCheckCommand.Run(string[] args, TextWriter output, TextWriter error) with the same arguments the tool takes.

In CI

Run the check in the job that builds the plugin, since both need the game's assemblies. Run it before anything launches the game. See Run tests in CI for the workflow step.

Limits

• The check covers metadata references only. It misses name lookups at run time: Harmony's [HarmonyPatch(typeof(T), "Method")], AccessTools (nameof compiles to a string), reflection, and Jötunn or prefab names.
• It misses type-shape changes that fail when a mod type loads, such as a new interface member, a sealed base or a new abstract member.
• It misses generic constraint changes.
• If an attribute argument names an enum from an assembly it cannot find, the check notes it and skips the types in that attribute's arguments.
• A pass means the checked references bind. It does not mean the mod behaves correctly with the new game version.

Mono.Cecil is MIT-licensed (Jb Evain, Novell); see THIRD-PARTY-NOTICES.md in the package.

Unofficial community tooling; not affiliated with or endorsed by Iron Gate or Coffee Stain. Valheim is a trademark of Iron Gate AB.