Description

Changelog

Reviews (0)

VortarisModLoader

A data-driven mod loader for Godot 4.7+, written in C++ as a GDExtension (godot-cpp). Open source, no runtime dependencies.

Every piece of moddable content is addressed by a namespaced id (namespace.path, Minecraft ResourceLocation style). Mods stack above the base game and "change" it by replacing the resource an id points to — no game code changes needed. Built for data-driven / ECS games (systems, components, entities are all data) and traditional games alike (texture/model/scene overrides).

Features

Id-indexed everything — every moddable content is an id (e.g. game:units.knight); implicit path convention: drop a file under assets/<ns>/ or data/<ns>/ and it becomes addressable with zero declaration.
Unified content database — preload all data into memory for O(1) id lookups; set_data/delete_data rewrite live entries; batched async preload with progress signals.
Declarative hooks — hook points are ids; invoke_hook (pipeline rewrite), emit_hook (broadcast), check_hook (predicate). No fragile regex source rewriting.
Deterministic override arbitration — later-loaded mods win; priority + explicit flag + mod id; re-enabled mods always keep their override rank.
Runtime lifecycle — enable/disable/load/unload whole mods at runtime; cascade enable/disable with cycle guards; transactional zip install/uninstall.
Persisted content registry — a saveable id → resource route table (user://vml/registry.json, auto-loaded at finish_startup); edit it visually in the VML IDs editor panel (right dock, next to the Inspector).
Runtime reroute — reroute(id, path) / clear_reroute(id) hot-swap an id's target at runtime (theme switches, day/night cycles, A/B testing).
Per-mod config — declare a config_schema in the manifest; read/write with get_config/set_config.
Data-driven scenes & validation — build_node(id) builds a Node tree from data; validate() scans all loaded data and reports missing id references.
Dev hot reload — mtime polling; edit mod or base files and they apply live; vortarismodloader/verbose for detailed load logging.
Native vml:// loading — load("vml://ns.path") works, including in exported builds.
Beginner-friendly API — get/load/exists/get_mod_path sugar; F1 bilingual docs (English + 中文).
EditorPlugin — VML Mods (left-bottom dock, next to Import): mod list/state/toggle/install, one-click mod skeleton wizard, mod config editor, dependency-confirmation dialogs; VML IDs (right dock): persisted registry editor + loaded-id browser, popup editor with type dropdown, resizable columns.

Installation

Copy addons/vortarismodloader/ into your project.
Enable VortarisModLoader under Project → Project Settings → Plugins.
Add a bootstrap autoload (first in the list) that calls VML.finish_startup() in _ready.

The VML singleton and all VML* classes become available from GDScript. Base content lives under res://assets/game/ and res://data/game/; mods under res://mods-unpacked/<mod_id>/ (development) or installed at runtime from a zip.

Platforms

Single addon zip with prebuilt binaries for Windows x86_64, LinuxBSD x86_64 and macOS universal (debug and release). Requires a 64-bit platform and Godot 4.7+.