How to add animations to your asset template

This guide shows how to package animations so SuperbulletAI can guide users to re-upload them and wire the correct asset IDs automatically.

Why re-upload is required

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

Prerequisite: connect the SuperbulletAI plugin and server

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

What you need to include in your zip

Place animation instances as .rbxm or .rbxmx files under the required folder. Each file should contain a single KeyframeSequence Roblox Studio Instance (Animation data).

TemplateSystem.zip
└─ To_Upload_By_User/
   └─ Animations/
      ├─ RunForward.rbxm
      ├─ JumpStart.rbxm
      └─ DoorOpen.rbxmx

Notes:

• Use one KeyframeSequence (Roblox Studio Instance) per file.
• File format can be .rbxm or .rbxmx.
• Do not add scripts or extra folders here.
• If you include animation 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/Animations

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

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

How users re-upload animations (Studio steps)

For each KeyframeSequence under ReplicatedStorage/To_Upload_By_User/Animations:

1. Right-click the KeyframeSequence.
2. Choose: Save/Export → Save to Roblox...
3. Name it clearly (e.g., "DoorOpen").
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), animations may not play.

How SuperbulletAI uses the IDs

During extraction, SuperbulletAI detects entries in To_Upload_By_User/Animations and prompts for the newly uploaded Animation IDs. The importer blocks progress until valid IDs are provided to ensure everything will play in your experience.

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

-- ReplicatedStorage/SharedSource/Datas/AssetIds.lua
return {
  Animations = {
    RunForward = "rbxassetid://1234567890",
    DoorOpen = "rbxassetid://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 [===[DoorOpen]===] inside text files (Lua/JSON/etc.).
• Key matching: The placeholder name (e.g., DoorOpen) should match the animation key shown in the Assets Modal. By default this is the file basename from To_Upload_By_User/Animations/<Key>.rbxm(x).
• Replacement value: Each [===[<Key>]===] is replaced with rbxassetid://<UploadedId>.

Example (inline placeholder in Lua):

-- Before
local OPEN_ANIM_ID = "[===[DoorOpen]===]"
 
-- After providing IDs (DoorOpen => 987654321)
local OPEN_ANIM_ID = "rbxassetid://987654321"

Tip: Prefer centralizing IDs in ReplicatedStorage/SharedSource/Datas/AssetIds.lua and referencing them from code. Inline placeholders are supported but a shared map improves maintainability.

superbullet_metadata.json (token-to-file mapping)

Add a mapping file at To_Upload_By_User/Animations/superbullet_metadata.json so the importer knows which animation 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": "Animation 1",
    "file_path": "To_Upload_By_User/Animations/Animation_ID_1.rbxm",
    "source_path": "ReplicatedStorage/SharedSource/Datas/SampleSystemData.lua",
    "token": "[===[Animation_ID_1]===]"
  },
  {
    "display_name": "Run Forward",
    "file_path": "To_Upload_By_User/Animations/RunForward.rbxm",
    "source_path": "ReplicatedStorage/ClientSource/Client/SampleSystem/Others/Movement.lua",
    "token": "[===[RunForward]===]"
  }
]

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": "{{WALK_ANIMATION_ID}}",
    "display_name": "Walk Animation",
    "file_path": "To_Upload_By_User/Animations/Walk.rbxm"
  },
  {
    "instruction_token": "{{RUN_ANIMATION_ID}}",
    "display_name": "Run Animation",
    "file_path": "To_Upload_By_User/Animations/Run.rbxm"
  }
]

Instructions.md example (before upload):

After uploading, configure your animations:
 
- Walk Animation ID: {{WALK_ANIMATION_ID}}
- Run Animation ID: {{RUN_ANIMATION_ID}}

Instructions.md sent to chat (after upload):

After uploading, configure your animations:
 
- Walk Animation ID: rbxassetid://111222333
- Run Animation ID: rbxassetid://444555666

When to use each method

Example: The "Fireball Skill" template uses the fallback method. Download it from the marketplace panel or request it from your team to see a working implementation.

Rules for primary method (token)

• file_path (required): Full path from the zip root to the actual animation file to upload, including the leading To_Upload_By_User/Animations/ folder. Use forward slashes. Examples: To_Upload_By_User/Animations/RunForward.rbxm, To_Upload_By_User/Animations/Character/Jump.rbxmx.
• 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 animation file.
• instruction_token (required): The exact placeholder string to find and replace in Instructions.md. Use a distinctive format like {{ANIMATION_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 Animation Instances in marketplace content. Instances included under To_Upload_By_User/Animations exist only to help users re‑upload; SuperbulletAI does not edit Instance properties.
• Do this instead: store Animation asset IDs in a source file (for example ReplicatedStorage/SharedSource/Datas/AssetIds.lua) and create Animation Instances at runtime.

Example (runtime creation):

local AssetIds = require(ReplicatedStorage.SharedSource.Datas.AssetIds)
 
local function loadAnimation(humanoid, key)
  local animator = humanoid:FindFirstChildOfClass("Animator") or Instance.new("Animator", humanoid)
  local anim = Instance.new("Animation")
  anim.AnimationId = AssetIds.Animations[key]
  local track = animator:LoadAnimation(anim)
  return track
end
 
-- usage
local runTrack = loadAnimation(humanoid, "RunForward")
runTrack:Play()

Why: Keeping only IDs in source and creating instances on demand avoids brittle property edits and keeps templates deterministic.

Checklist

• Each animation is a single KeyframeSequence saved as .rbxm/.rbxmx.
• Files live under To_Upload_By_User/Animations/.
• You (or your group) re-upload each animation in Studio.
• Provide the resulting asset IDs when prompted by SuperbulletAI.
• Each metadata entry includes file_path pointing to the animation file to upload.