How to add a utility to the marketplace

This guide explains what a "utility" is, how it differs from a full "system", and how to structure and upload utilities so they import and update reliably.

What is a utility vs a system?

• System: end‑to‑end gameplay or feature package (controllers, services, UI, assets, instructions). A system may include optional subsystems and bundled relevant systems.
• Utility: a smaller, focused, reusable building block (e.g., math helpers, data structures, small services) that can be shared across many systems. Utilities have their own identity and versions and are updated independently.

Key differences:

• Scope: Utilities are granular; systems are feature‑complete bundles.
• Versioning: Utilities must declare identity and version in utilities_superbullet_meta.json and are upgraded independently. Systems use metadata.json for their version.
• Priority on extraction: Utilities are processed and resolved first (never optional), before any system files are copied.
• Bundling: Systems can reference utilities; utilities should not depend on system‑specific structure.

Required: utilities_superbullet_meta.json

Utilities are discovered and reconciled using a root‑level file named utilities_superbullet_meta.json. This file exists at the zip root for the incoming template and at the workspace root after installation.

Schema (required fields):

[
  {
    "DisplayName": "My Utility",
    "unique_id": "unique_id_of_uploaded_template",
    "version_number": "1.2.3",
    "created_by": "Superbullet"
  }
]

Processing rules:

• Read the Template’s utilities_superbullet_meta.json first, before copying any other files.
• Read the Workspace’s utilities_superbullet_meta.json (or create it if missing).
• For each incoming utility by unique_id:
  • Not installed → install utility files and append entry.
  • Installed with older version_number → replace utility files and update entry.
  • Installed with same/newer version → skip replace.
• Name collision with different/missing unique_id → prompt to rename or skip.

Notes:

• If a utility is missing its own utilities_superbullet_meta.json (legacy), the importer will synthesize one using available provenance (fills unique_id from TRF metadata and version_number from the system’s root metadata.json).
• Utilities are never optional. They are installed or updated deterministically before the rest of the system extraction begins.

Zip layout (simplified for utilities)

Utilities use a simplified version of the TemplateSystem.zip contract. Most system-only components are omitted.

TemplateSystem.zip
├─ utilities_superbullet_meta.json   # required for utilities; processed first
├─ metadata.json                     # required; contains name, description, and version
└─ Unpack_On_Source/                 # primary location for utility code (text-based)

You can ship a utility with utilities_superbullet_meta.json, metadata.json, and Unpack_On_Source/. Skip Unpack_On_Roblox_Studio/, To_Upload_By_User/, Optionals/, and Instructions.md entirely for utilities.

Required: metadata.json (zip root)

The setup for metadata.json is the same as for template assets. It contains the utility's name, description, and version information.

{
  "version_number": "1.0.0",
  "created_by": "Superbullet"
}

• Use semantic versioning for version_number (e.g., 1.0.1, 1.1.0, 2.0.0).
• Bump version_number on every re‑upload so utilities update for everyone.
• created_by is set automatically by the uploader.

Recommended folder layout for a utility

Place the utility’s files under the appropriate service folders so merges are idempotent. Keep names stable.

TemplateSystem.zip
├─ utilities_superbullet_meta.json   # required; processed first
├─ metadata.json                     # system‑level version (if part of a system)
├─ Unpack_On_Source/
│  └─ ReplicatedStorage/
│     └─ SharedSource/
│        └─ Utilities/
│           └─ MyUtility/
│              ├─ init.lua
│              └─ helpers.lua
└─ (other system folders if this utility ships with a system)

Guidelines:

• Put shared code under ReplicatedStorage/SharedSource/Utilities/<UtilityName> or your team’s chosen utilities root.
• Avoid placing .rbxm/.rbxmx here. Those belong to Studio assets and are handled separately.
• Keep the public API small and stable. Document expected inputs/outputs in comments or README inside the utility folder.

Versioning and updates

• Use semantic versioning in utilities_superbullet_meta.json (major.minor.patch).
• Bump versions whenever you change API or behavior.
• The importer compares versions and upgrades in place when the incoming version is newer.

Collisions and provenance

• The importer writes per‑folder provenance markers like superbulletai_metadata.json for Controllers/Services/Utilities when applicable.
• If a folder with the same name exists but has a different or missing unique_id, you’ll be prompted to rename incoming content or skip to avoid clobbering unrelated code.

Quick checklist before upload

• utilities_superbullet_meta.json exists at the zip root and lists your utility with a stable unique_id and correct version_number.
• metadata.json exists at the zip root with the correct version number (same setup as template assets).
• Utility files are under a stable path (e.g., ReplicatedStorage/SharedSource/Utilities/<UtilityName>).
• No .rbxm/.rbxmx files in Unpack_On_Source/.
• Skip Unpack_On_Roblox_Studio/, To_Upload_By_User/, Optionals/, and Instructions.md entirely for utilities.