How to add sounds to your asset template

This guide mirrors the animations process for packaging sounds so SuperbulletAI can guide users to re-upload them and wire the correct asset IDs.

Why re-upload is required

Due to Roblox platform permissions, sounds must be owned by the experience creator (you or your group). Even if a sound is included in a template, it must be re-uploaded under your account or group to be usable in your game.

Prerequisite: connect the SuperbulletAI plugin and server

For the assets to appear under ReplicatedStorage/To_Upload_By_User/Sounds in Studio, ensure the SuperbulletAI Plugin is installed and connected to the local SuperbulletAI server.

• Open the SuperbulletAI application to start the local server.
• In Roblox Studio, enable the SuperbulletAI plugin and confirm it shows as connected.
• If disconnected, the To_Upload_By_User/Sounds folder may not appear and validation will not work.

What you need to include in your zip

Place either raw audio files (.mp3, .ogg, or another Roblox‑supported format) or Sound Instances as .rbxm/.rbxmx under the required folder. Each .rbxm/.rbxmx should contain a single Roblox Studio Sound Instance.

TemplateSystem.zip
└─ To_Upload_By_User/
   └─ Sounds/
      ├─ ButtonClick.mp3
      ├─ EngineStart.rbxm
      └─ DoorOpenSFX.rbxmx

Notes:

• Use one Roblox Studio Sound Instance per file.
• File format can be .rbxm or .rbxmx.
• Do not add scripts or extra folders here. -. If you include raw audio files, you must reference them via file_path inside superbullet_metadata.json.

Where these appear in Roblox Studio

When the template is opened in Studio, these will appear at:

ReplicatedStorage/To_Upload_By_User/Sounds

You’ll see each Sound instance ready to re-upload.

Warning: If the SuperbulletAI plugin is not connected to the local SuperbulletAI server, this folder may not appear and sounds cannot be validated. Open the SuperbulletAI application to start the server and reconnect the plugin in Studio.

How users re-upload sounds (Studio steps)

For each Sound under ReplicatedStorage/To_Upload_By_User/Sounds:

1. Right-click the Sound.
2. Choose: Save/Export → Save to Roblox...
3. Name it clearly (e.g., "ButtonClick").
4. Set the Creator correctly:
   • Use your Group if the game belongs to a group (recommended for team games).
   • Use your personal account only if the game is under your user.
5. Complete the upload.

Important: If ownership does not match your experience (e.g., uploaded under a different user), sounds may not play.

How SuperbulletAI uses the IDs

During extraction, SuperbulletAI detects entries in To_Upload_By_User/Sounds and prompts for the newly uploaded Audio IDs. The importer blocks progress until valid IDs are provided.

On save, the app writes a mapping (Lua or JSON) the systems can consume, for example:

-- ReplicatedStorage/SharedSource/Datas/AssetIds.lua
return {
  Audio = {
    ButtonClick = "rbxassetid://1122334455",
    EngineStart = "rbxassetid://6677889900"
  }
}

How replacements are determined (path + placeholders)

• Source file path: Pre‑extraction. Start at the service root (e.g., ReplicatedStorage/SharedSource/... or ServerScriptService/Server/...). The Unpack_On_Source/ root is implied; do not include it.
• Placeholder pattern: Use unique, collision‑resistant tokens like [===[ButtonClick]===] inside text files (Lua/JSON/etc.).
• Key matching: The placeholder name (e.g., ButtonClick) should match the sound key shown in the Assets Modal. By default this is the file basename from To_Upload_By_User/Sounds/<Key>.rbxm(x).
• Replacement value: Each [===[<Key>]===] is replaced with rbxassetid://<UploadedId>.

Example (inline placeholder in Lua):

-- Before
local CLICK_SFX_ID = "[===[ButtonClick]===]"
 
-- After providing IDs (ButtonClick => 1122334455)
local CLICK_SFX_ID = "rbxassetid://1122334455"

superbullet_metadata.json (token-to-file mapping)

Add a mapping file at To_Upload_By_User/Sounds/superbullet_metadata.json so the importer knows which audio file to upload and where to replace placeholder tokens. There are two methods for specifying replacements:

Method 1: Primary (token-based) — Replaces in Lua source files

Use this method when you want the asset ID inserted directly into your Lua code automatically.

