modding
Use when a Godot game should accept player-made mods, levels, skins or data, when loading PCK or ZIP packs at run time, when adding Steam Workshop or mod.io, or when a mod fails to load or breaks the game.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- modding
- description
- Use when a Godot game should accept player-made mods, levels, skins or data, when loading PCK or ZIP packs at run time, when adding Steam Workshop or mod.io, or when a mod fails to load or breaks the game.
03 SKILL.md 正文
Mod support in Godot 4 (C#)
Decide first what a mod may do: change data and assets (safe), or run code (full rights on the player's machine,
desktop only). Everything below was tested on an exported Godot 4.7.2 mono game; sources:
${CLAUDE_PLUGIN_ROOT}/docs/modding.md.
1. Three levels
| Level | What mods contain | Risk | Platforms |
|---|---|---|---|
| Data | JSON or CSV tables, plain images (Image.LoadFromFile), audio (AudioStreamOggVorbis.LoadFromFile) |
None if validated | All, consoles through a vetted service |
| Assets and scenes | A PCK or ZIP of Godot resources | Code: a .tres or .tscn can carry a script that runs on load |
Desktop |
| Scripts | GDScript or C# in a pack | Full rights: files, network, OS.Execute; Godot has no sandbox |
Desktop only (C# needs JIT) |
- Start with data mods: the game reads files it validates, like the C# example's
datarunner does withdata.json. Keep gameplay in data and scripts that can be replaced, and when rewriting internals, keep the old data contract working. - Loading a
.tresfrom a mod or save folder runs any script embedded in it (tested). Never load Godot resources fromuser://or a Workshop folder unless that mod is trusted as code; thearchitecturerunner warns (untrusted-load).
2. Packs: PCK or ZIP
// In an autoload's constructor or _Init, before anything else is loaded.
bool ok = ProjectSettings.LoadResourcePack(modPath, replaceFiles: true);
- Export a mod with the Godot editor:
godot --headless --path mod_project --export-pack "Linux" coolmod.pck(no export templates needed). ZIP and PCK behave the same. - A mod file at a game path replaces it, but only for loads that happen after mounting: a resource already loaded or
preloaded stays the old one. Mount mods first, or reload with
ResourceLoader.Load(path, "", ResourceLoader.CacheMode.Replace), which also updates the copies already in use. Data read withFileAccesschanges at once. - Every pack carries the mod project's
project.binary, class-name list and UID cache. WithreplaceFiles: truethe game's class list is replaced by the mod's (GetGlobalClassList()then lists only the mod's classes); withfalse, the mod's UIDs and class names do not resolve. So mods refer to their files by path, under their own folder,res://mods/<id>/..., never by class name or UID. - Load order is override order: make it explicit and fixed (sorted, not the order files happen to be found), and show it. Decide which game paths mods may replace; any file at the same path silently wins.
- Official patches and DLC are packs too; sign them (
Cryptowith an asymmetric key) if they come from a launcher. Godot cannot stop a PCK being copied.
3. C# mods (desktop only)
The way the Godot docs show, Assembly.LoadFile, crashes an exported game (segfault, not catchable): the mod binds to a
second, uninitialised copy of GodotSharp. So does AssemblyLoadContext.Default and a plain new context. Load mods into
the game assembly's own context instead:
using System.Runtime.Loader;
var gameContext = AssemblyLoadContext.GetLoadContext(typeof(Main).Assembly)!; // not Default in an export
var mod = gameContext.LoadFromAssemblyPath(dllPath); // or LoadFromStream(bytes) from a mod pack
Godot.Bridge.ScriptManagerBridge.LookupScriptsInAssembly(mod); // so scenes can load its scripts by path
- For
GD.Load("res://mods/x/Thing.cs")to work, each mod class sits in its own file named after the class (Godot's source generator only adds[ScriptPath]then). - A collectible context that hands back the game's own assemblies (GodotSharp, the game) also works, but unloading while mod objects are alive is untested: plan to restart the game to unload a mod.
- A mod that needs NuGet packages the game lacks needs an
AssemblyDependencyResolver. - .NET has no sandbox. A C# mod is a program the player chose to run.
4. Distribution
- Steam Workshop (through a Steamworks binding): upload with
CreateItem, thenSetItemContent(a folder) andSubmitItemUpdate, sending players to the Workshop agreement whenUserNeedsToAcceptWorkshopLegalAgreement; install withGetSubscribedItemsandGetItemInstallInfo, and read a download only afterDownloadItemResult_t. - mod.io: REST API or its C++ SDK (no official Godot plugin); moderation tools built in; consoles on paid tiers.
- On consoles mods are user content: reporting or filtering is required (Xbox XR-018), and only data and asset mods through a vetted service are realistic.
5. Safety and support
- Say plainly in the game that code mods run with full rights; show where each mod came from; never run downloaded code without the player choosing it; offer a "start without mods" mode.
- Record the active mods (ids and versions) in saves and crash reports (
game-telemetryfingerprints); mark saves that need mods. - Multiplayer: compare a hash of the mod list on joining, or refuse modded clients in ranked play (
anti-cheat). - Write a mod policy: who owns mods, whether they may be sold, which game assets may be redistributed. Third-party assets in
the game may forbid it (
assets.json,asset-pipeline).
6. Prove it
- [ ] an exported build loads a sample mod pack that replaces a texture, adds a scene and changes a data table, and the change shows (a smoke run with the mod in place)
- [ ] a broken mod (bad JSON, missing file, a value out of range) is reported by name and skipped, never a crash
- [ ] a
.tresin a data-mod folder is not loaded - [ ] mods load in the order shown, and "start without mods" starts clean
04 同仓库更多 Skills
over-budget
Use when a fixture exceeds the size budget.
bad-yaml
暂无简介
bad-workflow-description
Use when testing; runs the kit and then reads the JSON.
bad-version
Use when a fixture quotes a stale package version.
bad-value
Use when a fixture passes a value outside a parameter's set.
bad-trigger
Helps with Godot tests.