How to add gamepasses to your asset template

This guide shows how to package gamepasses so SuperbulletAI can guide users to create them and wire the correct asset IDs automatically.

Why re-upload is required

Due to Roblox platform permissions, gamepasses must be created by the experience creator (you or your group). Even if gamepass metadata is included in a template, the actual gamepass must be created 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/Gamepasses 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/Gamepasses folder may not appear and validation will not work.

What you need to include in your zip

Place gamepass icon images (.png or .jpg) under the required folder. Each image will be used as the icon for a gamepass the user creates.

TemplateSystem.zip
└─ To_Upload_By_User/
   └─ Gamepasses/
      ├─ VIP_icon.png
      ├─ DoubleCoins_icon.png
      └─ ExtraLives_icon.jpg

Notes:

• Use .png or .jpg format for icons.
• Recommended icon size: 150x150 pixels (Roblox standard).
• Do not add scripts or extra folders here.
• If you include icon files, you must reference them via icon_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/Gamepasses

You'll see each icon image ready to be used when creating gamepasses.

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

How users create gamepasses (Roblox steps)

For each gamepass defined in the template:

1. Go to the Roblox Creator Dashboard.
2. Select your experience.
3. Navigate to Monetization → Passes.
4. Click "Create a Pass".
5. Upload the icon from To_Upload_By_User/Gamepasses/.
6. Set the name and description as suggested in the template.
7. Set the price (can differ from suggested price).
8. Save and note the Gamepass ID.

Important: Gamepasses must be created under the same account or group that owns the experience.

How SuperbulletAI uses the IDs

During extraction, SuperbulletAI detects entries in To_Upload_By_User/Gamepasses and prompts for the newly created Gamepass 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 {
  Gamepasses = {
    VIP = "123456789",
    DoubleCoins = "987654321"
  }
}

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 [===[GAMEPASS_VIP]===] inside text files (Lua/JSON/etc.).
• Key matching: The placeholder name (e.g., GAMEPASS_VIP) should match the gamepass key shown in the Assets Modal.
• Replacement value: Each [===[<Key>]===] is replaced with the Gamepass ID number only (e.g., 123456789), not including rbxassetid:// prefix.

Note: Unlike animations and sounds which use rbxassetid:// URLs, gamepasses use numeric IDs directly.

Example (inline placeholder in Lua):

-- Before
local VIP_GAMEPASS_ID = "[===[GAMEPASS_VIP]===]"
 
-- After providing IDs (GAMEPASS_VIP => 123456789)
local VIP_GAMEPASS_ID = "123456789"

superbullet_metadata.json (token-to-file mapping)

Add a mapping file at To_Upload_By_User/Gamepasses/superbullet_metadata.json so the importer knows which gamepass icon to use 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 gamepass ID inserted directly into your Lua code automatically.

[
  {
    "token": "[===[GAMEPASS_VIP]===]",
    "display_name": "VIP Access",
    "description": "Get exclusive VIP access with special perks and benefits",
    "suggested_price": 100,
    "icon_path": "To_Upload_By_User/Gamepasses/VIP_icon.png",
    "source_path": "ReplicatedStorage/SharedSource/Datas/GamepassData.lua"
  },
  {
    "token": "[===[GAMEPASS_DOUBLE_COINS]===]",
    "display_name": "Double Coins",
    "description": "Earn 2x coins from all sources permanently",
    "suggested_price": 250,
    "icon_path": "To_Upload_By_User/Gamepasses/DoubleCoins_icon.png",
    "source_path": "ReplicatedStorage/SharedSource/Datas/GamepassData.lua"
  }
]

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

Use this method when you want the gamepass 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": "{{GAMEPASS_VIP}}",
    "display_name": "VIP Access",
    "description": "Get exclusive VIP access with special perks and benefits",
    "suggested_price": 100,
    "icon_path": "To_Upload_By_User/Gamepasses/VIP_icon.png"
  },
  {
    "instruction_token": "{{GAMEPASS_DOUBLE_COINS}}",
    "display_name": "Double Coins",
    "description": "Earn 2x coins from all sources permanently",
    "suggested_price": 250,
    "icon_path": "To_Upload_By_User/Gamepasses/DoubleCoins_icon.png"
  }
]

Instructions.md example (before upload):

After creating gamepasses, configure your code:
- VIP Gamepass ID: {{GAMEPASS_VIP}}
- Double Coins Gamepass ID: {{GAMEPASS_DOUBLE_COINS}}

Instructions.md sent to chat (after upload):

After creating gamepasses, configure your code:
- VIP Gamepass ID: 123456789
- Double Coins Gamepass ID: 987654321

When to use each method

Rules for primary method (token)

• icon_path (optional): Full path from the zip root to the icon file to use, including the leading To_Upload_By_User/Gamepasses/ folder. Use forward slashes. Examples: To_Upload_By_User/Gamepasses/VIP_icon.png, To_Upload_By_User/Gamepasses/Passes/DoubleCoins.jpg. If omitted, users will need to create their own icon.
• 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.

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)

• icon_path (optional): Full path from the zip root to the icon file. If omitted, users will need to create their own icon.
• instruction_token (required): The exact placeholder string to find and replace in Instructions.md. Use a distinctive format like {{GAMEPASS_NAME}} to avoid accidental matches.
• display_name (required): The name shown in the Assets Modal and suggested for gamepass creation.
• description (required): The suggested description for the gamepass.
• suggested_price (required): The suggested Robux price.
• 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

• Store gamepass IDs in a centralized source file (for example ReplicatedStorage/SharedSource/Datas/AssetIds.lua) and reference them from code.
• Use descriptive token names that clearly indicate what the gamepass does (e.g., GAMEPASS_VIP, GAMEPASS_DOUBLE_COINS).
• Provide clear descriptions that explain the value proposition to players.
• Set reasonable suggested prices based on the gamepass benefits.

Example (checking gamepass ownership):

local MarketplaceService = game:GetService("MarketplaceService")
local AssetIds = require(ReplicatedStorage.SharedSource.Datas.AssetIds)
 
local function hasVIP(player)
  local success, ownsPass = pcall(function()
    return MarketplaceService:UserOwnsGamePassAsync(player.UserId, AssetIds.Gamepasses.VIP)
  end)
  return success and ownsPass
end

Checklist

• Each gamepass has an icon image (.png or .jpg).
• Icon files live under To_Upload_By_User/Gamepasses/.
• You create each gamepass in the Roblox Creator Dashboard.
• Provide the resulting gamepass IDs when prompted by SuperbulletAI.
• Each metadata entry optionally includes icon_path pointing to the icon file (full path from zip root).
• Each metadata entry includes display_name, description, and suggested_price.