imnyang/BlockModLoader
Archived
Watch
2
0
Fork
You've already forked BlockModLoader
 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Release BlockModLoader 1.0.0 with loader whitelist and recommendations

Browse source
This commit is contained in:
암냥 2026-10-05 14:02:51 +09:00
commit 43a421d224
1 changed files with 301 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

111
README.md
View file

@ -1,36 +1,96 @@
# BlockMelonLoader
# BlockModLoader
A .NET Framework 4.8 library with no Unity or MelonLoader dependency.
Call `BlockMelonLoader.LoaderGuard.EnsureAllowed("YourMod")` before initializing
a mod. Building this library does not require a game installation.
A .NET Framework 4.8 library with no Unity or mod loader dependency.
Call `BlockModLoader.LoaderGuard.EnsureAllowed("YourMod")` before initializing
a mod or game integration. Building this library does not require a game installation.
If an assembly named `MelonLoader` is loaded in the current AppDomain, the guard
shows a Windows error dialog and calls `Environment.FailFast` after dismissal.
Termination also happens if showing the dialog fails. On other platforms the
message is written to standard error before termination; there is no native dialog.
The guard does not inspect installation folders, modify loader files, or monitor
assemblies loaded after the check. UMM and MelonLoader running together are blocked.
By default, the guard blocks any of these loaded assemblies in the current AppDomain
(exact names, case-insensitive):
Add a `PackageReference` dependency on `BlockMelonLoader` version `1.0.0`.
Ship `BlockMelonLoader.dll` alongside your mod DLL; NuGet copies the runtime asset
to the consuming project's build output.
| Loader | Assembly names |
| --- | --- |
| MelonLoader | `MelonLoader` |
| BepInEx | `BepInEx`, `BepInEx.Core` |
| Unity Mod Manager (UMM) | `UnityModManager` |
This is an initialization guard, not a MelonLoader plugin. Simply placing the
UMM-only mod DLL in MelonLoader's Mods folder will not invoke the guard.
A bridge that invokes the UMM entry point is checked; direct assembly loading
without invoking that entry point is not. Modified binaries can bypass this check.
The BepInEx assembly names follow the [BepInEx 5 API](https://docs.bepinex.dev/api/index.html)
and [BepInEx 6 API](https://docs.bepinex.dev/master/api/index.html); UMM uses
[`UnityModManager`](https://github.com/newman55/unity-mod-manager/blob/master/UnityModManager/UnityModManager.csproj).
When a non-whitelisted supported loader is detected, the guard names it in a Windows error
dialog and calls `Environment.FailFast` after dismissal, terminating the entire
game process. Termination also happens if showing the dialog fails. On other
platforms the message is written to standard error before termination.
When multiple loaders are present, the first detected non-whitelisted loader triggers
one dialog and termination. Without a whitelist, all three loaders are blocked.
The guard checks only assemblies already loaded when `EnsureAllowed` is called.
It does not inspect installation folders, modify loader files, or monitor later
assembly loads. Names such as `MelonLoader.Helper` or `BepInEx.Helper` are not
matched. Renamed or modified loader binaries can bypass the check.
This is an initialization guard. Merely placing its DLL in a game or loader
folder will not invoke it: the consuming mod or game must call `EnsureAllowed`.
## Allowed loaders
Use `WhiteListLoader` to allow selected loaders for each guard call:
```csharp
using BlockModLoader;
// Allow BepInEx; block MelonLoader and UMM.
LoaderGuard.EnsureAllowed("YourMod", whiteListLoader: WhiteListLoader.BepInEx,
recommendedLoader: "BepInEx");
// Allow both BepInEx and UMM; block MelonLoader.
LoaderGuard.EnsureAllowed("YourMod", WhiteListLoader.BepInEx | WhiteListLoader.UMM);
```
Available values are `None`, `MelonLoader`, `BepInEx`, `UMM`, and `All`.
Combine values with `|`. `None` (the default for existing calls) blocks all three;
`All` allows all three. `BepInEx` allows both `BepInEx` and `BepInEx.Core`.
An allowed loader does not prevent detection of another blocked loader in the
same AppDomain. Unknown flag values throw `ArgumentOutOfRangeException`.
The whitelist applies only to these three known loaders; other assemblies are
still ignored. Each call supplies its own whitelist, with no shared global setting.
## Recommended loader in the alert
Pass an optional display name as the second argument to include a recommendation
in the alert:
```csharp
BlockModLoader.LoaderGuard.EnsureAllowed("YourMod", recommendedLoader: "YourPreferredLoader");
```
The alert adds `Recommended mod loader: YourPreferredLoader.` before the game
closure notice. Omit the second argument, or pass null, an empty string, or
whitespace, to keep the original generic guidance. Leading and trailing
whitespace is trimmed. This setting changes only the alert text; it does not
allow the recommended loader or change which loaders are blocked.
## Migration from BlockMelonLoader
Replace the `BlockMelonLoader` package reference with `BlockModLoader` version
`1.0.0`, update imports to `using BlockModLoader;`, and ship `BlockModLoader.dll`
alongside your mod DLL. NuGet copies the runtime asset to the consuming project's
build output. The `LoaderGuard.EnsureAllowed("YourMod")` method remains the same,
but now blocks BepInEx and UMM as well as MelonLoader.
## Build and test
On Windows, run `./build.ps1 -Test`. Visual Studio or Rider MSBuild is required;
use `-MSBuildPath` to select it explicitly. The script downloads .NET Framework
4.8 reference assemblies into the ignored `packages` folder when needed.
The DLL is written to `bin/Release/BlockMelonLoader.dll` and the NuGet package to
`artifacts/BlockMelonLoader.1.0.0.nupkg`. Packaging uses `NuGet.Build.Tasks.Pack`.
The DLL is written to `bin/Release/BlockModLoader.dll` and the NuGet package to
`artifacts/BlockModLoader.1.0.0.nupkg`. Packaging uses `NuGet.Build.Tasks.Pack`.
The standalone tests check detection, notification ordering, and dialog failure
handling. They substitute the dialog and termination callbacks and do not crash
the game. Run them directly with `Tests/bin/Release/BlockMelonLoader.Tests.exe`.
The standalone tests check every loader name, case-insensitive detection,
unrelated assemblies, multiple loaders, notification ordering, and dialog failure
handling, plus every whitelist combination and invalid flags.
They substitute the dialog and termination callbacks and do not crash
the game. Run them directly with `Tests/bin/Release/BlockModLoader.Tests.exe`.
## Installation
@ -40,16 +100,17 @@ The NuGet feed for this project is:
https://git.mizuki.guru/api/packages/imnyang/nuget/index.json
```
Add that feed to the consuming project's `NuGet.Config`, then add the dependency:
After the new package has been published to that feed, add it to the consuming
project's `NuGet.Config`, then add the dependency:
```xml
<PackageReference Include="BlockMelonLoader" Version="[1.0.0]" />
<PackageReference Include="BlockModLoader" Version="[1.0.0]" />
```
For local development, build this repository and use the generated `.nupkg` in
a local NuGet feed. The source repository is not required when building a consumer.
New library versions must use a new package version and update the consumer's
dependency version.
dependency version. The source repository is https://git.mizuki.guru/imnyang/BlockModLoader.
## License