How to add places to your asset template

This guide shows how to package places so SuperbulletAI can guide users to upload them and wire the correct place IDs automatically.

Why re-upload is required

Due to Roblox platform permissions, places must be uploaded by the experience creator (you or your group). Even if place files are included in a template, they must be uploaded under your account or group to be part of your game universe.

Prerequisite: connect the SuperbulletAI plugin and server

For the assets to appear under ReplicatedStorage/To_Upload_By_User/Places 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/Places folder may not appear and validation will not work.

What you need to include in your zip

Place Roblox place files (.rbxl or .rbxlx) under the required folder. Each file represents a place that will be uploaded to the user's universe.

TemplateSystem.zip
└─ To_Upload_By_User/
   └─ Places/
      ├─ Lobby.rbxl
      ├─ Arena.rbxl
      └─ Shop.rbxlx

Notes:

• Use .rbxl (binary) or .rbxlx (XML) format.
• Each file should be a complete, standalone place.
• Do not add scripts or extra folders here beyond place files.
• If you include place 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/Places

You'll see each place file ready to be uploaded to your universe.

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

How users upload places (Roblox steps)

For each place defined in the template:

1. Open the place file (.rbxl/.rbxlx) in Roblox Studio.
2. Go to File → Publish to Roblox As...
3. Select the target universe (your game).
4. Choose to create a new place or overwrite an existing one.
5. Name it appropriately (e.g., "Lobby", "Arena").
6. Complete the upload and note the Place ID.

Alternative method using Game Settings:

1. Open your main game in Roblox Studio.
2. Go to Game Settings → Places.
3. Click "Add New Place".
4. Upload the place file.
5. Note the Place ID.

Important: Places must be uploaded to the same universe (game) that will use them for teleportation to work correctly.

How SuperbulletAI uses the IDs

During extraction, SuperbulletAI detects entries in To_Upload_By_User/Places and prompts for the newly uploaded Place 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 {
  Places = {
    Lobby = "123456789",
    Arena = "987654321",
    Shop = "456789123"
  }
}

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

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

Example (inline placeholder in Lua):

-- Before
local LOBBY_PLACE_ID = "[===[PLACE_LOBBY]===]"
 
-- After providing IDs (PLACE_LOBBY => 123456789)
local LOBBY_PLACE_ID = "123456789"

superbullet_metadata.json (token-to-file mapping)

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

[
  {
    "token": "[===[PLACE_LOBBY]===]",
    "display_name": "Lobby",
    "description": "Main lobby area where players spawn and socialize",
    "file_path": "To_Upload_By_User/Places/Lobby.rbxl",
    "source_path": "ReplicatedStorage/SharedSource/Datas/PlaceData.lua",
    "is_start_place": false
  },
  {
    "token": "[===[PLACE_ARENA]===]",
    "display_name": "Arena",
    "description": "Combat arena for PvP battles",
    "file_path": "To_Upload_By_User/Places/Arena.rbxl",
    "source_path": "ReplicatedStorage/SharedSource/Datas/PlaceData.lua",
    "is_start_place": false
  }
]

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

Use this method when you want the place 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": "{{PLACE_LOBBY}}",
    "display_name": "Lobby",
    "description": "Main lobby area where players spawn and socialize",
    "file_path": "To_Upload_By_User/Places/Lobby.rbxl",
    "is_start_place": false
  },
  {
    "instruction_token": "{{PLACE_ARENA}}",
    "display_name": "Arena",
    "description": "Combat arena for PvP battles",
    "file_path": "To_Upload_By_User/Places/Arena.rbxl",
    "is_start_place": false
  }
]

Instructions.md example (before upload):

After uploading places, configure your teleportation code:
- Lobby Place ID: {{PLACE_LOBBY}}
- Arena Place ID: {{PLACE_ARENA}}

Instructions.md sent to chat (after upload):

After uploading places, configure your teleportation code:
- Lobby Place ID: 123456789
- Arena Place ID: 987654321

When to use each method

Rules for primary method (token)

• file_path (required): Full path from the zip root to the place file to upload, including the leading To_Upload_By_User/Places/ folder. Use forward slashes. Examples: To_Upload_By_User/Places/Lobby.rbxl, To_Upload_By_User/Places/Arenas/PvPArena.rbxlx.
• 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)

• file_path (required): Full path from the zip root to the place file.
• instruction_token (required): The exact placeholder string to find and replace in Instructions.md. Use a distinctive format like {{PLACE_NAME}} to avoid accidental matches.
• display_name (required): The name shown in the Assets Modal and suggested for the place name.
• description (required): The description of what this place is for.
• is_start_place (optional): Set to true if this should be the universe's start place.
• 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 place 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 the place purpose (e.g., PLACE_LOBBY, PLACE_ARENA, PLACE_SHOP).
• Provide clear descriptions that explain what the place is used for.
• Only one place can be the start place per universe - typically this is your main game, not a sub-place.
• Ensure all places are uploaded to the same universe for teleportation to work.

Example (teleporting players between places):

local TeleportService = game:GetService("TeleportService")
local AssetIds = require(ReplicatedStorage.SharedSource.Datas.AssetIds)
 
local function teleportToLobby(player)
  local placeId = tonumber(AssetIds.Places.Lobby)
  TeleportService:Teleport(placeId, player)
end
 
local function teleportToArena(players)
  local placeId = tonumber(AssetIds.Places.Arena)
  TeleportService:TeleportAsync(placeId, players)
end

Checklist

• Each place is saved as .rbxl or .rbxlx format.
• Place files live under To_Upload_By_User/Places/.
• You upload each place to your universe via Roblox Studio.
• Provide the resulting place IDs when prompted by SuperbulletAI.
• Each metadata entry includes file_path pointing to the place file (full path from zip root).
• Each metadata entry includes display_name and description.
• Set is_start_place appropriately (only one place should be the start place).