If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/LavaGang/MelonLoader shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit today
• 11 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 79% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live LavaGang/MelonLoader repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/LavaGang/MelonLoader.

What it runs against: a local clone of LavaGang/MelonLoader — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in LavaGang/MelonLoader | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of LavaGang/MelonLoader. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/LavaGang/MelonLoader.git
#   cd MelonLoader
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of LavaGang/MelonLoader and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "LavaGang/MelonLoader(\\.git)?\\b" \\
  && ok "origin remote is LavaGang/MelonLoader" \\
  || miss "origin remote is not LavaGang/MelonLoader (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "Dependencies/CompatibilityLayers" \\
  && ok "Dependencies/CompatibilityLayers" \\
  || miss "missing critical file: Dependencies/CompatibilityLayers"
test -f "BaseLibs/MonoBleedingEdgePatches" \\
  && ok "BaseLibs/MonoBleedingEdgePatches" \\
  || miss "missing critical file: BaseLibs/MonoBleedingEdgePatches"
test -f ".github/workflows/compile_windows.yml" \\
  && ok ".github/workflows/compile_windows.yml" \\
  || miss "missing critical file: .github/workflows/compile_windows.yml"
test -f "Dependencies/Dotnet/linux/x86_64/shared/Microsoft.NETCore.App/6.0.25" \\
  && ok "Dependencies/Dotnet/linux/x86_64/shared/Microsoft.NETCore.App/6.0.25" \\
  || miss "missing critical file: Dependencies/Dotnet/linux/x86_64/shared/Microsoft.NETCore.App/6.0.25"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/LavaGang/MelonLoader"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MelonLoader is a universal mod loader for Unity games that injects into and patches both Il2Cpp and Mono runtime environments, allowing community-created plugins and mods to extend game functionality without source code modification. It handles game hooking, mod lifecycle management, and provides compatibility layers across Windows, Linux, and macOS platforms. Monorepo structure with BaseLibs/ housing pre-patched Mono assemblies and .NET Standard compatibility layers, Dependencies/ managing external libs, and main source organized by subsystem (likely in src/ directory not fully shown here). CI/CD is multi-platform: separate workflows for Windows/Linux/macOS compilation, NuGet publishing, and Thunderstore distribution indicate modular build pipeline.

Game modders and plugin developers who want to create mods for Unity-based games (both Il2Cpp and Mono), and game communities that need a standardized loader to manage third-party extensions. Power users running modded games also use this to organize and load multiple mods seamlessly.

Actively maintained and production-ready — the project has significant community adoption (shown by nightly builds on master, alpha-development, and universality branches), comprehensive CI/CD workflows across Windows/Linux/macOS, and organized issue/release infrastructure. Presence of BaseLibs with patched Mono assemblies and multiple compatibility layers indicates battle-tested runtime handling.

Core risk is the complexity of runtime patching across two fundamentally different .NET runtimes (Il2Cpp vs. Mono), which requires careful version management and platform-specific handling. The reliance on custom Mono patches (MonoBleedingEdgePatches/) creates maintenance burden; breaking changes in Unity versions or .NET could cascade across all dependent mods. Single-organization governance (LavaGang) but healthy contributor count mitigates maintainer burnout risk.

Active development across three branches (master for stable, alpha-development for next version, universality for experimental features). Workflow files (compile_all.yml, compile_windows.yml, etc.) show continuous integration on every commit. Recent GitHub Actions setup includes Dependabot integration (dependabot.yml) for dependency updates and stale issue management (stale.yml), indicating mature DevOps practices.

Clone and examine structure: git clone https://github.com/LavaGang/MelonLoader.git && cd MelonLoader. Build targets are Windows/Linux/macOS via GitHub Actions workflows (see .github/workflows/compile_*.yml). Consult Dependencies/ and BaseLibs/ folders to understand binary compatibility layers. Reference TestPlugin (https://github.com/LavaGang/TestPlugin) and TestMod (https://github.com/LavaGang/TestMod) example projects to understand mod/plugin authoring.

Daily commands: No traditional 'dev server' — this is a game injection tool. Build via GitHub Actions workflows or locally using MSBuild on Windows or build scripts inferred from workflow YAML. Output produces MelonLoader.Installer executable (seen in releases) that patches game installations. Test by running installer against a target Unity game; logs write to MelonLoader/Logs/ in game directory.

