hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-24 06:34:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update rules

Browse source
This commit is contained in:
Joe 2026-02-02 14:05:11 -06:00
parent 4c390fdd37
commit d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
Download patch file Download diff file Expand all files Collapse all files

226
.cursor/rules/roblox/en-us/projects/assets/api.md Normal file
View file

@ -0,0 +1,226 @@
---
title: Creator Store queries
description: Creator Store Queries let you externally query the Creator Store and Marketplace Catalog.
---
You can search Roblox's assets outside Studio by accessing the Creator Store API. Use the [Creator Store API](#creator-store-api) to query Studio assets, such as meshes, models, and audio, and the [Marketplace API](#marketplace-api) to query avatar assets on the Marketplace.
Each API requires a URL and custom search parameters for that specific catalog. If both URL and parameters are valid, the API returns a JSON format with the results of your search.
## Creator Store API
For information on making calls to the Creator Store API for search, see Toolbox Service in the [Open Cloud reference](../../cloud/features/creator-store.md#toolbox-service).
## Marketplace API
You can query avatar items from the Marketplace using the following URL:
`https://catalog.roblox.com/v1/search/items/details?[params]`
You can replace `[params]` with the appropriate [query parameters](#query-parameters) to customize your search.
### Query parameters
You can specify search parameters by appending a series of parameters and values to the URL, each separated by a `&`.
Use the following parameters to query the Marketplace:
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Options and Values</th>
</tr>
</thead>
<tbody>
<tr>
<td>Category</td>
<td>byte</td>
<td>`0` = Featured<br />`1` = All<br />`2` = Collectibles<br />`3` = Clothing<br />`4` = BodyParts<br />`5` = Gear<br />`11` = Accessories<br />`12` = AvatarAnimations<br />`13` = CommunityCreations</td>
</tr>
<tr>
<td>CreatorType</td>
<td>byte</td>
<td>`1` = User<br />`2` = Group<br /><br />Queries using `CreatorType` also require the `CreatorTargetId` parameter.</td>
</tr>
<tr>
<td>CreatorTargetId</td>
<td>long</td>
<td>The user or group ID depending on the CreatorType provided.<br /><br />Queries using `CreatorTargetId` also require the `CreatorType` parameter.</td>
</tr>
<tr>
<td>CreatorName</td>
<td>string</td>
<td>Search by creator name. If `Enum.CreatorType` is not provided, search is for users only.</td>
</tr>
<tr>
<td>Cursor</td>
<td>string</td>
<td>Each search response contains a `nextPageCursor` if there is a next page and `previousPageCursor` if there is a previous page. Pass either of these values in the Cursor parameter of your next query to get the next or previous page of results. The cursor is valid if the other query parameters remain the same.</td>
</tr>
<tr>
<td>Genres</td>
<td>byte</td>
<td>Specifies the genre for the search. The recommended approach to filtering on genres is to match the URL of a catalog page.<br /><br />`1` = TownAndCity<br />`2` = Medieval<br />`3` = SciFi<br />`4` = Fighting<br />`5` = Horror<br />`6` = Naval<br />`7` = Adventure<br />`8` = Sports<br />`9` = Comedy<br />`10` = Western<br />`11` = Military<br />`13` = Building<br />`14` = FPS<br />`15` = RPG</td>
</tr>
<tr>
<td>Keyword</td>
<td>string</td>
<td>Standard keyword search.</td>
</tr>
<tr>
<td>Limit</td>
<td>int</td>
<td>Number of results to return. Values are currently limited to 10, 28, and 30.</td>
</tr>
<tr>
<td>MaxPrice</td>
<td>int</td>
<td>The maximum price in Robux of items in the query.</td>
</tr>
<tr>
<td>MinPrice</td>
<td>int</td>
<td>The minimum price in Robux of items in the query.</td>
</tr>
<tr>
<td>SortAggregation</td>
<td>byte</td>
<td>`1` = PastDay<br />`3` = PastWeek<br />`4` = PastMonth<br />`5` = AllTime</td>
</tr>
<tr>
<td>SortType</td>
<td>byte</td>
<td>`0` = Relevance (Default)<br />`1` = Favorited<br />`2` = Sales<br />`3` = Updated<br />`4` = PriceAsc <br />`5` = PriceDesc </td>
</tr>
<tr>
<td>Subcategory</td>
<td>byte</td>
<td>`0` = Featured<br />`1` = All<br />`2` = Collectibles<br />`3` = Clothing<br />`4` = BodyParts<br />`5` = Gear<br />`9` = Hats<br />`10` = Faces<br />`12` = Shirts<br />`13` = TShirts<br />`14` = Pants<br />`15` = Heads<br />`19` = Accessories<br />`20` = HairAccessories<br />`21` = FaceAccessories<br />`22` = NeckAccessories<br />`23` = ShoulderAccessories<br />`24` = FrontAccessories<br />`25` = BackAccessories<br />`26` = WaistAccessories<br />`27` = AvatarAnimations<br />`37` = Bundles<br />`38` = AnimationBundles <br />`39` = EmoteAnimations<br />`40` = CommunityCreations<br />`41` = Melee<br />`42` = Ranged<br />`43` = Explosive<br />`44` = PowerUp<br />`45` = Navigation<br />`46` = Musical<br />`47` = Social<br />`48` = Building<br />`49` = Transport<br />`54` = HeadAccessories<br />`55` = ClassicTShirts<br />`56` = ClassicShirts<br />`57` = ClassicPants<br />`58` = TShirtAccessories<br />`59` = ShirtAccessories<br />`60` = PantsAccessories<br />`61` = JacketAccessories<br />`62` = SweaterAccessories<br />`63` = ShortsAccessories<br />`64` = ShoesBundles<br />`65` = DressSkirtAccessories<br />`66` = DynamicHeads</td>
</tr>
</tbody>
</table>
The following URL will search for the first 10 "Gear" items in "Accessories" sorted by all-time ("SortAggregation") and relevance ("SortType") created by Roblox ("CreatorTargetId" and "CreatorType"):
`https://catalog.roblox.com/v1/search/items/details?Category=11&Subcategory=5&CreatorTargetId=1&CreatorType=User&SortType=0&SortAggregation=5&Limit=10`
### Response fields
API responses return in a JSON format. The response provides asset details in the `data` key using the following fields:
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>assetType</td>
<td>One of the following asset type values (only returned if the item is an asset).<br /><br />`2` = T-Shirt<br />`8` = Hat<br />`11` = Shirt<br />`12` = Pants<br />`17` = Head<br />`18` = Face<br />`19` = Gear<br />`25` = Arms<br />`26` = Legs<br />`27` = Torso<br />`28` = RightArm<br />`29` = LeftArm<br />`30` = LeftLeg<br />`31` = RightLeg<br />`41` = HairAccessory<br />`42` = FaceAccessory<br />`43` = NeckAccessory<br />`44` = ShoulderAccessory<br />`45` = FrontAccessory<br />`46` = BackAccessory<br />`47` = WaistAccessory<br />`48` = ClimbAnimation<br />`49` = DeathAnimation<br />`50` = FallAnimation<br />`51` = IdleAnimation<br />`52` = JumpAnimation<br />`53` = RunAnimation<br />`54` = SwimAnimation<br />`55` = WalkAnimation<br />`56` = PoseAnimation<br />`61` = EmoteAnimation</td>
</tr>
<tr>
<td>bundleType</td>
<td>The bundle type ID (only returned if the item is a bundle). Possible values are `BodyParts` and `AvatarAnimations`.</td>
</tr>
<tr>
<td>creatorName</td>
<td>The creator's name.</td>
</tr>
<tr>
<td>creatorTargetId</td>
<td>The creator's ID.</td>
</tr>
<tr>
<td>creatorType</td>
<td>The item's creator type.</td>
</tr>
<tr>
<td>description</td>
<td>The item description.</td>
</tr>
<tr>
<td>favoriteCount</td>
<td>The favorite count of an item.</td>
</tr>
<tr>
<td>genres</td>
<td>List of the item's genres. Possible values include `All`, `Tutorial`, `Scary`, `TownAndCity`, `War`, `Funny`, `Fantasy`, `Adventure`, `SciFi`, `Pirate`, `FPS`, `RPG`, `Sports`, `Ninja`, and `WildWest`.</td>
</tr>
<tr>
<td>id</td>
<td>The ID of the item.</td>
</tr>
<tr>
<td>itemRestrictions</td>
<td>List of the item's restrictions. Possible values include `ThirteenPlus`, `LimitedUnique`, `Limited`, and `Rthro`.</td>
</tr>
<tr>
<td>itemStatus</td>
<td>List of the item's status flags. Possible values include `New`, `Sale`, `XboxExclusive`, `AmazonExclusive`, `GooglePlayExclusive`, `IosExclusive`, and `SaleTimer`.</td>
</tr>
<tr>
<td>itemType</td>
<td>The item type. Possible values are `Asset` or `Bundle`.</td>
</tr>
<tr>
<td>lowestPrice</td>
<td>The lowest reseller price of the item (only returned if the item is resellable).</td>
</tr>
<tr>
<td>name</td>
<td>The item name.</td>
</tr>
<tr>
<td>price</td>
<td>The listing price of the item (current price may differ if the item is resellable).</td>
</tr>
<tr>
<td>priceStatus</td>
<td>The price status of an item that is not on sale. Possible values are `Free`, `OffSale`, or `NoResellers`.</td>
</tr>
<tr>
<td>purchaseCount</td>
<td>The purchase count of an item.</td>
</tr>
<tr>
<td>unitsAvailableForConsumption</td>
<td>The unit available for consumption of a limited unique item.</td>
</tr>
</tbody>
</table>
The following is an example of expected return output for a single item:
```json
{
"keyword": null,
"previousPageCursor": null,
"nextPageCursor": "2_1_c541d05046b5c1c78a5d386b5e302243",
"data": [
{
"id":527373900,
"itemType":
"Asset",
"assetType":42,
"name":"Restless Souls Bandana",
"description":"This bandana won't help you blend in with ghosts, but at least you'll be stylish.",
"productId":41270974,
"genres":[
"Scary",
"Adventure"
],
"itemStatus":[],
"itemRestrictions":[],
"creatorType":"User",
"creatorTargetId":1,
"creatorName":"Roblox",
"price":300,
"favoriteCount":15943,
"offSaleDeadline":null
}
]
}
```

83
.cursor/rules/roblox/en-us/projects/assets/in-experience-asset-creation.md Normal file
View file

@ -0,0 +1,83 @@
---
title: In-Experience asset creation
description: Explains how to allow users to create and save assets in your experience.
---
With the in-experience asset creation feature, you can allow your users to save creations they made in your experience to their inventories. Your users can use these in-experience creations just like any other asset. Additionally, these creations attribute to your experience when displayed on the Roblox platform, so any user can use the attribution link to come to your experience and create their own.
For example, you can enable users to create custom creatures as pets in your experience, and allow them to save their favorite pets to their inventories. You have full control to specify which objects users can modify and save from your experience. Users in turn can display their creations on their profiles with attribution to your experience, boosting visibility of your experience.
## Supported asset types and limits
Just like all assets on the platform, in-experience creations are subject to [asset moderation](../../projects/assets/index.md#asset-moderation). Currently, you can only allow users to create [packages](../../projects/assets/packages.md) from your experience. These packages can't contain any scripts or private assets, such as audio, video, and nested packages. If the system detects scripts or private assets in a package that can be saved by users, it blocks the in-experience save action by hiding the save prompt for users.
When you are running or testing your experience and add scripts or private assets as part of an in-experience creation, it fails to save and prompts error messages to the Studio [Output window](../../studio/output.md) or the [Developer Console](../../studio/developer-console.md).
## Enabling in-experience asset creation
To enable in-experience asset creation for your users, use the `Class.AssetService:PromptCreateAssetAsync()` API method in a server-side script, along with other creation logic. Specify which instances in your experience you want to enable this functionality, set a custom trigger (such as a UI icon) for invoking the method, and listen for client remote events for saving assets.
`Class.AssetService:PromptCreateAssetAsync()` takes the following parameters:
- A `Class.Player` object representing the user who submits an asset creation.
- An `Class.Instance` object representing the asset for creation.
- The `Enum.AssetType`, which is currently limited to `Enum.AssetType.Model`.
When the server invokes `Class.AssetService:PromptCreateAssetAsync()`, it prompts a **Submit Package** dialog on the client, so the user who triggers the save action can enter a name and description for the package. Roblox provides the dialog UI out-of-the-box, as the save workflow is a platform-level functionality.
The following example server-side script prompts users to save a car that they paint in an experience:
```lua title="Example Script for In-Experience Asset Creation"
-- Define the AssetService variable
local AssetService = game:GetService("AssetService")
-- Set up PromptCreateAssetAsync() for prompting the submission dialog
local function CreateAsset(player, instance)
local complete, result, assetId = pcall(function()
return AssetService:PromptCreateAssetAsync(player, instance, Enum.AssetType.Model)
end)
if complete then
if result == Enum.PromptCreateAssetResult.Success then
print("successfully uploaded, AssetId:", assetId)
else
print("Received result", result)
end
else
print("error")
print(result)
end
end
-- Car painting logic omitted
-- Add an event handler
local function onUserPublish(player, promptObject)
-- User saves the car instance with the experience's default color
if promptObject.Name == "car" then
CreateAsset(player, car)
elseif promptObject.Name == "CarPaintYellow" or promptObject.Name == "CarPaintBlue" or promptObject.Name == "CarPaintBlack" or promptObject.Name == "CarPaintRed" then
PaintCarColor(promptObject.Name)
end
end
PublishEvent.OnServerEvent:Connect(onUserPublish)
```
[In-Experience Creation Demo Arena](https://www.roblox.com/games/12992503026/In-Experience-Creation-Demo-Arena) showcases an example on how you can use this feature. You can join the demo to walk through the in-experience creation workflow as a user, or edit the place in Studio to reference the design.
## Post-creation and attribution
After users create and save an asset from your experience, they can find it in the following places:
- Their [My Inventory](https://en.help.roblox.com/hc/en-us/articles/360000463726-How-to-View-or-Hide-Your-Inventory-in-a-Browser) page.
- The **Creations** tab of their [Profile](https://en.help.roblox.com/hc/en-us/articles/203313660-All-About-Profiles-Blurbs-and-Profile-Customization) page.
- The **Development Items** tab under their Creator Dashboard [Creations](https://create.roblox.com/dashboard/creations?activeTab=Model) page.
- The **Inventory** tab of their [Toolbox](../../projects/assets/toolbox.md) in Studio.
When users see in-experience creations on their connections' profiles or inventories, they see attribution to the original experience in which the asset was created. Users can click on the attribution link to redirect to the experience page, so they can join the experience and create their own.
<Alert severity="warning">
Attribution is currently tied to a specific version of the created asset. If a user saves a package from an experience and further edits in Studio to create a new version, attribution no longer displays for the new version.
</Alert>

353
.cursor/rules/roblox/en-us/projects/assets/index.md Normal file
View file

@ -0,0 +1,353 @@
---
title: Assets
description: An overview of how assets work on the platform.
---
Almost everything in Roblox is represented as a cloud-based asset with a unique corresponding ID. This ID is typically in the form of `rbxassetid://[ID]`, which gets applied to various instances as a property that's appropriate for that particular asset type. For example, `Class.Texture`, `Class.MeshPart`, and `Class.AudioPlayer` instances reference image, mesh, and audio assets through their respective `Class.Texture.ColorMapContent|ColorMapContent`, `Class.MeshPart.MeshId|MeshId`, and `Class.AudioPlayer.Asset|Asset` properties.
<GridContainer numColumns="3">
<figure>
`rbxassetid://7229442422`
<img src="../../assets/modeling/textures-decals/Texture-Example-Grafitti04.png" alt="A decal asset of a young woman with a button for an eye." width="90%" />
</figure>
<figure>
`rbxassetid://6768917255`
<img src="../../assets/modeling/meshes/Base-Mesh-In-Marketplace.png" alt="An untextured treasure chest MeshPart asset." width="90%" />
</figure>
<figure>
`rbxassetid://9125402735`
<audio controls><source src="../../assets/studio/general/Boom-Impact.mp3" type="audio/mpeg"></source></audio>
</figure>
</GridContainer>
This cloud-based asset system allows you to store assets through Roblox and reuse them across the platform in various contexts, such as in different objects and places, without maintaining local copies as part of each saved Studio experience. You can find millions of project assets in the [Creator Store][CreatorMarketplaceURL], equip avatar assets in the [Marketplace][MarketplaceURL], or you can create your own assets and [import](#asset-management) them directly into Studio through the asset management tools.
When you import assets, they must pass a [moderation](#asset-moderation) check before users can see and interact with them in published experiences. After Roblox approves imported assets, you can choose to retain ownership of their usage on the platform or make them publicly available as detailed in [Asset permissions](#asset-permissions).
## Asset types
All [asset types](/reference/engine/enums/AssetType) available on the platform generally fall into one of three categories:
- Assets that map to project-level items. You can find and configure these assets for specific experiences on the [Creator Dashboard][CreatorDashboardURL].
- Assets that are objects, or that change the appearance or behavior of objects within places. You can [import](#asset-management) these assets or find them in the [Creator Store][CreatorMarketplaceURL].
- Assets that change the body, clothing, or animation of avatars and non-playable characters. You can find these assets in the [Marketplace][MarketplaceURL].
Every asset type works differently depending on where it lives on the platform. See the following sections for information on how to use each asset type for [experiences](#for-experiences), [places](#for-places), and [avatars](#for-avatars).
### For experiences
There are three asset types that map to project-level items. These asset types are unique to the experience that they map to, meaning they are non-transferable to other projects.
- **Places** — Every experience has one or more [places](../../projects/index.md#places), or individual 3D worlds. Each place is represented by a [data model](../../projects/data-model.md) that describes the place's 3D world and logic.
- **Badges** — A [badges](../../production/publishing/badges.md) is a special award you can gift users when they meet a goal within an experience, such as completing a difficult objective or playing for a certain amount of time.
- **Passes** — A [pass](../../production/monetization/passes.md) is a monetization product that allows you to charge a one-time Robux fee in order for users to access special privileges within an experience, such as entry to a restricted area, an in-experience avatar item, or a permanent power-up.
### For places
In general, there are two categories of asset types for places that you can either [import](#asset-management) or find in the [Creator Store][CreatorMarketplaceURL]:
- Assets that exist as objects within the data model, such as [models](../../parts/models.md) and [meshes](../../parts/meshes.md).
- Assets that you apply as an object's property, such as audio, images, fonts, and videos.
For more information on both types of these assets for places, such as where and how you can use them in Studio, reference the following table.
<table>
<thead>
<tr>
<th>Asset&nbsp;Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Model**</td>
<td>A `Class.Model` is a container object for geometric groupings such as `Class.BasePart|BaseParts`, `Class.MeshPart|MeshParts`, and other `Class.Model` objects. Models can also contain objects such as `Class.Script|Scripts`. Whenever you group objects together in Studio, they automatically become a `Class.Model` object. For more information, see [models](../../parts/models.md).</td>
</tr>
<tr>
<td>**Mesh**</td>
<td>A `Class.MeshPart` is a type of part object that includes a physically-simulated custom mesh. For more information, see [meshes](../../parts/meshes.md).</td>
</tr>
<tr>
<td>**Audio**</td>
<td>An `Class.AudioPlayer` instance loads and plays an audio file and passes the output through a `Class.Wire` to an `Class.AudioEmitter` or `Class.AudioDeviceOutput`. For more information, see [audio assets](../../audio/assets.md) and [audio objects](../../audio/objects.md).</td>
</tr>
<tr>
<td>**Image**</td>
<td>Images are used in several ways within a place, including [textures/decals](../../parts/textures-decals.md) on parts, [image labels](../../ui/labels.md), [mesh textures](../../parts/meshes.md#adding-textures), textures for [custom materials](../../parts/materials.md), textures for [special effects](../../environment/index.md#special-effects), and more.</td>
</tr>
<tr>
<td>**Font**</td>
<td>`Class.TextButton`, `Class.TextLabel`, and `Class.TextBox` objects display typography in a specific style when you apply a font asset ID. You cannot import fonts, but the [Creator Store][CreatorMarketplaceURL] offers over 80 different fonts for your use.</td>
</tr>
<tr>
<td>**Video**</td>
<td>A `Class.VideoFrame` object displays a video through its `Class.VideoFrame.Video|Video` asset property. See [video frames](../../ui/video-frames.md) for more information.</td>
</tr>
</tbody>
</table>
### For avatars
There are three categories of asset types for avatars that you can find in the [Marketplace][MarketplaceURL] and equip to avatars:
- **Body Parts** — Assets that represent sections of the avatar character model, such as its head, torso, or legs.
- **Clothing and Accessories** — Assets that represent clothing and accessories on top of body parts.
- **Animations** — Assets that animate the avatar character model, such as how it runs, jumps, or swims.
Every [character](../../characters/index.md) model contains a `Class.HumanoidDescription` object with asset IDs for the character's body parts, clothing, accessories, and animations. By default, a user's playable character references their personal Roblox avatar, but you can apply a custom `Class.HumanoidDescription` if desired. For more information, see [character appearance](../../characters/appearance.md).
## Packages
Within Studio, you can convert single assets or asset hierarchies into **packages** and reuse them in multiple experiences, letting you optimize asset management across your entire team or across multiple projects. When a package is updated, you or your team members can update specific copies to the most current version, update all copies across an experience, or set specific copies to auto update.
For more information, see [packages](../../projects/assets/packages.md).
## Asset URIs
Assets and other content stored outside of the current place are identified through **Uniform Resource Identifiers** (URIs) which are formatted strings that point to a file stored online, within the Roblox application package, or saved to the client's device.
The basic structure is a **scheme** followed by `://` and a **path** that varies according to the scheme.
<span><Chip label='[Scheme]://[Path]' color='primary' size='large' /></span><br/>
The Roblox Engine supports several custom URI schemes for referencing content stored on the platform.
### rbxassetid
`rbxassetid` points to a user-uploaded asset on Roblox. This format is a common standard for properties such as `Class.Decal.ColorMapContent`, `Class.ParticleEmitter.Texture`, and `Class.AudioPlayer.Asset`.
<GridContainer numColumns="3">
<figure>
<figcaption><Chip label='rbxassetid://7229442422' color='primary' size='large' /></figcaption>
<br />
<img src="../../assets/modeling/textures-decals/Texture-Example-Grafitti04.png" alt="A decal asset of a young woman with a button for an eye." width="90%" />
</figure>
<figure>
<figcaption><Chip label='rbxassetid://3845386987' color='primary' size='large' /></figcaption>
<br />
<img src="../../assets/lighting-and-effects/particle-emitter/Texture-Indicated.jpg" alt="Three particle emitters emit red, blue, and yellow particles over jar assets that sit on top of a stone tower. The red particles are highlighted." width="90%" />
</figure>
<figure>
<figcaption><Chip label='rbxassetid://9125402735' color='primary' size='large' /></figcaption>
<br />
<audio controls>
<source src="../../assets/studio/general/Boom-Impact.mp3" type="audio/mpeg"></source></audio>
</figure>
</GridContainer>
### rbxasset
`rbxasset` points to Roblox's content folder on the user's device, for example:
<span><Chip label='rbxasset://textures/face.png' color='primary' size='large' /></span><br />
The content folder's location depends on the user's operating system:
<Tabs>
<TabItem label="Windows">
`%LOCALAPPDATA%\Roblox\Versions\<version>\content`<br />
(alternatively `C:\Program Files (x86)\Roblox\Versions\<version>\content`)
</TabItem>
<TabItem label="Mac">
`Applications/RobloxStudio.app/Contents/Resources/content`
</TabItem>
</Tabs>
### rbxthumb
`rbxthumb` points to a thumbnail image for the provided asset. Its string format takes a thumbnail type (`type`), an asset ID (`id`), and width/height (`w`/`h`).
<span><Chip label='rbxthumb://type=Asset&id=24813339&w=150&h=150' color='primary' size='large' /></span><br />
<table size="small">
<thead>
<tr>
<th>Type (`type`)</th>
<th>Expected `id` Value</th>
<th>Supported Sizes (`w`&times;`h`)</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Asset`</td>
<td>ID for a 2D or 3D asset</td>
<td scope="row">150&times;150, 420&times;420</td>
</tr>
<tr>
<td>`Avatar`</td>
<td>ID for a Roblox user (`Class.Player.UserId`)</td>
<td scope="row">48&times;48, 60&times;60, 100&times;100, 150&times;150, 180&times;180, 352&times;352, 420&times;420, 720&times;720</td>
</tr>
<tr>
<td>`AvatarBust`</td>
<td>ID for a Roblox user (`Class.Player.UserId`)</td>
<td scope="row">50&times;50, 60&times;60, 75&times;75, 100&times;100, 150&times;150, 180&times;180, 352&times;352, 420&times;420</td>
</tr>
<tr>
<td>`AvatarHeadShot`</td>
<td>ID for a Roblox user (`Class.Player.UserId`)</td>
<td scope="row">48&times;48, 60&times;60, 100&times;100, 150&times;150, 180&times;180, 352&times;352, 420&times;420</td>
</tr>
<tr>
<td>`BadgeIcon`</td>
<td>ID for a [badge](../../production/publishing/badges.md#locating-badge-ids)</td>
<td scope="row">150&times;150</td>
</tr>
<tr>
<td>`BundleThumbnail`</td>
<td>ID for a [Marketplace][MarketplaceURL] bundle such as a [character](https://www.roblox.com/catalog?Category=17), [head](https://www.roblox.com/catalog?Category=4&Subcategory=66), or [shoes](https://www.roblox.com/catalog?Category=3&Subcategory=64)</td>
<td scope="row">150&times;150, 420&times;420</td>
</tr>
<tr>
<td>`FontFamily`</td>
<td>ID for a font in the [Creator Store](../../production/creator-store.md) or [Toolbox](../../projects/assets/toolbox.md) inventory</td>
<td scope="row">1200&times;80</td>
</tr>
<tr>
<td>`GameIcon`</td>
<td>ID for an experience (`Class.DataModel.GameId`); shows the experience's [icon](../../production/publishing/experience-icons.md)</td>
<td scope="row">50&times;50, 150&times;150</td>
</tr>
<tr>
<td>`GamePass`</td>
<td>ID for a [pass](../../production/monetization/passes.md#locating-pass-ids)</td>
<td scope="row">150&times;150</td>
</tr>
<tr>
<td>`GameThumbnail`</td>
<td>ID for an experience (`Class.DataModel.PlaceId`); shows the experience's primary [thumbnail](../../production/publishing/thumbnails.md)</td>
<td scope="row">256&times;144, 384&times;216, 480&times;270, 576&times;324, 768&times;432</td>
</tr>
<tr>
<td>`GroupIcon`</td>
<td>ID for a [group](../../projects/groups.md)</td>
<td scope="row">150&times;150, 420&times;420</td>
</tr>
<tr>
<td>`Outfit`</td>
<td>ID gathered from an `Class.OutfitPages` table</td>
<td scope="row">150&times;150, 420&times;420</td>
</tr>
</tbody>
</table>
```lua title="Apply Avatar Head Shot Thumbnail"
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = playerGui
local imageLabel = Instance.new("ImageLabel")
imageLabel.AnchorPoint = Vector2.new(0, 0)
imageLabel.Size = UDim2.new(0, 150, 0, 150)
imageLabel.Position = UDim2.new(0, 16, 0, 16)
imageLabel.BorderSizePixel = 0
imageLabel.BackgroundColor3 = Color3.new(0, 0, 0)
imageLabel.BackgroundTransparency = 0.8
imageLabel.Parent = screenGui
local success, content, isReady = pcall(function()
return Players:GetUserThumbnailAsync(player.UserId, Enum.ThumbnailType.HeadShot, Enum.ThumbnailSize.Size352x352)
end)
if success then
-- Apply thumbnail content to image label
imageLabel.Image = content
-- Crop thumbnail to circle
local corner = Instance.new("UICorner")
corner.CornerRadius = UDim.new(1, 0)
corner.Parent = imageLabel
end
```
### rbxgameasset
`rbxgameasset` points to an asset uploaded through the [Asset Manager](../../projects/assets/manager.md). It allows access to assets by a user‑friendly name instead of ID, so if you upload an image named `Potion.png`, you can reference it as:
<span><Chip label='rbxgameasset://Images/Potion' color='primary' size='large' /></span><br />
In the above example, `Images` is the category/folder that appears in the [Asset Manager](../../projects/assets/manager.md) and `Potion` is the asset name, minus its extension.
<Alert severity="warning">
`rbxgameasset` only works for the current experience. If you paste a parent object that utilizes the asset into another experience, the asset will not load (or will load a different asset if you've uploaded one with the same name to that other game). If you need an asset to work across multiple experiences, use `rbxassetid` instead of `rbxgameasset`.
</Alert>
### rbxhttp
`rbxhttp` is shorthand for `Class.ContentProvider.BaseUrl`, for example:
<span><Chip label='rbxhttp://Thumbs/Avatar.ashx?x=100&y=100&format=png' color='primary' size='large' /></span>
### rbxtemp
`rbxtemp` allows you to refer `Class.File|Files`. Use `Class.File:GetTemporaryId()` to generate a valid `rbxtemp` URL. For example:
<span><Chip label='rbxtemp://1' color='primary' size='large' /></span>
### https / http
`https` or `http` points to the exact location of something on the internet. It only works on Roblox-approved domains and raises an error if you use it elsewhere.
<span><Chip label='https://www.roblox.com/asset/?id=9723979220' color='primary' size='large' /></span>
## Asset permissions
An asset's privacy status determines who has permission to use the asset within their experiences. By default, all assets are **private** when you or your [group](../../projects/groups.md) members import them into Studio. If you want to grant everyone access to the asset ID, you must distribute the asset to the [Creator Store][CreatorMarketplaceURL].
<Alert severity="warning">
Special privacy rules and workflows apply to **audio** and **video** assets. See [asset privacy](../../projects/assets/privacy.md) for details on sharing these asset types among connections and experiences.
</Alert>
## Asset moderation
Roblox performs both human and automated asset moderation on a proactive and reactive basis to ensure assets adhere to the [Community Rules](https://en.help.roblox.com/hc/articles/203313410), [Terms of Use](https://en.help.roblox.com/hc/articles/115004647846), and [Digital Millennium Copyright Act](../../production/publishing/dmca-guidelines.md) (DMCA). If any asset violates these moderation policies, such as including discriminatory or adult content, the Moderation team flags and removes the asset to protect users from harmful or non-compliant content. This process generally happens within a few hours after you import the asset.
If an asset is still in the moderation queue when you publish your experience, users cannot see or interact with the asset until Roblox approves it. If the asset doesn't pass moderation, you will receive a [notification](https://en.help.roblox.com/hc/en-us/articles/360020870412-Understanding-Moderation-Messages) explaining why the asset cannot be on the platform in its current state. For more information, see Working with Assets - Asset Moderation.
<Alert severity="warning">
To maintain community safety and civility, Roblox may take down experiences and/or terminate accounts that maliciously import or publish non-compliant assets.
</Alert>
## Asset management
Roblox offers several tools to import, store, and publish your assets:
<table>
<thead>
<tr>
<th>Tool</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[Asset Manager](../../projects/assets/manager.md)</td>
<td>Imports and stores [images](../../parts/textures-decals.md), [meshes](../../parts/meshes.md), [audio](../../audio/assets.md), and more. Only displays assets that you've imported into the currently opened experience.</td>
</tr>
<tr>
<td>[Toolbox](../../projects/assets/toolbox.md)</td>
<td>Stores every asset that you or your [groups](../../projects/groups.md) have ever imported into Studio, regardless of what experience you currently have open. Also includes assets from the [Creator Store][CreatorMarketplaceURL], allowing you to quickly drop user-generated assets directly into your experiences.</td>
</tr>
<tr>
<td>[3D Importer](../../art/modeling/3d-importer.md)</td>
<td>Imports 3D models from third-party modeling tools as a custom `Class.Model` instance. </td>
</tr>
</tbody>
</table>
## Archive assets
To further help with organization, you can archive most asset types in the **Creations** &rang; **Development Items** section of the [Creator Dashboard][CreatorDashboardURL]. To archive an item, hover over an asset's thumbnail, click the **&ctdot;** button, and select **Archive** from the context menu.
<img src="../../assets/creator-dashboard/Options-Button-Asset.png" width="200" alt="Options button indicated for an asset." />
After you archive an asset, it disappears from the website and is no longer usable or visible in Roblox experiences, including your own.
<Alert severity = 'warning'>
For more information on how archiving works with Marketplace items, see [moderation](../../marketplace/moderation.md#archive-assets).
</Alert>
[CreatorMarketplaceURL]: https://create.roblox.com/store
[MarketplaceURL]: https://www.roblox.com/catalog
[CreatorDashboardURL]: https://create.roblox.com/dashboard/creations

490
.cursor/rules/roblox/en-us/projects/assets/manager.md Normal file
View file

@ -0,0 +1,490 @@
---
title: Asset Manager
description: The Asset Manager lets you manage places and bulk import assets into your experience.
---
import BetaAlert from '../../includes/beta-features/beta-alert.md'
The **Asset Manager**, accessible from Studio's **Window** menu or **Home** tab, lets you manage [places](../../production/publishing/publish-experiences-and-places.md) and bulk import assets into your experience, including [images](../../parts/textures-decals.md), [meshes](../../parts/meshes.md), [packages](../../projects/assets/packages.md), [audio](../../audio/assets.md), and [models](../../parts/models.md).
## Current
<Alert severity="info">
The following sections outline the current Asset Manager. The [V2 Beta](#v2-beta) is documented below.
</Alert>
### Asset folders
Assets are organized within folders based on their type. You can switch between **grid view** and **list view** by clicking the view toggle button.
<img src="../../assets/studio/asset-manager/View-Toggle.png" width="460" alt="The Asset Manager window with the View toggle button highlighted." />
### Importing assets
The **bulk import** tool is ideal for importing up to 50 files in one batch. Imported assets enter the moderation queue and are only visible to you within their respective [folder](#asset-folders) and within the **Inventory** tab of the [Toolbox](../../projects/assets/toolbox.md).
<img src="../../assets/studio/asset-manager/Import-Button-V1.png" alt="The Asset Manager window with the Bulk Import button highlighted." width="360" />
<table>
<thead>
<tr>
<th>Asset&nbsp;Type</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Image**</td>
<td>You can import images in `.png`, `.jpg`, `.gif`, `.tga`, or `.bmp` format for use as [textures/decals](../../parts/textures-decals.md) on parts, [image labels](../../ui/labels.md), [mesh textures](../../parts/meshes.md#adding-textures), textures for [custom materials](../../parts/materials.md), textures for [special effects](../../environment/index.md#special-effects), and more.</td>
</tr>
<tr>
<td>**Mesh**</td>
<td>You can bulk import meshes in either `.fbx` or `.obj` format, although this workflow does not support complex meshes such as those with rigging, skinning, or animation data. For complex meshes, it's recommended that you use the [3D&nbsp;Importer](../../art/modeling/3d-importer.md).</td>
</tr>
<tr>
<td>**Audio**</td>
<td>You can import audio assets that you are certain you have permission to use in `.ogg`, `.mp3`, `.flac`, or `.wav` format. If you're uncertain whether you have permission to use an audio file, the [Creator Store](../../production/creator-store.md) has a variety of free-to-use audio, including more than 100,000 professionally-produced audio assets. See [Audio Assets](../../audio/assets.md) for details.</td>
</tr>
</tbody>
</table>
### Insert assets
You can insert assets into the [Explorer](../../studio/explorer.md) window hierarchy by dragging-and-dropping or by right-clicking the asset name/tile and selecting **Insert**.
Behavior of dragging-and-dropping into the 3D viewport varies by asset type:
<table>
<thead>
<tr>
<th>Asset&nbsp;Type</th>
<th>Drag-and-Drop Behavior</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Image**</td>
<td>If hovering over a valid parent object like a `Class.BasePart`, creates a new `Class.Decal` inside that parent with its `Class.Decal.ColorMapContent|ColorMapContent` property preset to the asset ID.</td>
</tr>
<tr>
<td>**Mesh**</td>
<td>Inserts the asset as a new `Class.MeshPart` in the workspace with its `Class.MeshPart.MeshId|MeshId` property preset to the asset ID.</td>
</tr>
<tr>
<td>**Audio**</td>
<td>Creates a new `Class.Sound` object in the workspace with its `Class.Sound.SoundId|SoundId` property preset to the asset ID.</td>
</tr>
<tr>
<td>**Package**</td>
<td>Inserts a copy of the package into the workspace.</td>
</tr>
</tbody>
</table>
### Quick actions
Quick actions are accessible by right-clicking an asset name/tile and selecting a context option.
<Tabs>
<TabItem label="Places">
<table>
<thead>
<tr>
<th>Quick Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Rename**</td>
<td>Lets you enter a new name for the place.</td>
</tr>
<tr>
<td>**Copy&nbsp;ID&nbsp;to&nbsp;Clipboard**</td>
<td>Copies the place ID to the clipboard.</td>
</tr>
<tr>
<td>**View History**</td>
<td>Opens the place version history, letting you view previous commits (publish actions) and their date/time. If desired, you can roll back to a previous version by selecting it and clicking the <b>Open</b> button.</td>
</tr>
<tr>
<td>**Remove From Game**</td>
<td>Completely removes the place from the experience. Not applicable to the [starting place](../../production/publishing/publish-experiences-and-places.md#change-start-place).</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Images">
<table>
<thead>
<tr>
<th>Quick Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Edit Asset**</td>
<td>Lets you edit general details such as the image title and description.</td>
</tr>
<tr>
<td>**Rename Alias**</td>
<td>Renames the image alias in the **Asset Manager**.</td>
</tr>
<tr>
<td>**Insert**</td>
<td>Inserts the image into the selected instance (or the workspace).</td>
</tr>
<tr>
<td>**Copy&nbsp;ID&nbsp;to&nbsp;Clipboard**</td>
<td>Copies the image ID to the clipboard.</td>
</tr>
<tr>
<td>**Remove From Game**</td>
<td>Removes the image from the **Asset Manager** but does not remove its instances from the experience.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Meshes">
<table>
<thead>
<tr>
<th>Quick Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Edit Asset**</td>
<td>Lets you edit general details such as the mesh title and description.</td>
</tr>
<tr>
<td>**Rename Alias**</td>
<td>Renames the mesh alias in the **Asset Manager**.</td>
</tr>
<tr>
<td>**Insert**</td>
<td>Inserts the mesh into the workspace.</td>
</tr>
<tr>
<td>**Insert With Location**</td>
<td>Inserts the mesh into the workspace, retaining location data stored during the mesh import process.</td>
</tr>
<tr>
<td>**Copy ID to Clipboard**</td>
<td>Copies the mesh ID to the clipboard.</td>
</tr>
<tr>
<td>**Copy&nbsp;Mesh&nbsp;ID&nbsp;to&nbsp;Clipboard**</td>
<td>Copies the mesh `Class.MeshPart.TextureID` to the clipboard.</td>
</tr>
<tr>
<td>**Remove From Game**</td>
<td>Removes the mesh from the **Asset Manager** but does not remove its instances from the experience.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Packages">
<table>
<thead>
<tr>
<th>Quick Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Insert**</td>
<td>Inserts a copy of the package into the workspace.</td>
</tr>
<tr>
<td>**View on Website**</td>
<td>Opens up your browser to the package asset page.</td>
</tr>
<tr>
<td>**Copy&nbsp;ID&nbsp;to&nbsp;Clipboard**</td>
<td>Copies the package ID to the clipboard.</td>
</tr>
<tr>
<td>**Package Details**</td>
<td>Lets you manage basic package details, access permissions, and package versions.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Audio">
<table>
<thead>
<tr>
<th>Quick Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Edit Asset**</td>
<td>Lets you edit general details such as the audio title and description.</td>
</tr>
<tr>
<td>**Rename Alias**</td>
<td>Renames the item alias in the **Asset Manager**.</td>
</tr>
<tr>
<td>**Insert**</td>
<td>Inserts the audio as a `Class.Sound` object into the selected instance (or the workspace).</td>
</tr>
<tr>
<td>**Copy&nbsp;ID&nbsp;to&nbsp;Clipboard**</td>
<td>Copies the audio file ID to the clipboard.</td>
</tr>
<tr>
<td>**Remove From Game**</td>
<td>Removes the audio from the **Asset Manager** but does not remove its instances from the experience.</td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>
### Asset inspection
You can closely inspect an image, mesh, package, or audio file by hovering over its thumbnail in [grid view](#asset-folders) and clicking the "magnify" icon, or by right-clicking its name in [list view](#asset-folders) and selecting **Asset&nbsp;Preview**.
<img src="../../assets/studio/asset-manager/Asset-Inspect-Icon.png" width="400" alt="A preview view of an asset in the Asset Manager. The Insect Asset icon is highlighted." />
When previewing 3D assets like meshes, you can move the virtual camera around to get a better view from all angles. For videos, you can preview the entire video in the popup.
<Grid container spacing={3}>
<Grid item>
<video src="../../assets/studio/general/3D-Asset-Preview.mp4" controls width="315"></video>
</Grid>
<Grid item>
<table size="small">
<thead>
<tr>
<th>Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Left mouse button&nbsp;+ drag</td>
<td>Rotate around the object.</td>
</tr>
<tr>
<td>Right mouse button&nbsp;+ drag</td>
<td>Pan left, right, up, or down.</td>
</tr>
<tr>
<td>Mouse scroll wheel</td>
<td>Zoom in or out.</td>
</tr>
</tbody>
</table>
</Grid>
</Grid>
In the lower-right corner of the preview frame, the **composition** button reveals the full hierarchy of the asset including `Class.Script|Scripts`, `Class.MeshPart|MeshParts`, `Class.Animation|Animations`, and more.
<img src="../../assets/studio/general/Preview-Panel-Hierarchy.png" width="560" alt="A preview view of an asset in the Asset Manager, and the full hierarchy of the asset displays underneath the 3D representation. The Asset Composition icon is highlighted." />
## V2 Beta
<BetaAlert betaName="Revamped Asset Manager" leadIn="The revamped Asset Manager is currently in beta. Enable it through " leadOut="." components={props.components} />
### Inventory sorting
Assets are sorted by various **inventories** as selected through the collapsible menu on the left side of the window. If you don't see the sorting list, click the expand/collapse button in the lower‑left area of the window.
<img src="../../assets/studio/asset-manager/Inventory-Sorts.png" width="800" alt="A preview of how inventories are sorted in the left navigation of the Asset Manager." />
- **Shared With Experience** — Assets that are [shared with the open experience](../../projects/assets/privacy.md#to-experiences).
- **Places In Experience** — The experience's current [places](../../production/publishing/publish-experiences-and-places.md).
- **My Inventory** — Assets imported to your own user account, [shared with you](../../projects/assets/privacy.md#to-creators), or acquired from the [Creator Store](../../production/creator-store.md).
- **Group Inventories** — Assets imported into [groups](../../projects/groups.md) you own or groups you belong to (assuming you have sufficient [permissions](../../projects/groups.md#roles-and-permissions) within the group), or assets [shared with the groups](../../projects/assets/privacy.md#to-groups). Right‑clicking over a group reveals a context menu with the following options:
<table size="small">
<tbody>
<tr>
<td>**Hide Group**</td>
<td>Hides the group from the sidebar.</td>
</tr>
<tr>
<td>**Customize Groups**</td>
<td>Allows you to choose the groups which appear in the sidebar and search filter options.</td>
</tr>
<tr>
<td>**Refresh Groups**</td>
<td>Refreshes the list of groups that you're eligible to show or hide.</td>
</tr>
</tbody>
</table>
### Asset display options
In the main panel, assets for the selected [inventory](#inventory-sorting) are displayed. To toggle the view type, click on the **view&nbsp;type** button and select either **List** or **Grid**. While in grid view, asset tiles can be resized through the slider widget.
<img src="../../assets/studio/asset-manager/Display-Options.png" width="800" alt="Diagram of the view type button and options in the Asset Manager." />
In **List** view, click on a column header to order assets by that detail and resize columns by dragging the separator bar between them.
<img src="../../assets/studio/asset-manager/List-View-Ordering.png" width="800" alt="Diagram of how columns can be ordered and resized in List view within the Asset Manager." />
<Alert severity="info">
Columns can be toggled on or off by right‑clicking in the header bar region. While columns cannot be reordered by dragging, you can toggle any column off and then toggle it back on to add it as the furthest column to the right.
</Alert>
In **Grid** view, ordering is controlled through the **sort** button:
<img src="../../assets/studio/asset-manager/Grid-View-Ordering.png" width="600" alt="Location of the sort button for Grid view within the Asset Manager." />
### Asset type filters
The **filter items** button lets you control which assets are displayed.
<img src="../../assets/studio/asset-manager/Asset-Type-Filters.png" width="600" alt="Location of the filter button in the Asset Manager." />
<table size="small">
<thead>
<tr>
<th>Filter Type</th>
<th>Options</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Asset Type**</td>
<td>**Animation**&nbsp;| **Audio**&nbsp;| **Decal**&nbsp;| **FontFamily**&nbsp;| **Image**&nbsp;| **Mesh**&nbsp;| **MeshPart**&nbsp;| **Model**&nbsp;| **Place**&nbsp;| **Plugin**&nbsp;| **Video**</td>
</tr>
<tr>
<td>**Creator**</td>
<td></td>
</tr>
<tr>
<td>**Source**</td>
<td>**Creator Store**&nbsp;| **Shared With Me**&nbsp;| **Uploaded**</td>
</tr>
<tr>
<td>**Is Package**</td>
<td></td>
</tr>
<tr>
<td>**Only&nbsp;Archived**</td>
<td></td>
</tr>
</tbody>
</table>
### Asset import
The **import** button lets you import up to 50 files in one batch. Imported assets enter the moderation queue and, upon approval, are added to the inventory of the user/group that owns the experience.
<img src="../../assets/studio/asset-manager/Import-Button.png" width="600" alt="Location of the import button in the Asset Manager." />
<table>
<thead>
<tr>
<th>Asset&nbsp;Type</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Image**</td>
<td>You can import images in `.png`, `.jpg`, `.gif`, `.tga`, or `.bmp` format for use as [textures/decals](../../parts/textures-decals.md) on parts, [image&nbsp;labels](../../ui/labels.md), [mesh&nbsp;textures](../../parts/meshes.md#texture), textures for [custom&nbsp;materials](../../parts/materials.md#custom-materials), textures for [special&nbsp;effects](../../effects/index.md), and more.</td>
</tr>
<tr>
<td>**Mesh**</td>
<td>You can import meshes in either `.fbx` or `.obj` format, although this workflow does not support complex meshes such as those with rigging, skinning, or animation data. For complex meshes or `.gltf` format, it's recommended that you use the [3D&nbsp;Importer](../../art/modeling/3d-importer.md).</td>
</tr>
<tr>
<td>**Audio**</td>
<td>You can import audio assets in either `.ogg`, `.mp3`, `.flac`, or `.wav` format. See [Audio Assets](../../audio/assets.md#import-audio) for details.</td>
</tr>
<tr>
<td>**Video**</td>
<td>You can import video assets in either `.mp4` or `.mov` format if all of the [requirements](../../ui/video-frames.md) are met.</td>
</tr>
</tbody>
</table>
### Insert and quick actions
Quick actions are accessible by right‑clicking an asset name/tile and selecting an option from the context menu. Note that places offer unique actions versus other assets.
<Tabs>
<TabItem label="General">
<table>
<thead>
<tr>
<th>Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Insert**</td>
<td>Lets you select from either **Insert&nbsp;at&nbsp;Camera** or **Insert&nbsp;at&nbsp;Asset&nbsp;Position** for spatial 3D assets (non‑spatial assets like audio are simply inserted into the `Class.Workspace` or the currently selected [Explorer](../../studio/explorer.md) instance). Does not appear for **FontFamily** or **Plugin** assets.</td>
</tr>
<tr>
<td>**Edit Asset**</td>
<td>Opens the asset configuration window to edit details such as the asset title, description, and more. Does not appear for **FontFamily** or **Plugin** assets.</td>
</tr>
<tr>
<td>**Copy Asset ID**</td>
<td>Copies the asset ID to the clipboard, convenient for pasting the ID into an object's property value such as `Class.AudioPlayer.AssetId` or `Class.MeshPart.MeshId`.</td>
</tr>
<tr>
<td>**View&nbsp;in&nbsp;Browser**</td>
<td>Opens your browser to the asset's page.</td>
</tr>
<tr>
<td>**Install**&nbsp;/ **Update**&nbsp;/ **Report**</td>
<td>Applicable only for **Plugin** assets. Installs, updates, or reports the plugin, respectively.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Places">
<table>
<thead>
<tr>
<th>Action</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Open**</td>
<td>Opens the place in another Studio session if it's not the currently open place.</td>
</tr>
<tr>
<td>**Rename**</td>
<td>Lets you enter a new name for the place.</td>
</tr>
<tr>
<td>**View History**</td>
<td>Opens the place version history, letting you view previous commits (publish actions) and their date/time. If desired, you can roll back to a previous version by selecting it and clicking the **Open** button.</td>
</tr>
<tr>
<td>**Remove&nbsp;From Experience**</td>
<td>Completely removes the place from the experience. Not applicable to the [starting place](../../production/publishing/publish-experiences-and-places.md#change-start-place).</td>
</tr>
<tr>
<td>**Copy Asset ID**</td>
<td>Copies the place's `Class.DataModel.PlaceId|PlaceId` to the clipboard.</td>
</tr>
<tr>
<td>**View&nbsp;in&nbsp;Browser**</td>
<td>Opens your browser to the place's page.</td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>

26
.cursor/rules/roblox/en-us/projects/assets/monetize.md Normal file
View file

@ -0,0 +1,26 @@
---
title: Monetize your creator assets
description: An overview of creator assets and the Creator Store.
---
## Create and sell Studio plugins
You can create and sell Studio [plugins](../../studio/plugins.md) to the creator community through the [Creator Store](../../production/creator-store.md). A plugin is an extension that adds additional features or functionality to [Roblox Studio](../../studio/index.md) and helps improve creator workflows. You can either offer plugins for free or sell them for a minimum of $4.99 USD. Roblox offers a market-leading revenue share for these sales, as only taxes and payment processing fees are deducted. For more information, see [Sell on the Creator Store](../../production/sell-on-creator-store.md).
Creator assets promote collaboration and resource sharing, and help developers create better and more dynamic experiences.
<table>
<thead>
<tr>
<th>Feature</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[Plugins](../../production/sell-on-creator-store.md)</td>
<td>Generate real-world income by selling plugins on the Creator Store. Plugins are tools designed to improve development workflows.</td>
</tr>
</tbody>
</table>

303
.cursor/rules/roblox/en-us/projects/assets/packages.md Normal file
View file

@ -0,0 +1,303 @@
---
title: Packages
description: Packages allow you to reuse single assets or asset hierarchies across experiences.
id: packages
---
To keep assets organized and reusable across your team or across multiple projects, you can group your instances and convert them into reusable **packages**. Packages make the overall process of building worlds faster and more ergonomic, but they also help with consistency, deduplication, collaboration, and versioning:
- Easily [update all copies](#mass-updates) of a package to the latest version, or only [update specific copies](#update-outdated-copies).
- Set packages to [automatically update](#automatic-updates) whenever there's a new version.
- Give collaborators **Edit** or **Use** permissions to the contents of a package.
- View the full version history for a package, compare versions, and restore old versions.
The most efficient workflow is to [create a package](#create-packages), [share it](#share-and-access-levels) with any collaborators, and [set it to auto-update](#automatic-updates). And you don't have to wait for a model to be "done" before using it in a package. Even if the package is a placeholder on top of a simple shape, you can use it to [greybox your environment](../../tutorials/curriculums/environmental-art/greybox-your-environment.md) and then have the placeholder copies automatically update as you publish more detailed versions.<br /><br />
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/AzKZy2BqIh8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Create packages
<Alert severity="warning">
If you want to create a package with restricted assets that you don't have [explicit permission](../../projects/assets/privacy.md#view-permissions) to use, you can still create the package but those specific restricted assets will **not** be visible or audible at runtime unless the experience itself has permission to use those assets.
</Alert>
You can create a package from any single object or any single parent and children branch of objects. If you want to create a package for a single object, add it to a `Class.Model` grouping first so that you can add, remove, or scale child objects within the package later without breaking the package.
To create a package:
1. In the [Explorer](../../studio/explorer.md) window or 3D viewport, right-click the object(s) you want to turn into a package and, in contextual menu, select **Convert&nbsp;to&nbsp;Package**.
1. In the new window, fill in the package details. In particular, if you're working in a [group](../../projects/groups.md), set **Ownership** to the appropriate group in which you have permission to create/edit group experiences.
<Alert severity="warning">
Ownership transfers are **not** supported by the asset system, so carefully consider the owner when creating a package.
</Alert>
1. Click **Submit**.
1. After the conversion completes, the object receives a "chain link" symbol in the [Explorer](../../studio/explorer.md) window to identify it as a package. Additionally, you can see a new `Class.PackageLink` object parented to the object.
<img src="../../assets/studio/packages/Package-Structure-Explorer.png" alt="A maple tree model in the Explorer window with the package icon next to it." width="320" />
1. <Chip label="OPTIONAL" size="small" variant="outlined" /> Select the `Class.PackageLink` object and enable `Class.PackageLink.AutoUpdate|AutoUpdate` in the [Properties](../../studio/properties.md) window. Note how the icon changes to indicate that the package is set to automatically update.
<Alert severity="error">
Do not delete or move the `Class.PackageLink` object! Doing so for any package copy converts the copy back into a normal object and loses package capabilities, such as ability to update itself when there's a new version.
</Alert>
## Insert packages
To insert a package that doesn't already exist in the current place, you must **initially** insert it from the [Toolbox](../../projects/assets/toolbox.md):
- From **Inventory** ⟩ **My Packages** for packages that you've published to or obtained from the [Creator Store](../../production/creator-store.md), as well as packages that a connection owns and has given you [permissions](#share-and-access-levels) to use.
- From **Creations** ⟩ **Group Packages** for packages published by members of your [group](../../projects/groups.md) (including yourself).
<GridContainer numColumns="2">
<figure>
<img src="../../assets/studio/toolbox/Inventory-My-Packages.png" alt="A close up view of the Toolbox with both the Inventory tab and the assets dropdown menu highlighted." width="360" />
<figcaption>Toolbox ⟩ Inventory ⟩ My Packages</figcaption>
</figure>
<figure>
<img src="../../assets/studio/toolbox/Creations-Group-Packages.png" alt="A close up view of the Toolbox with the Creations tab highlighted." width="360" />
<figcaption>Toolbox ⟩ Creations ⟩ Group Packages</figcaption>
</figure>
</GridContainer>
Once you've inserted a package into a published place's data model, it appears in the [Asset Manager](../../projects/assets/manager.md) and remains there even if you later delete all copies of it.
<Alert severity="warning">
Be careful when inserting assets that you didn't create into your experiences, as they can contain malicious scripts. Save your experience first and then investigate any scripts within unfamiliar assets so that you can easily revert back to the place version.
</Alert>
## Modify packages
You can edit packages and their children just like other objects. Modifying packages disables [auto‑update](#automatic-updates) until you [publish](#publish-package-changes) or [revert](#revert-package-changes) the changes.
Most edits flag the package as modified, although the following changes are **not** considered package modifications:
- Changing the **name** of the root node.
- Changing the **position** or **rotation** of the root node of a package that is a `Class.BasePart`, `Class.Model`, or `Class.GuiObject`.
- Changing the `Class.LayerCollector.Enabled|Enabled` property of a root node `Class.GuiObject` such as a `Class.ScreenGui`, `Class.SurfaceGui`, or `Class.BillboardGui`.
- Changing a part reference of a `Class.Weld` inside the package that references an instance outside of the package.
Once modified, packages with unpublished changes get a modified icon in the [Explorer](../../studio/explorer.md) window:
<img src="../../assets/studio/packages/Package-Modified.png" alt="The Explorer window with an icon that identifies unpublished package changes." width="320" />
### Add or update configurations
You can include [instance attributes](../../studio/properties.md#instance-attributes) at the root of a package to customize its behavior. When you publish a package, the current set of attributes/values will become the package's **default configurations**. On any given **copy** of a package, those attribute values can be changed on a per‑instance basis, and those changed are noted through **bold italics**. When package copies are [updated](#update-outdated-copies), modified configuration values will be preserved, while other attributes will be updated to the latest default value.
<img src="../../assets/studio/packages/Package-Configured-Attributes.png" width="320" alt="The Attributes section of the Properties window showing one attribute value modified and noted through bold italics." />
<Alert severity="info">
Currently the only way to handle configuration values is to add scripts in the package which read and apply behavior based on the configuration at runtime.
</Alert>
<Alert severity="info">
If you simply want to update the default **values** for configurations, you can change those attribute values and republish the package (the package will **not** be flagged as modified in this case). If you want to publish other modifications but not change the default configuration values, you should publish on a package without any value changes, or revert the configurations to their defaults before you publish.
</Alert>
### Nested packages
You can nest packages inside of other packages to maintain and collaborate on complex hierarchies, such as a series of vehicle mechanics which can be modified independently of the vehicle's parent package.
If you modify a nested package, both the nested package **and** the parent package are considered as modified. You must [publish changes](#publish-package-changes) to any **nested** package before you're allowed to publish changes to its **parent** package, since publishing the parent would mark it as current/unmodified and conflict with the nested package's modifications.
### Package scripts
Each script within an **unmodified** package is read-only and shows a notification on the top with a hyperlink to unlock the script.
<img src="../../assets/studio/packages/Script-Unlock-Link.png" alt="A script tab with a yellow notification that you can click to modify the script that's within an unmodified package." width="840" />
Clicking the hyperlink:
- Flags the package as modified regardless of whether you edit the script.
- Removes the notification/hyperlink from **other** scripts within the package.
Once the package is published and moved to an **unmodified** state, the scripts under it become read‑only with a hyperlink to modify.
## Publish package changes
You can publish any change to a package as a new version, making your updates available to other package copies throughout the place and across all experiences. It's **not** required to publish a modified package before publishing a place because the modified version is saved along with the place for future iteration.
To publish changes to a package:
1. In the [Explorer](../../studio/explorer.md) window or 3D viewport, right-click the modified copy and select **Publish&nbsp;to&nbsp;Package**.
1. If a package copy has [auto-update](#automatic-updates) turned on, it immediately pulls in the updated version when you open the place that contains them. Other copies get a "download" symbol that indicates an update is available. You can [individually update](#update-outdated-copies) or [mass-update](#mass-updates) all copies.
<img src="../../assets/studio/packages/Package-Update-Available.png" alt="Icons next to packages that have a potential update." width="320" />
1. <Chip label="OPTIONAL" size="small" variant="outlined" /> Add a description of your changes:
1. Right-click the package and select **Package Details**.
1. In the **Asset Configuration** window, select **Versions**.
1. Under your most-recent change, select **Add**.
1. Describe your changes, then click the **Submit** button.
## Update outdated copies
You can update outdated package copies to the most recent version, or you can continue to use the older version.
1. In the [Explorer](../../studio/explorer.md) window, locate outdated copies by the "download" symbol. You can also select the outdated copy in the 3D viewport.
<img src="../../assets/studio/packages/Package-Update-Available.png" alt="Icons next to packages that have a potential update." width="320" />
1. Right-click an outdated copy and select **Get Latest Package**. You can also select multiple packages, right-click, and **Get Latest For Selected Packages**.
### Mass updates
Extensive use of packages may result in many package copies across multiple places in an experience. In addition to [individual syncing](#update-outdated-copies) and [automatic updates](#automatic-updates), you can update all copies of a package through **mass updating**.
1. <Chip label="RECOMMENDED" size="small" variant="outlined" color="success" /> Close other Studio instances with any of the experience's places open; this prevents another unsaved instance of a place from potentially overwriting your updates.
1. In the [Explorer](../../studio/explorer.md) window or 3D viewport, right-click the desired package and select **Update All**.
1. Choose all places in the experience or some subset of places and click **Update**.
<Alert severity="info">
Mass updating packages automatically **saves** the selected places but does not **publish** them. Additionally, to prevent unintended overwrites, mass updating does not affect [modified](#modify-packages) versions of a package; after the mass update completes, Studio displays a warning with the number of packages that it did **not** update, if any.
</Alert>
### Automatic updates
To make syncing easier, you can set a package copy to update automatically whenever a newer version is published. Auto-update of the package copies will take place when a place is opened in Studio.
1. In the [Explorer](../../studio/explorer.md) window, expand the package's hierarchy tree and select its `Class.PackageLink` object.
<img src="../../assets/studio/packages/PackageLink-Explorer.png" alt="A close up view of a package in the Explorer window with its PackageLink object highlighted." width="320" />
1. In the [Properties](../../studio/properties.md) window, enable the `Class.PackageLink.AutoUpdate|AutoUpdate` property. If you have [nested packages](#nested-packages), this property only applies to the highest-level parent package, meaning automatic updates only occur when the **parent** package is updated.
<Alert severity="warning">
Automatic updating does not apply to [modified](#modify-packages) package copies. Once you modify a package instance, its **AutoUpdate** property becomes disabled and is ignored.
</Alert>
## Share and access levels
You can grant permission to connections, experiences, groups, or specific group user roles so that they can freely use your packages in their creations. For more information on asset access, see [Asset privacy](privacy.md).
<Alert severity="warning">
If you share a package with restricted assets that you don't have [explicit permission](../../projects/assets/privacy.md#view-permissions) to use, you can still share the package but those specific restricted assets will **not** be visible or audible at runtime unless the connection, experience, or group has permission to use those assets.
</Alert>
<Tabs>
<TabItem key = "1" label="To collaborators">
To change package permissions for a collaborator, such as a connection or group:
1. In the [Explorer](../../studio/explorer.md) window, [Toolbox](../assets/toolbox.md), or [Asset Manager](../assets/manager.md), right-click the desired package and select **Package Options**&nbsp;⟩ **Package Details**.
1. In the **Asset Configuration** window, select **Permissions**.
1. Using the search bar, input and select a collaborator that you want to grant permission to use your package, then choose a permission level.
<table>
<thead>
<tr>
<th>Permission</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Use & View**</td>
<td>The collaborator can use and view (but not edit) the current and previous package versions. Once you provide a collaborator with this ability, you cannot revoke access to a copy they already inserted into their experience; revoking access prevents reinsertion or package updates, but package copies in their data model remain intact.</td>
</tr>
<tr>
<td>**Edit**</td>
<td>The collaborator can use, view, and edit the current and previous package versions, including publishing changes to it.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem key = "2" label="To experiences">
To grant package access to an experience, the experience must be editable to either you or a group that you belong to in which you have the **Create and edit group experiences** role permission.
To change package permissions for an experience:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the upper tab bar, select **Development Items**, then click **Models & Packages**.
1. Select the package you want your experience to have permission to use. The package's **Configure** page displays.
1. In the package's left-hand navigation, select **Permissions**. The package's **Permissions** page displays.
1. From the **Experiences** tab, click the **Add experiences** button.
1. Type the experience's universeID into the **Enter Universe IDs** input, then click the **Add** button. The experience displays beneath the input with its access visible.
<Alert severity="info">
If you want to give multiple experiences permission to use your restricted access at the same time, you can enter multiple universeIDs as long as you separate them with a comma.
</Alert>
1. Click the **Done** button to finalize your package asset access permissions.
</TabItem>
</Tabs>
## Revert package changes
Instead of undoing an entire series of package changes one by one, you can [revert unpublished changes](#revert-unpublished-changes) in one action, restore a package to a previous [version](#restore-to-published-version), or revert changes to specific [configurations](#revert-configurations).
### Revert unpublished changes
To undo an entire series of **unpublished** changes:
1. In the [Explorer](../../studio/explorer.md) window, locate modified copies by the dot on their package icons. You can also select modified copies in the 3D viewport.
<img src="../../assets/studio/packages/Package-Modified.png" alt="The Explorer window with an icon that identifies unpublished package changes." width="320" />
1. Right-click a single modified copy and select **Undo Changes to Package**, or select multiple copies (at least one of them modified), right-click, and select **Undo Changes to Selected Packages**.
### Restore to published version
To restore a package to a **previously published** version:
1. In the [Explorer](../../studio/explorer.md) window, [Toolbox](../assets/toolbox.md), or [Asset Manager](../assets/manager.md), right-click the desired package and select **Package Options**&nbsp;⟩ **Package Details**.
1. In the **Asset Configuration** window, select **Versions**. The window displays details for each published version, including the date and time of publication, along with any descriptions of the changes.
1. Click the checkmark next to the version you want to restore and click **Submit**.
<Alert severity="warning">
Reverting changes to a package does not reset the configuration to the default. See [revert configurations](#revert-configurations).
</Alert>
### Revert configurations
To revert any [configuration](#add-or-update-configurations) attribute to its default, select **Reset** from its options menu in the **Attributes** section of the [Properties](../../studio/properties.md) window.
<img src="../../assets/studio/packages/Package-Configured-Attributes-Reset.png" alt="The Attributes section of the Properties window with the attribute's option menu expanded." width="320" />
## Compare package versions
When a package has multiple versions, you can compare changes between versions using the diff viewer. The tool has a package hierarchy menu that indicates all added, removed, or modified instances between versions using corresponding icons, including the following features:
- **Visual Overview** shows the visual differences of the 3D rendering under different camera positions. It's the default view for packages with a 3D object (models, parts) as the root object, and it's currently only available for the root object.
- **Properties** shows changes of properties and attributes. It's the default view for packages with a non-3D object (scripts, lights, 2D objects) as the root object, and it's available for all instances in a package.
- **Script** shows line-by-line script differences. It's available for packages containing scripts, regardless of whether the script is the root object or not.
To compare package versions:
1. In the [Explorer](../../studio/explorer.md) or 3D viewport, right‑click the target package and select **Package Options**&nbsp;⟩ **Compare Package Versions**.
1. By default, the window compares changes between your local copy and the latest version. Use the two dropdown menus to compare different versions.
<img src="../../assets/studio/packages/Compare-Versions-Selector.png" alt="A close up view of an example diff viewer. The compare settings are highlighted." width="840" />
<Alert severity="warning">
Some older versions might be incompatible with the package diff tool.
</Alert>
1. After selecting versions:
1. To compare the visual renderings of the root model, if applicable, select the **Visual Overview** tab and adjust the camera control for your desired angle. Controls are synchronized across views:
- Pan the camera using left mouse clicks.
- Rotate the camera using right mouse clicks.
- Zoom in and out the camera with the mouse wheel.
- Recenter using the keyboard shortcut <kbd>F</kbd>.
1. To compare properties and attributes of an instance, select the instance and the **Properties** tab.
1. To compare script differences for a package that is a script or contains scripts, use the **Script** tab.
<Alert severity="warning">
This tool only allows you to compare script changes between the current version and the latest published or local version, without indicating the collaborators who made the change.
</Alert>
<Alert severity="info">
Alternatively, you can open the script diff tool directly by right‑clicking the target package in the [Explorer](../../studio/explorer.md) window or 3D viewport and selecting **View Script Changes**.
</Alert>

280
.cursor/rules/roblox/en-us/projects/assets/privacy.md Normal file
View file

@ -0,0 +1,280 @@
---
title: Asset privacy
description: Explore how the asset privacy system lets you control which Roblox creators can use your assets in their experiences.
---
The **asset privacy system** lets you control how creators and experiences can use and distribute your models, meshes, images, decals, audio, video, and animation assets on Roblox. Assets can have one of two access privacy types:
- **Restricted** — Creators or experiences can only use the asset after the asset owner grants permission.
- **Open Use** — Any creator or experience can use the asset.
If a creator or experience doesn't have permission to use an asset, it cannot load in Studio, and a clickable error message displays in the [Output](../../studio/output.md) window. If a creator has permission to use an asset but the experience they're working on does not, clicking the error message displays a pop-up window to allow the creator to grant permission to the experience for any restricted assets.
When an asset is open use, Roblox doesn't need to check its permissions when it loads into an experience because every creator and experience can freely use it. However, when an asset is restricted, Roblox **always** checks its permissions when it loads into an experience or when a creator takes an action on the asset, such as inserting it into Studio, sharing it with another creator, or listing it on the [Creator Store](../../production/creator-store.md).
<Alert severity="info">
The asset privacy system controls which creators and experiences can use the asset, but others can still see its metadata, such as its name and description.
</Alert>
## Restrict permissions
<Alert severity="info">
You can list your or your group's restricted assets by themselves or as a dependency of a restricted asset on the Creator Store. This allows creators to use your assets as you list them under models, mesh parts, or packages, and disallows them from accessing and repackaging your restricted asset dependencies.
</Alert>
Every model, mesh part, and animation that you create are restricted **by default** to ensure that no one else can use your assets unless you explicitly grant permission to a creator, group, or experience, or list them on the Creator Store. If you want to extend this default permission to meshes, images, and decals, you must opt-in to the **Asset Privacy** beta.
### Beta opt-in
Individual creators and groups can opt into the beta via Creator Dashboard to apply permissions to newly created assets by default. Users and groups who are opted into the beta have their Images, Meshes, and Decals created as **Restricted** as default.
<Tabs>
<TabItem key = "1" label="As a creator">
To restrict your mesh, image, and decal assets on creation through the Asset Privacy beta:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the top-right corner of the page, click on your username and select **Settings**.
1. In the left-hand navigation, select **Advanced**.
1. In the **Asset Privacy** section, enable the **Opt-in to restrict assets on creation** toggle. Every non-avatar asset you create is now restricted by default.
</TabItem>
<TabItem key = "2" label="As a group">
<Alert severity="warning">
You can only complete this process if you are the group owner.
</Alert>
To restrict your group mesh, image, and decal assets on creation through the Asset Privacy beta:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the upper-left, expand the account switcher and select your group.
1. Expand the account switcher again, select **Settings** under the group's name, then select **Group Profile**.
1. In the **Asset Privacy** section, enable the **Allow restricted assets on creation** toggle. Every non-avatar asset your group creates is now restricted by default.
</TabItem>
</Tabs>
After opting into the beta, you can verify the asset permission of any newly uploaded asset in the asset configuration page:
<img src="../../assets/creator-dashboard/Asset-Toggle.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="60%" />
Selecting **Open Use** warns that once an asset has been set to **OpenUse**, it cannot be set back to **Restricted**.
<img src="../../assets/creator-dashboard/Asset-Make-OpenUse.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="60%" />
After setting to **Open Use**, the asset displays its current asset access permission.
<img src="../../assets/creator-dashboard/Asset-OpenUse.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="60%" />
### Decals
All `Class.Decal|Decals` are linked to an `Image`, which means a `Decal` can only be set to OpenUse if its `Image` dependency is OpenUse. Otherwise the following warning displays:
<img src="../../assets/creator-dashboard/Asset-Decals-Warning.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="60%" />
### Avatar assets
Avatar assets, such as accessories, clothing, and bodies, require all dependent textures and meshes to be `OpenUse` when uploading the Avatar asset to the Marketplace.
If you are opted into the beta and use a newly imported model in an avatar asset, you will be prompted to set your restricted texture and mesh dependencies to `OpenUse` during Marketplace [upload](../../marketplace/publish-to-marketplace.md#upload-an-asset):
<GridContainer numColumns = "2">
<figure>
<img src="../../assets/creator-dashboard/Asset-Avatar-Restricted.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="100%" />
<figcaption>
If your avatar item or bundle contains any restricted primitive assets, you must convert them to Open Use.
</figcaption>
</figure>
<figure>
<img src="../../assets/creator-dashboard/Asset-Avatar-Success.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="100%" />
<figcaption>
If your entire avatar item has correct permissions, you can continue to upload and publish your avatar item to the Marketplace.
</figcaption>
</figure>
</GridContainer>
## Grant permissions
In order for a collaborator, such as an individual creator or group, or an experience to use one of your restricted assets, you must explicitly grant permission before it's visible or audible at runtime. Once a collaborator or experience has **explicit** permission to use a restricted asset, they also receive **implicit** permission to use the asset in a variety of additional scenarios. For more information, see the following subsections.
### To collaborators
To grant a collaborator permission to use one of your restricted assets, the following must be true depending on if you are granting permission to another creator or a group:
- The creator must be your [connection](https://en.help.roblox.com/hc/en-us/articles/203313580-How-to-Make-Friends) on the platform, or
- You must have [Edit all group experiences](../../projects/groups.md#roles-and-permissions) permission in that group.
If you meet these conditions and explicitly grant the collaborator permission,
- The creator gains implicit permission to use the asset in any of their individual or group-owned experiences, and the ability to grant other experiences permission to use the restricted asset.
- All group members with edit access gain permission to use the asset in experiences owned by that group.
Once a collaborator has permission to use one of your restricted assets, they can insert the asset from the **Inventory** and/or **Creation** tab of the [Toolbox](../../projects/assets/toolbox.md), or by using the restricted asset ID in the [Properties](../../studio/properties.md) window.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/studio/toolbox/Inventory-Tab.png" width="360" alt="A close up view of the Toolbox with the Inventory tab highlighted." />
<img src="../../assets/studio/toolbox/Creations-Tab.png" width="360" alt="A close up view of the Toolbox with the Creations tab highlighted." />
<figcaption>Inserting a restricted asset through the Toolbox</figcaption>
</figure>
<figure>
<img src="../../assets/studio/properties/Enter-Private-Asset-ID.png" width="320" alt="A close up view of the Properties window with the Asset property highlighted." />
<figcaption>Inserting a restricted asset in the Properties window</figcaption>
</figure>
</GridContainer>
However, if a collaborator wants to use the restricted asset in a script, or if they want to save or publish a template place that includes the restricted asset, the collaborator must also give the [experience](#to-experiences) itself permission to use the asset. If the creator or group member doesn't complete this step, the asset isn't visible or audible during runtime, and a clickable error message displays in the **Output** window.
To grant a collaborator permission to use a restricted asset in any of these scenarios:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the upper tab bar, select **Development Items**, then click one of the following tabs:
- **Models & Packages**
- **Audio**
- **Decals**
- **Images**
- **Videos**
- **Meshes**
- **MeshParts**
- **Animations**
1. Select the asset you want your collaborator to have permission to use in their experiences. The asset's **Configure** page displays.
1. In the asset's left-hand navigation, select **Permissions**. The asset's **Permissions** page displays.
1. From the **Collaborators** tab, click the **Add collaborators** button.
<img src="../../assets/creator-dashboard/Permissions-Collaborators.png" alt="The landing page for asset permissions with the Collaborators tab selected." width="80%" />
1. Using the search bar, input and select a connection or group that you want to grant permission to use your restricted asset. The creator or group displays beneath the search bar with their access type.
<img src="../../assets/creator-dashboard/Add-Collaborators.png" alt="The Add Collaborators pop-up menu." width="60%" />
1. **(Optional)** If your selected asset type is a model or package, you can choose one of the following access types:
- **Use** - The collaborator receives permission to use the asset in their experiences.
- **Edit** - The collaborator receives permission to edit the asset's metadata, such as its name and description.
1. Click the **Done** button to finalize your asset access permissions.
### To experiences
<Alert severity="error">
Once an experience has permission to use a restricted asset, you cannot revoke access to the asset.
</Alert>
To grant an experience permission to use one of your restricted assets, the experience must be editable to either you or a group that you belong to in which you have the [Edit all group experiences](../../projects/groups.md#roles-and-permissions) permission.
After you or a collaborator with permission grants an experience access to use a restricted asset, anyone who has **Edit** access to that experience gains implicit permission to:
- Copy and paste the asset into another place file within that experience.
- Use its asset ID in the **Properties** window or in scripts within any place file within the experience.
<Alert severity="info">
When you grant permission to an experience by inserting it into a collaborator’s experience, the asset is also automatically shared with the experience's owner.
</Alert>
The following tabs walk you through the process of either granting one or more experiences access to a single restricted asset, or granting an experience access to one or more restricted assets.
<Tabs>
<TabItem key = "1" label="On an asset level">
To grant an experience permission to use a restricted asset:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the upper tab bar, select **Development Items**, then click one of the following tabs:
- **Models & Packages**
- **Audio**
- **Decals**
- **Images**
- **Videos**
- **Meshes**
- **MeshParts**
- **Animations**
1. Select the asset you want the experience to have permission to use. The asset's **Configure** page displays.
1. In the asset's left-hand navigation, select **Permissions**. The asset's **Permissions** page displays.
1. From the **Experiences** tab, click the **Add experiences** button.
<img src="../../assets/creator-dashboard/Permissions-Experiences.png" alt="The landing page for asset permissions with the Experiences tab selected." width="80%" />
1. Type the experience's universeID into the **Enter Universe IDs** input, then click the **Add** button. The experience displays beneath the input with its access visible.
<Alert severity="info">
If you want to give multiple experiences permission to use your restricted access at the same time, you can enter multiple universeIDs as long as you separate them with a comma.
</Alert>
<img src="../../assets/creator-dashboard/Add-Experiences.png" alt="The Add Experiences pop-up menu." width="60%" />
1. Click the **Done** button to finalize your asset access permissions.
</TabItem>
<TabItem key = "2" label="On an experience level">
To grant an experience permission to use many restricted assets in the previous scenarios:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. Select one of your or your group's experiences. The experience's overview page displays.
1. In the experience's left-hand navigation, navigate to the **Configure** section, then select **Permissions**. The asset's **Permissions** page displays.
1. In the **Enter asset IDs** input, type every asset ID you want the experience to have access to separated by commas, then click the **Add** button. All restricted assets the experience has access to display beneath the input with the asset's name, asset ID, owner, and asset type.
1. At the bottom of the page, click the **Save Changes** button.
</TabItem>
</Tabs>
## View permissions
You can view every restricted asset that your or your group's experiences have permission to use by reviewing the experience's **Permissions** page on the Creator Dashboard.
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. Select one of your or your group's experiences. The experience's overview page displays.
1. In the experience's left-hand navigation, navigate to the **Configure** section, then select **Permissions**. The asset's **Permissions** page displays.
1. **(Optional)** You can download the data for offline processing by clicking the download arrow button.
## Revoke permissions
<Alert severity="warning">
Unconnecting a creator does not automatically revoke permissions to use a restricted asset.
</Alert>
If you revoke restricted asset permission for a connection, they can no longer use the asset in any **additional** experiences. However, if they have used the restricted asset in their experiences, the experiences continue to have access to the restrictued asset.
To revoke permission for a creator to use a restricted asset in any additional experience that isn't currently using the asset:
1. Navigate to the [Creator Dashboard](https://create.roblox.com/dashboard/creations).
1. In the upper tab bar, select **Development Items**, then click one of the following tabs:
- **Models & Packages**
- **Audio**
- **Decals**
- **Images**
- **Videos**
- **Meshes**
- **MeshParts**
- **Animations**
1. Select the asset you want to revoke permission for one or more creators to use in their own experiences. The asset's **Configure** page displays.
1. In the asset's left-hand navigation, select **Permissions**. The asset's **Permissions** page displays.
1. From the **Collaborators** tab, locate the creator you want to revoke permission from, then click the Access dropdown next to their username. Additional options display.
1. Click the **Remove** button. A pop-up displays to confirm that you want to revoke permission from the collaborator.
1. From the pop-up, click the **Remove** button.
## Open permissions
<Alert severity="error">
Opening an asset's permissions is irreversible. Once you set an asset to open use, it **cannot** be reset to the restricted privacy type.
</Alert>
While opting in to the **Asset Privacy** beta allows you to restrict your or your group's mesh, image, and decal assets on creation, you are still able to open their permissions so that any creator or experience to freely access and use them in their projects.
To open permissions for your or your group's mesh, image, or decal asset through the Asset Privacy beta:
1. Follow the steps to opt-in to the Asset Privacy beta in [Restrict permissions](#restrict-permissions).
1. Back in the [Creator Dashboard](https://create.roblox.com/dashboard/creations), navigate to the upper tab bar, select **Development Items**, then click either **Decalss**, **Images**, or **Meshes**. All of your decal, image, or mesh assets display.
<Alert severity="warning">
If you want to set a decal asset to open use, you must set its image dependency to open use **first**, otherwise the Asset Privacy system will block you in future steps.
</Alert>
1. Select the asset that you want to every creator and experience to freely use in their projects. The asset's **Configure** page displays.
1. In the **Asset Access** section, enable **Open Use**. A pop-up displays asking you to confirm this permanent change.
1. In the pop-up, click the **Make Open Use** button. Anyone on Roblox can now use your asset.

118
.cursor/rules/roblox/en-us/projects/assets/toolbox.md Normal file
View file

@ -0,0 +1,118 @@
---
title: Toolbox
description: The Toolbox contains a selection of assets made by Roblox or Roblox community members.
id: toolbox
---
import ToolboxFindUse from '../../includes/studio/toolbox-find-use.md'
The **Toolbox**, accessible from Studio's **Window** menu or **Home** tab toolbar, contains a selection of [models](../../parts/models.md), [images](../../parts/textures-decals.md), [meshes](../../parts/meshes.md), [audio](../../audio/assets.md), [plugins](../../studio/plugins.md), [videos](../../ui/video-frames.md), and fonts made by Roblox or Roblox community members. It also includes all of the creations that you've personally published or those which were published by [groups](../../projects/groups.md) you belong to.
<img src="../../assets/studio/general/Toolbar-Toolbox.png" width="800" alt="Toolbox highlighted in Studio's toolbar." />
The toolbox contains four distinct sections:
<Tabs>
<TabItem label="Creator Store">
<figure>
<img src="../../assets/studio/toolbox/Creator-Store-Tab.png" width="360" height="121" alt="A close up view of the Toolbox with the Creator Store tab highlighted." />
The **Creator Store** section contains models, decals, meshes, audio, plugins, videos, and fonts made by Roblox or Roblox community members. See [Creator Store](../../production/creator-store.md) for more information.
</figure>
</TabItem>
<TabItem label="Inventory">
<figure>
<img src="../../assets/studio/toolbox/Inventory-Tab.png" width="360" height="121" alt="A close up view of the Toolbox with the Inventory tab highlighted." />
The **Inventory** section contains models, decals, meshes, audio, packages, videos, plugins, animations, and fonts that you've personally published, those which were published by [groups](../../projects/groups.md) you belong to, or those taken from the [Creator Store](../../production/creator-store.md).
</figure>
</TabItem>
<TabItem label="Recent">
<figure>
<img src="../../assets/studio/toolbox/Recent-Tab.png" width="360" height="121" alt="A close up view of the Toolbox with the Recent tab highlighted." />
The **Recent** tab is similar to **Inventory** except that filters your recently used models, decals, meshes, audio, videos, and animations.
</figure>
</TabItem>
<TabItem label="Creations">
<figure>
<img src="../../assets/studio/toolbox/Creations-Tab.png" width="360" height="121" alt="A close up view of the Toolbox with the Creations tab highlighted." />
The **Creations** tab is similar to **Inventory**, with the important distinction that it filters models, decals, meshes, audio, plugins, and animations that you've personally published or those which were published by [groups](../../projects/groups.md) you belong to. You can [configure](#asset-configuration) all assets in this section directly within Studio.
</figure>
</TabItem>
</Tabs>
## Find and use assets
With millions of assets available, it's helpful to narrow the search results to find exactly what you are looking for. To browse and use assets:
<ToolboxFindUse components={props.components} />
## Asset configuration
Right-clicking an asset and selecting **Edit Asset** opens the **Asset Configuration** window. In this window, you can edit the asset's details or restore it to a previous version.
<Alert severity="info">
Asset configuration is only possible for assets you've personally published or those which were published by [groups](../../projects/groups.md) you belong to. The **Creations** tab is particularly useful for filtering assets in this way.
</Alert>
## Troubleshooting
The toolbox runs through a web view. If you're experiencing any of the following issues, run the associated troubleshooting steps.
<BaseAccordion>
<AccordionSummary><Typography variant="subtitle2">General Issues</Typography></AccordionSummary>
<AccordionDetails>
<Alert severity="warning">
Make sure there are no active instances of Roblox Studio running before running these steps.
</Alert>
<table>
<thead>
<tr>
<th>Windows</th>
</tr>
</thead>
<tbody>
<tr>
<td>
1. [Reinstall](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) your Windows WebView2 installation.
2. Delete the WebView2 data folder found at `%LOCALAPPDATA%\Roblox\RobloxStudio\WebView2`. Studio will automatically recreate this folder when it opens.
</td>
</tr>
</tbody>
<thead>
<tr>
<th>Mac</th>
</tr>
</thead>
<tbody>
<tr>
<td>Delete the WebKit data folders found at `~/Library/WebKit/com.Roblox.RobloxStudio` and `~/Library/Caches/com.Roblox.RobloxStudio/WebKit`. Studio will automatically recreate these folders when it opens.</td>
</tr>
</tbody>
</table>
</AccordionDetails>
</BaseAccordion>
<BaseAccordion>
<AccordionSummary><Typography variant="subtitle2">Audio Not Working</Typography></AccordionSummary>
<AccordionDetails>
<table>
<thead>
<tr>
<th>Windows</th>
</tr>
</thead>
<tbody>
<tr>
<td>
1. Right click the speaker icon in the taskbar.
2. Click **Open Volume Mixer**.
3. Make sure that **Microsoft Edge WebView2** is not muted.
</td>
</tr>
</tbody>
</table>
</AccordionDetails>
</BaseAccordion>