[
  {
    "display_name": "Button Click",
    "file_path": "To_Upload_By_User/Sounds/ButtonClick.mp3",
    "source_path": "ReplicatedStorage/SharedSource/Datas/SampleSystemData.lua",
    "token": "[===[ButtonClick]===]"
  },
  {
    "display_name": "Engine Start",
    "file_path": "To_Upload_By_User/Sounds/EngineStart.rbxm",
    "source_path": "ReplicatedStorage/ClientSource/Client/VehicleSystem/SoundEffects.lua",
    "token": "[===[EngineStart]===]"
  }
]

Method 2: Fallback (instruction_token) — Replaces in Instructions.md

Use this method when you want the asset ID communicated via instructions instead of automatic code insertion. The user will see the replaced IDs in the chat instructions and can manually copy them where needed.

[
  {
    "instruction_token": "{{BUTTON_CLICK_SOUND_ID}}",
    "display_name": "Button Click Sound",
    "file_path": "To_Upload_By_User/Sounds/ButtonClick.mp3"
  },
  {
    "instruction_token": "{{DOOR_OPEN_SOUND_ID}}",
    "display_name": "Door Open Sound",
    "file_path": "To_Upload_By_User/Sounds/DoorOpen.ogg"
  }
]

Instructions.md example (before upload):

After uploading, configure your sounds:
- Button Click Sound ID: {{BUTTON_CLICK_SOUND_ID}}
- Door Open Sound ID: {{DOOR_OPEN_SOUND_ID}}

Instructions.md sent to chat (after upload):

After uploading, configure your sounds:
- Button Click Sound ID: rbxassetid://111222333
- Door Open Sound ID: rbxassetid://444555666

When to use each method

Rules for primary method (token)

• file_path (required): Full path from the zip root to the actual audio file to upload, including the leading To_Upload_By_User/Sounds/ folder. Use forward slashes. Examples: To_Upload_By_User/Sounds/ButtonClick.mp3, To_Upload_By_User/Sounds/SFX/UI/ButtonClick.ogg.
• Use source_path as a pre‑extraction path starting at the Roblox service root (e.g., ReplicatedStorage/, ServerScriptService/), using forward slashes. The Unpack_On_Source/ root is implied; do not include it.
• The token is the exact placeholder string to replace. It must appear verbatim in the target file.
• Provide one entry per placeholder occurrence you want replaced.
• Do not include the token string anywhere in the source_path or its folders/filename. Tokens must appear only inside file contents, never in paths.
• display_name (optional): Controls the label shown in the Assets Modal. If omitted, the UI uses the derived key (usually the file basename).

If the token is not found in the specified file, validation will fail and you'll be prompted to fix the path or the token.

Rules for fallback method (instruction_token)

• file_path (required): Full path from the zip root to the audio file.
• instruction_token (required): The exact placeholder string to find and replace in Instructions.md. Use a distinctive format like {{SOUND_NAME_ID}} to avoid accidental matches.
• display_name (required for fallback): The label shown in the Assets Modal.
• Do not include a token field — its presence activates the primary method instead.
• The instruction_token placeholder must exist in your Instructions.md file.

Best practices

• Not supported: shipping or mutating Roblox Studio Sound Instances in marketplace content. Instances included under To_Upload_By_User/Sounds are for user re‑upload only; SuperbulletAI does not edit Instance properties.
• Do this instead: store Audio asset IDs in a source file (for example ReplicatedStorage/SharedSource/Datas/AssetIds.lua) and create Sound Instances at runtime.

Example (runtime creation with lightweight memory footprint):

local AssetIds = require(ReplicatedStorage.SharedSource.Datas.AssetIds)
 
local function playSound(parent, key, volume)
  local sound = Instance.new("Sound")
  sound.SoundId = AssetIds.Audio[key]
  if volume ~= nil then sound.Volume = volume end
  sound.Parent = parent
  sound.Ended:Once(function()
    sound:Destroy()
  end)
  sound:Play()
  return sound
end
 
-- usage
playSound(workspace, "ButtonClick", 0.6)

Why: Creating sounds on demand avoids preloading many Sound instances at startup and reduces memory usage.

Checklist

• Each sound is either a raw audio file (.mp3, .ogg, etc.) or a single Sound instance saved as .rbxm/.rbxmx.
• Files live under To_Upload_By_User/Sounds/.
• You (or your group) re-upload each sound in Studio.
• Provide the resulting asset IDs when prompted by SuperbulletAI.
• Each metadata entry includes file_path pointing to the audio file to upload.