• .github/workflows/build.yml — Primary CI/CD build pipeline orchestrating compilation for Il2Cpp and Mono across Windows, Linux, and macOS platforms—essential for understanding release automation
• Dependencies/CompatibilityLayers — Core abstraction layer wrapping multiple game mod loader frameworks (IPA, Demeo, Muse Dash, Stress Level Zero)—critical for understanding plugin compatibility strategy
• BaseLibs/MonoBleedingEdgePatches — Patched system assemblies for Mono runtime compatibility—foundational for understanding Il2Cpp and Mono runtime support differences
• .github/workflows/compile_windows.yml — Windows-specific compilation workflow defining build steps, artifact generation, and platform-specific optimizations
• Dependencies/Dotnet/linux/x86_64/shared/Microsoft.NETCore.App/6.0.25 — Embedded .NET 6.0 runtime for Linux—critical for cross-platform deployment and understanding runtime dependencies
• CHANGELOG.md — Historical record of versioning, breaking changes, and feature evolution—essential for understanding project stability and API contracts
• .editorconfig — Code style and formatting standards enforced across C# projects—foundational for contribution consistency

Add Support for a New Game Framework

1. Create a new directory under Dependencies/CompatibilityLayers/{GameName} (Dependencies/CompatibilityLayers/{GameName})
2. Create a .csproj file referencing the target framework (e.g., Dependencies/CompatibilityLayers/{GameName}/{GameName}.csproj) (Dependencies/CompatibilityLayers/{GameName}/{GameName}.csproj)
3. Implement Module.cs as the entry point for your compatibility layer, following the pattern in Dependencies/CompatibilityLayers/IPA/Module.cs (Dependencies/CompatibilityLayers/{GameName}/Module.cs)
4. Create wrapper classes (e.g., {GameName}ModWrapper.cs) that implement MelonLoader interfaces and delegate to the game's native plugin API (Dependencies/CompatibilityLayers/{GameName}/{GameName}ModWrapper.cs)
5. Add a build step in .github/workflows/compile_windows.yml, compile_linux.yml, and compile_macos.yml to compile your new compatibility layer (.github/workflows/build.yml)

Update Runtime Patches for Mono Compatibility

1. Identify the failing System assembly (e.g., System.Core.dll) (BaseLibs/MonoBleedingEdgePatches/System.Core.dll)
2. Patch the assembly using a .NET assembly editing tool (dnlib or mono-cecil) to add or fix compatibility shims (BaseLibs/MonoBleedingEdgePatches)
3. Replace the old .dll in BaseLibs/MonoBleedingEdgePatches with the patched version (BaseLibs/MonoBleedingEdgePatches)
4. Test by running MelonLoader on a Mono-based game and verify the fix in logs (.github/workflows/compile_linux.yml)

Add a New Platform Build Target

1. Create a new workflow file following the pattern of compile_windows.yml or compile_linux.yml (.github/workflows/compile_{platform}.yml)
2. Define platform-specific environment variables (e.g., DOTNET_ROOT, architecture flags) (.github/workflows/compile_{platform}.yml)
3. Reference the new workflow in .github/workflows/build.yml as a reusable workflow job (.github/workflows/build.yml)
4. For runtime dependencies, add the corresponding architecture folder under Dependencies/Dotnet/{platform}/{arch}/ (Dependencies/Dotnet/{platform}/{arch}/shared/Microsoft.NETCore.App/6.0.25)
5. Update .github/workflows/upload_github.yml to include artifacts from the new platform (.github/workflows/upload_github.yml)

• C# with .NET 6.0 & Mono runtime — Unity games use .NET; MelonLoader must run on both Il2Cpp (JIT via Mono wrapper) and Mono runtimes for universal compatibility
• GitHub Actions (multi-platform workflows) — Enables automated compilation and testing on Windows, Linux, and macOS to verify cross-platform build integrity
• Embedded .NET runtime (Dependencies/Dotnet) — Ships bundled .NET 6.0.25 to avoid external runtime installation; guarantees version consistency across all game installations
• Patched Mono assemblies (BaseLibs/MonoBleedingEdgePatches) — Legacy games use older Mono versions; patches provide forward compatibility with modern C# features and fix runtime bugs
• Compatibility layer adapter pattern (IPA, Demeo, etc.) — Isolates game-specific plugin APIs behind a unified Mel

Runtime patching timing: Mono vs. Il2Cpp games hook differently; your mod must detect which runtime runs and adapt. BaseLibs versioning: MonoBleedingEdgePatches are locked to specific Mono versions — updating .NET libs requires repatching those DLLs or your mods break. File paths: Logs, Plugins, Mods folders are created at game installation directory, not repo root — tests must mock filesystem or use real game dirs. No local dev game: You cannot easily test the loader without a target Unity game; use provided TestPlugin/TestMod repos with a dummy game or Unity Editor. Assembly conflicts: Loading mods can cause .NET assembly version conflicts if multiple mods reference incompatible versions of the same library.

