📦 VendorFiles: Unofficial Global Plugin API for TheoTown

Author: Hadestia & Erksmit

VendorFiles is a global, extensible API system designed to provide shared resources like NinePatches, Icons, and GUI utilities across multiple TheoTown plugins. This system ensures that shared assets and helper functions only need to be declared once, reducing duplication and improving plugin maintainability.

---

🧩 How It Works

✅ What Changed

• Removed use of Draft.append() in favor of JSON draft attribute: "once": true
• Each draft has a unique id and contains a script that auto-registers its contents into the global VendorFiles table during script:earlyInit()
• Updates and new content are added by creating additional drafts (not replacing or renaming the original)

🔁 Auto Registration

Each draft (e.g., for icons, NinePatches) shares a script that loads its contents using the loader.lua script. When the game loads that draft, the script calls script:earlyInit() and registers itself with VendorFiles, like so:

function script:earlyInit()
  VendorFiles.NinePatch['group_name'] = draft:getFrame(0)
end

---

⚠️ Important Load Order Note

TheoTown loads plugins in arbitrary order. To guarantee that VendorFiles and its dependencies load before other plugins:

✅ Rename Folder with Prefix

Use characters like !, $, or _ in vendor plugin folder name:

!vendorfiles/

This will sort the plugin alphabetically to the top so the game loads it first.

❗ Early Init Limitation

You cannot fetch or use NinePatches, icons, or other animation drafts in your plugin’s script:earlyInit() because, even though the draft’s frames are already available at that point, VendorFiles is still initializing them. This means they aren’t yet fully ready for use in other plugin logic.

✅ Instead, use script:init() or script:lateInit() to cache or fetch these globally registered resources:

function script:init()
  icon = VendorFiles.Icon -- cache Icon contents
end

---

🚀 How To Use in Your Plugin

1. Download this and rename (e.g., !vendorfiles) to your plugin directory
2. Ensure it loads first by renaming it with special characters
3. Access globally indexed items like so:

local np = VendorFiles.NinePatch
local icon = VendorFiles.Icon

---

📚 GUI Utility API Documentation

The VendorFiles.Gui module provides helpers for common GUI layout tasks.

To be continued

---

🔗 Contribution & Future Updates

• Submit a PR or fork this repo to expand the API
• Add new drafts with "once": true for future content
• Avoid overwriting existing IDs — use version-aware file naming

---

📎 License

MIT License – Free to use, modify, and distribute with credit to original authors.

---

Crafted with care for the TheoTown plugin dev community ❤️