Add a template asset to the marketplace

How to add a template asset to the marketplace

This guide explains exactly how to structure your asset zip so SuperbulletAI can import it reliably and without manual fixes.

1. Zip layout (contract)

TemplateSystem.zip
├─ Instructions.md               # consumed by Instruction Runner
├─ metadata.json                 # base system metadata (version_number, created_by)
├─ relevant_systems.json         # bundled systems index: [{ display_name, unique_id, always_on, isInitiallyChecked }]
├─ Unpack_On_Source/             # copy-merge into src/... (text-based, no binary models)
├─ Unpack_On_Roblox_Studio/      # DataModel-bound assets (models/UI/VFX) as .rbxm/.rbxmx
├─ To_Upload_By_User/            # assets that must be uploaded by the user (Animations/Sounds)
└─ Optionals/                    # optional subsystems the user can choose to add
   └─ Sub_System/
      ├─ Instructions.md
      ├─ metadata.json           # contains { "DisplayName": "..." } only
      ├─ Unpack_On_Source/
      ├─ Unpack_On_Roblox_Studio/
      └─ To_Upload_By_User/

2. Folder rules and best practices

Both Unpack_On_Source/ and Unpack_On_Roblox_Studio/ are treated like a src/ root. Use Roblox service names as top‑level folders to indicate destinations (e.g., ReplicatedStorage/, ServerScriptService/, StarterGui/, Workspace/).

a. Unpack_On_Source/

  • Purpose: code and other text‑based assets that can be merged into source control.
  • Do: organize by service folders (e.g., ReplicatedStorage/Systems/Inventory).
  • Do: keep names stable and deterministic for idempotent merges.
  • Do not: include .rbxm or .rbxmx files.
  • Do not: include runtime‑only assets that belong in the DataModel (UI/VFX/meshes).

Example

Unpack_On_Source/
  ReplicatedStorage/
    Systems/
      Inventory/
        ItemDefinitions.lua
        InventoryController.lua
  ServerScriptService/
    Systems/
      Inventory/
        InventoryService.lua

b. Unpack_On_Roblox_Studio/

  • Purpose: non‑script assets destined for the DataModel.
  • Do: package assets as .rbxm/.rbxmx (UI, VFX, models, folders of Parts, etc.).
  • Do: place under service folders to indicate where they go.
  • Do not: include any Scripts/LocalScripts/ModuleScripts here.

Example

Unpack_On_Roblox_Studio/
  StarterGui/
    InventoryUI.rbxmx
  ReplicatedStorage/
    VFX/
      ItemPickupVFX.rbxm

c. To_Upload_By_User/

  • Purpose: assets that must be uploaded under the developer’s account so the importer can reference their asset IDs.
  • Structure:
    • To_Upload_By_User/Animations/ — contains only Animation instances
    • To_Upload_By_User/Sounds/ — contains only Sound instances
  • Do: include pure instances only (no scripts, no extra folders beyond the two above).
  • Do: give descriptive names (e.g., SwordSwing, BackpackOpen), one instance per file if you export models.
  • Do not: mix sounds and animations in the same folder.

Example

To_Upload_By_User/
  Animations/
    SwordSwing
    PotionDrink
  Sounds/
    SwordSwingSFX
    BackpackOpenSFX

3. relevant_systems.json (bundled systems you can import together)

Purpose

  • Lists other systems packaged alongside the current system that the user may want to import together.
  • Triggers a "Relevant systems" modal so users can pick which to include.
  • Lives at the zip root next to metadata.json. It does not enumerate Optionals/.

Schema (array of entries)

  • display_name (string): User‑facing name.
  • unique_id (string): Globally unique ID of the system (from marketplace registry).
  • always_on (boolean): If true, cannot be unchecked in the modal and is installed first if missing.
  • isInitiallyChecked (boolean): If true, checked by default (unless always_on true).

Example

[
  {
    "display_name": "Inventory Core",
    "unique_id": "a2b4c6d8-e0f2-4a6c-9b8d-1234567890ab",
    "always_on": true,
    "isInitiallyChecked": true
  },
  {
    "display_name": "Economy Basics",
    "unique_id": "c0ffee00-0000-4000-8000-0000c0ffee00",
    "always_on": false,
    "isInitiallyChecked": true
  },
  {
    "display_name": "Vehicles Extension",
    "unique_id": "deadbeef-dead-beef-dead-beefdeadbeef",
    "always_on": false,
    "isInitiallyChecked": false
  }
]

Guidelines

  • Use unique_id only; do not include file paths or download URLs.
  • Keep the list short and relevant.
  • Mark required dependencies with always_on: true. The app installs these first if missing and then proceeds.

Learn more: see the dedicated page "relevant_systems.json" for full contract and behaviors.

4. metadata.json (zip root)

{
  "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 templates update for everyone.
  • created_by is set automatically by the uploader.

5. Instructions.md (how to write high‑quality instructions)

Write concise, deterministic steps so the AI can make idempotent changes. Prefer imperative, testable language.

Do

  • State the goal up front.
  • Reference exact locations by service and path.
  • Specify concrete values and types.
  • Include acceptance checks the AI can verify.

Avoid

  • Vague language ("tweak", "adjust").
  • Hidden manual steps.
  • Multi‑goal instructions in one paragraph.

Minimal example

Goal: Add a coins counter to player profiles.

1) In ReplicatedStorage/Systems/ProfileService/ProfileTemplate, add a new number field:
   Coins = 0

2) In StarterGui/PlayerHUD, ensure a TextLabel named CoinsLabel exists.

3) In ReplicatedStorage/Systems/Currency/CurrencyController.lua, update render loop to display Coins on CoinsLabel.

Acceptance:
- A new player starts with Coins == 0.
- CoinsLabel shows "0" on spawn.

6. Common mistakes (avoid these)

  • Putting .rbxm/.rbxmx files inside Unpack_On_Source/.
  • Including any Scripts/LocalScripts/ModuleScripts inside Unpack_On_Roblox_Studio/.
  • Not using service folders at the top level (e.g., dropping files directly under root).
  • Mixing animations and sounds in the same folder under To_Upload_By_User/.
  • Forgetting to bump version_number in metadata.json when re‑uploading.

7. Pre‑upload checklist

  • The zip matches the layout above and uses service folders correctly.
  • No .rbxm/.rbxmx in Unpack_On_Source/; no scripts in Unpack_On_Roblox_Studio/.
  • Animations and sounds are pure instances in the right folders.
  • relevant_systems.json lists only truly related systems with valid unique_id values.
  • metadata.json has a bumped semantic version_number.
  • Instructions.md is precise, testable, and idempotent.
  • relevant_systems.json entries reference valid unique_id values; use always_on for required dependencies when applicable.
IntroductionAdd a utility to the marketplace