• Runtime Hooking / API Trampolining — MelonLoader injects hooks into game methods without source code; understanding how trampolines intercept calls before invoking original logic is essential to grasp how mods intercept game behavior
• Il2Cpp vs. Mono Runtime Differences — The core challenge MelonLoader solves is supporting both runtimes; Il2Cpp compiles C# to C++ (requires different metadata access), Mono is JIT-compiled — knowing their differences explains why CompatibilityLayers exist
• Assembly Injection / Dynamic Loading — MelonLoader loads plugin/mod DLLs at runtime into the game process; understanding AppDomain (or .NET 5+ AssemblyLoadContext) is critical for troubleshooting version conflicts and mod isolation
• Process Patching / Code Instrumentation — Game executables are patched before launch (seen in MelonLoader.Installer); understanding PE file format modification and inline hooking prevents breaking changes when games update
• Compatibility Layers / Adapter Pattern — BaseLibs/ uses patched assemblies as adapters hiding runtime differences from mods; this design pattern (Strategy/Adapter) is why the same mod code works on both Il2Cpp and Mono games
• Cross-Platform Binary Compatibility — Separate compile workflows for Windows/Linux/macOS with different native hooking code (.cpp files); knowing platform-specific ABI constraints helps debug 'works on Windows, breaks on Linux' mod issues
• Reflection & Metadata Access — Mods use IL2CPP.Bind() or Mono reflection to locate game classes/methods at runtime; understanding IL (Intermediate Language) metadata format explains why Il2Cpp requires special handling vs. Mono

• LavaGang/TestPlugin — Official example plugin project demonstrating MelonLoader plugin authoring and how to hook into OnInitializeMelon() lifecycle
• LavaGang/TestMod — Official example mod project showing how to create mods using MelonLoader's modding API and mod.json manifest format
• LavaGang/MelonLoader.Installer — Companion installer tool that patches game executables and deploys MelonLoader; sources the downloadable MelonLoader.Installer.exe seen in releases
• BepInEx/BepInEx — Alternative mod loader for Unity games (Mono-focused); many games support both loaders, understanding BepInEx's approach illuminates design trade-offs in MelonLoader
• protobuf-net/protobuf-net — Likely used in Dependencies/ for serializing mod metadata or game state; understanding its schema is relevant for mod compatibility versioning

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add compatibility layer tests for IPA plugin wrapper

The Dependencies/CompatibilityLayers/IPA folder contains critical plugin compatibility code (IPA/IPAPluginWrapper.cs, IEnhancedPlugin.cs, IPlugin.cs) but there are no visible unit tests. Since IPA is a legacy mod loader with different plugin signatures, regression tests would ensure compatibility doesn't break during MelonLoader updates. This is high-value because IPA compatibility is a core feature mentioned in the repo description.

• [ ] Create Tests/CompatibilityLayers/IPA directory with xUnit test project
• [ ] Add tests for IPAPluginWrapper.cs covering plugin initialization and lifecycle methods
• [ ] Add tests for ModPrefs.cs covering configuration read/write operations
• [ ] Add tests for PluginManager.cs covering plugin discovery and loading
• [ ] Integrate test project into compile_all.yml workflow

Create platform-specific documentation for Il2Cpp vs Mono compatibility

The repo advertises being 'compatible with both Il2Cpp and Mono' but there's no dedicated documentation explaining the technical differences, limitations, or best practices for each. The Dependencies/CompatibilityLayers structure shows complex platform-specific handling (MonoBleedingEdgePatches, NetStandardPatches), but this isn't documented. New contributors need clarity on what code paths handle what scenarios.

• [ ] Create docs/compatibility/IL2CPP.md covering Il2Cpp-specific behavior and limitations
• [ ] Create docs/compatibility/MONO.md covering Mono-specific behavior and patches
• [ ] Document why BaseLibs/MonoBleedingEdgePatches and NetStandardPatches exist with examples
• [ ] Add decision tree diagram showing when each compatibility layer is used
• [ ] Reference these docs in main README.md

Add workflow for validating compatibility layer implementations across platforms

There are multiple platform-specific compile workflows (compile_windows.yml, compile_linux.yml, compile_macos.yml) but no workflow that validates the compatibility layers (IPA, Demeo, Muse_Dash_Mono) actually load and instantiate correctly on each platform. This is a gap since these wrappers are core infrastructure. A validation workflow would catch platform-specific loader bugs early.

