unity-modding — Claude Code skill: Unity modding and setup
The unity-modding skill covers Unity mod support, asset loading, Lua scripting, mod managers, Steam Workshop distribution, and runtime code patching.
MIT 132 installs ★ 66 updated 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a claude-codeWhat unity-modding does
The skill maps Unity modding from data changes through asset packages, scripted extensions, and runtime code patches. It compares Addressables with Asset Bundles, shows how to load catalogs or bundles from a mod directory, and covers hot reload for JSON and CSV content.
It uses MoonSharp for Lua with a restricted game API, plus a ModManager that discovers manifests, checks dependencies and versions, and controls load order. The material also covers Steam Workshop through Steamworks.NET or Facepunch.Steamworks, along with Harmony and BepInEx patterns for existing games. MoonSharp is installed through NuGet or a DLL. Untrusted Lua must not receive System.IO, HTTP, or socket access.
What it helps with
- design Unity mod support by capability tier
- load Asset Bundles and Addressables from mod folders
- expose a safe Lua API through MoonSharp
- build a manifest-based ModManager with dependencies
- connect installed mods to Steam Workshop
Example prompts for the agent
- Design a Unity modding architecture with data mods, Asset Bundles, and Lua support through MoonSharp.
- Compare Addressables and Asset Bundles for local mod loading, then outline the ModManager and manifest format.
- Create a restricted Lua API for spawning entities, reading player health, and registering game events.
How to install unity-modding
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a claude-code2Manually: put the files in place
~/.claude/skills/unity-modding/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/unity-modding/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a codex2Manually: put the files in place
.agents/skills/unity-modding/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a cursor2Manually: put the files in place
.cursor/skills/unity-modding/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/unity-master/skills/unity-modding2Manually: put the files in place
.github/skills/unity-modding/SKILL.md1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a gemini-cli2Platform CLI
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/unity-master/skills/unity-moddingManually: put the files in place
.devin/skills/unity-modding/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about unity-modding
How do I install unity-modding in Claude Code?
Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a claude-code. The skill file will be at ~/.claude/skills/unity-modding/SKILL.md.
What does the unity-modding skill do?
It guides Unity mod architecture for asset and data loading, MoonSharp scripting, mod manifests, Steam Workshop delivery, and Harmony-based runtime patching.
How should Lua mods be sandboxed in Unity?
Keep System.IO, HTTP, and socket APIs out of Lua. Restrict registered types and apply an instruction limit with script.Options.InstructionLimit.
Source text
SKILL.md · MIT
---
name: unity-modding
description: |
Unity game modding architecture and mod-loading systems.
PROACTIVELY activate for: (1) adding modding support to a Unity game, (2) Asset Bundles for mods, (3) Addressables for mod content, (4) Lua scripting via MoonSharp, (5) Harmony patching for runtime IL injection, (6) Steam Workshop integration, (7) mod manager UI, (8) plugin architecture for user-generated content (UGC), (9) custom content loading at runtime, (10) sandboxing and security for untrusted mods.
Provides: AssetBundle vs Addressables tradeoffs, MoonSharp setup, Harmony patch patterns, Steam Workshop SDK integration, mod manager templates, and security guidelines.
---
# Unity Modding Architecture
## Overview
Guide for designing Unity games that support community modding. Covers asset loading systems, scripted mod APIs, mod manager patterns, distribution platforms, and techniques for modding existing games.
## Modding Architecture Tiers
| Tier | What Modders Can Do | Complexity |
|------|---------------------|------------|
| **Data Mods** | Replace textures, sounds, configs (JSON/XML) | Low |
| **Asset Mods** | Add new models, maps, items via Asset Bundles | Medium |
| **Script Mods** | Custom game logic via Lua/scripting API | High |
| **Code Mods** | Patch game assemblies via Harmony/BepInEx | Expert |
Design your game to support at least Tier 1-2 from the start. Tiers 3-4 require deliberate API design.
## Asset Loading for Mods
### Addressables (Recommended)
Addressables provide a unified API for loading assets from local bundles, remote servers, or mod directories.
```csharp
// Load a mod's asset catalog at runtime
public async Awaitable LoadModCatalog(string modPath)
{
string catalogPath = Path.Combine(modPath, "catalog.json");
var locator = await Addressables.LoadContentCatalogAsync(catalogPath);
Debug.Log($"Loaded mod catalog with {locator.Keys.Count()} assets");
}
// Load an asset by address (works for both base game and mods)
var prefab = await Addressables.LoadAssetAsync<GameObject>("enemies/goblin");
Instantiate(prefab);
```
**Mod workflow:**
1. Modders use a Unity project with Addressables configured
2. Build Addressable groups into Asset Bundles
3. Ship the catalog.json + .bundle files
4. Game loads catalogs at runtime from the mod directory
### Asset Bundles (Legacy but Simpler)
```csharp
public async Awaitable<AssetBundle> LoadModBundle(string path)
{
var request = AssetBundle.LoadFromFileAsync(path);
await request;
return request.assetBundle;
}
// Load specific asset from bundle
var bundle = await LoadModBundle("mods/weapons/swords.bundle");
var swordPrefab = bundle.LoadAsset<GameObject>("BroadSword");
```
**Key rules:**
- Never load the same bundle twice (track loaded bundles)
- Unload bundles when mods are disabled: `bundle.Unload(true)`
- Use `AssetBundle.LoadFromFileAsync` for local files (not `LoadFromMemory`)
### Hot-Reloadable Data Mods
For simple data mods (JSON configs, CSV tables):
```csharp
public T LoadModConfig<T>(string modPath, string fileName)
{
string filePath = Path.Combine(modPath, fileName);
if (!File.Exists(filePath)) return default;
string json = File.ReadAllText(filePath);
return JsonUtility.FromJson<T>(json);
}
```
Use `FileSystemWatcher` to detect changes and hot-reload during development.
## Lua Scripting with MoonSharp
MoonSharp is a Lua interpreter written in C# that runs on all Unity platforms.
### Setup
Install via NuGet or download the DLL. Register safe API surfaces for modders:
```csharp
public class ModScriptEngine
{
Script _lua;
public void Initialize()
{
_lua = new Script();
// Register safe game API
_lua.Globals["SpawnEntity"] = (Func<string, float, float, float, bool>)SpawnEntity;
_lua.Globals["GetPlayerHealth"] = (Func<float>)(() => player.Health);
_lua.Globals["ShowMessage"] = (Action<string>)ShowMessage;
_lua.Globals["RegisterEvent"] = (Action<string, DynValue>)RegisterEvent;
}
public void LoadMod(string luaFilePath)
{
string code = File.ReadAllText(luaFilePath);
_lua.DoString(code);
}
bool SpawnEntity(string id, float x, float y, float z)
{
// Validate and spawn - never trust mod input
if (!entityRegistry.Contains(id)) return false;
var pos = new Vector3(x, y, z);
if (!IsValidSpawnPosition(pos)) return false;
entityRegistry.Spawn(id, pos);
return true;
}
}
```
### Modder-Side Lua
```lua
-- my_mod/init.lua
RegisterEvent("OnPlayerEnterZone", function(zoneName)
if zoneName == "boss_arena" then
SpawnEntity("dragon_boss", 0, 5, 0)
ShowMessage("A dragon appears!")
end
end)
```
### Security Considerations
| Risk | Mitigation |
|------|-----------|
| File system access | Do NOT expose System.IO to Lua |
| Infinite loops | Set instruction count limits: `script.Options.InstructionLimit = 100000` |
| Memory abuse | Limit table sizes, monitor allocation |
| Network access | Never expose HTTP/socket APIs |
| Reflection abuse | MoonSharp sandboxes by default, but validate registered types |
## Mod Manager Pattern
### Architecture
```text
Game
├── ModManager (singleton)
│ ├── DiscoverMods(modsFolder) // Scan for mod manifests
│ ├── ValidateMod(manifest) // Version compat, dependencies
│ ├── LoadMod(modId) // Load assets + scripts
│ ├── UnloadMod(modId) // Clean teardown
│ └── GetLoadOrder() // Dependency-sorted order
├── ModManifest (ScriptableObject / JSON)
│ ├── id, name, version, author
│ ├── dependencies[]
│ ├── gameVersionMin / gameVersionMax
│ └── entryPoint (script path)
└── ModSandbox
├── Lua scripting environment
└── Restricted API surface
```
### Mod Manifest Format
```json
{
"id": "com.author.mymod",
"name": "My Awesome Mod",
"version": "1.2.0",
"author": "ModAuthor",
"description": "Adds new enemies and weapons",
"gameVersionMin": "1.0.0",
"gameVersionMax": "2.0.0",
"dependencies": ["[email protected]"],
"entryPoint": "scripts/init.lua",
"assets": "bundles/"
}
```
## Steam Workshop Integration
Use Steamworks.NET or Facepunch.Steamworks for Steam Workshop integration:
1. **Upload:** Modder packages mod folder, calls `SteamUGC.CreateItem` + `SteamUGC.SubmitItemUpdate`
2. **Subscribe:** Players subscribe in Steam Workshop UI
3. **Download:** Game queries `SteamUGC.GetSubscribedItems()` at startup
4. **Load:** Read from `SteamUGC.GetItemInstallInfo` path into ModManager
## Harmony Patching (Modding Existing Games)
Harmony is used by modders (via BepInEx/MelonLoader) to patch compiled game code at runtime.
```csharp
[HarmonyPatch(typeof(PlayerHealth), "TakeDamage")]
class DamageModifier
{
// Prefix: runs before original method
static bool Prefix(ref float damage)
{
damage *= 0.5f; // Halve all damage
return true; // true = continue to original
}
// Postfix: runs after original method
static void Postfix(PlayerHealth __instance)
{
Debug.Log($"Health after damage: {__instance.CurrentHealth}");
}
}
```
If designing a game intended to be modded via Harmony, avoid aggressive code obfuscation and keep method signatures stable across updates.
## Additional Resources
### Reference Files
- **`references/mod-framework-detail.md`** -- Complete mod manager implementation, dependency resolution algorithm, mod load ordering, versioned API patterns, hot-reload systems, mod testing frameworks, BepInEx/MelonLoader setup guide
© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace