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; .rbxm/.rbxmx allowed sparingly)
├─ 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)

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.
• Allowed, but sparingly: .rbxm/.rbxmx files. Prefer Unpack_On_Roblox_Studio/ for DataModel-bound assets; only place them here when there is a specific reason to.
• 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.

.rbxm file rules

• One unique instance name per .rbxm: Each .rbxm file must contain only one top-level instance with a unique name.
• Avoid duplicate children names: Duplicate children names within an .rbxm are not properly supported and may result in instance loss when exported from Superbullet to Roblox Studio.
• File name must match instance name exactly: The .rbxm filename must match the exact name of the instance in Roblox Studio (e.g., an instance named Example_Model in Studio should be saved as Example_Model.rbxm).

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.

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)

What is the Instruction Runner?

The Instruction Runner is the part of SuperbulletAI that delivers your Instructions.md to the AI after your system is unpacked. It reads the file (including any subsystem Instructions.md files) and sends the raw markdown as a normal user message — no wrapper, no special format. The AI then applies the described edits using its file‑edit tools. If your markdown includes a structured "Steps" section, the AI treats it as the source of truth; otherwise it derives steps from the prose.

In short: the Instruction Runner doesn't execute anything itself — your Instructions.md is read verbatim by the AI, so write it as if you were messaging the AI directly.

Writing guidelines

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)

• Overusing .rbxm/.rbxmx files inside Unpack_On_Source/ (allowed, but use sparingly — prefer Unpack_On_Roblox_Studio/).
• 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.
• Using duplicate children names in .rbxm files (causes instance loss on export).
• Mismatching .rbxm filenames with the instance name in Roblox Studio.
• Having multiple top-level instances in a single .rbxm file.

7. Pre‑upload checklist

• The zip matches the layout above and uses service folders correctly.
• .rbxm/.rbxmx in Unpack_On_Source/ are used only sparingly (prefer Unpack_On_Roblox_Studio/); 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.