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

rules

Browse source
This commit is contained in:
Joe 2026-02-02 12:08:47 -06:00
parent a9b4f8e83b
commit e6efc04756
8494 changed files with 495610 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

398
.cursor/rules/roblox/art/modeling/3d-importer.md Normal file
View file

@ -0,0 +1,398 @@
---
title: 3D Importer
description: 3D Importer imports third-party .fbx, .gltf, and .obj 3D model assets into Studio.
---
The 3D Importer allows you to import `.fbx`, `.gltf`, or `.obj` 3D models into Studio as a custom `Class.Model`. This includes meshes with PBR textures, meshes with rigging, skinning, and animation data, and meshes designed as avatar items.
<Grid container spacing={2} style={{ marginBottom: 24, width: '100%' }}>
<Grid item xs={6} style={{ padding: 16 }}>
<Grid item container wrap="nowrap" direction="column" style={{ gap: 8, flex: 1 }}>
<div
className="container"
style={{ position: "relative", paddingBottom: "56.25%", height: 0, marginBottom: 12 }} >
<iframe
src="https://www.youtube-nocookie.com/embed/ikYZloBgqtE"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }} ></iframe>
</div>
<Typography variant="body1">
Import general 3D custom models into Studio.
</Typography>
</Grid>
</Grid>
<Grid item xs={6} style={{ padding: 16 }}>
<Grid item container wrap="nowrap" direction="column" style={{ gap: 8, flex: 1 }}>
<div
className="container"
style={{ position: "relative", paddingBottom: "56.25%", height: 0, marginBottom: 12 }} >
<iframe
src="https://www.youtube-nocookie.com/embed/RCsYZe3LoDM"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }} ></iframe>
</div>
<Typography variant="body1">
Use the 3D importer to import assets with avatar item components.
</Typography>
</Grid>
</Grid>
</Grid>
To import a 3D object:
1. From Studio's **File** menu, select **Import 3D**.
2. In the file browser, select the supported `.fbx`, `.gltf` or `.obj` files you intend to import.
1. If selecting one object, the [import preview](#import-preview) window screen appears for that object.
2. If selecting multiple objects, the files are added to the [import queue](#import-queue).
3. Configure your import settings and verify any [warning or error messages](#warnings-and-errors).
4. Click **Import**.
<Alert severity ='info'>
To directly import 3D assets using HTTP requests, see the [Open Cloud usage guide for assets](../../cloud/guides/usage-assets.md).
</Alert>
## Supported file types
Before importing a 3D object, ensure that the `.fbx`, `.gltf` or `.obj` meets Studio's [mesh requirements](../../art/characters/specifications.md) to reduce errors or unexpected behavior.
<table><thead>
<tr>
<th style={{width:"20%"}}>**File type**</th>
<th style={{width:"40%"}}>**Studio compatibility**</th>
<th>**Best for**</th>
</tr></thead>
<tbody>
<tr>
<td>OBJ (`.obj`)</td>
<td>— Basic single mesh objects</td>
<td>Simple mesh geometry use-cases.</td>
</tr>
<tr>
<td>FBX (`.fbx`)</td>
<td>— Multiple mesh objects and hierarchies<br/>— Textures, including basic and [PBR textures](../../art/modeling/surface-appearance.md).<br/>— Cage mesh objects<br/>— [Rigging and armature data](../../art/modeling/rigging.md)<br/>— Additional components for [avatar](../../avatar/index.md) items<br/>— Animation data<br/>— [Vertex colors](../blender.md#vertex-painting)</td>
<td>Any type of 3D import, including but not limited to [game assets](../../assets.md) or [avatar items](../../avatar).</td>
</tr>
<tr>
<td>gLTF (`.gltf`)</td>
<td>— Multiple mesh objects and hierarchies<br/>— Textures, including basic and [PBR textures](../../art/modeling/surface-appearance.md).<br/>— Cage mesh objects<br/>— [Rigging and armature data](../../art/modeling/rigging.md)<br/>— Additional components for [avatar](../../avatar/index.md) items<br/>— Animation data<br/>— [Vertex colors](../blender.md#vertex-painting)</td>
<td>Any type of 3D import, including but not limited to [game assets](../../assets.md) or [avatar items](../../avatar).</td>
</tr>
</tbody></table>
## Import queue
If you selected multiple files with the 3D Importer, you can use the import queue to bulk manage your various imports.
<img src="../../assets/modeling/meshes/3d-Import-Queue.png" width="80%" alt="The 3D importer interface, showing a preview of the mesh in the top left, a list of 3D objects on the bottom left, and a list of toggle-able properties on the right side."/>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-A.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **top bar** allows you to add new files, clear the queue, search and filter, and import all enabled models.
</Grid>
</Grid>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-B.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **import queue** lists all added files, with quick access dropdowns to change creator, presets, and file paths.
</Grid>
</Grid>
### Add files to queue
To open a file browser and add additional files to the import queue, you can:
- Click the **Add file** button in the top bar of the import queue window.
- From Studio's **File** menu, select **Import 3D**.
### Remove files from queue
To remove all files from the queue, click the **Clear queue** button with the broom icon. To remove an individual file from the queue, right-click an item in the queue and select **Delete from queue**.
### Apply preset settings
Use the **Import Preset** column to select a preset configuration to apply to your model. For more information, see [Presets](#presets).
You can also apply the settings of one item to all items by right-clicking an item with the desired settings and selecting **Apply settings to all**.
### Access individual preview and settings
Click the individual **Asset** name of an unimported model to access the import preview for that item. Use the import preview to view and check your model, as well as set any individual [import settings](#import-settings).
### Import files
Ensure that each item you want to import has a checkbox enabled in the first column. By default, all items are selected if they are importable.
Press the **Import** button to start the import process.
## Import preview
The import preview window appears if you are importing a single file, or if you selected an individual item from the import queue. This preview window provides individual controls for the various objects in your model.
The preview window is divided into multiple sections:
<img src="../../assets/modeling/meshes/3d-Importer-Panels.png" width="80%" alt="The 3D importer interface, showing a preview of the mesh in the top left, a list of 3D objects on the bottom left, and a list of toggle-able properties on the right side."/>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-A.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **file path** of your model file. Click **Browse** to edit.
</Grid>
</Grid>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-B.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **preset** applied to your import. Use the dropdown to select multiple presets, or the hamburger menu to set a new preset.
</Grid>
</Grid>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-C.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **3D preview** of your model. Use mouse buttons and top-right icons for various camera options and views.
</Grid>
</Grid>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-D.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **object hierarchy** of the imported object. Includes mesh objects and other supported components.
</Grid>
</Grid>
<Grid container spacing={2}>
<Grid item XSmall={2} Medium={1} Large={1} XLarge={1}><img src="../../assets/misc/Box-Label-E.png" width="40" style={{float:"right"}} /></Grid>
<Grid item XSmall={10} Medium={11} Large={11} XLarge={11} style={{marginTop:"4px"}}>
The **import settings** for your import. For a complete list of settings, see [Import settings](#import-settings).
</Grid>
</Grid>
### Import settings
Depending on the object selected in the hierarchy panel, the inspector panel displays the following groups of settings:
- **File General**: Affects the entire imported file.
- **Rig General**: Affects the selected mesh object if rigging data is present.
- **File Transform**: Affects the transform properties of the imported file.
- **File Geometry**: Affects the geometry properties of the imported file.
- **Object General**: Affects the selected child object.
- **Object Geometry**: Affects the geometry of the selected child object.
#### File general
The 3D Importer provides the following settings for all meshes:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Name</td>
<td>Sets the name of the imported asset as it will appear in your project.</td>
</tr>
<tr>
<td>Import Only As Model</td>
<td>If enabled, the 3D Importer imports the model as a single asset even if the model contains multiple children. By default, this is **enabled**. <br /><br />If disabled, the 3D Importer imports the model and all descendants, such as the multiple meshes, as individual assets.</td>
</tr>
<tr>
<td>Add Model To Inventory</td>
<td>If enabled, the 3D Importer adds the model to your **Toolbox** and **Asset Manager** inventory as a new asset. By default, this is **enabled**. <br /><br />If disabled, the 3D Importer does not add the asset to your inventory.</td>
</tr>
<tr>
<td>Insert In Workspace</td>
<td>If enabled, the 3D Importer inserts the model into the `Class.Workspace` as well as your **Toolbox** and **Asset Manager** inventory. If importing from a saved or published experience, this setting also grants permission to the experience to use the restricted asset. By default, this is **enabled**. <br /><br />If disabled, this setting only adds the model to your inventory and does **not** grant the experience permission to use the asset.</td>
</tr>
<tr>
<td>Insert Using Scene Position</td>
<td>If enabled, the 3D Importer uses the current scene position when inserting the model into the workspace. By default, this is **disabled**.</td>
</tr>
<tr>
<td>Set Pivot to Scene Origin</td>
<td>If enabled, the 3D Importer sets the pivot point of the entire model to the scene origin. By default, this is **enabled**.</td>
</tr>
<tr>
<td>Anchored</td>
<td>If enabled, the 3D Importer sets the `Class.BasePart.Anchored|Anchored` property to `true` on all the imported `Class.MeshPart|MeshParts`. This is disabled for meshes with rig data / avatars. By default, this is **disabled**.</td>
</tr>
<tr>
<td>Uses Cage</td>
<td>If enabled, the 3D Importer finds cage meshes in the model and converts them to `WrapInstance` objects, such as `Class.WrapLayer` or `Class.WrapTarget`. If disabled, the Importer treats them as regular meshes. If the 3D Importer initially detects cage meshes in the model, this is **enabled** by default.</td>
</tr>
</tbody>
</table>
#### Rig general
The 3D Importer provides the following settings for meshes with rigging data, typically character bodies or clothing accessories:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Rig Type</td>
<td>Sets the type of rig the mesh should be associated with. The options are:<br />- **R15**<br />- **Custom**<br />- **No Rig**<br /><br />By default, the 3D importer attempts to select the most appropriate setting based on the detected rigging and skinning data of the mesh. </td>
</tr>
<tr>
<td>Validate UGC Body</td>
<td>After importing, Studio opens the assets in the [Avatar Setup](../../avatar-setup/index.md) tool, allowing you to quickly begin testing and uploading avatar assets to the Marketplace.</td>
</tr>
<tr>
<td>Rig Scale</td>
<td>If Rig Type is set to R15, the importer provides additional options to specify [body type scaling](../../art/characters/specifications.md#body-scale). The options are:<br />- **Default**<br />- **Rthro**<br />- **Rthro Narrow**</td>
</tr>
</tbody>
</table>
#### File transform
The 3D Importer provides the following settings for all meshes:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>World Forward</td>
<td>Sets the forward facing axis of the object. By default, this is set to **Front**.</td>
</tr>
<tr>
<td>World Up</td>
<td>Sets the upward facing axis of the object. By default, this is set to **Top**.</td>
</tr>
</tbody>
</table>
#### File geometry
File geometry includes information on the file dimensions and polycount of the entire model. You can edit the following settings for all meshes:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scale Unit</td>
<td>Sets what units the file was modeled in so that it's sized appropriately when imported. By default, this is set to **Studs**.</td>
</tr>
<tr>
<td>Merge Meshes</td>
<td>If enabled, merges all MeshParts in the model into a single MeshPart and creates one MeshPart rather than a Model. By default, this is **disabled**.</td>
</tr>
<tr>
<td>Invert Negative Faces</td>
<td>Inverts the orientation of negative faces in the mesh. By default, this is **disabled**.</td>
</tr>
</tbody>
</table>
#### Object general
When selecting a specific child object of your mesh, the 3D Importer populates Object General settings. You can edit the following settings for the selected child objects:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Name</td>
<td>Sets the name of the selected child object within the model.</td>
</tr>
<tr>
<td>Anchored</td>
<td>If enabled, sets the `Class.BasePart.Anchored|Anchored` property to `true` on the selected child object. By default, this is **disabled**.</td>
</tr>
<tr>
<td>Use Imported Pivot</td>
<td>If enabled, imports the object using the pivot point set within the child object. By default, this is **enabled**.</td>
</tr>
</tbody>
</table>
#### Object geometry
Object Geometry includes information on the dimensions and polycount of the selected child object of the model. You can edit the following settings for the selected child objects:
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Make Double Sided</td>
<td>If disabled, sets the vertices as one-sided. One-sided vertices means that you can see through them from one side. <br /><br />If enabled, sets the vertices as double-sided. Vertices that are double sided visually render on both sides. Double-sided is more performance intensive.<br /><br />By default, this is **disabled**. </td>
</tr>
<tr>
<td>Ignore Vertex Colors</td>
<td>If enabled, ignores the vertex color data in the child object. By default, this is **disabled**. </td>
</tr>
</tbody>
</table>
## Presets
You can save presets of various import settings to quickly apply later within the [import preview](#import-preview) or [import queue](#import-queue).
By default, you can select between two presets:
- **Studio Default**: The default import behavior.
- **Last Imported**: Uses the settings applied to the most recent import.
You can use the **&ctdot;** menu next to the Presets dropdown for additional options:
- **Reset all**: Removes any changes to the current configuration, putting settings back in the default state for the current preset.
- **Save selection**: Allows you to save any new changes to the importer settings into the currently selected preset.
- **Save as new**: Sets the current settings as a new preset. A dialogue box displays allowing you to set a name.
- **Set as default**: Sets the current preset as the default for all imports moving forward.
- **Rename**: Renames the current preset.
- **Delete**: Deletes the current preset. Resets to `Studio Default` preset.
## Warnings and errors
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/UEHEsmCslBU" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<br />
If Studio detects any issues with your model, a small indicator displays in the hierarchy panel or the settings panel.
If you see a warning icon in the hierarchy, expand the hierarchy until you reach the specific child object to see more information about the issue. Warning and error messages display in the settings panel or as a tooltip.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/Warning-Settings-Panel.png" alt="A warning message in orange stating an error about cages mismatching."/>
<figcaption>Warning and error messages display in the appropriate section in the inspector panel.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/Warning-Mouse-Over.png" alt="An error message in red with a pop-up message about missing textures."/>
<figcaption>Some errors display a tooltip when hovering over the error icon.</figcaption>
</figure>
</GridContainer>

70
.cursor/rules/roblox/art/modeling/assign-textures.md Normal file
View file

@ -0,0 +1,70 @@
---
title: Blender and Maya texture settings
description: Learn to assign basic or PBR textures in Blender or Maya to natively import into Studio.
---
This guide covers the process to assign texture images in Blender or Maya to your 3D model so that they import seamlessly into Studio. The import process supports both basic textures and realistic PBR textures, as long as they meet Roblox's [texture specifications](./texture-specifications.md).
<Alert severity = 'warning'>
The following information is **specific for applying makeup textures generic meshes**. For more information on reassigning textures for makeup assets, see [Reassign textures in Blender and Maya](../../makeup/reassign-textures.md).
</Alert>
## Blender
To assign Roblox-supported textures to your 3D model in Blender:
1. In the Outliner, select your mesh object.
2. In the Properties panel, navigate to the **Materials tab**.
3. Verify that your object has a Material assigned with the Surface set to `Principled BSDF`.
<img src="../../assets/modeling/textures-decals/Blender-Material-Check.png" width="30%" alt=""/>
4. If no material is assigned, click the + symbol to add a material.
1. Click the New button. A new `Principled BSDF` material populates.
<img src="../../assets/modeling/textures-decals/Blender-Create-New-Material.png" width="30%" alt=""/>
5. Navigate to the **Shading tab**.
6. With your mesh object selected, check the node graph. There may already be texture image nodes connected to the `Principled BSDF` node.
7. In the node graph area, add a texture image node with right-click > **Add** > **Texture** > **Image Texture**.
<img src="../../assets/modeling/textures-decals/Blender-Add-Image-Texture.png" width="80%" alt=""/>
8. In the new Image Texture node, click Open to open a file browser and insert your custom texture.
<img src="../../assets/modeling/textures-decals/Blender-Image-Texture-No-Assignment.png" width="30%" alt=""/>
<Alert severity = 'info'> Alternatively to steps 7-8, you can **drag and drop** texture file from another window into the graph editor space.</Alert>
9. After adding image texture nodes and assigning the appropriate files, drag the `Image Texture` sockets to the appropriate sockets in the `Principled BSDF` node:
<img src="../../assets/makeup/resources/Blender-Expected-Nodes.png" width="90%" />
- **Basic texture** or **PBR color/albedo**: connect `Color` to `Base Color`.
- **Metallic texture**: connect `Color` to `Metallic`.
- **Roughness texture**: connect `Color` to `Roughness`.
- **Normal texture** images need to be added to a NormalMap node:
1. Right-click in the graph-editor area and select **Add** > **Vector** > **Normal Map**.
2. Connect Image Texture `Color` to NormalMap's `Color`.
3. Connect NormalMap's `Normal` to PrincipledBSDF's `Normal` socket.
<Alert severity ='success'>
After replacing your PBR textures, [export the entire model](../../art/modeling/export-requirements.md#blender) and follow instructions to [import into Studio](./3d-importer.md).
</Alert>
## Maya
To assign Roblox-supported textures to your 3D model in Maya:
1. In the Status Line near the top of the default layout, click on the Hypershade icon.
<img src="../../assets/makeup/resources/Maya-Select-Hypershade.png" width="65%" />
2. In the Create Window panel on the Hypershade popup, navigate to **Maya** > **Surface** and click **Standard Surface**. A surface node appears in the node editor.
<img src="../../assets/modeling/textures-decals/Maya-Create-Surface.png" width="65%" />
3. If adding a normal map, navigate to **Maya** > **Utilities** and click **Bump 2d**. A node required for normal maps appears in the node editor.
<img src="../../assets/modeling/textures-decals/Maya-Bump-2D.png" width="65%" />
4. Drag and drop your PBR textures to the graph network.
<img src="../../assets/makeup/resources/Maya-Select-Graph-Network.png" width="65%" />
1. If adding a normal map, select the Bump 2d node, and change to Tangent Space Normals.
<img src="../../assets/modeling/textures-decals/Maya-Tangent-Space-Normals.png" width="65%" />
5. Select your model and navigate to your material you intend to assign. Right-click and hold over the material and select **Assign Material to Selection**.
<img src="../../assets/modeling/textures-decals/Maya-Assign-Material.png" width="65%" />
<Alert severity ='success'>
After replacing your PBR textures, [export the model](../../art/modeling/export-requirements.md#maya) and follow instructions to [import into Studio](./3d-importer.md).
</Alert>

142
.cursor/rules/roblox/art/modeling/calisthenics-tool.md Normal file
View file

@ -0,0 +1,142 @@
---
title: Calisthenics Tool
description: Calisthenics Tool is a Blender plugin that you can use to verify skinning quality of an asset.
---
The **Calisthenics Tool** is a supplemental [Blender](https://www.blender.org/) add-on that allows you to quickly test your asset through a set of animation cycles to verify your skinning data. At any point during the animation testing, you can pause and use Blender's skinning Tools, such as [Weight Painting brushes](https://docs.blender.org/manual/en/latest/sculpt_paint/weight_paint/introduction.html), to resolve any skinning imperfections.
Skinning your clothing and characters is a critical and often time-intensive process to create high quality assets that move and fit with different character bodies. Similar to the [Layered Clothing Validation Tool](../../art/accessories/validation-tool.md), the Calisthenics Tool can save you time when testing your character models after rigging and skinning.
<Alert severity = 'info'>
The Calisthenics Tool doesn't provide complete verification of all potential skinning issues. You must also ensure that your custom models meet Studio's [avatar character specifications](../../art/characters/specifications.md) and any applicable [layered clothing specifications](../../art/accessories/specifications.md) for the best results in your experience.
</Alert>
<GridContainer numColumns="3">
<figure>
<video controls loop muted src="../../assets/modeling/skinned-meshes/calisthenic-tool/Walking-Reference.mp4" width="90%"></video>
<figcaption>Walking Animation</figcaption>
</figure>
<figure>
<video controls loop muted src="../../assets/modeling/skinned-meshes/calisthenic-tool/Running-Reference.mp4" width="90%"></video>
<figcaption>Running Animation</figcaption>
</figure>
<figure>
<video controls loop muted src="../../assets/modeling/skinned-meshes/calisthenic-tool/Movement-Reference.mp4" width="90%"></video>
<figcaption>Generic Movements</figcaption>
</figure>
</GridContainer>
## Installation
<Alert severity = 'info'>
The Calisthenics Tool plugin is designed for [Blender 3.0+](https://www.blender.org/download/). You can download and modify the tool for any use.
</Alert>
To install the Calisthenics Tool in Blender:
1. Download the [CalisthenicsTool.zip](../../assets/modeling/skinned-meshes/calisthenic-tool/CalisthenicsTool.zip) and save the `.zip` file locally.
2. In Blender, navigate to **Edit** > **Preferences**.
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Blender-Preferences.png" width="70%" />
3. In the left sidebar of the **Preferences** window, navigate to the **Add-Ons** section.
4. Click the **Install…** button. A file browser displays.
5. Select the `.zip` and click **Install Add-On**.
6. Using the search bar, search for "Calisthenics Tool" and select the add-on.
7. Enable the add-on by checking the box next to the add-on name.
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Calisthenics-Tool-Addon.png" width="70%" />
8. Close the Preferences window. You can now access the Calisthenics Tool by expanding the tool sidebar in the Viewport.
<GridContainer numColumns ="2">
<figure>
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Toolbar-Slider.png" width="97%" />
<figcaption>Use the arrow on the side of the Viewport to open the sidebar.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Calisthenics-Tool-Open.png" width="100%" />
<figcaption>Access the Calisthenics Tool by selecting the tab in the sidebar tool menu.</figcaption>
</figure>
</GridContainer>
## Use the Calisthenics Tool
After installation, you can use the Calisthenics Tool whenever you want to test an R15 character rig with skinning data. With the Calisthenics Tool, you can check how a character would move with generic animations, as well as attach rigid reference accessories to verify attachment during these movements. The tool also includes an option to automatically export your character, removing reference animation and accessory data.
You can try out the Calisthenics Tool using an [example character model](../../assets/modeling/skinned-meshes/calisthenic-tool/Fish-Character-No-FACS.fbx).
<Alert severity = 'info'>
For demonstration purposes, this reference model doesn't contain FACS data. If you require a reference with facial animation, you can download the same model with FACS data from our [reference models](../../art/characters/specifications.md#reference-files).
</Alert>
### Test animations
When testing your character model, first set the armature in the Calisthenics Tool then select one of the reference animations. It is important to visually verify your skinning quality using various movements and angles to ensure the best results for your model.
<Alert severity ='warning'>
If you encounter any errors or warnings when setting armature or playing animations, verify that your model uses an appropriate bone hierarchy and naming convention outlined in Roblox's [custom mesh requirements](../../art/characters/specifications.md).
</Alert>
To test animations:
1. Open a Blender project with an existing R15 character model, or import an appropriate character model `.fbx` using **File** > **Import** > **FBX (.fbx)**.
2. For easier visualization, hide non-rendered mesh objects, such as armature, cages, and attachments to better preview the reference animations.
<video controls src="../../assets/modeling/skinned-meshes/calisthenic-tool/1_Hide-Armature.mp4" width="80%"></video>
3. Set which rig you want to test a reference animation on:
1. In the add-on's **Armature** field, select the Eyedropper.
2. In the Outliner, select the **Armature** object that contains your character's rig data.
4. Click on an animation cycle to preview, such as **Walk**, **Run**, **Move** or **Idle**.
5. Press **Stop Animation** to clear animation data.
<video controls src="../../assets/modeling/skinned-meshes/calisthenic-tool/2_Set-Armature-Test.mp4" width="80%"></video>
6. If you notice any unexpected skinning deformations, pause on the frame and switch to **Weight Paint mode** or use Blender's other skinning tools to resolve. See [Skin a humanoid model](../../art/modeling/skin-a-humanoid-model.md) for additional instruction.
<video controls src="../../assets/modeling/skinned-meshes/calisthenic-tool/3_Fix-Skinning-Example.mp4" width="80%"></video>
### Test accessory attachments
You can add reference attachments to your character model using the **Attach Test Accessory** buttons. These test accessories help preview how rigid accessories attach to your character and how they can move with your model. The tool includes two sets of rigid accessories to apply to your character.
<GridContainer numColumns ="2">
<figure>
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Normal-Reference.png" width="85%" />
<figcaption>**Normal Size** - Loads normal accessory references.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Slender-Reference.png" width="85%" />
<figcaption>**Slender Size** - Loads slender accessory references.</figcaption>
</figure>
</GridContainer>
To test accessories:
1. Use the following **Attach Test Accessory** buttons to add or remove sample accessories to your character's attachment points:
- **Normal Size**: Adds normal scale test accessories.
- **Slender Size**: Adds slender scale test accessories.
- **Detach Test Accessories**: Removes any test accessories from your character.
2. If an accessory is not attaching at an expected location, reposition the associated **Attachment object** in your character rig.
### Export models
When you are ready to export your model, you can export your character directly through the Calisthenics Tool. The tool automatically clears any of the test data and applies appropriate export settings.
<Alert severity = 'info'>
Using this tool to export models with [facial animations](../../art/characters/facial-animation/index.md) may result in unexpected behavior because the stored FACS data can conflict with the tool's reference animations.
</Alert>
To export from the Calisthenics Tool:
1. In the **Export Path** field, set the export directory by clicking the folder icon and browsing to the appropriate file directory.
<img src="../../assets/modeling/skinned-meshes/calisthenic-tool/Exporting-Model.png" width="60%" />
2. Click the **Export Model** button. The character model `.fbx` populates in the designated folder as `Character_Model_Export.fbx`.
<Alert severity = 'warning'>
If you are manually exporting your model with Blender's `.fbx` importer instead of the Calisthenics Tool, ensure the following before export:
- Detach the Calisthenics Tool's test accessories.
- Use the **Stop Animation** button to clear test animations from the timeline.
- Return the model to the default pose with no additional pose data.
- Verify your settings follow Roblox's [Blender export settings](../../art/modeling/export-requirements.md).
</Alert>

62
.cursor/rules/roblox/art/modeling/export-requirements.md Normal file
View file

@ -0,0 +1,62 @@
---
title: Export settings
description: Use the appropriate export settings in Maya and Blender to generate Studio-ready .fbx files.
---
Export your mesh or model as a `.fbx` to take advantage of all of Studio's 3D import features. When rigging or skinning a model, a `.fbx` export contains both the rig and influence data you need to later [import](../../parts/meshes.md#import-meshes) into Studio.
Check that your model meets Roblox's [modeling specifications](../../art/modeling/specifications.md) before exporting to ensure Studio compatibility. Specific types of assets, like characters and accessories, have additional specifications:
<Alert severity = 'warning'>
<AlertTitle>If creating other types of 3D models:</AlertTitle>
<ul>
<li>For rigid accessories, see [accessory specifications](../../art/accessories/specifications.md) and [accessory export settings](../accessories/export-settings.md).</li> <br />
<li>For layered accessories, see [layered accessory specifications](../accessories/clothing-specifications.md) and [layered export settings](../accessories/clothing-export-settings.md).</li> <br />
<li>For avatar characters, see [avatar specifications](../../art/characters/specifications.md) and [avatar export settings](../characters/export-settings.md).</li>
</ul>
</Alert>
## Blender
Before exporting a mesh from Blender, make sure to set the Scene Unit Length to **Centimeters** and, if applicable, set the Unit Scale to **.01** to ensure similar `.fbx` scaling within Studio.
To export the `.fbx` file in Blender:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Export**, then **FBX (.fbx)**. The **Blender File View** window displays.
3. On the right-hand side, change the **Path Mode** property to **Copy**, then toggle the **Embed Textures** button.
<img src="../../assets/modeling/skinned-meshes/Blender-Export-Settings-1.png" width="320" alt="Blender export sidebar showing Path Mode set to Copy and the Embed Textures button enabled."/>
4. If your project doesn't already have .01 scene unit scaling, set the **Transform** > **Scale** to `.01`.
<img src="../../assets/modeling/skinned-meshes/Blender-Export-Settings-2.png" width="320" />
5. Under the **Armature** section, disable **Add Leaf Bones**.
<img src="../../assets/modeling/skinned-meshes/Blender-Export-Settings-3.png" width="320" alt="Blender export sidebar showing Transform Scale set to .01"/>
6. Unless exporting content with animation keyframes, such as a walk cycle or a character with [facial animation data](../../art/characters/facial-animation/index.md), disable **Bake Animation**.
<img src="../../assets/modeling/skinned-meshes/Blender-Export-Settings-4.png" width="320" alt="Blender export sidebar showing Add Leaf Bones as unchecked"/> <br />
7. Click the **Export FBX** button.
## Maya
To export a mesh in Maya as a `.fbx` file:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Export All**. The **Export All** window displays.
3. Near the bottom of the window, click the **Files of type** dropdown, then select **FBX export**.
4. On the right-hand side of the window, navigate to the **Options...** section.
5. In the **Geometry** section, enable **Smooth Mesh** and **Referenced Asset Content**.
6. In the **Animation** section, disable **Animation**, unless you need to import an animation to Studio. Some avatar assets require animation.
1. If you are exporting animation, enable **Bake Animation**.
7. If you need to import textures as a `.png`, in the **Embed Media** section, enable **Embed Media**.
8. In the **Advanced Options** section,
- Navigate to **Units**, then enable **Automatic**.
- Navigate to **Axis Conversion**, then set the **Up Axis** property to **Y**.
9. Click the **Export All** button.
<img src="../../assets/accessories/lc-requirements-maya-settings.png" alt="Maya export sidebar showing Bake Animation as unchecked" />

85
.cursor/rules/roblox/art/modeling/gltf-export.md Normal file
View file

@ -0,0 +1,85 @@
---
title: 3D Export
description: 3D Importer imports third-party .fbx, .gltf, and .obj 3D model assets into Studio.
---
import BetaAlert from '../../includes/beta-features/beta-alert.md'
<BetaAlert betaName="glTF Export" leadIn="This feature is currently in beta. Enable it through " leadOut="." components={props.components} />
You can export your 3D Roblox assets as a **.glTF** ([GL Transmission Format](https://en.wikipedia.org/wiki/GlTF)) file format. This open standard format allows for efficient transfer of 3D assets and associated data between Studio and other software, such as Blender or Maya.
<br />
Some common use cases for .glTF export includes:
- Running [Avatar auto setup](../../avatar-setup/index.md#auto-setup), exporting the output and finalizing the meshes, cages, or rigging in a third-party tool.
- Exporting your entire place for high-fidelity scene renders in another 3D application.
- Creating 3D content in Studio, such as part-based models or editable meshes and making modifications in an external application.
Keep in mind that glTF supports specific 3D [components](#supported-components), has some [limitations](#limitations), and requires correct [permissions](#limitations) to export assets from Studio. Some of these specifications may change over the course of the beta.
## Supported components
glTF export supports the following types of 3D data:
- Meshes
- Textures
- Rigging and skinning data
- Vertex colors
- Cages
- Dynamic head FACS data.
## Limitations
<Alert severity = 'warning'>
See the beta announcement for the latest information on limitations and currently known bugs.
</Alert>
At this time, glTF has the following limitations:
- Does not support animation data.
- Inconsistent support for layered clothing — clothing accessories may not always position correctly and won't deform to avatar bodies outside of Roblox.
## Permissions
<Alert severity = 'warning'>
See the beta announcement for the latest information on permissions and upcoming changes.
</Alert>
You must have the correct permissions to export assets as .glTF. When exporting .glTF, Studio verifies that you have permissions to export that asset and may warn you if there are any conflicts.
<br />
You can export the following assets:
- Assets directly uploaded to your account
- Assets directly uploaded to one of your group accounts
- Mesh and image assets that have been explicitly shared with you or your group
You cannot export the following assets:
- Avatar Marketplace assets
- Acquired Creator Store assets
- Shared collaborator assets where the underlying meshes/images have not been explicitly shared
- Other `Open Use` (public) assets that have not been explicitly shared with you or your group
## How to use .glTF export
<BetaAlert betaName="glTF Export" leadIn="This feature is currently in beta. Enable it through " leadOut="." components={props.components} />
You can export selected items from the Explorer, or export the entire place.
<br />
To export from the Explorer:
1. Select the items you intend to export.
2. Right-click and navigate to **Save / Export** > **Export as glTF**.
3. Follow the prompts on screen to fine-tune your export components. Click **Export** when ready.
1. After clicking Export, Studio runs a permission check. If there are any permission conflicts, a permission prompt appears with additional details.
4. In the file browser, select a location to save the .glTF file.
To export an entire place:
1. Navigate to **File** > **Export as glTF**.
2. Follow the prompts on screen to fine-tune your export components. Click **Export** when ready.
1. After clicking Export, Studio runs a permission check. If there are any permission conflicts, a permission prompt appears with additional details.
3. In the file browser, select a location to save the .glTF file.

142
.cursor/rules/roblox/art/modeling/index.md Normal file
View file

@ -0,0 +1,142 @@
---
title: Custom meshes
description: External modeling is the use of a third-party modeling software to create custom meshes.
---
**Custom meshes** are 3D objects that enhance the visual appeal and uniqueness of your environment and characters. In Studio, custom meshes are represented as `Class.MeshPart` objects, and you can use them to create assets like characters, clothing, environment props, and cosmetics. To create a custom mesh, you must use a third-party modeling application, such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview), to design and model the asset before importing the 3D object into Studio.
Many 3D assets, like characters, are made up of several meshes and are represented in Studio as a single `Class.Model`. See [Models](../../parts/models.md) for more information.
In Roblox, custom 3D assets generally fall under three types of applications:
- **Generic meshes or models** you can use for environmental props, buildings, characters, and decoration within an experience.
- **Avatar models** for users or non-player characters (NPCs).
- **Accessory models** that character models can equip and wear, like clothing and cosmetics.
If you meet certain account requirements, you can publish and sell your avatar-ready models on the Marketplace and earn a commission for each sale. For more information, see [Roblox avatars](../../avatar/index.md).
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Layered-Clothing-Example.png" alt="A Roblox avatar wearing a glossy puffy jacket and jeans"/>
<figcaption>Create custom accessories, clothing, and characters that anyone can wear and use</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/Beyond-The-Dark-Example.png" alt="A floating alien creature in space, from the Beyond The Dark experience"/>
<figcaption>Design a custom character unique to your experience</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/Mystery-of-Duvall-Example.png" alt="A cluttered interior room with a candle in the forefront and spooky interior lighting from the Mystery of Duvall Drive experience"/>
<figcaption>Use custom meshes and models to give your environments ambiance and depth</figcaption>
</figure>
</GridContainer>
## Supported meshes
Roblox supports many types of custom meshes, as long as they adhere to the [general mesh specifications](../../art/modeling/specifications.md). A basic custom mesh consists of at least one mesh object and one texture:
<GridContainer numColumns="3">
<figure>
<img src="../../assets/art/Basic-Mesh-Example.png" alt="A plain white tree mesh without a texture"/>
<figcaption>A mesh object sets the shape and geometry of the 3D object</figcaption>
</figure>
<figure>
<img src="../../assets/art/Basic-Texture-Example.png" alt="Various color maps used to apply textures to the tree bark, and inner, middle, and outer leaves"/>
<figcaption>A texture image map applies a surface appearance and color</figcaption>
</figure>
<figure>
<img src="../../assets/art/Basic-Mesh-Combined-Example.png" alt="The tree mesh and the image maps combined to create a single tree"/>
<figcaption>The mesh and texture combine to make a unique custom 3D object</figcaption>
</figure>
</GridContainer>
Studio also supports meshes that include [rigging and skinning](#rigging-and-skinning) data, [PBR textures](#pbr-textures), and other [Studio-related objects](#studio-related-objects) like cage meshes and attachments. Many of these various components are required if you are creating avatar character models or accessories.
### Rigging and skinning
A **rigged mesh** is a mesh with an internal poseable skeleton rig and bone structure. Rigged meshes allow mesh surfaces to rotate and move where internal bone joints are placed within a model, such as a character's knee or elbow. Skinning a rigged mesh allows the mesh object to bend organically, imitating the natural way joints would move in real life.
<GridContainer numColumns="2">
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Head-Rigid-Example.mp4"></video>
<figcaption>Without skinning, the entire head mesh rotates on a single axis</figcaption>
</figure>
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Head-Skinned-Example.mp4"></video>
<figcaption>With skinning, the head mesh bends naturally at the neck, and the bottom of the neck stays connected to the torso</figcaption>
</figure>
</GridContainer>
For more information on rigging and skinning, see [Rigging and skinning](../../art/modeling/rigging.md).
### PBR textures
**Physically-Based rendering** (PBR) textures allow you to represent realistic shading and lighting by using multiple types of texture images, or **maps**, on a single object. Combining multiple texture maps can more accurately simulate color, roughness, and reflectivity in any lighting environment and can enhance the visual elements of your assets and environment.
<GridContainer numColumns="2">
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-Example-1.jpg" alt="A realistic looking leafy bush with shadows and depth."/>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-Example-3.jpg" alt="A realistic looking rock with moss on the top." />
</GridContainer>
For more information on PBR textures, see [PBR textures](../../art/modeling/surface-appearance.md).
### Studio-related objects
Studio automatically converts certain types of objects found in 3D modeling files as specific workspace objects in the experience. These are typically used when creating a character or accessory, and configuring these in your modeling software can sometimes be the primary way of correctly setting up these Studio objects.
The following objects are automatically created in Studio if they are detected by the importer:
- `Class.Attachment` - Created when Studio detects mesh objects that include `_Att` at the end of their name.
- `Class.WrapTarget` - Created when Studio detects mesh objects that include `_OuterCage` at the end of their name.
- `Class.WrapLayer` - Created when Studio detects a mesh object with `_InnerCage` and similarly named mesh object with `_OuterCage` at the end of their names.
- `Class.FaceControls` - Created when Studio detects an avatar character head and the appropriate facial animation data in the model.
## Resources
There are a variety of resources available for creators of all backgrounds to get started with custom meshes.
If you are interested in specific avatar creation topics, use the following table to find guides and resources that best match your needs:
<table>
<thead>
<tr>
<th>Topic</th>
<th>Resources</th>
</tr>
</thead>
<tbody>
<tr>
<td>Reference files</td>
<td>[Example models, project kits, and templates](../../art/modeling/project-files.md)</td>
</tr>
<tr>
<td>Technical specs</td>
<td>[.FBX export settings](../../art/modeling/export-requirements.md)<br /><br />[General mesh specifications](../../art/modeling/specifications.md)<br /><br />
[Avatar specifications](../../art/characters/specifications.md)<br /><br />[Accessory specifications](../../art/accessories/specifications.md)<br /><br />[Marketplace policy](../../marketplace/marketplace-policy.md)</td>
</tr>
<tr>
<td>Bodies and clothing creation</td>
<td>[Accessories overview](../../art/accessories/index.md)<br /><br />[Bodies overview](../../art/characters/index.md)<br /><br />[Face accessory creation](../../art/characters/facial-animation/create-face-accessories.md)<br /><br />[Accessory Fitting Tool](../../art/accessories/accessory-fitting-tool.md)<br /><br />[Accessory specifications](../../art/accessories/specifications.md)<br /><br />[Marketplace requirements](../../marketplace/marketplace-policy.md)</td>
</tr>
<tr>
<td>Texturing</td>
<td>[Texture specifications](../../art/modeling/texture-specifications.md)<br /><br />[PBR textures](../../art/modeling/surface-appearance.md)</td>
</tr>
<tr>
<td>Rigging and skinning</td>
<td>[Rigging and skinning overview](../../art/modeling/rigging.md)<br /><br />[Basic mesh rigging](../../art/modeling/rig-a-simple-mesh.md) <br /><br />[Facial bone rigging](../../art/characters/facial-animation/create-basic-heads.md#rigging)<br /><br />[Facial bone skinning](../../art/characters/facial-animation/create-basic-heads.md#skin-face-bones)<br /><br />[Avatar rigging requirements](../../art/characters/specifications.md#rigging)<br /><br />[Automatic skinning transfer](../../art/accessories/automatic-skinning-transfer.md)</td>
</tr>
<tr>
<td>Facial animation and live heads</td>
<td>[Basic head creation](../../art/characters/facial-animation/create-basic-heads.md)<br /><br />[Face accessory creation](../../art/characters/facial-animation/create-face-accessories.md)<br /><br />[FACS pose references](../../art/characters/facial-animation/facs-poses-reference.md)</td>
</tr>
<tr>
<td>Testing and validation</td>
<td>[Calisthenics Tool](../../art/modeling/calisthenics-tool.md)<br /><br />[Clothing Validation Tool](../../art/accessories/validation-tool.md)</td>
</tr>
<tr>
<td>Publishing and Marketplace</td>
<td>[Upload to Marketplace](../../marketplace/publish-to-marketplace.md)<br /><br />[Marketplace policy](../../marketplace/marketplace-policy.md)<br /><br />[Fees and commissions](../../marketplace/marketplace-fees-and-commissions.md)</td>
</tr>
</tbody>
</table>

181
.cursor/rules/roblox/art/modeling/material-reference.md Normal file
View file

@ -0,0 +1,181 @@
---
title: Material references
description: PBR texture examples and various texture map values.
---
When combining different combinations of metalness and roughness values with your PBR textures, Roblox can render virtually every type of surface with a high level of realism. The following includes various material values for common materials and [clothing examples](#clothing-examples) that you can use when creating your own PBR surfaces.
The following figure illustrates the various base surface types you can achieve with various roughness and metallic values:
<figure>
<img src="../../assets/modeling/surface-appearance/Roughness-Metalness-Matrix.png"/>
</figure>
## Common materials
You can use the following material reference values as a baseline for creating your own custom surfaces:
<GridContainer numColumns="4">
<figure>
<img src="../../assets/modeling/surface-appearance/01_GlossyPlastic.png" />
<figcaption><center><b>Glossy Plastic</b><br />Roughness: 0.1 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/02_MattePlastic.png" />
<figcaption><center><b>Matte Plastic</b><br />Roughness: 0.4 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/03_Rubber.png" />
<figcaption><center><b>Rubber</b><br />Roughness: 0.5-0.6 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/04_Latex.png" />
<figcaption><center><b>Latex</b><br />Roughness: 0.0 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/05_GlossyWood.png" />
<figcaption><center><b>Glossy Wood</b><br />Roughness: 0.2-0.3 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/06_WornWood.png" />
<figcaption><center><b>Worn Wood</b><br />Roughness: 0.7-0.9 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/07_CottonCanvasDenim.png" />
<figcaption><center><b>Cotton, Canvas, Denim</b><br />Roughness: 0.8-0.9 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/08_PolyesterNylon
.png" />
<figcaption><center><b>Polyester, Nylon</b><br />Roughness: 0.6-0.8 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/09_WoolLinen.png" />
<figcaption><center><b>Wool, Linen</b><br />Roughness: 0.9-0.096 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/010_SilkSatin.png" />
<figcaption><center><b>Silk, Satin</b><br />Roughness: 0.4-0.6 <br /> Metalness: 0.4-0.6 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/011_VelvetSuede.png" />
<figcaption><center><b>Velvet, Suede</b><br />Roughness: 0.6-0.8 <br /> Metalness: 0.4-0.6 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/012_GlossyLeather.png" />
<figcaption><center><b>Glossy Leather</b><br />Roughness: 0.2-0.4 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/013_WornLeather.png" />
<figcaption><center><b>Worn Leather</b><br />Roughness: 0.5-0.7 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/014_Fur.png" />
<figcaption><center><b>Fur</b><br />Roughness: 0.65-0.75 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/015_Scales.png" />
<figcaption><center><b>Scales</b><br />Roughness: 0.5-0.6 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/016_Bone.png" />
<figcaption><center><b>Bone</b><br />Roughness: 0.5 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/017_Skin.png" />
<figcaption><center><b>Skin</b><br />Roughness: 0.65 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/018_Wax.png" />
<figcaption><center><b>Wax</b><br />Roughness: 0.38 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/019_Marble.png" />
<figcaption><center><b>Marble</b><br />Roughness: 0.375 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/020_Jade.png" />
<figcaption><center><b>Jade</b><br />Roughness: 0.15 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/021_PaintedMetal.png" />
<figcaption><center><b>Painted Metal</b><br />Roughness: 0.3 <br /> Metalness: 0.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/022_PureMetals.png" />
<figcaption><center><b>Pure Metals (Gold, Silver, Bronze)</b><br />Roughness: 0.2-0.3 <br /> Metalness: 1.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/023_WornMetals.png" />
<figcaption><center><b>Worn Metals</b><br />Roughness: 0.2-0.4 <br /> Metalness: 1.0 </center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/024_GlassMirror.png" />
<figcaption><center><b>Glass Mirror</b><br />Roughness: 0.0 <br /> Metalness: 0.1 </center></figcaption>
</figure>
</GridContainer>
## Clothing examples
Layered clothing can take advantage of PBR textures to achieve realistic and visually popping cosmetics for avatar characters. Use the following reference examples to compare how various material values are used to achieve a certain cosmetic effect and its comparable real-time rendering in Substance Painter and Roblox Studio:
<table>
<thead>
<tr>
<th><center>Substance Painter render</center></th>
<th><center>Roblox Studio render</center></th>
<th>Material values</th>
</tr>
</thead>
<tbody>
<tr>
<td><img src="../../assets/modeling/surface-appearance/Leather-Jacket-Sp.png"/></td>
<td><img src="../../assets/modeling/surface-appearance/Leather-Jacket-St.png"/></td>
<td>**Leather fabric:**<br />
Roughness: 0.62 <br />
Metalness: 0.0 <br /> <br />
**Brass zipper:**<br />
Roughness: 0.25<br />
Metalness: 1.0<br /></td>
</tr>
<tr>
<td><img src="../../assets/modeling/surface-appearance/Gold-Puffy-Jacket-Sp.png"/></td>
<td><img src="../../assets/modeling/surface-appearance/Gold-Puffy-Jacket-St.png"/></td>
<td>**Metallic puffer fabric:**<br />
Roughness: 0.62 <br />
Metalness: 1.0 <br /> <br />
**Brass zipper and buttons:**<br />
Roughness: 0.482<br />
Metalness: 1.0<br /><br />
**Fur hood:**<br />
Roughness: 0.75<br />
Metalness: 0.0<br /><br />
**Cotton band:**<br />
Roughness: 0.8<br />
Metalness: 0.0<br /></td>
</tr>
<tr>
<td><img src="../../assets/modeling/surface-appearance/Green-Jacket-Sp.png"/></td>
<td><img src="../../assets/modeling/surface-appearance/Green-Jacket-St.png"/></td>
<td>**Silk fabric:**<br />
Roughness: 0.52 <br />
Metalness: 0.3 <br /> <br />
**Steel zipper and buttons:**<br />
Roughness: 0.25<br />
Metalness: 1.0<br /><br />
**Cotton band:**<br />
Roughness: 0.9<br />
Metalness: 0.0<br /><br /></td>
</tr>
<tr>
<td><img src="../../assets/modeling/surface-appearance/Denim-Jacket-Sp.png"/></td>
<td><img src="../../assets/modeling/surface-appearance/Denim-Jacket-St.png"/></td>
<td>**Denim fabric:**<br />
Roughness: 0.9 <br />
Metalness: 0.0 <br /> <br />
**Tarnished steel buttons:**<br />
Roughness: 0.33<br />
Metalness: 1.0<br /></td>
</tr>
</tbody>
</table>

590
.cursor/rules/roblox/art/modeling/project-files.md Normal file
View file

@ -0,0 +1,590 @@
---
title: Modeling project files and references
description: Download various modeling-related project files and reference files.
hideInPageNavigation: true
---
The following `.fbx`, `.blend`, and `.ma` project files are available to use as templates or as reference:
<Grid container alignItems='stretch'>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Maple leaf tree</center>
<figure>
<center> <img src="../../assets/art/resources/Tree-Resource.png" width="100%" alt="A green maple tree mesh"/> </center>
</figure>
<figure>
A skinned tree model with the soil, branches, and leaves as separate meshes bound to a single armature. This is packaged with UV textures that can be applied with `Class.SurfaceAppearance`. This is an advanced version of the tree model used in the <a href="../../art/modeling/skin-a-simple-mesh.md">Skin a simple mesh</a> guide.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/skinned-meshes/MapleLeafTree_S3.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Shoebot</center>
<figure>
<center> <img src="../../assets/art/resources/Shoebot-Resource.png" width="100%" alt="A white round robot with arms and orange trim."/> </center>
</figure>
<figure>
A robot non-player character used in the <a href="https://www.roblox.com/games/7208091524/Beyond-the-Dark-Vistech-Showcase">Beyond The Dark</a> showcase.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/meshes/reference-files/shoebot-base-model.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Creature</center>
<figure>
<center> <img src="../../assets/art/resources/Creature-Resource.png" width="100%" alt="A black and blue alien creature with tentacles."/> </center>
</figure>
<figure>
Creature model from the <a href="https://www.roblox.com/games/7208091524/Beyond-the-Dark-Vistech-Showcase">Beyond The Dark</a> showcase. This model is made up of 11 meshes and over 50 bones.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/skinned-meshes/CreatureModel.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
</Grid>
## Avatar and accessories
The following include examples and templates utilizing Roblox's required [avatar components](../../art/characters/index.md#components-of-an-avatar). Many of these project files and references require additional configuration in your modeling software before importing into Studio as a complete avatar character. See [Avatars](../../art/characters/index.md) for additional resources and template usage instruction.
### References
<Grid container alignItems='stretch' style={{margin: -6}}>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Fish person</center>
<figure>
<center> <img src="../../assets/art/resources/Fish-Person-Resource.png" width="100%" alt="A blue-green scaly creature with a bulb-ish head ornament."/> </center>
</figure>
<figure>
A rigged and skinned humanoid character model with a full body cage, facial animation rig, and associated PBR texture maps. <br /><br /> If this asset were to be uploaded to the Marketplace, the bulb antenna must be a separate head accessory and not part of the character's head geometry.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/avatar/dynamic-heads/reference-files/Fish-Person.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Goblin</center>
<figure>
<center> <img src="../../assets/art/resources/Goblin-Resource.png" width="100%" alt="A brown goblin with bright green eyes."/> </center>
</figure>
<figure>
A rigged and skinned humanoid character model with a full body cage, facial animation rig.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/avatar/dynamic-heads/reference-files/GoblinCharacter.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Blocky</center>
<figure>
<center> <img src="../../assets/art/resources/Blocky-Resource.png" width="100%" alt="A colorless blocky-like character."/> </center>
</figure>
<figure>
A Blocky character model with an animatable head and a full body cage.
</figure>
<br />
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/avatar/dynamic-heads/reference-files/BlockyCharacter.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Lola</center>
<figure>
<center> <img src="../../assets/art/resources/Lola-Resource.png" width="100%" alt="A pink-haired character complete with brown jacket, goggles, leggings, and pants."/> </center>
</figure>
<figure>
A skinned R15 character created from the <a href="../../art/modeling/skin-a-humanoid-model.md">Skin a humanoid model</a> guide. Since this reference model doesn't yet have [inner and outer cage mesh data](../../art/characters/specifications.md#outer-cages), this model can't equip layered clothing or accessories.
</figure>
<br />
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/skinned-meshes/Lola.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Tshirt - uncaged</center>
<figure>
<center> <img src="../../assets/art/resources/Tshirt-Resource.png" width="100%" alt="A tie-dye tshirt with a rainbow of colors in a general spiral toward the torso."/> </center>
</figure>
<figure>
Uncaged example clothing ready for caging in a 3D modeling software.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/accessories/reference-files/Tshirt-model.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Clothing examples</center>
<figure>
<center> <img src="../../assets/art/Generic-Icon.png" width="100%" alt=""/> </center>
</figure>
<figure>
Caged 3D accessory models and associated PBR textures. Ready for import into Studio or in a modeling tool.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/accessories/reference-files/Additional-FBX-assets.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Caging Examples</center>
<figure>
<center> <img src="../../assets/art/Additional-Caging-Examples.png" width="100%" /> </center>
</figure>
<figure>
Additional caged clothing items from How to cage Roblox's 3D [clothing video guide](https://www.youtube.com/watch?v=QwZaA9Gc-WQ).
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/accessories/reference-files/Caging-examples.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Classic mannequin</center>
<figure>
<center> <img src="../../assets/art/resources/Body-Scale-Classic.png" width="100%" alt="A white untextured mannequin in the blocky style."/> </center>
</figure>
<figure>
A blank mannequin using Roblox's [Classic](../../art/characters/specifications.md#classic) avatar proportions. <br /> <br />Use this reference to aid your creation process for accessories, clothing, and characters in third-party applications.<br /> <br /> The caged `.fbx` contains the individual outer body cages for the body and may not import correctly into Studio without modification.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/ClassicMannequin.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Model</Button>
<Button href="../../assets/art/reference-files/ClassicMannequin_With-Cages.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>With cage</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Rthro mannequin</center>
<figure>
<center> <img src="../../assets/art/resources/Body-Scale-Rthro-Normal.png" width="100%" alt="A white untextured mannequin in a larger build humanoid style."/> </center>
</figure>
<figure>
A blank mannequin using Roblox's [Rthro Normal](../../art/characters/specifications.md#normal) avatar proportions. <br /> <br />Use this reference to aid your creation process for accessories, clothing, and characters in third-party applications.<br /> <br /> The caged `.fbx` contains the individual outer body cages for the body and may not import correctly into Studio without modification.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/RthroMannequin.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Model</Button>
<Button href="../../assets/art/reference-files/RthroMannequin_With-Cages.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>With cage</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Rthro slender mannequin</center>
<figure>
<center> <img src="../../assets/art/resources/Body-Scale-Rthro-Slender.png" width="100%" alt="A white untextured mannequin in a slimmer build humanoid style."/> </center>
</figure>
<figure>
A blank mannequin using Roblox's [Rthro Slender](../../art/characters/specifications.md#slender) proportions. <br /> <br />Use this reference to aid your creation process for accessories, clothing, and characters in third-party applications.<br /> <br /> The caged `.fbx` contains the individual outer body cages for the body and may not import correctly into Studio without modification.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/RthroSlenderMannequin.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Model</Button>
<Button href="../../assets/art/reference-files/RthroSlenderMannequin_With-Cages.fbx" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>With cage</Button>
</CardActions>
</Card>
</Grid>
</Grid>
## Templates
These project files require additional configuration before they are ready for Studio import. See [Create with templates](../characters/creating/index.md) for additional information.
<Alert severity = 'warning'>
If you are using Roblox's avatar template files, you must perform the [cleanup steps](../../art/characters/creating/combine-head-geometry.md) in order for the assets to properly validate before publishing to the Marketplace.
</Alert>
<Grid container style={{margin: -6}}>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Round-Head-Templates.png" width = "100%" alt="A male and female presenting pair with a prominently round shaped head."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/RoundMale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Male</Button>
<Button href="../../assets/art/reference-files/RoundFemale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Female</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Square-Head-Templates.png" width = "100%" alt="A male and female presenting pair with a prominently square shaped head."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/SquareMale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Male</Button>
<Button href="../../assets/art/reference-files/SquareFemale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Female</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Muzzle-Head-Templates.png" width = "100%" alt="A male and female presenting pair with a prominently elongated snout and mouth."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/MuzzleMale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Male</Button>
<Button href="../../assets/art/reference-files/MuzzleFemale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Female</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/SemiRealistic-Templates.png" width = "100%" alt="A male and female presenting pair with realistic body proportions and facial shape."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/SemiRealisticMale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Male</Button>
<Button href="../../assets/art/reference-files/SemiRealisticFemale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Female</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Anime-Templates.png" width = "100%" alt="A male and female presenting pair with larger anime-like eyes and prominently oval shaped faces."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/AnimeMale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Male</Button>
<Button href="../../assets/art/reference-files/AnimeFemale.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Female</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Caricature-Templates.png" width = "100%" alt="A humanoid cartoonish figure with exaggerated features, including a prominent forehead, nose, and chin."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/Caricature.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<figure>
<img src="../../assets/art/avatar/templates/Stylized-Templates.png" width = "100%" alt="A cartoonish figure with a round head and exaggerated forehead."/>
</figure>
<figure>
Blender and .fbx template files with pre-baked avatar components.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/art/reference-files/StylizedHuman.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download</Button>
</CardActions>
</Card>
</Grid>
</Grid>
### Project files
<Grid container alignItems='stretch' style={{margin: -6}}>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>R15 rig and attachments</center>
<figure>
<center> <img src="../../assets/art/resources/Rig-And-Attachments-Resource.png" width="100%" alt="A Blender visualization of bones and attachment meshes in a neutral humanoid pose."/> </center>
</figure>
<figure>
Standard armature rig template for Blender. Use this template for rigging **bodies** and **clothing** items.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/meshes/reference-files/Rig_and_Attachments_Templates.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download (.blend, .ma, .fbx)</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Cages for clothing</center>
<figure>
<center> <img src="../../assets/art/resources/Clothing-Cage-Resource.png" width="100%" alt="A humanoid shaped mesh in a neutral A-pose."/> </center>
</figure>
<figure>
Project files for creation, includes a full-body inner and outer cage mesh for creation of **clothing** items.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/meshes/reference-files/Clothing_Cage_Templates.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download (.blend, .ma, .fbx)</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Cages for bodies</center>
<figure>
<center> <img src="../../assets/art/resources/Body-Cages-Resource.png" width="100%" alt="A humanoid shaped mesh in a neutral A-pose. Each section of the mesh is colored differently based on the body part."/> </center>
</figure>
<figure>
Project files for creation, includes the 15 individual body part cages required for caging your avatar **bodies**.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/meshes/reference-files/Body_Cage_Templates.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download (.blend, .ma, .fbx)</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Combined project files</center>
<figure>
<center> <img src="../../assets/art/Generic-Icon.png" width="100%" alt="" /> </center>
</figure>
<figure>
Template file containing all content from previous templates, includes rig skeleton, body cages, attachment points. <br /> <br /> Use this template to rig and cage bodies and clothing.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/meshes/reference-files/Combined_Templates.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"4px;"}}>Download (.blend, .ma, .fbx)</Button>
</CardActions>
</Card>
</Grid>
</Grid>
### Add-ons and tools
<Grid container alignItems='stretch'>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Blender Studio plugin</center>
<figure>
<center> <img src="../../assets/art/Generic-Icon.png" width="100%" alt=""/> </center>
</figure>
<figure>
Open-source Blender Studio add-on that allows you to upload assets directly from Blender to Studio.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../art/modeling/roblox-blender-plugin.md" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0px;"}}>Link to Github</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Blender validation tool</center>
<figure>
<center> <img src="../../assets/art/Generic-Icon.png" width="100%" alt=""/> </center>
</figure>
<figure>
Blender add-on for verifying avatar technical compatibility before importing into Studio.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../art/accessories/validation-tool.md" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0px;"}}>Link to instructions</Button>
</CardActions>
</Card>
</Grid>
<Grid item XSmall={12} Medium={6} Large={4} style={{padding: 6}}>
<Card style={{height: '100%'}}>
<CardContent style={{marginBottom:'66px'}}>
<center>Blender Calisthenics tool</center>
<figure>
<center> <img src="../../assets/art/Generic-Icon.png" width="100%" alt=""/> </center>
</figure>
<figure>
Blender add-on for checking skinning data on characters and clothing.
</figure>
</CardContent>
<CardActions style={{position: 'absolute', bottom: 0, width: '100%'}}>
<Button href="../../assets/modeling/skinned-meshes/calisthenic-tool/CalisthenicsTool.zip" fullWidth size='large' color='primary' variant='contained' style={{marginBottom:"0"}}>Link to instructions</Button>
</CardActions>
</Card>
</Grid>
</Grid>

116
.cursor/rules/roblox/art/modeling/reimport.md Normal file
View file

@ -0,0 +1,116 @@
---
title: Reimport
description: Reimport allows you to update an existing custom mesh and textures without generating a new instance.
---
<Alert severity = 'info'>
Reimport is currently in beta. Enable the Reimport beta by navigating to **File** > **Beta Features** and enable **Reimport**.
For latest information on updates and limitations, see the [DevForum Announcement](https://devforum.roblox.com/t/studio-beta-reimport-one-click-updates-for-imported-3d-content/4068650).
</Alert>
**Reimport** allows you to update existing custom models and their textures from an external 3D file. Unlike regular [import](./3d-importer.md#import-files), which creates brand new instances, the reimport function updates existing objects non-destructively to help support the iterative nature of 3D development.
<iframe width="880" height="495" src="https://www.youtube-nocookie.com/embed/HVUO3Dl7qT0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe> <br />
Along with asset updates, reimport remembers the file and settings used to import the original asset. This means you can easily update an imported asset with a single click or hotkey without going through all the initial import settings. This memory persists across Studio sessions.
## Supported instances
At this time, reimport supports `Class.MeshPart` and `Class.SurfaceAppearance` objects parented within a `Class.Model` container. This is the common object structure of an imported custom model with PBR textures. Reimport also supports [packages](../../projects/assets/packages.md), allowing you to reimport batches of asset instances at once.
- `Class.Model` - The reimport feature scans the container, updating any changed `Class.MeshPart` and `Class.SurfaceAppearance`.
- `Class.MeshPart` - Reimport replaces meshes based off of mesh names saved in Studio and the external 3D file. For specific behavior, see [MeshPart detection](#meshpart-detection).
- `Class.SurfaceAppearance` - Reimport replaces images for PBR textures based off of filenames. For specific behavior, see [SurfaceAppearance detection](#surfaceappearance-detection).
<Alert severity = 'info'>
Reimport memory is local to your device. A Reimport ID is stored on the `Class.Model` instance and referenced locally. Keep in mind the following:
- Filepaths are never saved in the place file.
- Reimport supports different reimport paths on different devices for the same instance.
- Reimport supports copy-pasting, saving and loading from rbxm/rbxl, and Asset Manager workflows.
</Alert>
### MeshPart detection
Reimport updates meshes based off of the path and name of the 3D source file, and the path and name of the mesh object in Studio. Reimport only updates the mesh content and transform properties and preserves other Roblox-specific properties.
Reimport relies on matching mesh names between the Studio and the 3D source file:
- If a mesh's `path/name` in the 3D source file **matches** a `Class.MeshPart` `path/name` in Studio, reimport updates the matching `Class.MeshPart`.
- If a mesh's `path/name` in the 3D source file **doesn't exist** as `Class.MeshPart` `path/name` in Studio, reimport creates a new `Class.MeshPart` within the `Class.Model`.
- If a `Class.MeshPart` `path/name` in Studio **doesn't exist** in the 3D source file, reimport does not modify the `Class.MeshPart` in Studio.
#### Known Asset Cache
Studio uses a **Known Asset Cache**, which helps detect duplicate imports in the same Studio session. If an imported or reimported asset is detected, Roblox reuses the existing asset ID instead of creating and uploading a new asset.
If you attempt to reimport a single mesh object, but the 3D file contains a larger number of meshes or textures, Roblox only applies a single asset upload for that object.
#### Duplicates
Reimport detects duplicate meshes, and doesn't reupload matching meshes that are the same in both Studio and the 3D source file.
In the scenario where a mesh in Blender is renamed from "Mesh1" to "Mesh2", reimport creates a new `Class.MeshPart` named "Mesh2" and doesn't apply changes to the original "Mesh1".
#### Pivot points
In cases where you may want to use the pivot point of the `Class.MeshPart` and not the `Class.Model`, right-click any `Class.MeshPart` with reimport information and select **Reimport** > **Reimport relative to this**.
**Reimport relative to this** triggers a reimport for the entire model using the pivot point of right-clicked `Class.MeshPart` as an anchor instead of the `Class.Model` pivot point. You can use this for models that have custom pivots by reimporting relative to a mesh that that has not changed position in the 3D file.
### SurfaceAppearance detection
Reimport can quickly batch update the textures of a model with [PBR textures](./surface-appearance.md) based off of the naming convention of the image files.
Reimport detects a set of known suffixes for color, metalness, normal, and roughness maps. You can find the full list of supported suffixes in the following table:
<table><thead>
<tr>
<th>Map Type</th>
<th>Suffixes</th>
<th>Example</th>
</tr></thead>
<tbody>
<tr>
<td>Color</td>
<td>diffuse, diff, albedo, base, col, color, alb</td>
<td>Tree_**Color**.png</td>
</tr>
<tr>
<td>Metalness</td>
<td>metallic, metalness, metal, mtl, met</td>
<td>Tree_**Metal**.png</td>
</tr>
<tr>
<td>Roughness</td>
<td>roughness, rough, rgh</td>
<td>Tree_**Normal**.png</td>
</tr>
<tr>
<td>Normal</td>
<td>normal, nor, nrm, nrml, norm</td>
<td>Tree_**Rough**.png</td>
</tr>
</tbody>
</table>
When reimporting an asset with a `Class.SurfaceAppearance` selected, a file dialog displays allowing you to select a new image file to use as a PBR texture. Reimport automatically detects other PBR images in the directory based off of naming and maps them to the `Class.SurfaceAppearance` object.
## Reimport models
To enable reimport for an imported `Class.Model`, first configure your imported asset to save reimport configuration information for the model:
1. Right-click the `Class.Model` of your imported asset and select **Reimport** > **Configure**.
<img src="../../assets/modeling/meshes/Reimport-menu.png" width="50%" alt="Right-click menu of an imported model, displaying reimport options"/>
2. In the Reimport configuration window, set the correct file path and import presets for future reimport actions.
3. Click **Save & Reimport** to initiate the reimport process.
4. For future reimports, right-click the `Class.Model` and select **Reimport** > **Reimport**.
1. Alternatively, when selecting the object, use the reimport hotkey <kbd>Shift</kbd><kbd>Alt</kbd><kbd>R</kbd>.
2. A loading indicator appears after selecting reimport. If there are any issues, a popup displays with any errors or warnings.
<Alert severity = 'warning'>
Since reimport relies on matching mesh paths/names to update a `Class.Model` from a 3D file, it’s important to maintain unique naming of meshes and their paths in your external 3D tools.
In Studio, you should also maintain the naming/tree structure of the `Class.MeshPart` objects within your model in order for reimport to update correctly.
</Alert>

155
.cursor/rules/roblox/art/modeling/rig-a-humanoid-model.md Normal file
View file

@ -0,0 +1,155 @@
---
title: Rig a humanoid model
description: Explains the process for rigging a humanoid R15 model in Blender.
---
An R15 humanoid character model, such as those that make up user avatar characters, is made up of 15 individual mesh objects. Similar to rigging a simple mesh, you can bind or parent a group of meshes to an internal rig. Models made up of multiple meshes require additional steps to rig in a third-party modeling tool such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
This advanced guide covers the process of rigging a humanoid model in Blender using a provided template and humanoid model. This rigging step is required before [skinning the humanoid model](../../art/modeling/skin-a-humanoid-model.md). You should be familiar with [rigging a basic model](./rig-a-simple-mesh.md) before continuing.
To rig a humanoid model in Blender:
- [Import a character model](#import-model) into a template file to easily access a premade R15 bone structure.
- [Create, size, and position bones](#set-bones-and-armature) symmetrically for a humanoid character.
- [Parent](#parent-armature) multiple meshes to a single armature to bind the skeleton rig.
- [Assign full influence](#assign-meshes-to-bones) to each mesh object and bone by assigning influences.
<Alert severity="info">
This guide uses a downloadable [Rig and Attachment Template Blender Project](../../assets/modeling/meshes/reference-files/Rig_and_Attachments_Templates.zip), a reference [Lola Character model](../../assets/modeling/meshes/reference-files/lola-base-model.fbx), and [Blender version 3.0](https://www.blender.org/download/releases/3-0/). If you are
using another version of Blender, there may be minor differences in UI and
settings.
</Alert>
## Set up Blender
To begin creating a humanoid rigged mesh, first set up the following in your Blender project:
- [Import](#import-model) the Lola character model in the Mannequin Template Blender project.
- Set up your [Viewport visualizations](#viewport-visualizations) to optimize the rigging process.
### Import model
When rigging a model, make sure the character model you are using follows Studio's [Avatar character specifications](../../art/characters/specifications.md). For this guide, import a [Lola reference model](../../assets/modeling/meshes/reference-files/lola-base-model.fbx) into the mannequin template project.
To import your model:
1. In Blender, navigate to **File** > **Open** and select `Rig_and_Attachments_Template.blend`.
2. Navigate to **File** > **Import** > **FBX (.fbx)** and import the reference Lola model file.
3. If required, scale the model to roughly match the scale of the armature bone structure. You can select all the mesh geometries in the Outliner and press <kbd>G</kbd> to reposition and <kbd>S</kbd> to scale the mesh objects by dragging your mouse.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/1-resizing-base-model.mp4" width="100%"></video>
### Viewport visualizations
For better visualization and access to your bone objects, set your bone objects to always be displayed in front of the Viewport.
To set the bone visualization:
1. In the **Viewport**, click on any of the bones in your armature.
2. In the **Properties Editor** panel, select the **Object Data Properties** tab.
3. Expand **Viewport Display**, navigate to the **Show** property, then enable **In Front**.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/2-bone-visualization.mp4" width="100%"></video>
At any point during the skinning process, you can also toggle one of the various material previews options in the top right of your 3D Viewport to change the visualization of your character model, such as enabling X-ray or texture view.
## Set bones and armature
In this guide, set up X-Axis Mirroring to make symmetrical changes to the left and right bones before repositioning the bones to the imported model. Try to maintain symmetry whenever possible when rigging a model.
<Alert severity="warning">
If modifying bones or creating a new bone structure, keep in mind the <a href="../../art/characters/specifications.md#humanoid-rigs">specific bone hierarchy and naming requirements</a> for R15 character models.
</Alert>
### Enable x-axis mirror
The X-Axis Mirror setting allows you to maintain symmetry with your left and right bones by mirroring changes to their positions. To reduce issues with posing and animating, it is important to retain symmetry with your bone structure whenever possible.
To set up X-Axis Mirror:
1. In **Object Mode**, select your **armature** by clicking on any bone.
2. Switch to **Edit Mode** (<kbd>Tab</kbd>).
3. In the Viewport's right sidebar, extend the Tool panel and enable **X-Axis Mirror**.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/3-x-axis-mirror.mp4" width="100%"></video>
### Position bones
With the model added to the project, you can reposition the bones provided in the template to match the character structure. In most cases, each bone should be positioned in the center of their corresponding mesh objects, such as the Head bone being centered within the Head_Geo mesh object.
Bone positioning may differ based on use-case and may need to be revisited after weight painting and testing if a certain pose or animation doesn't work as intended.
To position your individual bones:
1. In Object Mode, click on the **bone** you intend to reposition to highlight it.
2. From the Mode dropdown, switch to **Edit Mode**.
3. Click on the **tip** of the bone so that the tip is highlighted and press <kbd>G</kbd>. The top of the bone moves with your cursor.
4. Pull this bone to align with the interior center of the model, then click to set the bone's position.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/4-repositioning-bones.mp4" width="100%"></video>
5. Click and hold your mouse's scroll wheel or use one of the various perspective views to verify that the bone is within the mesh object.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/5-inspect-bones.mp4" width="100%"></video>
### Parent armature
After you position the bone structure, you need to parent the bone armature to the model. You must parent all 15 mesh objects to one armature.
For this example, the mesh objects are parented to the armature with Empty Groups to illustrate the vertex group assignment and weight painting process in the following [Skin a humanoid model](../../art/modeling/skin-a-humanoid-model.md) guide.
To parent the model to the armature:
1. Switch to **Object Mode**.
2. In the Outliner, filter your mesh objects by typing **"geo"** in the search bar.
3. Select all of the mesh objects in the Outliner by holding <kbd>Shift</kbd> and clicking on the first and last mesh objects.
4. With the meshes highlighted, hold <kbd>Shift</kbd> and click on the Armature object in the Viewport or Outliner.
5. Right click in the Viewport and select **Parent** > **With Empty Groups**.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/6-parenting-bones.mp4" width="100%"></video>
## Assign meshes to bones
Now that you have connected your armature to the mesh object, you can assign the vertices of your individual limbs to be fully influenced by one corresponding bone. After this process is completed, the model will be ready for skinning. See [Skin a humanoid model](../../art/modeling/skin-a-humanoid-model.md) for instructions on applying multiple bone influences to a mesh.
<Alert severity="warning">
The **Root** and **HumanoidRootNode** parent bones in a humanoid rig should not have any influences applied to them. Any added influences are dropped when importing into Studio.
</Alert>
To assign full influence to the head mesh:
1. In **Object Mode**, click on the **head mesh object** to highlight it.
2. Switch to **Edit Mode**.
3. Select all the vertices of your mesh object by pressing <kbd>A</kbd>.
4. After all the head vertices are highlighted, navigate to the **Object Properties** panel on the right side of the screen.
5. In the **Vertex Group** section of the panel, select the name of the bone you want to assign the Head geometry to and click **Assign**.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/7-assign-influence-head.mp4" width="100%"></video>
You can quickly iterate through all of your mesh objects in this mode by selecting the next mesh object in the Outliner and assigning it to the appropriate Vertex Group. For this guide, **assign all of your character's mesh objects to their appropriate bone**.
To quickly assign vertex groups to the rest of the body meshes:
1. In the **Outliner** panel, **click** the dot next to the object you intend to edit. The dot switches to the active edit icon when pressed.
2. If the vertices are not highlighted, press <kbd>A</kbd> to select all vertices.
3. In the **Object Properties** panel > **Vertex Groups** section, select the appropriate vertex group and click **Assign**. You can use the search bar to find the specific vertex group name.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/8-assign-influence.mp4" width="100%"></video>
## Test
You can test and pose bones and their assigned mesh objects in Pose Mode. It is important to test your model after applying or editing any influences.
To navigate to Pose mode and test your poses:
1. In **Object Mode**, select any part of your model.
2. Click on the Mode dropdown, then switch to **Pose** mode.
3. Hold <kbd>Shift</kbd> and click the bone you want to test to highlight it, then press <kbd>R</kbd> to test the rotation.
4. Press <kbd>Alt</kbd><kbd>A</kbd> (<kbd>⌥</kbd><kbd>A</kbd>) to deselect the current bone, then reselect and test another bone.
<video controls src="../../assets/modeling/meshes/rigging-humanoid/9-test-bones.mp4" width="100%"></video>
<Alert severity="info">
To reset the rotation of a selected bone to neutral, press <KeyboardInput>Alt</KeyboardInput>+<KeyboardInput>R</KeyboardInput>. While rotating, you can also press your mouse's scroll wheel to change the axes of your rotation.
</Alert>
At this stage, if all of your mesh objects are influenced by their corresponding bones, you can [export](../../art/modeling/export-requirements.md) this rigged model as an `.fbx` for use in Studio or continue on to the next stage of [Skin a humanoid model](../../art/modeling/skin-a-humanoid-model.md).

158
.cursor/rules/roblox/art/modeling/rig-a-simple-mesh.md Normal file
View file

@ -0,0 +1,158 @@
---
title: Rig a simple mesh
description: Explains the process for rigging a basic model in Blender.
---
You can create a **rigged mesh** using a third party modeling tool such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview). You should rig a model after designing it, but prior to [exporting](../../art/modeling/export-requirements.md).
To rig a simple model in Blender:
- [Set up Blender](#set-up-blender) to Studio's relative scene units before importing a model to rig.
- [Create and reposition bones](#create-a-bone-structure) within the mesh object.
- [Parent the mesh to the armature](#parent-armature) to bind the bone armature to the mesh object.
- [Assign vertices to specific bones](#assign-vertices-to-bones) to define which parts of the mesh is driven by which bones.
- [Test your rigged mesh](#test) to ensure that the bones are properly positioned and influenced within the mesh.
<Alert severity="info">
This guide uses a downloadable [example robot model](../../assets/modeling/meshes/reference-files/shoebot-base-model.fbx) and [Blender version 3.0](https://www.blender.org/download/releases/3-0/). If you are using another version of Blender, there may be minor differences in UI and settings.
</Alert>
## Set up Blender
To start the process of creating a rigged mesh, first set up the following in your Blender project:
- Set up Blender's [scene unit and unit scale properties](#set-scene-and-scale) to Studio's proportions.
- [Import the model into Blender](#import-a-model) using Blender's file importer.
### Set scene and scale
When setting up Blender projects for Roblox Studio to import, you should modify Blender's default **scene units** and **unit scale** properties to ensure they closely align with Studio's scale.
To start a new Blender project and set scene unit properties:
1. Open a new **General** project in Blender.
2. Select the default shape, camera, and lights, then press <kbd>Delete</kbd>.
3. In the left-hand navigation of the **Properties Editor**, navigate to **Scene Properties**.
<img src="../../assets/modeling/skinned-meshes/Blender-Scene-Units-Icon.png" width="320" />
4. In the **Units** section, change the **Unit Scale** to **0.01** and the **Length** to **Centimeters**.
<video controls src="../../assets/modeling/meshes/rigging-simple/1-setting-up-blender.mp4" width="80%"></video>
### Import a model
For this example, import a [robot model](../../assets/modeling/meshes/reference-files/shoebot-base-model.fbx) into Blender as your mesh object.
To import an existing `.fbx` model:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Import**, then the file format of the model you're importing. For this example, select **FBX (.fbx)** and the `.fbx` reference model. The model displays on the 3D viewport.
<img alt="Imported Model"
src="../../assets/modeling/meshes/rigging-simple/rigging-r1-imported.png" width="80%" />
## Create a bone structure
Now that your model is within Blender, you must add an **armature** and **bones** to your mesh object. An **armature** is a skeleton-like rigging object that acts as a container for bones, while **bones** are objects that control the movement and deformation of the group of vertices, or **vertex group**, that surround the bone.
### Add an armature
An armature is a structure required to add bones to your mesh. After you add in an armature, you can create and reposition any number of bones inside of your mesh object.
To add an armature:
1. At the top of the 3D viewport, select **Add** &rarr; **Armature**.
2. For better visualization of the bones, in the left-hand navigation of the **Properties Editor**, navigate to **Armature Object Properties**.
3. In the **Viewport Display** section, navigate to the **Show** property, then enable **In&nbsp;Front**.
<video controls src="../../assets/modeling/meshes/rigging-simple/2-adding-armature.mp4" width="80%"></video>
### Add and position bones
When you add an armature to your project, Blender automatically adds one bone to the armature at a default position and scale which will act as the root bone.
To add and position two additional bones:
1. Click on the **bone** to highlight it.
2. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Edit Mode**.
3. In the Viewport, click **Add** &rarr; **Single Bone**. Perform this step twice.
<video controls src="../../assets/modeling/meshes/rigging-simple/3.1-positioning-bones.mp4" width="80%"></video>
4. In the Viewport or Outliner, click on **a newly created bone** to highlight it.
5. Press <kbd>G</kbd> and use your mouse to drag the bone onto the **right arm**.
6. Click on the second bone and press <kbd>G</kbd> to drag the bone on the **left arm**.
<video controls src="../../assets/modeling/meshes/rigging-simple/3.2-positioning-bones.mp4" width="80%"></video>
7. Click on the top of the **right bone** so that the tip is highlighted. Press <kbd>G</kbd> to drag and orient the bone horizontally toward the right.
8. Click on the top of the **left bone** so that the tip is highlighted. Press <kbd>G</kbd> to drag and orient the bone horizontally toward the left.
<video controls src="../../assets/modeling/meshes/rigging-simple/3.3-positioning-bones.mp4" width="80%"></video>
9. In the Outliner, double-click and **rename** your bones so they can be easily referenced later.
<video controls src="../../assets/modeling/meshes/rigging-simple/4-rename-bones.mp4" width="80%"></video>
## Parent armature
After you create and position the bone structure, you need to connect the armature to the mesh object by parenting the armature to the mesh object.
In this guide, you should also use Blender's **Automatic Weights** function when you are parenting an armature, as it automatically adds weights and influences to your mesh.
To parent an armature to a mesh:
1. At the top of the 3D viewport, click on the Mode dropdown, then switch back to **Object Mode**.
2. Press <kbd>Alt</kbd><kbd>A</kbd> (Windows) or <kbd>⌥</kbd><kbd>A</kbd> (Mac) to deselect every object.
3. Hold <kbd>Shift</kbd> and select the **mesh object** and then the **armature**. The selection order is important.
4. In the **Viewport**, right-click on the mesh object. A pop-up menu displays.
5. Select **Parent**, then **With Automatic Weights**.
<video controls src="../../assets/modeling/meshes/rigging-simple/5-parenting-armature.mp4" width="80%"></video>
## Assign vertices to bones
With your armature connected to the mesh object, you can now assign the mesh vertices of your limbs to be fully influenced by their corresponding
bones. As a rigid model, each limb will completely bend and articulate when the bones are rotated, which is ideal for a non-organic character like a robot.
To assign bone influence to the left and right arms:
1. In Object Mode, select the **robot mesh object**.
2. In the Mode dropdown, switch to **Edit Mode**.
3. At the top-right of the Viewport, switch to **X-Ray** view using the Material Preview options.
<video controls src="../../assets/modeling/meshes/rigging-simple/6.1-assigning-vertices.mp4" width="80%"></video>
4. Drag and select the vertices you want to move with the right bone.
5. Navigate to the **Object Properties** panel.
6. In the **Vertex Group** section, select the name of the bone you want to assign and click **Assign**.
7. **Repeat steps 4-6** for the other bone and arm vertices.
<video controls src="../../assets/modeling/meshes/rigging-simple/6.2-assigning-vertices.mp4" width="80%"></video>
8. Drag and select the rest of the vertices in the center of the robot.
9. Navigate to the **Object Properties** panel.
10. In the Vertex Group section, select the **Middle bone** and click **Assign**.
<video controls src="../../assets/modeling/meshes/rigging-simple/6.3-assigning-vertices.mp4" width="80%"></video>
## Test
You can test your rig in different poses in Pose mode. It's important to test your rigs after applying or changing influences before exporting.
To test your applied influences:
1. In **Object Mode**, select any part of your model.
2. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Pose** mode.
3. Hold <kbd>Shift</kbd> and click the bone you want to test to highlight it, then press <kbd>R</kbd> to test the rotation.
4. Press <kbd>Alt</kbd><kbd>A</kbd> (<kbd>⌥</kbd><kbd>A</kbd>) to deselect the current bone, then reselect and test another bone.
<video controls src="../../assets/modeling/meshes/rigging-simple/7-testing.mp4" width="80%"></video>
<Alert severity="info">
To reset the rotation of a selected bone to neutral, press <KeyboardInput>Alt</KeyboardInput>+<KeyboardInput>R</KeyboardInput>. While rotating, you can also press your mouse's scroll wheel to change the axes of your rotation.
</Alert>
The robot model is now a rigged mesh and ready to [export](../../art/modeling/export-requirements.md) to Studio. For reference, you can download the [final export](../../assets/modeling/meshes/reference-files/shoebot-rigged-model.fbx) (`.fbx`) of the model rigged in this guide.

68
.cursor/rules/roblox/art/modeling/rigging.md Normal file
View file

@ -0,0 +1,68 @@
---
title: Rigging and skinning
description: Rigging and skinning is a modeling process that connects an armature to a mesh, allowing it to be animated or posed in Studio.
---
**Rigging** is the process of connecting a mesh with an internal poseable skeleton rig and bone structure. Rigged meshes allow mesh surfaces to rotate and move where internal bones are placed within the model during the modeling process. Rigging is often performed in conjunction with **skinning**, creating a natural looking stretch and bend when models are animated or repositioned. You can create rigged meshes with third-party software such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
<GridContainer numColumns="2">
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Transform-Demo-Default.mp4"></video>
<figcaption>A normal model can only rotate on its pivot point.</figcaption>
</figure>
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Transform-Demo-Skinned.mp4"></video>
<figcaption>A rigged model (or mesh) can rotate with any bone of its associated rig.</figcaption>
</figure>
</GridContainer>
<GridContainer numColumns="2">
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Head-Rigid-Example.mp4"></video>
<figcaption>A rigged model with no skinning data.</figcaption>
</figure>
<figure>
<video controls src="../../assets/modeling/skinned-meshes/Head-Skinned-Example.mp4"></video>
<figcaption>A skinned model that bends organically with the bone rotation.</figcaption>
</figure>
</GridContainer>
See the following resources to learn the basics and intermediate steps required to skin models in Blender:
- [Rig a simple mesh](../../art/modeling/rig-a-simple-mesh.md)
- [Skin a simple mesh](../../art/modeling/skin-a-simple-mesh.md)
- [Rig a humanoid model](../../art/modeling/rig-a-humanoid-model.md)
- [Skin a humanoid model](../../art/modeling/skin-a-humanoid-model.md)
## Rigs and bones
The **rig**, or bone structure, within a rigged mesh creates additional poseable points for the 3D model in Studio. By rotating or moving the bones of a mesh, the parts of the mesh assigned to those bones can move independently from the rest of the mesh. The assignment of influence between meshes and bones, such as a **LowerLeftArm** bone driving the movement of the **LowerLeftArm** geometry, is set in a third-party application like Blender or Maya. When imported into Studio, Roblox saves this influence assignment data to the `Class.MeshPart` asset data.
Once you successfully [import](../../parts/meshes.md#import-meshes) a rigged mesh model into Studio, Studio represents this rig structure with `Class.Bone` instances that you can then pose and animate. You can view bones in Studio by enabling **Show Constraint Details** from the **View** menu, or when you are using the [Animation Editor](../../animation/editor.md).
<Alert severity = "info">
When `Class.Bone` objects are used in animation, they affect the appearance of the parts but don't change the physical shape in cases such as [collision detection](../../workspace/collisions.md).
</Alert>
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/skinned-meshes/Rig-Constraint-Details.jpg" alt="A translucent humanoid outline, showing various sphere points where the constraints exist."/>
<figcaption>Constraint Details enabled</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/skinned-meshes/Rig-Bone-Visualization.jpg" alt="A translucent humanoid outline, showing 15 pink bones objects over various limbs."/>
<figcaption>When using the Animation Editor</figcaption>
</figure>
</GridContainer>
## Types of rigs
Rigged models use a naming convention starting with "R" and ending with the number of individual meshes that make up the model. This is used to quickly identify the type and number of meshes that a model has. Although R6 and R15 models are common, a model can be of varying subjects, sizes and can have any number of individual meshes, such as a R5, R20, or R200.
- **R1** refers to a single mesh that is rigged, or associated with an internal skeleton structure. Many models, such as a tree or accessory item, are good candidates to be made into an R1 model. Even humanoid characters, such as NPCs, can be created as R1 models but they will not be able to take full advantage of the animation and humanoid options available for R15 characters.
See [Rig a simple mesh](../../art/modeling/rig-a-simple-mesh.md) for instructions on turning a basic mesh into an R1 model in Blender.
- **R15** typically refers to humanoid models used as player or avatar characters. An R15 model is made up of 15 specific meshes that are parented to a single rig. A R15 character model often includes skinning data to allow the model to bend and pose naturally. Roblox uses the R15 standard for all avatars, and requires the [R15 technical specifications](../../art/characters/specifications.md) to ensure universal behavior and quality.
See [Rig a humanoid model](../../art/modeling/rig-a-humanoid-model.md) for instructions on turning a character model into an R15 humanoid model in Blender.

10
.cursor/rules/roblox/art/modeling/roblox-blender-plugin.md Normal file
View file

@ -0,0 +1,10 @@
---
title: Roblox Blender plugin
description: The Roblox Blender plugin allows you to transfer assets directly from Blender to Studio.
---
The Roblox Blender plugin is a Blender add-on that allows you to link your Roblox account and quickly transfer 3D modeling objects directly from Blender to your Studio session. This tool helps you save time and reduce errors by skipping the process of exporting and importing third-party modeling files between applications.
The Roblox Blender plugin is an open-source implementation of Roblox's [Open Cloud API](../../cloud/guides/index.md) and developers are encouraged to extend and build upon this tool for their own projects. For installation, use, licensing, and contribution details, see the [Roblox Blender plugin GitHub page](https://github.com/Roblox/roblox-blender-plugin).
<video controls src="../../assets/art/RobloxBlenderPluginDemo.mp4" width="100%"></video>

224
.cursor/rules/roblox/art/modeling/skin-a-humanoid-model.md Normal file
View file

@ -0,0 +1,224 @@
---
title: Skin a humanoid model
description: Explains the process for skinning a humanoid R15 model in Blender.
---
A humanoid skinned mesh is a character model that, when posed or animated, bends and stretches naturally at its joints. You can create a skinned mesh using a third party modeling tool such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
This is an advanced guide on skinning a humanoid model into an R15 model in Blender using the humanoid model completed in [Rig a humanoid model](./rig-a-humanoid-model.md). Before skinning a humanoid model, you should also familiarize yourself with the basic concepts in [Skin a simple mesh](../../art/modeling/skin-a-simple-mesh.md).
To skin a humanoid model in Blender, you need to:
- [Set up Blender](#set-up-blender) with a rigged model to optimize the weight painting process with bone visualization settings and Auto Normalize.
- [Weight paint](#weight-painting) vertices of your mesh objects by balancing influence of your vertices between two or more bones of a humanoid rig architecture.
<Alert severity="info">
This guide uses the humanoid model rigged in [Rig a humanoid model](./rig-a-humanoid-model.md) and [Blender version 3.0](https://www.blender.org/download/releases/3-0/). If you are
using another version of Blender, there may be minor differences in UI and
settings.
</Alert>
## Set up Blender
This guide uses the rigged model completed in [Rig a humanoid model](./rig-a-humanoid-model.md). You can also download the rigged model [Blender project](../../assets/modeling/meshes/reference-files/lola-rigged-r15.blend) to follow along with this guide.
To optimize the process of skinning a rigid character, first set up the following in your Blender project:
- Open the Blender project and configure the [bone visualization](#bone-visualization) settings.
- Enable [Auto Normalize](#auto-normalize) to help optimize the weight-painting process.
### Bone visualization
By default, Blender displays bone objects as octahedral shapes. This original shape is useful when positioning bones but can get in the way while weight painting. To help visualization during the weight painting process, change your bone visualization to sticks.
To update the visualization of your bones:
1. In Object Mode, click the **armature**.
2. In the **Object Data Properties**, change the **Display As** value to **Sticks**.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/1-bone-visualizations.mp4" width="100%"></video>
### Auto normalize
The Auto Normalize setting forces the influence on your vertices to equal one. This makes weight painting multiple meshes and bones more efficient by ensuring that each vertex in your character is fully influenced by at least one bone. See Blender's documentation on the [Auto Normalize](https://docs.blender.org/manual/en/latest/sculpt_paint/weight_paint/tool_settings/options.html) for more information.
Auto Normalize also prevents cases where a vertex is fully influenced by multiple bones and can prevent common weight painting mistakes.
<GridContainer numColumns="2">
<figure>
<video controls src="../../assets/modeling/meshes/skinning-humanoid/autonormalize-example2.mp4"></video>
<figcaption>Without Auto Normalize, it is not clear until testing that this fully influenced head is also influenced by another bone due to a painting mistake.</figcaption>
</figure>
<figure>
<video controls src="../../assets/modeling/meshes/skinning-humanoid/autonormalize-example.mp4"></video>
<figcaption>With Auto Normalize, painting influence to an incorrect bone removes the existing influence from the original bone. This makes mistakes easier to catch and resolve.</figcaption>
</figure>
</GridContainer>
<Alert severity="warning">
Studio doesn't support more than 4 bones to influence any single vertex. This may occur in complex rigs or inadvertently with Auto Normalize disabled.
</Alert>
To enable Auto Normalize:
1. In **Object Mode**, select the **armature**.
2. Hold <kbd>Shift</kbd> and select **any mesh object** on your model.
3. At the top of the 3D viewport, click on the Mode dropdown and switch to **Weight Paint** mode.
4. On the right side of the viewport, expand the **Tool** tab.
5. Under **Options**, enable **Auto Normalize**.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/2-auto-normalize.mp4" width="100%"></video>
## Weight painting
Weight painting applies specific weights, or influences, that bones will have over parts of a mesh using a painting workflow. There are also additional ways to apply influences through weight painting or other tools, some which are covered in [Skin a simple mesh](../../art/modeling/skin-a-simple-mesh.md). See additional online resources such as Blender's [Character Rigging](https://www.youtube.com/watch?v=f2pTkW-1JkE) and [Vertex Groups](https://www.youtube.com/watch?v=dKZrzG5r13g) fundamental guides for more information on skinning and applying weights.
This guide will cover one process of weight painting the head and arm meshes of a humanoid model. These weight painting techniques can be used to weight paint the rest of the model.
<Alert severity="warning">
Do not apply influences on the Root or HumanoidRootNode parent bones in a humanoid rig. Any added influences are dropped when importing into Studio.
</Alert>
### Paint the head mesh
The head mesh connects to the upper torso at the bottom vertices of the neck. To create a realistic bend in the model, the head mesh needs to share influence with the Head bone and the Upper Torso bone near the neckline.
To begin weight painting the Head mesh object:
1. In Object Mode, click the **armature** then hold <kbd>Shift</kbd> and click the **Head mesh object**.
2. In the Mode dropdown, switch to **Weight Paint** mode.
3. Hold <kbd>Shift</kbd> and click the **Upper Torso bone**. The head should be completely blue as the Upper Torso doesn't yet influence any head vertices.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/3-select-head.mp4" width="100%"></video>
<Alert severity="info">
A common error is to apply weights with the incorrect bone selected. Make sure to <kbd>Shift</kbd> select and un-select the correct bones when applying weights. The name of the bone currently being painted will populate in the Viewport.
</Alert>
4. In the top right of the Viewport, open the **Tool** menu and set the **brush strength** to **1**.
5. With the Upper Torso bone selected, **paint** the Head of your model at the neckline. You can temporarily **Hide** the Upper Torso mesh in the Outliner to have direct access to the bottom of the neck.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/4-weight-paint-head.mp4" width="100%"></video>
6. At any point, check the applied influences by holding <kbd>Shift</kbd> and deselecting the Upper Torso bone and selecting the Head bone. Press <kbd>R</kbd> to rotate the Head bone with your mouse and test how the mesh object shares influences between the Head and Upper Torso bone.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/5-test-head.mp4" width="100%"></video>
7. If additional painting is required, hold <kbd>Shift</kbd> and select the bone you want to add or remove influence from, and use the Brush tool to apply.
The final result of weight painting the head of the model should balance the head mesh influences with the Head bone and the Upper Torso bone:
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/skinning-humanoid/head-example-headbone-selected.png" />
<figcaption>The Head bone fully influences the Head_Geo mesh from the neck up.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/skinning-humanoid/head-example-uppertorso-selected.png" />
<figcaption>The Upper Torso bone fully influences the Head_Geo mesh from the neck down.</figcaption>
</figure>
</GridContainer>
### Paint the arm meshes
Similar to the process for balancing influences between the Head bone and Upper Torso bone, arms and legs require a similar weight painting process.
The right arm includes the Right Hand, Right Lower Arm, and Right Upper Arm, each with their corresponding bones. The following instructions provide guidance on painting influences to all of the arm mesh objects. You can then apply these techniques to the rest of the meshes in your model.
#### Hand
Starting with the Right Hand, you can balance the influences of the mesh between the **Hand bone** and the **Lower Arm bone** to create a natural bend at the wrist.
To weight paint influences to the right hand:
1. From Object Mode, click the **armature**, hold <kbd>Shift</kbd>, and click the right **hand** geometry.
2. In the mode dropdown, switch to **Weight Paint** mode. With the hand bone selected in this mode, you can press <kbd>R</kbd> and test the current rotation of the hand mesh object.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/6-select-hand-and-test.mp4" width="100%"></video>
3. In the top right of the Viewport, open the **Tool** menu and set the **brush strength** to **1**.
4. With the Lower Arm bone selected, **paint** the hand of your model at the wrist. You can temporarily **Hide** the Lower Arm mesh in the Outliner to get better access to the wrist.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/7-weight-paint-hand.mp4" width="100%"></video>
5. During and after weight painting the hand, press <kbd>R</kbd> with the bone selected to test the rotation and flexibility.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/8-test-hand.mp4" width="100%"></video>
<Alert severity="info">
You can add and skin additional bones, such as fingers, if you want additional controls to your skinned mesh.
Extra bone objects that are skinned to a mesh but do not share a Humanoid bone object name (such as LowerTorso, LeftFoot, Right UpperArm) are imported into Studio as a `Class.Bone` with the same name it was assigned with in the 3D modeling software.
</Alert>
#### Lower arm
After the wrist of the right hand is weight painted, you can proceed to balance the influences of the Lower Arm mesh between the **Lower Arm bone** and the **Upper Arm bone** to create a natural bend at the elbow.
To weight paint influences to the lower arm:
1. Switch back to Object Mode.
2. Click the **armature** and hold <kbd>Shift</kbd> and click the right **lower arm** geometry.
3. In the mode dropdown, switch to **Weight Paint** mode.
4. Hold <kbd>Shift</kbd> and deselect other bones besides the Lower Arm bone. You can test the current rotation of the highlighted Lower Arm bone by pressing <kbd>R</kbd>.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/9-switch-to-lower-arm.mp4" width="100%"></video>
5. Hold <kbd>Shift</kbd> and select the Upper Arm bone.
6. With the Upper Arm bone selected, **paint** the lower arm of your model at the elbow. You can temporarily **Hide** the Upper Arm mesh in the Outliner to get better access to the elbow.
7. During and after weight painting the lower arm, press <kbd>R</kbd> with the lower arm bone selected to test the rotation and flexibility.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/10-weight-paint-lower-arm.mp4" width="100%"></video>
#### Upper arm
After the elbow of the right lower arm is weight painted, you can proceed to balance the influences of the Upper Arm mesh between the **Upper Arm bone** and the **Upper Torso bone** to create a natural bend at the underarm.
To weight paint influences to the upper arm:
1. Switch back to Object Mode.
2. Click the **armature** and hold <kbd>Shift</kbd> and click the right **upper arm** geometry.
3. In the mode dropdown, switch to **Weight Paint** mode.
4. Hold <kbd>Shift</kbd> and deselect other bones besides the Upper Arm bone. You can test the current rotation of the highlighted Upper Arm bone by pressing <kbd>R</kbd>.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/11-switch-to-upper-arm.mp4" width="100%"></video>
5. Press <kbd>R</kbd> and drag your mouse to rotate the Upper Arm so that the arm is horizontal. This makes it easier to access the vertices of the underarm.
6. Hold <kbd>Shift</kbd> and select the Upper Torso bone.
7. With the Upper Torso bone selected, **paint** the upper arm of your model at the underarm. You can temporarily **Hide** the Upper Torso mesh in the Outliner to get better access to the elbow.
8. During and after weight painting the lower arm, press <kbd>R</kbd> with the upper arm bone selected to test the rotation and flexibility.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/12-weight-paint-upper-arm.mp4" width="100%"></video>
#### Shoulder
After the underarm is weight painted, you can proceed to balance the influences of the Upper Torso mesh between the **Upper Torso bone** and the **Upper Arm bone** to create a natural bend at the shoulder when the arm is moved. Since this movement is subtle, you only need to apply a partial strength influence to these vertices.
To weight paint a partial strength influence to the upper torso:
1. Switch back to Object Mode.
2. Click the **armature** and hold <kbd>Shift</kbd> and click the **upper torso** geometry.
3. In the mode dropdown, switch to **Weight Paint** mode.
4. Hold <kbd>Shift</kbd> and deselect other bones besides the Upper Arm bone. You can test the current rotation of the highlighted Upper Arm bone by pressing <kbd>R</kbd>.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/13-switch-to-upper-torso.mp4" width="100%"></video>
5. In the top right of the Viewport, open the **Tool** menu and set the **brush strength** to **.25**. You may want to adjust this based on the results when testing.
6. With the Upper Torso bone selected, **paint** the upper torso of your model at the shoulder.
7. During and after weight painting the lower arm, press <kbd>R</kbd> with the upper arm bone selected to test the rotation and flexibility of your influences to the upper torso.
<video controls src="../../assets/modeling/meshes/skinning-humanoid/14-weight-paint-upper-torso.mp4" width="100%"></video>
<Alert severity = 'warning'>
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/skinning-humanoid/Candywrap-Example.png" width='100%'/>
</figure>
<figure>
When rotating arms to their full range of motion, a candy-wrapping effect may occur between the shoulder and torso where the skinning loses volume and doesn't deform naturally. This effect may not be avoidable in many cases.
</figure>
</GridContainer>
</Alert>
You can continue to weight paint the rest of the limbs of your model using these processes. When completed, you can [export](../../art/modeling/export-requirements.md) your skinned model as a `.fbx` using the Blender export settings for use in Studio. For reference, you can download a [Blender project](../../assets/modeling/meshes/reference-files/lola-skinned-s15.blend) with the model fully skinned.
<Alert severity="warning">
Since this reference model doesn't yet have [inner and outer cage mesh data](../../art/characters/specifications.md#inner-and-outer-cages), this model can't equip layered clothing or accessories.
</Alert>

301
.cursor/rules/roblox/art/modeling/skin-a-simple-mesh.md Normal file
View file

@ -0,0 +1,301 @@
---
title: Skin a simple mesh
description: Explains the process for skinning a basic model in Blender.
---
A skinned mesh is a rigged mesh that bends and flexes naturally when the internal skeleton rig is posed or animated. You can create a skinned mesh using a third party modeling tool such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview). Skinning must be completed after the model is [rigged](./rigging.md).
This guide covers the process for rigging and then skinning a simple tree model in Blender with 3 bones. For basics on rigging, see [Rig a simple mesh](./rig-a-simple-mesh.md) before continuing this guide.
To skin a simple mesh, you need to:
- [Set up Blender](#set-up-blender) to Studio's relative scene units before importing a model.
- [Create, size, and position bones](#position-bones) inside of an armature.
- [Parent a mesh to an armature](#parent-armature) to bind the skeleton rig to the mesh object.
- [Weight paint](#weight-paint) the mesh to assign which parts of the mesh will move with which bone.
<Alert severity="info">
This guide uses a downloadable [example tree model](../../assets/modeling/skinned-meshes/MapleLeafTree.fbx) and [Blender version 3.0](https://www.blender.org/download/releases/3-0/). If you are
using another version of Blender, there may be minor differences in UI and
settings.
</Alert>
## Set up Blender
To start the process of creating a skinned mesh, first set up the following in your Blender project:
- Set [scene unit and unit scale properties](#adjust-scene-and-scale) to Studio's proportions.
- [Import the model into Blender](#import-a-model) using Blender's file importer.
### Adjust scene and scale
When setting up Blender projects for Roblox Studio import, modify Blender's default **scene units** and **unit scale** properties to ensure they closely align with Studio's scale.
To modify Blender's scene and scale units in a new project:
1. Open a new **General** project in Blender.
2. Select the default shape, camera, and lights, then press <kbd>Delete</kbd>.
3. In the left-hand navigation of the **Properties Editor**, navigate to **Scene Properties**.
<img src="../../assets/modeling/skinned-meshes/Blender-Scene-Units-Icon.png" width="222" />
4. In the **Units** section, change the **Unit Scale** to **0.01** and the **Length** to **Centimeters**.
<img src="../../assets/modeling/skinned-meshes/Blender-Scene-Units-Settings.png" width="222" />
### Import a model
For this guide, you'll import a [maple tree model](../../assets/modeling/skinned-meshes/MapleLeafTree.fbx) into Blender as your mesh object.
To import a model into Blender:
1. In the topbar, click **File**. A pop-up menu displays.
2. Select **Import**, then the file format of the model you're importing. For this example, select **FBX (.fbx)** and the `.fbx` reference model. The model displays on the 3D viewport.
<img alt="Viewport Display Settings"
src="../../assets/modeling/skinned-meshes/Import-Model.jpg" width="800" />
## Create a bone structure
Now that your model is within Blender, add an armature and **bones** to your mesh object. An **armature** is a skeleton-like rigging object that acts as a container for bones, while **bones** are objects that control the movement and deformation of the group of vertices, or **vertex group**, that surround the bone.
### Add an armature
An armature is a structure required to add bones to your mesh. After you add in an armature, you can create and reposition any number of bones inside of your mesh object.
To add an armature:
1. At the top of the 3D viewport, select **Add** &rarr; **Armature**.
<video controls src="../../assets/modeling/skinned-meshes/Adding-Armature.mp4" width="80%"></video>
2. For better visualization of the bones, in the left-hand navigation of the **Properties Editor**, navigate to **Armature Object Properties**.
3. In the **Viewport Display** section, navigate to the **Show** property, then enable **In&nbsp;Front**.
<img src="../../assets/modeling/skinned-meshes/Bone-Visualization.png" width="451" />
<video controls src="../../assets/modeling/skinned-meshes/Bone-In-Front.mp4"
width="80%"></video>
### Position bones
When you add an armature to your project, Blender also adds one bone to the armature at a default position and scale. You can rotate and scale the bone to more accurately represent the internal structure of your mesh object.
To reposition the bone:
1. Click on the **bone object** to highlight it.
2. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Edit Mode**.
3. Click on the **top of the bone** and press <kbd>G</kbd>. The top of the bone moves with your cursor.
4. Pull this bone to align with the interior center of the model, then click to set the bone's position.
<video controls
src="../../assets/modeling/skinned-meshes/Position-First-Bone.mp4"
width="80%"></video>
5. Press and hold your mouse's scroll wheel to move the camera around the mesh object to see different views and angles to ensure that the bone is centered within the mesh object.
### Add additional bones
In this guide, you need 3 bones within your mesh so the tree can move and rotate at three points.
To add additional bones into the armature:
1. While still in **Edit Mode**, click on the tip of the bone.
2. Press <kbd>E</kbd> and drag your mouse upward. This extends an additional bone out of the original root bone.
<video controls
src="../../assets/modeling/skinned-meshes/Extrude-Second-Bone.mp4"
width="80%"></video>
3. Repeat this process for the second bone.
<video controls
src="../../assets/modeling/skinned-meshes/Extrude-Last-Bone.mp4"
width="80%"></video>
4. Press and hold your mouse's scroll wheel to move the camera around the mesh object to see different views and angles to ensure that the bones are within the mesh object. [Reposition the bones](#position-bones) as necessary.
5. In the Outliner, expand the **Armature** object. The armature's bone hierarchy displays.
6. In the Outliner, double-click and **rename** each bone. Bone object names remain the same when you import the mesh object into Studio.
<video controls src="../../assets/modeling/skinned-meshes/Renaming-Bones.mp4"
width="80%"></video>
## Parent armature
After the bone structure is created and positioned, you need to connect the armature to the mesh object by parenting the armature to the mesh object.
This guide uses Blender's **Automatic Weights** function when you are parenting an armature, as it automatically adds weights and influences to your mesh. This can save you time during the [weight painting](#weight-paint) process.
To parent an armature to a mesh:
1. At the top of the 3D viewport, click on the Mode dropdown, then switch back to **Object Mode**.
2. Press <kbd>Alt</kbd><kbd>A</kbd> (Windows) or <kbd>⌥</kbd><kbd>A</kbd> (Mac) to deselect every object.
3. Hold <kbd>shift</kbd> and select the **mesh object** and then the **armature**. The selection order is important.
4. In the viewport, right-click on the **mesh object**. A pop-up menu displays.
5. Select **Parent**, then **With Automatic Weights**.
<video controls
src="../../assets/modeling/skinned-meshes/Parenting-Armature.mp4"
width="80%"></video>
## Weight paint
With your armature connected to the mesh object, you can use the process of **weight painting** to change the amount of influence (weight) the bones will have on specific vertices to allow for more natural movement and flexibility.
Blender represents weight strength with a [blue to red gradient](https://docs.blender.org/manual/en/latest/sculpt_paint/weight_paint/introduction.html#the-weighting-color-code), where **blue** represents a value of **0** and **red** represents a fully influenced value of **1**. Vertices on a mesh object that are painted red will be fully influenced by that specific bone's rotation while vertices that are yellow or green will be partially influenced by the bone's rotation.
You can quickly assign influence with the [Brush tool](https://docs.blender.org/manual/en/latest/sculpt_paint/weight_paint/tools.html) in Blender's **Weight Paint** mode using the **Draw**, **Add**, or **Subtract** brush tools. For each brush, you can set the influence weight and radius in the **Tools** setting to the right of the **Viewport**.
<img src="../../assets/modeling/skinned-meshes/Brush-Settings.png" width="107" />
To optimize the painting process, [set up visualization and brush settings](#setup) before [painting influences](#paint-influence) to the mesh.
### Setup
When assigning influences for complex models, you can configure the following Blender settings to optimize the Weight Painting process.
#### Bone visualization
By default, Blender displays bone objects as octahedral shapes. This original shape is useful when positioning bones within the rig but can get in the way while painting. To help visualize the weight painting process, change your bone visualization to sticks.
To update the visualization of your bones:
1. In **Object Mode**, select the **Armature**.
2. In the left-hand navigation of the **Properties Editor**, navigate to **Object Data Properties**.
3. Change the **Display As** value to **Stick**.
<video controls
src="../../assets/modeling/skinned-meshes/Stick-Visualization.mp4"
width="80%"></video>
#### Auto normalize
The [Auto Normalize](https://docs.blender.org/manual/en/latest/sculpt_paint/weight_paint/tool_settings/options.html) setting forces the influence on your vertices to equal one. This makes weight painting more efficient by ensuring that each vertex in your character is fully influenced by at least one bone. In this guide, Auto Normalize allows you to first apply full influence to the entire mesh quickly and then make minor adjustments with each bone.
To enable Auto Normalize:
1. In **Object Mode**, select the **Armature**.
2. Hold <kbd>shift</kbd> and select the **mesh object**.
3. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Weight Paint** mode.
<Alert severity="info">
You must select the appropriate object to access specific modes, such as selecting a mesh object to access **Weight Paint** mode. If you are unfamiliar with switching to different modes, refer to <a href ="https://docs.blender.org/manual/en/latest/editors/3dview/modes.html">Object Modes</a>.
</Alert>
4. On the right side of the viewport, click the **Tool** tab.
5. Under the **Options** section, enable **Auto Normalize**.
<video controls
src="../../assets/modeling/skinned-meshes/Enabling-Autonormalize.mp4"
width="80%"></video>
#### Projected brush
A projected brush allows you to easily apply influence through a mesh, instead of just the surface. This is useful when painting influences on meshes that may be geometrically layered, such as the foliage of the tree.
To set up a projected brush:
1. In **Object Mode**, select the **Armature**.
2. Hold <kbd>shift</kbd> and select the **mesh object**.
3. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Weight Paint** mode.
4. On the right side of the viewport, click the **Tool** tab.
5. Expand the **Advanced** section, then uncheck **Front Faces Only**.
6. Expand the **Falloff** section, then select **Projected**.
<video controls
src="../../assets/modeling/skinned-meshes/Setting-Projected-Brush.mp4"
width="80%"></video>
### Paint influence
With the [projected brush](#projected-brush) set up, you can now begin applying influence to the tree. Take advantage of the [Auto Normalize](#auto-normalize) setting by painting full red influence to the entire tree to the bottom bone and then assigning a partial influence on the middle and top bones.
#### Bottom bone
The bottom bone should fully influence the movement of the entire tree starting from the trunk.
To start painting influence to the bottom bone:
1. In **Object Mode**, hold <kbd>shift</kbd>, select the bones and then the mesh object.
2. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Weight Paint** mode.
3. Hold <kbd>shift</kbd> and click on the bottom bone.
4. Use the brush tools to paint a red area of influence from the base of the bone and the rest of the tree.
<video controls
src="../../assets/modeling/skinned-meshes/Paint-Bottom-Bone.mp4"
width="80%"></video>
<Alert severity="info">
You can adjust the radius of the brush in the <b>Tool</b> tab, or by holding <KeyboardInput>F</KeyboardInput> and dragging your mouse to change the size.
</Alert>
5. With the bone highlighted, test that the bone is influencing the entire model by pressing <kbd>R</kbd> and rotating the mouse. Paint any vertices that are not influenced correctly to apply influence to them.
<video controls
src="../../assets/modeling/skinned-meshes/Test-Bottom-Bone.mp4"
width="80%"></video>
#### Middle bone
The middle bone represents most of the foliage above the bottom bone. For a more subtle effect, apply a 50% influence (green) from the middle bone upwards.
To paint influence to the middle bone:
1. In **Weight Paint** mode, press <kbd>Alt</kbd><kbd>A</kbd> (Windows) or <kbd>⌥</kbd><kbd>A</kbd> (Mac) to deselect the current bone object.
2. Hold <kbd>shift</kbd> and <kbd>click</kbd> on the middle bone.
3. On the right side of the viewport, click the **Tool** tab.
4. Change the **Weight** value to **.5**.
5. Starting from the area at the middle bone, paint the middle and top area of the tree.
6. Press <kbd>R</kbd> to rotate the bone and test the influence at different angles.
<video controls
src="../../assets/modeling/skinned-meshes/Paint-Middle-Bone.mp4"
width="80%"></video>
#### Top bone
The top bone should influence the top leaf area above the middle bone. Paint this top area using 25% influence (teal) for a more natural effect.
To paint influence to the top bone:
1. In **Weight Paint** mode, press <kbd>Alt</kbd><kbd>A</kbd> (Windows) or <kbd>⌥</kbd><kbd>A</kbd> (Mac) to deselect the current bone object.
2. Hold <kbd>shift</kbd> and click on the top bone.
3. On the right side of the viewport, click the **Tool** tab.
4. Change the **Weight** value to **0.25**.
5. Starting from the area at the top bone, paint the top area of the tree.
6. Press <kbd>R</kbd> to rotate the bone and test the influence at different angles.
<video controls
src="../../assets/modeling/skinned-meshes/Paint-Top-Bone.mp4"
width="80%"></video>
After weight painting each bone, each section of this tree should now be influenced by the bottom, middle, or top bones. The bottom bone fully controls the trunk of the tree while the middle and top bones have a reduced influence on the branches and leaves.
<video controls
src="../../assets/modeling/skinned-meshes/Test-Bones.mp4"
width="80%"></video>
### Test
It is important to constantly test the influences of your bone **throughout** the weight painting process.
Blender allows you to test and pose bones **while** painting if both the armature and mesh are selected in Object Mode **before** switching to Weight Paint mode. This hybrid pose and weight paint functionality doesn't work unless you select both armature and mesh before entering Weight Paint mode.
To test your weight painting:
1. In **Object Mode**, select the **Armature**.
2. Hold <kbd>shift</kbd> and select the **mesh object**.
3. At the top of the 3D viewport, click on the Mode dropdown, then switch to **Weight Paint** mode.
4. Hold <kbd>shift</kbd> and click the bone you want to test, then press <kbd>R</kbd> to test the rotation.
5. Press <kbd>Alt</kbd><kbd>A</kbd> (<kbd>⌥</kbd><kbd>A</kbd>) to deselect the current bone, then reselect and test another bone.
<video controls loop muted
src="../../assets/modeling/skinned-meshes/Weight-Painting-Example-Gradient.mp4"
width="80%"></video>
<Alert severity="info">
To reset the rotation of a selected bone to neutral, press <KeyboardInput>Alt</KeyboardInput>+<KeyboardInput>R</KeyboardInput>. While rotating, you can also press your mouse's scroll wheel to change the axes of your rotation. It is recommended to prioritize testing positions you expect to use in your animations and poses in Studio.
</Alert>
Your S1 tree model is now a skinned mesh and is ready for [export](../../art/modeling/export-requirements.md) for Studio. The <a href="../../assets/modeling/skinned-meshes/MapleTreeS1.blend" download>Blender project file</a> and [final export](../../assets/modeling/skinned-meshes/MapleLeafTree.fbx) (`.fbx`) are available for reference.

88
.cursor/rules/roblox/art/modeling/specifications.md Normal file
View file

@ -0,0 +1,88 @@
---
title: General specifications
description: Lists the specific technical requirements for custom models created outside of Studio.
---
Roblox supports a wide variety of mesh configurations created from third-party software such as [Blender](https://www.blender.org) or [Maya](https://www.autodesk.com/products/maya/overview).
Check that your model meets the following modeling specifications and guidelines before exporting to ensure Studio compatibility. Specific types of assets, like characters and accessories, have additional specifications:
<Alert severity = 'warning'>
<AlertTitle>If creating other types of 3D models:</AlertTitle>
<ul>
<li>For rigid accessories, see [accessory specifications](../accessories/specifications.md) and [accessory export settings](../accessories/export-settings.md).</li> <br />
<li>For layered accessories, see [layered accessory specifications](../accessories/clothing-specifications.md) and [layered export settings](../accessories/clothing-export-settings.md).</li> <br />
<li>For avatar characters, see [avatar specifications](../characters/specifications.md) and [avatar export settings](../characters/export-settings.md).</li>
</ul>
</Alert>
When ready to export, see the [export settings](../../art/modeling/export-requirements.md) for mesh export settings for Blender and Maya.
<Alert severity='info'>
If you meet certain account requirements, you can sell your custom meshes as accessories on the Marketplace. See [Rigid accessories](../../art/accessories/index.md) for an overview on the creation process for these types of accessories.
</Alert>
## Geometry
See the following specifications for general geometry:
- **Budgets** - Individual meshes can not exceed 20,000 triangles. Avatar items have their own individual budget requirements for [characters](../../art/characters/specifications.md) and [accessories](../../art/accessories/specifications.md).
- **Watertight** - All geometry must be watertight without exposed holes or backfaces.
- **No N-gons** - Meshes must be in quads where possible.
- **Volume** - Meshes cannot be 0 thickness and must have some volume.
## Rigging and skinning
Roblox supports third-party meshes with an internal rig, or skeleton structure that can be used as additional articulation points in your model. See [Character rigs](../../art/characters/specifications.md#rig) for specific standards for an R15 character rig.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/animation/importing-custom-3d-rigs/Rig-Custom-Puffer-Blender.png" alt="A cartoon-ish low polygon model of a puffer fish."/>
<figcaption>Generic rig model.</figcaption>
</figure>
<figure>
<img src="../../assets/animation/importing-custom-3d-rigs/Rig-Hierarchy-Custom-Blender-Bones.png" width="75%" alt="The Outliner in Blender of the puffer fish model, showing the armature bone structure."/>
<figcaption>Generic rig bone structure (Blender).</figcaption>
</figure>
</GridContainer>
See the following requirements for general rigging and skinning:
- **Transformations** - All bones (Blender) or joints (Maya) must be frozen and have scale values set to `1`, `1`, `1` and rotation values set to `0`, `0`, `0`.
- **Symmetry** - When possible, maintain symmetry when applying influences to a rig
- **Root joint** - The root bone or joint should always be set to `0`, `0`, `0`.
- **Max influences** - A vertex can not be influenced by more than 4 bones or joints.
- **No Root influences** - Do not apply influences to the Root bone or joint.
## Textures
- Roblox supports basic color textures and modern [PBR textures](../../art/modeling/surface-appearance.md).
- For instructions on assigning texture images to natively import with your mesh, see [Assign textures in modeling tools](./assign-textures.md).
- For technical requirements and best practices when generating individual texture images, see [Texture specifications](../../art/modeling/texture-specifications.md).
## Animations
An animation can be included on any `.fbx` mesh export. For information on prepping a character animation from a modeling software for export, see [Export animations from Maya](../../art/characters/export-avatar-animations-from-maya.md).
See the following requirements for assets with animation:
- **Single track animation** - Only a single animation track can be exported with a mesh or model. If you want to export multiple animations, you need to create separate exports for each animation you want to import.
## Inner and outer cages
Inner and Outer cages are non-rendered meshes that Roblox uses to define the inner and outer surfaces of a mesh using a `Class.WrapLayer` or `Class.WrapTarget` instance. These cages are most often used with characters and accessories, though you can use cage meshes for any mesh object.
<Alert severity="warning">
Character models must include an outer cage in order to properly equip layered clothing and accessories. See [Character specifications](../../art/characters/specifications.md) for additional information.
</Alert>
For general use, see the following requirements for adding inner and outer cage meshes to your model:
- **Naming conventions** - The inner and outer cage must be named after the primary mesh object with **\_InnerCage** and **\_OuterCage** affixed.
<img src="../../assets/accessories/lc-blender-selecting-cage-in-outlier.png" alt="The Outliner in Blender showing two mesh objects called Tshirt_InnerCage and Tshirt_OuterCage."/>
- **Outer cage** - Models, such as a playable character, that aren't expected deform but are the target of meshes that will stretch over it, only require an Outer Cage.
- For more information on applying and implementing cages on non-Humanoid targets, see [layered clothing on non-R15](../../characters/appearance.md#layered-clothing-on-non-r15).
- **Vertices and UV map** - Don't delete vertices or alter the UVs on the Inner or Outer Cages as this can cause errors when importing in Studio or when equipping onto a character.
- **Symmetry and consistency** - Keep each face (the space between vertices) consistently sized and retain symmetry wherever possible. Use symmetry tools in your modeling software whenever possible.

424
.cursor/rules/roblox/art/modeling/surface-appearance.md Normal file
View file

@ -0,0 +1,424 @@
---
title: PBR textures
description: PBR textures are advanced textures using multiple texture maps.
---
**Physically-Based Rendering** (PBR) textures allow you to represent realistic shading and lighting by using multiple types of texture images, or **maps**, on a single object. Combining multiple texture maps can more accurately simulate color, roughness, and reflectivity in any lighting environment and can enhance the visual elements of your assets and environment.
<Tabs>
<TabItem label="Clothing">
<GridContainer numColumns="2">
<img src="../../assets/modeling/surface-appearance/Layered-Clothing-Example.png" alt="A humanoid avatar with dreadlocks, a glossy jacket, jeans with decals, and boots." />
<img src="../../assets/modeling/surface-appearance/Layered-Clothing-Example-2.jpg" alt="A humanoid avatar with a short haircut, leather jacket, capri pants, and orange shoes." />
</GridContainer>
</TabItem>
<TabItem label="Environment">
<GridContainer numColumns="2">
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-Example-1.jpg" alt="A realistic leafy bush" />
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-Example-3.jpg" alt="A realistic mossy rock" />
</GridContainer>
</TabItem>
</Tabs>
Various applications and workflows are available for creating PBR textures. You can use these during the modeling and texturing phases of custom 3D object creation, provided that Roblox Studio [supports](../../art/characters/specifications.md#textures) the specific texture maps you're using.
<Alert severity = 'info'>
For information on how to properly connect PBR textures to your model in Blender and Maya for import into Studio, see [Blender / Maya texture settings](./assign-textures.md).
</Alert>
This guide provides instructions on [setting up](#enable-surface-appearance) your mesh objects to use PBR texture maps, and describes common use-cases and best practices for Roblox's supported PBR [texture maps](#texture-maps). When creating your own surfaces, see [material references](../../art/modeling/material-reference.md) for common material values, image comparisons and clothing examples.
## Enable surface appearance
You can add PBR textures to any `Class.MeshPart` by adding a `Class.SurfaceAppearance` object which overwrites the original assigned texture. In general, you can't modify `Class.SurfaceAppearance` properties by scripts during an experience because the engine requires some pre-processing to display these graphics. Similar to adding a basic texture, each texture image map must point to the appropriate uploaded image asset ID.
To enable surface appearance for a `Class.MeshPart`:
1. In the [Explorer](../../studio/explorer.md) window, hover over the `Class.MeshPart` and click the &CirclePlus; button.
2. Insert a `Class.SurfaceAppearance` from the contextual menu.
<img src="../../assets/studio/explorer/MeshPart-SurfaceAppearance.png" width="320" alt="A SurfaceAppearance object parented within a MeshPart in Studio's Explorer window." />
When you're ready to add texture maps to the `Class.SurfaceAppearance` object, you can click each map property in the [Properties](../../studio/properties.md) window and enter an asset ID.
## Texture maps
Studio currently supports 4 types of PBR texture maps: [color](#color-albedo), [normal](#normal), [roughness](#roughness), and [metalness](#metalness). Each of these maps correspond to an important aspect of the object's surface appearance. Texture maps only change visual appearance and don't affect the geometry of the `Class.MeshPart` object.
<Alert severity = 'warning'>
Avoid adjusting material values to look better in one specific lighting situation. You should base your material values on the physical characteristics and test and iterate to achieve a result that remains visually accurate in various lighting environments.
</Alert>
See the following examples for an overview of Roblox's supported texture maps and additional resources:
<Tabs>
<TabItem label="Color">
The `Class.SurfaceAppearance.ColorMap|ColorMap` property sets the color data of the surface, including any transparency present in the map. See [color&nbsp;(albedo)](#color-albedo) for additional information.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-ColorMap.jpg" alt="A completely filled image, mostly red with various black splotches and white scratches."/>
<figcaption>Example map</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-ColorMap-Before.jpg" alt="A blank white sphere with a dark background."/>
<figcaption>Example mesh</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-ColorMap-After.jpg" alt="A red sphere with black splotches and white scratches with a dark background."/>
<figcaption>Mesh and texture</figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Normal">
The `Class.SurfaceAppearance.NormalMap|NormalMap` texture property defines the topography of the surface allowing you to add visual textures such as bumps, dents, or cracks to your surface. See [normal](#normal) for additional information.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-NormalMap.jpg" alt="A completely filled image, mostly cyan with streaks and bumps across the surface giving the impression of a tactile surface." />
<figcaption>Example map</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-NormalMap-Before.jpg" alt="A blank teal sphere with a dark background."/>
<figcaption>Example mesh</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-NormalMap-After.jpg" alt="A teal sphere with tactile streaks and bumps across the surface."/>
<figcaption>Mesh and texture</figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Roughness">
The grayscale `Class.SurfaceAppearance.RoughnessMap|RoughnessMap` texture property defines the smoothness of the surface, allowing for a glossy or matte visual appearance. See [roughness](#roughness) for additional information.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-RoughnessMap.png" alt="A completely filled image of black diamond shapes over a light grey background."/>
<figcaption>Example map</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-RoughnessMap-Before.jpg" alt="A blank purple sphere with a dark background."/>
<figcaption>Example mesh</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-RoughnessMap-After.jpg" alt="A purple sphere that has glossy diamond shapes over its surface."/>
<figcaption>Mesh and texture</figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Metalness">
The grayscale `Class.SurfaceAppearance.MetalnessMap|MetalnessMap` texture property defines the metallic visual properties of the surface. See [metalness](#metalness) for additional information.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-MetalnessMap.jpg" alt="A completely filled image with a completely black border and scratch-like streaks revealing a white center."/>
<figcaption>Example map</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-MetalnessMap-Before.jpg" alt="A blank light blue sphere with a dark background."/>
<figcaption>Example mesh</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-MetalnessMap-After.jpg" alt="A light blue sphere with parts of its surface looking scratched. The scratched areas reveal a metal-ness quality that is more reflective."/>
<figcaption>Mesh and texture</figcaption>
</figure>
</GridContainer>
</TabItem>
</Tabs>
<Alert severity = 'info'>
For technical details on texture file requirements, see [texture requirements](../../art/modeling/texture-specifications.md).
</Alert>
### Color (albedo)
The **color**, or **albedo**, map determines the color of your texture and consists of mostly color information with little to no lighting or textural information. For additional customization, you can also add [transparency](#alpha-modes) in your albedo texture by adding opacity to your image map.
<Alert severity = 'info'>
While albedo maps and generic [non-PBR texture maps](../../parts/textures-decals.md), commonly known as **diffuse maps**, contain very similar base color data for a surface, diffuse maps often include shading and lighting values to imitate a specific visual element that are more effectively handled by PBR's [normal](#normal), [roughness](#roughness), and [metalness](#metalness) maps. Using a typical diffuse map instead of an albedo map may often look incorrect when the lighting doesn't match with these added baked-in texture elements.
</Alert>
#### Alpha modes
For objects that require partial or complete sections of transparency, such as grass, leaves, lace, or decals like dirt or grunge, you can use various **alpha modes** to apply transparency to your color map. If your color map image format supports alpha channels, you can apply a grayscale alpha map where `0.0` is transparent and `1.0` is opaque. Similarly, when using an image format such as a `.png`, any opacity on the color map applies as transparency on the asset.
You can apply transparency in two different behaviors by setting the following `Class.SurfaceAppearance.AlphaMode|AlphaMode` values:
- [Overlay](#overlay) — Overlays the `Class.SurfaceAppearance.ColorMap|ColorMap` over the underlying mesh's `Class.MeshPart.Color`. Color maps using **Overlay** reveal the base color of the mesh anywhere transparency is present. This is the default setting.
- [Transparency](#alpha-modes) — Removes the visible mesh based on transparency in the `ColorMap`. This renders the mesh see-through and does not reveal the original mesh color whenever transparency is present.
- [TintMask](#tintmask) — Blends the tinted `Class.SurfaceAppearance.ColorMap|ColorMap` over the un-tinted `Class.SurfaceAppearance.ColorMap|ColorMap`.
##### Overlay
You can use **Overlay** to reveal sections of the mesh's original color. Since the transparent areas of the color map expose the underlying color, you can design a unique texture map that partially or fully reveals the mesh's `Class.MeshPart.Color|Color` property for custom skin tones or other situations with unique colors.
The following example demonstrates how the **Overlay** mode works using a white sphere reference:
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-ColorMap.png" alt="A completely filled image of a semi-repeating pattern with 8 by 8 small light blue squares. The background is checkered to indicate transparency."/>
<figcaption>Example color/albedo map with transparency</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-ColorMap-Before.jpg" alt="A blank white sphere over a dark background."/>
<figcaption>Example mesh object (white)</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-Overlay.jpg" alt="A white sphere with small blue squares scattered over the surface."/>
<figcaption>`Class.SurfaceAppearance.AlphaMode|AlphaMode` set to **Overlay** using reference map and material</figcaption>
</figure>
</GridContainer>
The following example uses the **Overlay** mode for custom characters, revealing the character's original skin-tone:
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/surface-appearance/Custom-Skin-Tone-Map.png" width = "73%" alt="A completely filled image of a texture map for a 3D humanoid model. Various parts of the image is checkered or partially checkered to indicate varying levels of transparency."/>
<figcaption>Color map containing transparency in sections to expose the original mesh color</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Custom-Skin-Tone-Example.png" alt="Four of the same humanoid models with different skin tones: light brown, black, white, dark green."/>
<figcaption>Several variations of characters with a single color map using **Overlay** mode</figcaption>
</figure>
</GridContainer>
See [custom skin tone](../../art/characters/specifications.md#custom-skin-tone) for additional details on optimizing an overlay for skin and similar applications.
##### Transparency
You can use the **Transparency** mode to create complex or extremely fine objects, such as lace or netting, by removing visible parts of the mesh as an alternative to sculpting the mesh geometry. Since this does not affect the geometry of the mesh object, this can allow you to create detailed objects without the performance impact of an intricate mesh model.
The following example demonstrates how a partial and full transparency in this mode visually removes sections of the mesh:
<Tabs>
<TabItem label="Sample Meshes">
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Opacity-0.png" alt="A sphere with a basket-like surface."/>
<figcaption><center>No transparency</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Opacity-Half.png" alt="A sphere with regular triangular patterns on its surface partially invisible." />
<figcaption><center>Half transparency in sections</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Opacity-1.png" alt="A sphere with regular triangular patterns on its surface completely invisible."/>
<figcaption><center>Full transparency in sections</center></figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Image Maps">
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/OpacityTexture-0.png" alt="A completely filled image of a thatched basket-like surface."/>
<figcaption><center>No transparency</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/OpacityTexture-Half.png" alt="A completely filled image with a thatched basket-like surface with a regular triangle pattern partially transparent."/>
<figcaption><center>Half transparency in sections</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/OpacityTexture-1.png" alt="A completely filled image with a thatched basket-like surface with a regular triangle pattern fully transparent."/>
<figcaption><center>Full transparency in sections</center></figcaption>
</figure>
</GridContainer>
</TabItem>
</Tabs>
There are two outcomes of `Enum.AlphaMode|Transparency` mode, depending on whether the `Class.MeshPart.Transparency` is set to `0` or **at&nbsp;least** `0.02`, although numerical precision may result in small values such as `0.01` triggering the opaque transparency.
- When alpha is used to cut out the shape of mostly opaque objects with hard edges such as foliage, lace fabric, and netting, set the `Class.MeshPart.Transparency` to `0`. When parts of the surface are fully opaque, the Roblox engine can render them with proper depth‑based occlusion. Opaque surfaces also generally work better with depth‑based effects like `Class.DepthOfFieldEffect`, glass and water refraction, and water reflection.
- When alpha is used to add detail to semi‑transparent objects or objects with smooth gradients of transparency, set the `Class.MeshPart.Transparency` to **at&nbsp;least** `0.02`. This improves the quality of blending for objects such as dirty windows and soft‑edged feathers, but it will not work with all effects.
##### TintMask
You can use the `Enum.AlphaMode.TintMask` mode to apply `Class.SurfaceAppearance.Color` tinting to selective areas of a surface. The tinting is strongest where the alpha channel is fully visible and not applied where the alpha channel is transparent.
<Tabs>
<TabItem label="ColorMap RGB">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-TintMask-Bricks-Albedo.jpg" width="50%" alt="A warm, light colored brick texture with darker grey textured grout between the bricks." />
<div style={{width: '50%'}}>
<figcaption>Example brick texture, showing the color detail on brick faces as well as in the grout between the bricks.</figcaption>
</div>
</figure>
</TabItem>
<TabItem label="ColorMap Alpha">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-TintMask-Bricks-Alpha.jpg" width="50%" alt="A monochrome brick texture showing white in the brick face areas and solid black in between the bricks." />
<div style={{width: '50%'}}>
<figcaption>Example brick texture alpha, with areas of the brick faces opaque (white) and the grout areas in between bricks transparent (black).</figcaption>
</div>
</figure>
</TabItem>
<TabItem label="Example Results">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-TintMask-Bricks.jpg" width="50%" alt="Four square panels with a brick texture arranged in a vertical stack. They are tinted blue, yellow, purple, and red." />
<div style={{width: '50%'}}>
<figcaption>Example brick texture with four different tint colors applied. The tint is affecting only the raised brick faces and not the grout between them.</figcaption>
</div>
</figure>
</TabItem>
</Tabs>
<Alert severity="info">
When creating `Class.SurfaceAppearance.ColorMap` textures for use with a tint mask, preserve color in the transparent regions and turn off options such as pre-multiplied alpha that darken the color in transparent areas. The alpha values can also be semi-transparent to apply a partial tint to areas of the texture.
</Alert>
#### Color tinting
You can apply a tint to your color map by modifying the `Class.SurfaceAppearance.Color` property. Tinting does not affect performance and you can save on memory by reusing a single color map with different tints. Use color tinting to create additional low-cost variation between your `Class.MeshPart` PBR textures or to programmatically modify your PBR surface colors in real-time.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Tinting-None.png" alt="A statue with a default yellow tint and reflective jade-like properties."/>
<figcaption>Statue mesh from [The Mystery of Duvall Drive](../../resources/the-mystery-of-duvall-drive/index.md) with no tinting.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Tinting-Red.png" alt="A statue with a red tint and continues to have a shiny reflective properties from its other texture maps."/>
<figcaption>Statue mesh with `Class.SurfaceAppearance.Color|Color` set to red.</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Tinting-Green.png" alt="A statue with a green tint and continues to have a shiny reflective properties from its other texture maps."/>
<figcaption>Statue mesh with `Class.SurfaceAppearance.Color|Color` set to green.</figcaption>
</figure>
</GridContainer>
`Class.SurfaceAppearance.Color` tinting applies as a multiplier, so the final appearance is a function of `Datatype.Color3` (texel color) times `Class.SurfaceAppearance.Color`. This means that authoring your original `Class.SurfaceAppearance.ColorMap` in near-white grayscale colors creates the strongest tinting effect when this property is applied.
Tinting only applies to the `Class.SurfaceAppearance.ColorMap` and not the `Class.MeshPart.Color`. You can continue to use alpha channels when applying [transparency](#transparency).
When `Class.SurfaceAppearance.AlphaMode` is set to `Enum.AlphaMode|Overlay` and an alpha channel is present, the underlying `Class.MeshPart.Color` is revealed and `Class.SurfaceAppearance.Color` tinting only applies to the visible `Class.SurfaceAppearance` color map.
When `Class.SurfaceAppearance.AlphaMode` is set to `Enum.AlphaMode|TintMask` and an alpha channel is present, the alpha channel controls the amount of `Class.SurfaceAppearance.Color` tinting. The tinting is strongest where the alpha channel is fully visible and not applied where the alpha channel is transparent.
<Tabs>
<TabItem label="Transparency AlphaMode">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-Gradient-Transparency.jpg" width="50%" alt="A floating square plane with a cyan slate texture, that gradually changes from fully transparent on the left to fully opaque on the right. A thin horizontal bar below the floating plane has a gradient with black on the left and white on the right."/>
<div style={{width: '50%'}}>
<figcaption>`Class.SurfaceAppearance.AlphaMode|AlphaMode` set to `Enum.AlphaMode|Transparency`. The greyscale gradient bar at the bottom indicates the alpha value. `Class.MeshPart.Color` is set to red and `Class.SurfaceAppearance.Color` is set to cyan.</figcaption>
</div>
</figure>
</TabItem>
<TabItem label="Overlay AlphaMode">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-Gradient-Overlay.jpg" width="50%" alt="A floating square plane that gradually turns from a solid red color on the left to a cyan slate texture on the right. A thin horizontal bar below the floating plane has a gradient with black on the left and white on the right."/>
<div style={{width: '50%'}}>
<figcaption>`Class.SurfaceAppearance.AlphaMode|AlphaMode` set to `Enum.AlphaMode|Overlay`. The greyscale gradient bar at the bottom indicates the alpha value. `Class.MeshPart.Color` is set to red and `Class.SurfaceAppearance.Color` is set to cyan.</figcaption>
</div>
</figure>
</TabItem>
<TabItem label="TintMask AlphaMode">
<figure>
<img src="../../assets/modeling/surface-appearance/SurfaceAppearance-AlphaMode-Gradient-TintMask.jpg" width="50%" alt="A floating square plane that gradually turns from a white slate texture on the left to a cyan slate texture on the right. A thin horizontal bar below the floating plane has a gradient with black on the left and white on the right."/>
<div style={{width: '50%'}}>
<figcaption>`Class.SurfaceAppearance.AlphaMode|AlphaMode` set to `Enum.AlphaMode|TintMask`. The greyscale gradient bar at the bottom indicates the alpha value. `Class.MeshPart.Color` is set to red and `Class.SurfaceAppearance.Color` is set to cyan. Tint masking is not affected by `Class.MeshPart.Color`.</figcaption>
</div>
</figure>
</TabItem>
</Tabs>
### Normal
The **normal**, or **surface**, map adds texture depth to your surface and behaves similarly to a [height map](../../parts/terrain.md#heightmaps). As a result, the effect may fade or intensify depending on the viewing angle and lighting environment. When a normal map is not present, the value is set to `0.0`.
In the following figure, you can switch between the mesh reference and the map reference for comparisons of normal map values:
<Tabs>
<TabItem label="Sample Meshes">
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-0.png" alt="A clay colored smooth sphere."/>
<figcaption><center>0.0</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-Half.png" alt="A clay colored sphere with a moderately rocky surface."/>
<figcaption><center>0.5</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-1.png" alt="A clay colored sphere with an extremely rocky surface"/>
<figcaption><center>1.0</center></figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Image Maps">
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-Map-0.png" alt="A completely filled teal image."/>
<figcaption><center>0.0</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-Map-Half.png" alt="A completely filled teal image with a moderate amount of surface aberrations in slightly lighter and darker shades"/>
<figcaption><center>0.5</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Normal-Map-1.png" alt="A completely filled teal image with a heavy amount of surface aberrations in slightly lighter and darker shades"/>
<figcaption><center>1.0</center></figcaption>
</figure>
</GridContainer>
</TabItem>
</Tabs>
The **R**, **G**, and **B** channels of the image correspond respectively to the **X**, **Y**, and **Z** components of the local surface vector. A uniform image of color <Typography noWrap>`[127, 127, 255]`</Typography> translates to a completely flat normal map. Roblox only supports **OpenGL format - Tangent Space** normal maps.
Normal maps prominently affect the visual surface of a mesh and can accentuate awkward seams in your texture. Whenever possible, keep your texture seams hidden to avoid visual issues with your mesh.
### Roughness
**Roughness**, or **microsurface**, maps determine how light is spread across your model's surface. When roughness is at `0.0`, the surface doesn't scatter light at all, resulting in a much sharper and brighter reflection and glossiness on your material. At `1.0`, light and reflections evenly scatter over the model resulting in a less reflective matte-like surface.
Roughness may impact how reflective an object is at different angles, referred to as the **Fresnel** effect. See [fresnel](#fresnel) for more details and best-practices to maintain consistent reflective behavior.
The following figure shows comparisons of various roughness map values:
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Roughness-0.png" alt="A blue glossy sphere with a legend indicating the roughness map is completely black." />
<figcaption><center>0.0</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Roughness-Half.png" alt="A blue semi-glossy sphere with a legend indicating the roughness map is exactly grey."/>
<figcaption><center>0.5</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Roughness-1.png" alt="A blue matte sphere with a legend indicating the roughness map is completely white."/>
<figcaption><center>1.0</center></figcaption>
</figure>
</GridContainer>
<Alert severity = 'info'>
Various combinations of the roughness and metalness can represent almost every possible real-world material surface. See [material references](../../art/modeling/material-reference.md) for examples and references of how combinations of material values can create various surface appearances.
</Alert>
#### Fresnel
**Fresnel** refers to the amount of reflection of a surface in reference to the current viewing angle. Studio's Fresnel processing aims for physical real-world accuracy, although you may get unexpected specular contribution at certain angles even with rough surfaces. In some cases, you can compensate by making your roughness map around `0.1` more rough to achieve a consistent lighting response with your materials.
Even though Roblox renders this lighting effect accurately, the brightness and reflectivity of a surface may not respond consistently between your texture content creating software, such as Substance Painter, and Studio. See [clothing examples](../../art/modeling/material-reference.md#clothing-examples) for differences in rendering between applications.
### Metalness
**Metalness** determines the reflectivity of a surface. Metalness values range between `0.0` and `1.0`. Roblox sets the default value to `0.0` if a metalness map is not present.
See the following figure for comparisons of various metalness map values:
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/surface-appearance/Metalness-0.png" alt="A brown sphere with light splotches. A legend indicates the metalness map is completely black."/>
<figcaption><center>0.0</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Metalness-Half.png" alt="A brown sphere with light splotches and some reflectiveness. A legend indicates the metalness map is exactly grey."/>
<figcaption><center>0.5</center></figcaption>
</figure>
<figure>
<img src="../../assets/modeling/surface-appearance/Metalness-1.png" alt="A brown sphere with moderate splotches and lots of reflectiveness. A legend indicates the metalness map is completely white."/>
<figcaption><center>1.0</center></figcaption>
</figure>
</GridContainer>
Different PBR renderers use various workflows for processing reflectiveness. Studio only uses the **metalness workflow** which determines whether a material is a **nonmetal** or a **metal**, sometimes referred to as an **insulator** or **conductor**.
In most cases, you should set this value to either `0.0` (non-metal) or `1.0` (metal). You can use partial metalness values when creating more uncommon surfaces with moderate reflective properties, like satin or silk. This practice can subtly fake the reflections in the material to highlight the color from the [color/albedo map](#color-albedo) over colors reflected in the environment.
<Alert severity = 'info'>
Various combinations of the roughness and metalness can represent almost every possible real-world material surface. See [material references](../../art/modeling/material-reference.md) for examples and references of how combinations of material values can create various surface appearances.
</Alert>

215
.cursor/rules/roblox/art/modeling/texture-specifications.md Normal file
View file

@ -0,0 +1,215 @@
---
title: Texture specifications
description: Texture Specifications lists the specific technical requirements and best practices for custom textures created outside of Studio.
---
A texture is a digital image applied to the surface of a 3D object to simulate and enhance its visual appearance. Roblox supports various texture types that you import with a custom 3D object, or upload directly as individual image files. For details on implementing basic textures, see [Textures and decals](../../parts/textures-decals.md).
Roblox also supports [physically-based rendering (PBR) textures](../../art/modeling/surface-appearance.md) which override a mesh's existing `Class.MeshPart.TextureID|TextureID` and can be used to create immersive environments and objects.
<Alert severity = 'info'>
For information on how to properly connect textures to your model in Blender and Maya for import into Studio, see [Blender / Maya texture settings](./assign-textures.md).
</Alert>
See the following requirements when creating your own basic and advanced textures:
- **File formats** — File formats for textures that are uploaded separately in Studio must be submitted as a `.png`, `.jpg`, `.tga`, or `.bmp`.
- **Resolution** — Roblox supports up to 4096x4096 pixel texture resolutions (4K). As an experience loads, the engine automatically starts with lower quality versions of the texture and ramps up quality based on device resources. Even still, manually sizing textures before you upload them can improve memory usage in some situations. Consider the following general guidance:
- For smaller 5×5 stud objects, use 256×256 texture resolutions.
- For medium 10×10 stud objects, use 512×512 texture resolutions.
- For larger 20×20 stud objects, use 1024×1024 texture resolutions.
- See [PBR texture budgets](#surfaceappearance) for similar guidances with PBR texture maps.
- **Single material** - Mesh objects can only have one material assigned.
<Alert severity ='info'>
Roblox default [materials](../../parts/materials.md) follow a similar texel resolution pattern:
- Parts display a 1024×1024 on an 8×8 stud face.
- Terrain displays 512×512 across 8×8 studs.
</Alert>
## SurfaceAppearance
You can add a [surface appearance](../../art/modeling/surface-appearance.md) to your mesh in Studio to add PBR texture options. The `Class.SurfaceAppearance` instance uses UV mapping, a form of texture mapping, to accurately map up to four 2D images onto the mesh object.
<Alert severity = 'info'>
For information on how to properly connect PBR textures to your model in Blender and Maya for import into Studio, see [Blender / Maya texture settings](./assign-textures.md).
</Alert>
See the following requirements for `Class.SurfaceAppearance` assets:
- **Texture files** — Ensuring your textures follow consistent conventions optimizes assets for tools like the [3D Importer](../../art/modeling/3d-importer.md) and helps with organization. When possible, texture files should include the appropriate name affix and follow the appropriate image details:
<table>
<thead>
<tr>
<th>Texture type</th>
<th>Texture schema suffix</th>
<th>Texture image details</th>
</tr>
</thead>
<tbody>
<tr>
<td>Albedo</td>
<td>_ALB</td>
<td>RGB (24-bit)</td>
</tr>
<tr>
<td>Metalness</td>
<td>_MET</td>
<td>Single Channel Grayscale (8-bit)</td>
</tr>
<tr>
<td>Normal</td>
<td>_NOR</td>
<td>RGB (24-bit) - Roblox only supports **OpenGL format - Tangent Space** normal maps.</td>
</tr>
<tr>
<td>Roughness</td>
<td>_RGH</td>
<td>Single Channel Grayscale (8-bit)</td>
</tr>
</tbody>
</table>
- **PBR Texture Budget** — Use an appropriate texture map size based on the asset you are texturing to optimize for visual quality and performance. As a general guideline, each asset should have a texture resolution of 256×256 for every 2×2×2 unit space the asset occupies. If larger than a 2×2×2 cube, use the next highest resolution. The following are some baseline texture sizing examples:
<table>
<thead>
<tr>
<th>Recommended map size</th>
<th>Approximate asset size (unit cube)</th>
<th>Example assets</th>
</tr>
</thead>
<tbody>
<tr>
<td>64×64 - 128×128</td>
<td>1×1×1</td>
<td>Jewelry, sunglasses, eyebrows, mustaches.</td>
</tr>
<tr>
<td>256×256</td>
<td>2×2×2</td>
<td>Hair, shoes, tank tops, t-shirts, shorts, short skirts. <br/><br/>256x256 is the **maximum budget** for non-albedo maps (RGH, MTL, NOR) for [rigid accessories](../accessories/specifications.md#textures).</td>
</tr>
<tr>
<td>512×512</td>
<td>4×4×4</td>
<td>Jackets, pants, overalls, long-sleeve shirts, long skirts.</td>
</tr>
<tr>
<td>1024×1024 (maximum)</td>
<td>8×8×8</td>
<td>Full body clothing (onesies, robes), humanoid characters.</td>
</tr>
</tbody>
</table>
<Alert severity = 'info'>
When rendering many textures at the same time, Roblox may downsample textures to optimize for performance.
</Alert>
## UV mapping
All textures use UV mapping, a 3D modeling process to project a 3D model's surface to a 2D image, or UV atlas. See the following requirements for UV mapping, especially if you're manually editing or optimizing your UV atlas:
- **Single UV Set** — Use a single UV set for each component, such as a humanoid or accessory. Studio doesn't allow for multiple UV sets.
- **Coordinates** — All UVs must be created within a 0:1 space.
- **Overlaps** — Overlapping UVs are allowed.
- **Maximum Texture Resolution** — Roblox supports up to 1024×1024 pixel spaces for texture maps. See [Optimizations](#optimizations) for more details on efficiently texturing your assets.
### Optimizations
Studio's UV compositor allows you to pack and size your UVs to best suit your needs because it can detect and repackage UVs for performance and storage efficiency. The compositor looks to each component of the model, such as a character (arms, legs, torso, head), and repackages and loads the UVs as needed when in-experience changes occur, such as swapping body parts.
Especially with character models and other advanced models, optimizing your UV layouts can help prevent texture issues, save loading time, and improve performance. Keep in mind the following best practices for optimizing your UV islands for Roblox's UV compositor:
- **Pixel space** — Studio's texture compositor repacks UVs by breaking up the following pixel spaces:
- **1024×1024** pixel space into **64×64 16 pixel** blocks.
- **512×512** pixel space into **32×32 16 pixel** blocks.
- **256×256** pixel space into **16×16 16 pixel** blocks.
<GridContainer numColumns="3">
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV_Grid_1024.png" width = "100%"/>
<figcaption>1024×1024 UV example</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV_Grid_512.png" width = "100%"/>
<figcaption>512×512 UV example</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV_Grid_256.png" width="100%" />
<figcaption>256×256 UV example</figcaption>
</figure>
</GridContainer>
- **Avoid Sharing 16 Pixel Blocks** — To maximize your UV space and the resolution of your model, keep all UV islands within these 16 pixel blocks when possible, and do not let two UV islands share the same 16 pixel block.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV-Layout-Poor.png" width = "100%"/>
<figcaption>
<Alert severity='error'>
<AlertTitle>Inefficient UV Layout</AlertTitle>
UV islands share blocks in the same 16 pixel grid. The compositor treats this as one large group.
</Alert>
</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV-Layout-Optimized.png" width="100%" />
<figcaption>
<Alert severity='success'>
<AlertTitle>Optimized UV Layout</AlertTitle>
UV islands are near each other but do not share any blocks on the 16 pixel grid. The compositor treats these as separate groups.
</Alert>
</figcaption>
</figure>
</GridContainer>
- **Use Smaller Islands** — When possible, use smaller islands to simplify layout and packing. This can help prevent a UV island for one body part incorrectly applying to another as the compositor can't differentiate the islands.
<GridContainer numColumns="2">
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV-Island-Poor.png" width = "100%"/>
<figcaption>
<Alert severity='error'>
<AlertTitle>Inefficient UV Island</AlertTitle>
Several UV islands overlap into other island spaces on the 16 pixel grid. The compositor treats them as a single large object and may not optimize efficiently.
</Alert>
</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/UV-Island-Optimized.png" width="100%" />
<figcaption>
<Alert severity='success'>
<AlertTitle>Optimized UV Islands</AlertTitle>
By using smaller islands, none of the UV islands overlap on 16 pixel blocks. The compositor can easily identify them as smaller block groups to repack efficiently.
</Alert>
</figcaption>
</figure>
</GridContainer>
By optimizing your UV layouts, you can prevent unexpected texture conflicts, save space, and improve performance. The following is an example of how Studio's compositor can process the same character body UV layouts with and without optimizations:
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Compositor-Example-Poor.png" width = "100%"/>
<figcaption>
<Alert severity='error'>
<AlertTitle>Texture Repacking with Inefficient UV</AlertTitle>The islands share too many of the same 16 pixel blocks and causes the compositor to combine many islands as one. In this example, the compositor incorrectly packs the island for the torso area by including several other islands as well.
</Alert>
</figcaption>
</figure>
<figure>
<img src="../../assets/modeling/meshes/mesh-requirements/Compositor-Example-Optimized.png" width="100%" />
<figcaption>
<Alert severity='success'>
<AlertTitle>Texture Repacking with Optimized UV</AlertTitle>The islands do not share any 16 pixel blocks and allows the compositor to correctly identify each island. This ensures that the compositor correctly packs the island specifically for the required part and prevents unnecessary UV space from being saved and repacked.
</Alert>
</figcaption>
</figure>