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

335
.cursor/rules/roblox/en-us/avatar-setup/auto-setup-requirements.md Normal file
View file

@ -0,0 +1,335 @@
---
title: Auto-setup model requirements
description: The Avatar Setup tool previews animations, clothing, accessories, and body constructs on avatar rigs, directly in Studio.
---
<Alert severity = 'warning'>
Auto-setup is currently in [active development](https://devforum.roblox.com/t/avatar-auto-setup-now-supports-clothing-and-accessories/3709128) with many improvements on the roadmap. Note that some inputs might work better than others and your results can vary over time as additional training and improvements are made.
</Alert>
[Auto-setup](./auto-setup.md) supports the automatic conversion of basic custom models to Roblox-ready bodies, rigid accessories, and layered clothing. By [bundling](#bundle-multiple-assets) your models together, you can automatically setup multiple custom models into avatar items for use in-experience or for upload to the Marketplace.
### Body
Auto-setup can attempt to process a 3D model into a Roblox-ready character model. This is one of the most common use-cases for auto-setup and can help you save time by automating the rigging, caging, and other configurations required to make a Roblox-ready avatar character.
At this time, avatar assets like [rigid accessories](#accessories) and [layered clothing](#layered-clothing) may require processing with a base body. Auto-setup is able to use this base body as a mannequin, creating more accurate attachment points and other components to ensure a better fit. If converting accessories or clothing, you must [bundle](#bundle-multiple-assets) them with a base body for fitting.
#### Supported inputs
Auto-setup detects the following partial avatar body inputs:
<table><thead>
<tr>
<th><b>Reference Image</b></th>
<th><b>Auto-setup support</b></th>
</tr></thead>
<tbody>
<tr>
<td><img src="../assets/avatar/avatar-setup/Partial-Inputs-None-Rigged.png"/></td>
<td><Alert severity = 'success'>A single or multiple mesh body with **no rigging**.</Alert>The most common input is a single mesh object that doesn't include rigging data or other components. The input body must meet auto-setup's [model requirements](#body). <br /><br /> In this case, auto-setup creates the rest of the avatar components automatically.</td>
</tr>
<tr>
<td><img src="../assets/avatar/avatar-setup/Partial-Inputs-Body-Rigged.png"/></td>
<td><Alert severity = "success">A single or multiple mesh body with **only body rigging**.</Alert>If the provided meshes include a compatible R15 body rig, auto-setup uses the provided rig, and creates the facial rig and all other components. <br /><br /> The input body rig must follow Roblox's [rigging configuration](../art/characters/specifications.md#rigging), otherwise auto-setup creates a brand new rig for you.</td>
</tr>
<tr>
<td><img src="../assets/avatar/avatar-setup/Partial-Inputs-Head-Rigged.png"/><br /></td>
<td><Alert severity = "success">A multiple mesh with **only facial rigging**.</Alert>If you intend to use your own custom facial rigging, set the FaceRootJoint (and all child bones) as a child of the R15 head joint. For more information, see [optional rig requirements](#rig-requirements-optional). </td>
</tr>
<tr>
<td><img src="../assets/avatar/avatar-setup/Partial-Inputs-All-Rigged.png"/><br /></td>
<td><Alert severity = "success">A **single mesh** body with **both body and facial rigging**.</Alert>If the body rig, facial rig, and appropriate FACS data is included, auto-setup preserves that data and only generates the missing Roblox-specific components. **Bodies comprised of multiple meshes are not supported for this input.**<br /><br />For more information, see [optional rig requirements](#rig-requirements-optional).</td>
</tr>
</tbody></table>
#### Mesh requirements
To achieve the best results when converting a model to a Roblox-ready avatar character, it's important to configure your base model so the tool can properly generate avatar components with.
Note that Roblox is actively adding improvements to this tool and these requirements may lift in the future.
<Alert severity = 'error'>
Many existing [downloadable resources](../avatar/resources.md) for avatar bodies do not follow the auto-setup requirements below. Existing avatar references may need modification to ensure the asset follows the auto-setup models. <br /> <br />See the specific [auto-setup references](../avatar/resources.md#auto-setup-references) for assets that were created for auto-setup requirements.
</Alert>
The full requirements for the input body model are as follows:
1. **Single or multiple mesh** — In most cases, auto-setup accepts bodies comprising of 1 or more meshes. If your body includes multiple meshes, the tool automatically recombines all selected meshes as a single mesh, then decimates the combined parts to the appropriate R15 structure.
1. If providing the standard 15 multiple meshes that adhere to the R15 character naming convention, auto-setup attempts to place joints according to the user-partitioned body parts.
2. **5 distinct head components** — Whether you are using a single or multi-mesh character model, the following head components are required:
1. **2 eyes** — Heads must include 2 connected eyebags containing half-sphere eyes that do not share any vertices with the head component.
2. **3 mouthparts** — Heads must include a connected mouthbag that houses the **upper teeth**, **lower teeth**, and **tongue**.
1. Each of these mouthparts must be singly connected and not share any vertices with each other or with the head mesh.
<GridContainer numColumns="2">
<figure>
<img src="../assets/avatar/avatar-setup/Mouthparts-1.png" alt ="" />
</figure>
<figure>
<img src="../assets/avatar/avatar-setup/Mouthparts-2.png" alt ="" />
</figure>
</GridContainer>
3. **Head geometry must not share vertices** — Eyeballs, teeth, and tongue must be part of the model without sharing vertices with the body mesh.
<GridContainer numColumns="2">
<figure>
<img src="../assets/avatar/avatar-setup/Mouthparts-3.png" alt ="" />
</figure>
<figure>
<img src="../assets/avatar/avatar-setup/Mouthparts-4.png" alt ="" />
</figure>
</GridContainer>
4. **Within triangle budget** — The total body mesh resolution must be within 10,742 triangles. Use the following guidance to ensure each part doesn't exceed expected polycounts:
<table>
<thead>
<tr>
<th>Body part grouping</th>
<th>Maximum triangles</th>
<th>Maximum quads</th>
</tr>
</thead>
<tbody>
<tr>
<td>Head</td>
<td>4000</td>
<td>2000</td>
</tr>
<tr>
<td>Arms</td>
<td>1248 per arm</td>
<td>624 per arm</td>
</tr>
<tr>
<td>Legs</td>
<td>1248 per leg</td>
<td>624 per arm</td>
</tr>
<tr>
<td>Torso</td>
<td>1750</td>
<td>875</td>
</tr>
<tr>
<td>Total: </td>
<td>10,742</td>
<td>5495</td>
</tr>
</tbody>
</table>
1. The setup tool segments and adds [caps](../art/characters/specifications.md#body-parts) to the character limbs which may add to your total polycount. If your character model is close to the polycount limit, the additional geometry may cause validation failures.
5. **Humanoid shape** — The body must follow a general humanoid shape, with two arms, two legs, a torso, and a head.
6. **A-pose or T-Pose** — The body should form an upright A-pose or T-Pose.
1. Bodies with I-pose may yield lower quality results.
2. Ensure that no limbs obscure or overlap each other from the front view.
7. **Negative Z Axis** — The body front should face the negative Z axis.
8. **Symmetrical** — Asymmetrical bodies may work on a case-to-case basis. Position the center of the body with the Y-axis to improve the accuracy of the result.
1. If your asymmetrical model experiences setup issues, try using a more symmetrical version.
9. **Watertight** — Ensure the model is watertight in all regions with the exception of the eyes and mouth. Watertight means that there are no holes in the mesh and no back faces are exposed.
10. **No accessories** — Do not include accessories, including face accessories, like hair, eyebrows, beards, and eyelashes.
11. **Distinct neck area** — Keep the neck distinct and not merged with the shoulders or upper torso.
12. **Includes texture** — Models should include one or more texture maps. If the input body includes multiple textures, the tool bakes the textures to a single map. This applies to [PBR textures](../art/modeling/surface-appearance.md) where the four textures are baked — one for each albedo, normal, metalness and roughness.
13. **Follows Marketplace and Community Policy** — The model must conform to Roblox's [Marketplace Policy](../marketplace/marketplace-policy.md) and [Community Standards](https://en.help.roblox.com/hc/en-us/articles/203313410-Roblox-Community-Standards).
#### Rig requirements (Optional)
You can use your own custom body and face rig for your character model input instead of allowing auto-setup to generate a new one.
<Alert severity = 'info'>
If you provide the standard 15 multiple meshes that adhere to the R15 character naming convention **without a rig**, auto-setup attempts to generate joints according to the user-partitioned body parts.
</Alert>
To ensure that auto-setup uses your **own custom body rig**:
- Ensure that your bones (Blender) or joints (Maya) meet [Roblox's avatar rigging requirements](../art/characters/specifications.md#rigging).
- Double-check naming conventions and hierarchy.
- Body rigs should not include additional bones beyond the standard 15, and facial rigs (no bone limit) should be correctly parented to a RootFaceJoint.
To ensure that auto-setup uses your **own custom face rig and FACs data**:
- A supported R15 body rig is required when submitting custom facial rigs and facial animation data.
- Review [supported body inputs](#body) to ensure you are submitting a supported body input and facial rig combination.
- Facial rig must include a `RootFaceJoint` bone (usually [mapped](../art/characters/facial-animation/create-basic-heads.md#map) as `DynamicHead`) whose parent is the `Head` joint of the R15 rig.
- All the other facial animation joints are descendants of the `RootFaceJoint`, and not direct children of the `Head` joint.
- Animations need to be provided for the [17 required poses](../art/characters/specifications.md#facial-animations), at minimum.
- Neutral animation must map to frame `0`.
- Since the head is part of the single mesh with the body, the facial animation mappings must be included with the single body mesh:
- The mapping between animation frames and facial poses are stored in the extra attributes / custom properties of the provided single mesh.
- The name of the root face joint is stored in the extra attributes / custom properties of the single mesh, mapping `RootFaceJoint` to the corresponding name (usually `DynamicHead`).
#### Examples of non-supported bodies
The following are common examples of bodies that may not yield expected results with auto-setup:
<BaseAccordion>
<AccordionSummary>
<Typography>Non-supported model examples</Typography>
</AccordionSummary>
<AccordionDetails>
<table>
<tbody>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/Assymetry.png" alt=""/><figcaption>**Extreme asymmetry** &mdash; If you are having issues with an asymmetrical model, try using a more symmetrical version and make minor adjustments.</figcaption></figure></center>
</td>
</tr>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/I-pose.png" alt=""/><figcaption>**I-pose** &mdash; If you are experiencing issues with your model in an I-pose, try resubmitting with A-pose or T-pose.</figcaption></figure></center>
</td>
</tr>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/Non-Contiguous.png" alt=""/><figcaption>**Non-contiguous mesh** &mdash; setup tool expects the body mesh to be completely contiguous.</figcaption></figure></center>
</td>
</tr>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/No-Neck.png" alt=""/><figcaption>**No neck** — setup tool expects a neck connecting a head to the torso.</figcaption></figure></center>
</td>
</tr>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/Long-Neck.png" alt=""/><figcaption>**Out of proportion limbs** &mdash; setup tool expects a more realistic humanoid-style character model.</figcaption></figure></center>
</td>
</tr>
<tr>
<td>
<center><figure><img src="../assets/avatar/avatar-setup/Non-Proportional-Limbs.png" alt=""/><figcaption>**Out of proportion limbs** &mdash; setup tool expects a more realistic humanoid-style character model.</figcaption></figure></center>
</td>
</tr>
</tbody>
</table>
</AccordionDetails>
</BaseAccordion>
### Accessories
<Alert severity = 'warning'>
At this time, you must [bundle](#bundle-multiple-assets) your accessory and clothing models with a base body to utilize auto-setup. For more information, see [supported inputs](#supported-inputs-1).
</Alert>
Auto-setup can convert models into rigid accessories, configuring the scale type and attachment components required for rigid accessories.
To convert a mesh model into an accessory using auto-setup:
1. Fit the model onto a base body in Studio or your 3D modeling software.
2. [Bundle](#bundle-multiple-assets) the assets together in a single `Class.Folder`.
3. Use **Avatar Setup** to use auto-setup on your assets.
During this process, you will be able to designate individual meshes or models as rigid accessories, layered accessories, or body parts. After conversion, a prompt displays allowing you to select the specific **Asset Type**.
For best results, ensure your models adhere to Roblox's [accessory geometry specifications](../art/accessories/specifications.md#geometry-and-budgets).
#### Supported inputs
Rigid accessory meshes must be bundled with a body for auto-setup to configure. See the following supported inputs for rigid accessory meshes.
<table><thead>
<tr>
<th>Input object</th>
<th>Auto setup generates</th>
</tr></thead>
<tbody>
<tr>
<td>
<ul>
<li>`Folder` [bundle](#bundle-multiple-assets) containing:</li>
<ul>
<li>`Class.Model` containing fully or partially configured character body </li>
<li>`Class.Model` containing accessory mesh object (this is the object created when importing a custom 3D object)</li>
</ul>
</ul>
</td>
<td>`Class.Accessory` containing clothing mesh, `BodyPartScaleType`, and attachment points</td>
</tr>
</tbody>
</table>
### Layered clothing
Auto-setup can convert models into clothing accessories, adding in rigging and caging data that normally requires manual configuration in a separate software.
To convert a mesh model into an accessory using auto-setup:
1. Fit the model onto a base body in Studio or your 3D modeling software.
2. (Optional - for best results) [Bundle](#bundle-multiple-assets) the assets together in a single `Class.Folder`.
3. Use Avatar Setup to use auto-setup on your assets.
During this process, you will be able to designate individual meshes or models as rigid accessories, layered accessories, or body parts. After conversion, a prompt displays allowing you to select the specific **Asset Type**.
For best results, ensure your models adhere to Roblox's [layered clothing geometry specifications](../art/accessories/clothing-specifications.md#geometry-and-budgets).
#### Supported inputs
Auto-setup can configure clothing models to a layered clothing `Class.Accessory` complete with caging and rigging data. While auto-setup can configure models without a bundled body, you may find better results if you include a base body for setup.
<table><thead>
<tr>
<th>Input object</th>
<th>Auto setup generates</th>
</tr></thead>
<tbody>
<tr>
<td>`Class.Model` containing clothing mesh object with no additional components (this is the object created when importing a custom 3D object) </td>
<td>
<ul>
<li>`Class.Accessory` containing clothing mesh and the following generated components:</li>
<ul>
<li>Inner and outer cage data</li>
<li>Attachment points</li>
</ul>
</ul>
<Alert severity = 'warning'>Without an accompanying body asset, auto setup makes a best effort for generating cage data.</Alert>
</td>
</tr>
<tr>
<td>
<ul>
<li>`Folder` [bundle](#bundle-multiple-assets) containing:</li>
<ul>
<li>`Class.Model` containing fully or partially configured character body </li>
<li>`Class.Model` containing accessory mesh object (this is the object created when importing a custom 3D object)</li>
</ul>
</ul>
</td>
<td>
<ul>
<li>`Class.Accessory` containing clothing mesh and the following generated components:</li>
<ul>
<li>Inner and outer cage data</li>
<li>Attachment points</li>
</ul>
</ul>
</td>
</tr>
</tbody>
</table>
## Bundle multiple assets
Auto-setup can process multiple accessory or clothing models with a single body model. To submit multiple models in the **Avatar Setup** tool, parent your models within a single folder.
<figure>
<center><img src="../assets/avatar/avatar-setup/Folder-Hierarchy.png"/></center>
<center><figcaption>A `Folder` containing the various `Model` objects ready to be processed by auto-setup into body, accessory, and clothing assets.</figcaption></center>
</figure>
To quickly parent your objects to folder:
1. In the **Explorer**, hold <kbd>Shift</kbd> and select the `Class.Model` objects you intend to process with auto-setup. Ensure you are selecting a [supported base body](#body) as one of the `Class.Model` objects.
2. Right-click and select **Group as Folder**.
3. Select the `Class.Folder` and then select the **Avatar Setup** tool to begin processing.
<Alert severity = 'warning'>
At this time, you must bundle your accessory and clothing models with a base body to utilize auto-setup.
</Alert>

165
.cursor/rules/roblox/en-us/avatar-setup/auto-setup.md Normal file
View file

@ -0,0 +1,165 @@
---
title: Auto-setup
description: The Avatar setup tool previews animations, clothing, accessories, and body constructs on avatar rigs, directly in Studio.
---
<Alert severity = 'warning'>
Auto-setup is currently in [active development](https://devforum.roblox.com/t/avatar-auto-setup-now-supports-clothing-and-accessories/3709128) with many improvements on the roadmap. Note that some inputs might work better than others and your results can vary over time as additional training and improvements are made.
</Alert>
<iframe width="880" height="495" src="https://www.youtube-nocookie.com/embed/Hp9pr2FpZa8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> <br />
If [Avatar Setup](./index.md) detects that the input model is an incomplete avatar asset model, the **auto-setup** feature attempts to convert the model into an avatar asset with all the advanced components that allow characters to interact with the world and express themselves with accessories and clothing. <br />
For characters, accessories, and clothing, auto-setup can perform the following:
- **Rigging** — Adds an R15 armature to your body model to enable movement and animation.
- **Skinning** — Adds weights and influences to various surfaces of your mesh, ensuring an organic and natural flexibility during movement.
- **Facial animation** — Generates the FACS poses, facial rigging, skinning, and animation data required for facial animation and avatar chat.
- **Caging** — Adds the required cages to your asset, enabling it to support layered clothing.
- **Partitioning** — Separates the body mesh into the appropriate R15 parts.
- **Creating attachments** — Adds the appropriate attachment points enabling the character to wear rigid accessories.
If the selected model already contains all the required components for a Roblox avatar, the Avatar Setup tool skips auto-setup and immediately opens the selected model in the [Avatar Setup test interface](./index.md#test-and-edit).
## Supported asset types
Auto-setup supports the conversion of following asset types from a base `Class.Model`:
<figure>
<table><thead>
<tr>
<th>Asset type</th>
<th>Input object</th>
<th>Output object</th>
</tr></thead>
<tbody>
<tr>
<td>Avatar body</td>
<td>`Class.Model` containing one or more `Class.MeshPart` objects that meets auto-setup's supported [body inputs](./auto-setup-requirements.md#body).</td>
<td>`Class.Model` parenting associated 15 `Class.MeshPart` objects and other expected [avatar components](../art/characters/index.md#components-of-an-avatar).</td>
</tr>
<tr>
<td>Accessory</td>
<td>`Class.Model` containing one or more `Class.MeshPart` objects that meet's auto-setup's supported [accessory inputs](./auto-setup-requirements.md#accessories). <br /> <br />Must [bundle](./auto-setup-requirements.md#bundle-multiple-assets) with an avatar body `Class.Model` for auto-setup.</td>
<td>`Class.Accessory` that includes all expected [rigid accessory components](../art/accessories/index.md#components-of-a-rigid-accessory).</td>
</tr>
<tr>
<td>Layered clothing</td>
<td>`Class.Model` containing one or more `Class.MeshPart` objects that meet's auto-setup's supported [accessory inputs](./auto-setup-requirements.md#accessories-and-clothing). <br /> <br />Can optionally [bundle](./auto-setup-requirements.md#bundle-multiple-assets) with an avatar body `Class.Model` for auto-setup.</td>
<td>`Class.Accessory` that includes all expected [layered accessory components](../art/accessories/layered-clothing.md#components-of-a-layered-clothing-accessory).</td>
</tr>
<tr>
<td>Multiple accessories and clothing with single body</td>
<td>`Folder` [bundle](./auto-setup-requirements.md#bundle-multiple-assets) containing one or more `Class.Model` that meet supported inputs for accessories, clothing, or body. <br /> <br />Must [bundle](./auto-setup-requirements.md#bundle-multiple-assets) with an avatar body `Class.Model` for auto-setup.</td>
<td>`Class.Model` character body and any `Class.Accessory` equipable items. <br /> <br />All generated assets include expected avatar item components.</td>
</tr>
</tbody>
</table>
</figure>
For more in-depth information on supported input configurations, see the individual asset specifications on [auto-setup requirements](./auto-setup-requirements.md).
## Auto-setup settings
The following settings provides additional controls to your auto-setup output.
### Platform and Development
You can configure auto-setup to generate avatars for either **Platform** or **Development** use.
- **Platform** — Auto-setup attempts to configure the input asset into a Marketplace-ready asset that users can purchase and use across the Roblox platform. Marketplace-ready assets have more restrictive requirements than assets used in-experience.
- **Development** — Auto-setup attempts to configure the input asset into an avatar asset usable in-experience. You can use development assets in your experience, such as non-playable characters, or in-experience UGC items. Auto-setup doesn't apply the same Marketplace requirements on development assets.
### Manually Align Front
Auto-setup attempts to determine the front direction of the input avatar and aligns it with the negative Z-axis in world space. You can skip this pre-processing step and do the alignment yourself.
### Improve Facial Caging
Enables an additional post-processing step that significantly improves the alignment of the head cage with the head model. Currently, this step takes about 30 seconds.
### Reduce Triangle Count
By default, auto-setup attempts to reduce triangle count of the input mesh using auto-decimation. If Reduce Triangle Count is disabled, auto-setup skips the decimation process. This setting is only accessible for [Development](#platform-and-development) setups allowing you to create assets with triangle counts above the Marketplace requirement.
## Reference models
Studio supports `.gltf`, `.fbx`, and `.obj` models using the 3D Importer. If you are exporting your model from a third-party tool, see [Export Settings](../art/characters/export-settings.md) for export configurations.
For an asset that meets all of these model requirements, download one of the following auto-setup templates for your own reference and testing:
<Grid container alignItems="stretch" style={{ margin: -6 }}>
<Grid item XSmall={12} Medium={6} Large={4} style={{ padding: 6 }}>
<Card style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
<CardContent style={{ flex: 1 }}>
<center>Nature Girl - Auto-Setup</center>
<figure>
<center>
<img
src="../assets/art/resources/Archer-Girl-Preview.png"
width="100%"
/>
</center>
</figure>
<figure>
A comprehensive <code>.zip</code> folder of an{' '}
<a href="./auto-setup-requirements.md">Avatar auto-setup</a> ready
character model, including clothing and rigid accessory assets and PBR
texture assets.
<br /><br />
This auto-setup template is not compatible with the traditional avatar
creation workflow.
</figure>
</CardContent>
<CardActions>
<Button
href="../assets/art/reference-files/NatureArcherGirl-AutoSetup.zip"
fullWidth
size="large"
color="primary"
variant="contained"
>
Download
</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{ padding: 6 }}>
<Card style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
<CardContent style={{ flex: 1 }}>
<center>Stylish Male - Auto-Setup</center>
<figure>
<center>
<img
src="../assets/art/resources/StylizedMale-Preview.png"
width="100%"
/>
</center>
</figure>
<figure>
A comprehensive <code>.zip</code> folder of an{' '}
<a href="./index.md">Avatar auto-setup</a> ready character model,
including the base body and associated PBR textures.
<br /><br />
This auto-setup template is not compatible with the traditional avatar
creation workflow.
</figure>
</CardContent>
<CardActions>
<Button
href="../assets/art/reference-files/StylizedMale-AutoSetup.zip"
fullWidth
size="large"
color="primary"
variant="contained"
>
Download
</Button>
</CardActions>
</Card>
</Grid>
</Grid>

75
.cursor/rules/roblox/en-us/avatar-setup/index.md Normal file
View file

@ -0,0 +1,75 @@
---
title: Avatar Setup
description: The Avatar Setup tool previews animations, clothing, accessories, and body constructs on avatar rigs, directly in Studio.
---
The **Avatar Setup** tool helps accelerate the avatar character, clothing, and accessory creation process by automatically processing custom models into avatar assets:
1. [Import](#import-a-model) a custom model.
2. Select the model and click on [Avatar setup](#run-avatar-setup) to run.
1. If your model does not include all the components of an avatar model, the tool attempts to [auto-setup](./auto-setup.md) the model into an avatar asset.
3. [Test and edit](#test-and-edit) the asset.
4. (Optional) [Publish](#publish) the asset to Marketplace.
<img src="../assets/studio/general/Toolbar-Avatar-Setup.png" width="800" alt="Avatar Preview button indicated in Avatar tab" />
<GridContainer numColumns="2">
<figure>
<img src="../assets/avatar/avatar-setup/Avatar-Setup-Example-A.png" />
<figcaption>Import a complete or incomplete avatar character into the tool. The auto-setup feature adds any missing components.</figcaption>
</figure>
<figure>
<img src="../assets/avatar/avatar-setup/Avatar-Setup-Example-B.png" />
<figcaption>You can try out various skin tones, animations, rigid and layered clothing, and more before uploading and selling the avatar asset.</figcaption>
</figure>
</GridContainer>
## Import a model
If you are using a custom 3D asset, import your asset into Studio using the 3D importer tool. To import the model into Studio:
1. From Studio's **File** menu, select **3D Importer**.
2. In the file browser, select your model object.
3. When your model object loads in the 3D Import preview, disable the **Upload To Roblox** option.
1. This prevents the asset immediately saving to your **Toolbox**, preventing unwanted copies of similar assets.
2. To save time in the future, click the **&ctdot;** dropdown in the top-right of the 3D Importer window and **Save as New** to create an import profile for this workflow.
4. Verify the preview and any warnings or errors in your model object.
1. See [3D Importer](../art/modeling/3d-importer.md) for additional information. Certain warnings and errors may require readjusting the model in a third-party software.
5. Select **Import** to add the `Class.Model` instance into your workspace.
<Alert severity = 'warning'>
When a new model is imported, it's also added to the moderation queue. If an avatar asset is moderated incorrectly, you will receive a moderation email with a link to appeal. This appeal takes up to 10 minutes to resolve.
</Alert>
## Run Avatar Setup
When your project has the appropriate `Class.Model` in your workspace, you can begin the avatar setup process.
1. Select the model in the workspace.
1. If you want to select only specific meshes of your model, navigate to the Explorer, expand the `Class.Model` object, and hold shift and click on the individual mesh objects.
2. With the Model selected, navigate to the **Avatar tab** and select **Avatar Setup**.
1. If your model requires [auto-setup](./auto-setup.md), the tool begins processing your model. This can take several minutes.
1. Once auto-setup is complete, a `Class.Model` of your avatar populates in your workspace and in the testing panel. Review any warnings or errors before using any testing or editing tools.
2. If your model doesn't require auto-setup, the tool populates your avatar asset in the preview panel and you can access the [test and edit](#test-and-edit) functionalities.
## Test and edit
After successfully loading a character model into the tool, the character populates in the preview window with various testing, editing, and preview tools. If you discover any issues that can't be resolved with the edit tools, you may need to update your base input model in your third-party modeling software and/or retry the auto-setup process.
For more information on the various testing interfaces and editing features, see [Test and Edit Tools](./tools.md).
<Alert severity = 'warning'>
It's important to test that your avatar components have correctly generated by testing out different clothing, rigid accessories, and animations.
</Alert>
## Publish
The **Publish** button opens the publish asset dialog, with an option to upload the avatar and any accessory items to the Marketplace. You can only publish assets that are correctly configured as platform avatar assets.
When selecting the Publish option, you can upload the asset to the Marketplace, where you can sell the item paying an [upload fee](../marketplace/publish-to-marketplace.md#upload-an-asset), clearing moderation, and publishing the asset to the catalog.
For additional resources on the publishing process and Marketplace, see the following:
- [Publish to the Marketplace](../marketplace/publish-to-marketplace.md)
- [Marketplace fees and commissions](../marketplace/marketplace-fees-and-commissions.md)
- [Marketplace policy](../marketplace/marketplace-policy.md)

92
.cursor/rules/roblox/en-us/avatar-setup/tools.md Normal file
View file

@ -0,0 +1,92 @@
---
title: Avatar Setup Tools
description: The Avatar setup tool previews animations, clothing, accessories, and body constructs on avatar rigs, directly in Studio.
---
Use the **Avatar Setup** tool's [preview and testing tools](#preview) to ensure your character moves, animates, equips accessories, and looks as expected.
**Avatar Setup** also provides tools for [minor editing and adjustments](#edit-tools) that allow you to make minor to moderate changes to your model. Major fixes may require you to make your adjustments in your third-party modeling software and re-export.
<Alert severity = 'info'>
As **Avatar Setup** continues development, check this page for additional tools and features when they release.
</Alert>
## Preview
In the **Avatar Setup** window, use the side navigation to access the various testing interfaces.
<GridContainer numColumns='2'>
<figure><img src="../assets/avatar/avatar-setup/Testing-Interface.png" alt="" width = "100%"/></figure>
<figure>Once an avatar is added to the tool, four tabs appear on the left side of the panel: <ul><li>[Check body](#check-body)</li> <li>[Check face](#check-face)</li> <li>[Test in experience](#test-in-experience)</li> <li>[Publish](./index.md#publish)</li></ul></figure>
</GridContainer>
### Check body
The **Check Body** interface contains tabs for Animations, Clothing, Accessories, and Body assets, such as skin-tone and swapping body parts. Clicking a subtab like Shirts, Waist, or Skin reveals a selection column along the left side of the window for testing various cosmetics and visuals.
<img src="../assets/avatar/avatar-setup/Skin-Tone-Selector.png" alt="" width = "60%"/>
### Check face
The **Check Face** interface zooms into the face and allows you test various facial poses.
<GridContainer numColumns="2">
<figure>
<img src="../assets/avatar/avatar-setup/Test-Face-1.png" />
<figcaption>Check the range of facial poses with multiple facial animation tests.</figcaption>
</figure>
<figure>
<img src="../assets/avatar/avatar-setup/Test-Face-2.png" />
<figcaption>Unexpected facial animation behavior, such as crashing or artifacts, may minor adjustment to the base mesh and re-running the auto-setup process.</figcaption>
</figure>
</GridContainer>
### Equip items
Selected items are equipped on the avatar and are added to the currently equipped column on the right side. Selected animations begin playing as a preview of how they'll look in a running experience.
To unequip an item, click it again in the selection column, press the **X** button at the top right of the equipped item, or right-click the asset in the Equipped column and select **Unequip**. You can also drag and order the various equipped accessories to set the worn order.
### Add items
The add item button allows you to add custom assets to the tool's palette for testing.
To add an item to the palette:
1. Select a valid **Accessory** or **Body Part** asset from the **Explorer** or 3D viewport.
2. Click the add item button at the bottom of the selection column along the left side of the window.
<img src="../assets/avatar/avatar-setup/Add-Object.png" alt=""width = "20%"/>
3. The item appears in the appropriate section and subsection of the Check Body interface, such as **Accessories** → **Hair**.
### Test in experience
The **Test in Experience** button starts playtesting the experience with the previewed avatar. Any changes made using the preview tools, such as equipped clothing or accessories, or modifications such as skin tone or body part swaps, do not transfer over to the playable character model in this mode.
## Edit tools
Use the **Avatar Setup** tool to make quick adjustments to your model and any generated assets.
<Alert severity = 'info'>
As **Avatar Setup** continues development, check here for additional tools and features when they release.
</Alert>
### Edit cage meshes
<iframe width="800" height="450" src="https://www.youtube-nocookie.com/embed/fwbuhzq1D0k" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<br /><br />
You can modify your body cage mesh using the cage mesh editing tool. Use the brush and various brush settings to modify your cage, allowing you to make adjustments to how clothing and other layered assets fit on your character. <br />
Use the following controls to get fine-grain control on your cage edits:
<img src="../assets/avatar/avatar-setup/Cage-Edit-Panel.png" alt=""width = "80%"/>
- Symmetrical and mirror edits along X-axis.
- Brush with radius and falloff controls.
- Brush falloff visualization over the vertices.
- Ability to hide or display equipped layered clothing items. Layered clothing will update in real time in the **Avatar Setup** tool's preview window
<Alert severity = 'warning'>
Major cage edits may require returning to your third-party modeling tool, making your cage adjustments, and then re-exporting the asset.
</Alert>