• [ ] Create .github/workflows/validate_compatibility_layers.yml
• [ ] Add step to build and load IPA compatibility layer on Windows/Linux/macOS
• [ ] Add step to verify Demeo module loads correctly where applicable
• [ ] Add step to verify Muse_Dash_Mono module loads correctly where applicable
• [ ] Add basic instantiation tests to catch symbol resolution issues per-platform
• [ ] Trigger on pull requests modifying Dependencies/CompatibilityLayers

• Add comprehensive unit tests for the CompatibilityLayers subsystem: currently no test files visible in file list, but this layer handles critical Mono vs. Il2Cpp branching logic. Mock game contexts and verify correct runtime detection.
• Document the BaseLibs patching process: README only says 'create MelonLoader/Logs folder' but doesn't explain how MonoBleedingEdgePatches were generated, version constraints, or how to patch new Mono versions when Unity updates. Add a PATCHING_GUIDE.md.
• Create a troubleshooting decision tree for common mod loading failures: error logs (MelonLoader/Logs/*.log) include raw exceptions but no guidance. Build interactive diagnostic tool or wiki page mapping error codes to root causes (missing dependency, runtime mismatch, hook failure).

MelonLoader is a mod loader framework with moderate security posture. Primary concerns include use of unmanaged binary dependencies without integrity verification, outdated .NET runtime, and inherent code execution risks from loading untrusted mods. The project lacks formal security policies and vulnerability disclosure processes. Strengths include organized structure and active GitHub workflows. Immediate actions should focus on updating .NET runtime, implementing dependency management best practices, establishing security policies, and hardening CI/CD pipelines. The architectural risk of arbitrary mod execution requires design-level mitigations such as code signing and sandboxing capabilities.

• High · Potential Insecure Dependency Management — BaseLibs/MonoBleedingEdgePatches/*.dll, BaseLibs/NetStandardPatches/*.dll. The project includes pre-compiled binary DLL files in the BaseLibs directory (MonoBleedingEdgePatches and NetStandardPatches) without visible version pinning or integrity verification mechanisms. These binaries could be vulnerable to tampering or contain outdated security patches. Fix: Implement NuGet package management with specific version pinning, add integrity verification (checksums/signatures), and establish a dependency update policy. Consider using a dependency scanning tool like OWASP Dependency-Check or Snyk in CI/CD pipeline.
• Medium · Missing Security Policy and Vulnerability Disclosure Process — Repository root. The repository structure shows issue templates and contributing guidelines but no visible SECURITY.md file or vulnerability disclosure policy. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file following GitHub's security policy template. Establish a responsible disclosure process and provide a security contact mechanism.
• Medium · Outdated .NET Runtime Dependency — Dependencies/Dotnet/linux/x86_64/shared/Microsoft.NETCore.App/6.0.25/. The project includes .NET 6.0.25 in Dependencies/Dotnet. .NET 6.0 reached end of life on November 12, 2024. Using EOL runtimes exposes the project to unpatched vulnerabilities. Fix: Upgrade to a currently supported .NET LTS version (8.0 or later). Update all workflow files and documentation to reference the newer runtime.
• Medium · Mod Loader Architecture Allows Arbitrary Code Execution — Dependencies/CompatibilityLayers/, Overall architecture. As a mod loader framework, MelonLoader by design loads and executes arbitrary mods. Without proper sandboxing or code verification, this inherently allows execution of malicious code. The CompatibilityLayers directory suggests multiple mod sources can be integrated. Fix: Implement code signing verification for mods, create a trusted mod repository with security scanning, document security best practices for mod developers, and consider implementing capability-based security restrictions.
• Low · Missing CODEOWNERS File — .github/ directory. No CODEOWNERS file is visible in the .github directory. This makes it difficult to ensure security reviews are conducted by appropriate maintainers for critical components. Fix: Add a CODEOWNERS file that specifies required reviewers for security-sensitive areas (core loader, dependency management, compatibility layers).
• Low · GitHub Actions Workflow Security Hardening — .github/workflows/*.yml. Multiple workflow files exist in .github/workflows/ but their permissions and security configurations are not visible in this analysis. Workflows handling releases and uploads are potential attack vectors. Fix: Audit all workflow files for: 1) Use of pull_request_target with untrusted code, 2) Insufficient permission scoping, 3) Unvetted third-party actions. Use workflow pinning (commit SHAs) for external actions and implement approval gates for deployments.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.