Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-modding -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/unity-modding/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/unity-modding/

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

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set96

The whole set →
advanced-array-patterns advanced-array-patterns is a Claude Code skill with Bash array recipes for indexed and associative arrays, mapfile, slicing, and safe iteration under set -u. CX Codex +1 155installs ffmpeg-noise-reduction ffmpeg-noise-reduction is a Claude Code skill that references FFmpeg filters for noisy video and audio, helping choose a filter and arguments for the noise. CX Codex +1 150installs cloudflare-knowledge cloudflare-knowledge is a Claude Code skill that opens Cloudflare references for Workers, Pages, R2, D1, Workers AI and Zero Trust during setup. CX Codex +1 139installs unity-shaders-rendering unity-shaders-rendering guides AI assistants through Unity shaders, lighting setups, and render pipelines across URP, HDRP, and Built-in RP. CX Codex +1 133installs viral-video-hook-templates viral-video-hook-templates is a Claude Code skill with ten hook templates and FFmpeg filters for the first 3 seconds of video. It helps test opening variations and hold viewers’ attention. CX Codex +1 131installs markdown-style markdown-style lints Markdown in two passes, syntax first and style second, and reports every finding by line. Rewrites only what you approve. CX Codex +1 125installs ffmpeg-karaoke-animated-text ffmpeg-karaoke-animated-text directs coding agents to generate FFmpeg commands and ASS subtitles for karaoke sync, scrolling credits, and dynamic text animations. CX Codex +1 121installs skill-development skill-development — a guide to authoring SKILL.md files for Claude plugin skills: frontmatter rules, folder layout, and fixes for skills that never fire. CX Codex +1 116installs

Project sponsors

Companies that keep this analytics open