hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-25 13:31:37 +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

288
.cursor/rules/roblox/parts/index.md Normal file
View file

@ -0,0 +1,288 @@
---
title: Parts
description: Parts are Roblox's primary building blocks.
---
`Class.Part|Parts` are descendants of the `Class.BasePart` class and are Roblox's
primitive building blocks with properties like position, size, orientation, and
color. You can use basic parts as is, or you can apply [solid
modeling](/parts/solid-modeling) operations to combine parts into more complex
shapes.
For advanced and intricate 3D models, you can also import third-party model
files as `Class.MeshPart|MeshParts` as outlined in [Meshes](../parts/meshes.md).
<GridContainer numColumns="3">
<figure>
<img src="../assets/modeling/parts/Basic-Part-Sphere.png" alt="A single gray sphere part" />
<figcaption>Basic sphere part</figcaption>
</figure>
<figure>
<img src="../assets/modeling/parts/Part-Example-CSG.jpg"alt="A bright blue hollow bowl that was made with solid modeling operations."/>
<figcaption>Bowl created with solid modeling</figcaption>
</figure>
<figure>
<img src="../assets/modeling/parts/Mesh-Example.jpg" alt="A high-quality treasure chest mesh with a texture." />
<figcaption>Mesh with texture</figcaption>
</figure>
</GridContainer>
By default, parts are rigid bodies that follow real-world physical mechanics,
including gravity, collision, and momentum. You can connect related parts
together as a single [assembly](../physics/assemblies.md) using a
`Class.WeldConstraint`, or a joint like `Class.Motor6D` or `Class.Bone`. As an
assembly, the connected parts act as a single rigid entity, referencing a common
position, orientation, and scale.
You can use a `Class.Model` container to group related parts together and access
the group as a single assembly in the [Explorer](../studio/explorer.md). See
[Models](../parts/models.md) for more information.
## Basic part types
`Class.Part` objects can take the shape of blocks, spheres, cylinders, wedges, or corner wedges. In addition, `Class.TrussPart` acts as a truss beam that characters can climb like a ladder.
<Grid container spacing={1}>
<Grid item XSmall={4} XLarge={2}>
<figure>
<img src="../assets/modeling/parts/Basic-Part-Block.png" alt="A single Block part." />
<figcaption><center>Block</center></figcaption>
</figure>
</Grid>
<Grid item XSmall={4} XLarge={2}>
<figure>
<img src="../assets/modeling/parts/Basic-Part-Sphere.png" alt="A single Sphere part." />
<figcaption><center>Sphere</center></figcaption>
</figure>
</Grid>
<Grid item XSmall={4} XLarge={2}>
<figure>
<img src="../assets/modeling/parts/Basic-Part-Cylinder.png" alt="A single Cylinder part." />
<figcaption><center>Cylinder</center></figcaption>
</figure>
</Grid>
<Grid item XSmall={4} XLarge={2}>
<figure>
<img src="../assets/modeling/parts/Basic-Part-Wedge.png" alt="A single Wedge part." />
<figcaption><center>Wedge</center></figcaption>
</figure>
</Grid>
<Grid item XSmall={4} XLarge={2}>
<figure>
<img src="../assets/modeling/parts/Basic-Part-Corner-Wedge.png" alt="A single Corner Wedge part." />
<figcaption><center>Corner Wedge</center></figcaption>
</figure>
</Grid>
</Grid>
## Part properties
Each part has a variety of properties that you can customize through the [Properties](../studio/properties.md) window.
<img src="../assets/studio/properties/Sections-Example.png" alt="A close up view of the Properties window with the Appearance and Transform properties highlighted." width="320" />
The following are commonly utilized properties:
- `Class.BasePart|Anchored` controls if physics affects the position of the part. When this property is set to true, the part never changes position due to gravity or any other force. You should anchor most parts in your experience or gravity and physics will affect your parts as soon as the experience runs.
<Alert severity="success">
To view lighted outlines around the base of anchored parts in order to visualize which parts cannot move under gravity or physics, toggle on **Anchored&nbsp;parts** from the [Visualization&nbsp;Options](../studio/ui-overview.md#visualization-options) widget in the upper‑right corner of the 3D viewport.
</Alert>
- `Class.BasePart|CanCollide` controls whether or not a part can collide with other parts. When this property is set to true, the part is impenetrable and the physics engine accounts for it within your experience. Conversely, when this property is set to false, the part can pass through anything, and the physics engine does **not** account for it.
- `Class.BasePart|Transparency` sets a part's visibility to any value between the default value of 0 (fully visible) and 1 (fully transparent). If you have many partially transparent parts, they can slow down performance. To alleviate this, merge them using [solid modeling](../parts/solid-modeling.md).
## Insert parts
The **Part** insertion button, accessible from the **Home** and **Model** tab toolbars, inserts a new part into the workspace. Click‑holding over the small corner arrow on the button lets you select either **Block**, **Sphere**, **Wedge**, **Corner&nbsp;Wedge**, or **Cylinder**.
<img src="../assets/studio/general/Toolbar-Insert-Part-Widget.png" width="800" alt="Part tool and its part type picker menu." />
<Alert severity="info">
To insert a `Class.TrussPart` (not available on the insertion menu), use the [Explorer](../studio/explorer.md) as outlined [here](../studio/explorer.md#insert-and-parent).
</Alert>
## Select parts
As you hover over parts in the 3D viewport, they are outlined to indicate their potential selection. You can select an outlined part by clicking it, or you can select multiple parts by holding <kbd>Shift</kbd>, <kbd>Ctrl</kbd>, or <kbd>⌘</kbd> as you hover over and click them. See [here](../studio/ui-overview.md#object-selection) for advanced methods of selecting parts in the viewport.
<img src="../assets/studio/general/Editor-Window-Object-Selection.jpg" width="800" alt="Multiple models selected in 3D viewport"/>
## Transform parts
You can move, scale, and rotate selected parts either through modeling tools or by setting a new position, size, or orientation in the [Properties](#part-properties) window.
<img src="../assets/studio/general/Toolbar-Transform-Tools.png" width="800" alt="Transform tools indicated in Studio's toolbar." />
<GridContainer numColumns="3">
<figure>
<img src="../assets/modeling/parts/Transform-Move-SM.png" alt="Move draggers shown on part in 3D viewport." />
<figcaption>Move</figcaption>
</figure>
<figure>
<img src="../assets/modeling/parts/Transform-Scale-SM.png" alt="Scale draggers shown on part in 3D viewport." />
<figcaption>Scale</figcaption>
</figure>
<figure>
<img src="../assets/modeling/parts/Transform-Rotate-SM.png" alt="Rotate draggers shown on part in 3D viewport." />
<figcaption>Rotate</figcaption>
</figure>
</GridContainer>
When using the tools, you can move, scale, or rotate parts in either **world** orientation or **local** orientation by pressing <kbd>Ctrl</kbd><kbd>L</kbd> on Windows or <kbd>⌘</kbd><kbd>L</kbd> on Mac. When you enable local orientation,
the arrow axis indicators change to a part's local orientation, and an **L** indicator displays.
<Tabs>
<TabItem label="World">
<img src="../assets/modeling/parts/Move-World-Orientation.png" width="720" height="405" alt="An angled block part with draggers in World orientation mode." />
</TabItem>
<TabItem label="Local">
<img src="../assets/modeling/parts/Move-Local-Orientation.png" width="720" height="405" alt="An angled block part with draggers in Local orientation mode." />
</TabItem>
</Tabs><br />
Tool transform **snapping** increments are based on **studs** for moving/scaling or **degrees** for rotating, each adjustable in the toolbar. While transforming, you can temporarily toggle snapping by holding the <kbd>Shift</kbd> key.
<img src="../assets/studio/general/Toolbar-Transform-Snapping.png" width="800" alt="Transform snapping tools indicated in Studio's toolbar." />
<Alert severity="info">
To quickly jump to the **move/scale** increment input, press <kbd>Shift</kbd><kbd>2</kbd>. To quickly jump to the **rotate** increment input, press <kbd>Alt</kbd><kbd>R</kbd> (Windows) or <kbd>⌥</kbd><kbd>R</kbd> (Mac).
</Alert>
### Move
You can move a selected part to a new position using the **Move** tool (default shortcut <kbd>2</kbd>) or by **cursor&nbsp;dragging**. While moving a part, you can temporarily toggle snapping by holding <kbd>Shift</kbd>.
<Tabs>
<TabItem label="Move Tool">
To move a part by an axis dragger along the **X**, **Y**, or **Z** axis, click/drag an arrow pointing along the desired axis of movement.
<img src="../assets/modeling/parts/Transform-Move.png" width="720" alt="A block part with the Move tool's visual aids." />
After releasing the drag, the numerical **distance indicator** remains visible. If desired, fine‑tune the distance that was moved by clicking inside the indicator and entering any number.
<img src="../assets/modeling/parts/Transform-Move-Indicator.png" width="720" alt="A moved part showing the distance moved in an indicator/input field" />
If you drag a part by its [pivot](../studio/pivot-tools.md) point while the **Move** tool is selected, the pivot will "soft&nbsp;snap" to surfaces and edges of nearby parts.
<img src="../assets/modeling/parts/Transform-Move-Pivot-Snap.png" width="720" alt="A block part with an offset pivot soft-snapping to the surface of a nearby part." />
</TabItem>
<TabItem label="Cursor Drag">
To move a part by cursor dragging, click anywhere on the part to grab it. If snapping is **enabled**, a ruler will appear as you hover, showing what point you'll grab the part by. As you drag the part around, another ruler will appear on the surface/edge of nearby parts, indicating alignment of the grab point.
<img src="../assets/modeling/parts/Transform-Move-Ruler-Snap.png" width="720" alt="A block part showing the grab point and snapping ruler on a neighboring part." />
If snapping is **disabled**, the part will "soft&nbsp;snap" to surfaces and edges of nearby parts.
<img src="../assets/modeling/parts/Transform-Move-Cursor-Drag-Snap.png" width="720" alt="A block part soft-snapping to the corner edges of a neighboring part." />
While cursor dragging, <kbd>T</kbd> and <kbd>R</kbd> can be used to quickly rotate the part in 90&deg; increments around the point you picked it up by. <kbd>T</kbd> tilts the part 90&deg; towards the camera, while <kbd>R</kbd> rotates the part 90&deg; around the normal of the hovered surface.
<img src="../assets/modeling/parts/Transform-Move-Cursor-Drag-T-R.png" width="720" alt="Diagram showing how parts can be tilted and rotated with the T and R keys respectively." />
</TabItem>
</Tabs>
### Scale
To scale (resize) a selected part along the **X**, **Y**, or **Z** axis, use the **Scale** tool (default shortcut <kbd>3</kbd>) and click/drag a handle. While dragging, you can temporarily toggle snapping by holding <kbd>Shift</kbd>.
<img src="../assets/modeling/parts/Transform-Scale.png" width="720" alt="A block part with the Scale tool's visual aids." />
### Rotate
To rotate a selected part around the **X**, **Y**, or **Z** axis, use the **Rotate** tool (default shortcut <kbd>4</kbd>) and click/drag a rotation ring. While dragging, you can temporarily toggle snapping by holding <kbd>Shift</kbd>.
<img src="../assets/modeling/parts/Transform-Rotate.png" width="720" alt="A block part with the Rotate tool's visual aids." />
<Alert severity="info">
In addition to using the **Rotate** tool, you can quickly rotate selected objects 90&deg; about their **X** axis by pressing <kbd>Ctrl</kbd><kbd>T</kbd> (<kbd>⌘</kbd><kbd>T</kbd>) or 90&deg; about their **Y** axis by pressing <kbd>Ctrl</kbd><kbd>R</kbd> (<kbd>⌘</kbd><kbd>R</kbd>).
</Alert>
## Other actions
### Group
You can group objects into a [model](../parts/models.md) by selecting them and clicking the **Group** button. This action has a default shortcut of <kbd>Ctrl</kbd><kbd>G</kbd> (Windows) or <kbd>⌘</kbd><kbd>G</kbd> (Mac).
Alternatively, you can group objects into a [folder](../studio/explorer.md#organizing-by-folders) by click‑holding over the small corner arrow on the button and selecting **Group&nbsp;as&nbsp;Folder** (default shortcut of <kbd>Alt</kbd><kbd>Ctrl</kbd><kbd>G</kbd> or <kbd>⌥</kbd><kbd>⌘</kbd><kbd>G</kbd>).
<img src="../assets/studio/general/Toolbar-Group.png" width="800" alt="Group tool indicated in Studio's toolbar" />
To **ungroup** an existing model or folder, select **Ungroup** from the **Edit** menu (default shortcut of <kbd>Ctrl</kbd><kbd>U</kbd> or <kbd>⌘</kbd><kbd>U</kbd>).
### Anchor
The **Anchor** toggle controls whether the part will be **immovable** by physics. When `Class.BasePart.Anchored|Anchored`, a part will never change position due to gravity, other parts collisions, overlapping other parts, or any other physics-related causes. This action has a default shortcut of <kbd>Alt</kbd><kbd>A</kbd> (Windows) or <kbd>⌥</kbd><kbd>A</kbd> (Mac).
<img src="../assets/studio/general/Toolbar-Anchor.png" width="800" alt="Anchor toggle indicated in Studio's toolbar" />
<Alert severity="info">
If you prefer a click-to-toggle workflow in the 3D viewport, click‑hold over the small corner arrow on the **Anchor** button and enable **Click&nbsp;object&nbsp;to&nbsp;anchor**. Once enabled, the tool operates as a "key" for both states&nbsp;&mdash; clicking on an unanchored object in the viewport anchors it, while clicking on an anchored object unanchors it.
</Alert>
### Color
While a part is gray by default, you can change it to any color through the following methods.
<Tabs>
<TabItem label="Color Button">
Clicking the **Color** button applies the selected color to all selected parts. You can choose a color by click‑holding over the small corner arrow on the **Color** button to reveal a hexagonal picker.
<img src="../assets/studio/general/Toolbar-Color-Picker.png" width="800" alt="Color widget's hexagonal picker." />
<Alert severity="info">
If you prefer a fill/paint workflow in the 3D viewport, enable **Click&nbsp;object&nbsp;to&nbsp;apply&nbsp;color** at the bottom of the hexagonal picker popup and then click parts in the viewport to apply the chosen color.
</Alert>
</TabItem>
<TabItem label="Color Popup">
The **Color** popup allows you to set a color through your operating system's color picker widget. To access it, navigate to the [Properties](../studio/properties.md) window and click the small box to the left of the `Class.BasePart.Color|Color` property.
<img src="../assets/studio/properties/Color-Picker.png" alt="A close up view of the Properties window with the Color property's color box highlighted." width="320" />
</TabItem>
<TabItem label="RGB Value">
To define a specific RGB color value for a part, enter an RGB value into the
`Class.BasePart.Color|Color` property field.
<img src="../assets/studio/properties/Color-RGB-Entry.png" alt="A close up view of the Properties window with the Color property's RGB color value highlighted." width="320" />
</TabItem>
</Tabs>
### Material
Similar to [color](#color), you can customize a part's [material](../parts/materials.md) to simulate real‑world materials such as wood, glass, or fabric. Click‑holding over the small corner arrow on the **Material** button reveals the [material](../parts/materials.md) picker.
<img src="../assets/studio/general/Toolbar-Material-Picker.png" width="800" alt="Material widget's picker highlighted." />
When selecting a material, consider the following:
- **Material affects the physical traits of a part, not just its appearance**. For example, the `Enum.Material.Concrete|Concrete` material is heavier than the `Enum.Material.Plastic|Plastic` material, so a concrete brick will have higher density than a plastic brick and sink in water faster.
- Some materials have special physical effects. For example, parts will appear to glow if they are set to the `Enum.Material.Neon|Neon` material.
<GridContainer numColumns="3">
<figure>
<img src="../assets/modeling/parts/Material-SmoothPlastic.png" alt="An angled red block part with a smooth plastic material." />
<figcaption>SmoothPlastic</figcaption>
</figure>
<figure>
<img src="../assets/modeling/parts/Material-Neon.png" alt="An angled red block part with a glowing neon material."/>
<figcaption>Neon</figcaption>
</figure>
</GridContainer>
See [Materials](../parts/materials.md) for more information on how to apply both
default and custom materials to parts.
### Lock
The **Lock** toggle controls whether the part can be selected from the 3D viewport. This action has a default shortcut of <kbd>Alt</kbd><kbd>L</kbd> (Windows) or <kbd>⌥</kbd><kbd>L</kbd> (Mac).
<img src="../assets/studio/general/Toolbar-Lock.png" width="800" alt="Lock tool indicated in Studio's toolbar" />
<Alert severity="info">
If you prefer a click-to-toggle workflow in the 3D viewport, click‑hold over the small corner arrow on the **Lock** button and enable **Click&nbsp;object&nbsp;to&nbsp;lock**. Once enabled, the tool operates as a "key" for both states&nbsp;&mdash; clicking on an unlocked object in the viewport locks it, while clicking on a locked object unlocks it.
</Alert>
To unlock all objects, select **Unlock All** from the **Edit** menu.

1805
.cursor/rules/roblox/parts/materials.md Normal file
View file

File diff suppressed because it is too large Load diff

182
.cursor/rules/roblox/parts/meshes.md Normal file
View file

@ -0,0 +1,182 @@
---
title: Meshes
description: Meshes are a collection of vertices, edges, and faces that make up 3D objects.
---
`Class.MeshPart` objects are descendants of the `Class.BasePart` class. They represent **meshes**, which are collections of vertices, edges, and faces that make up a 3D object. Unlike parts, which you can directly create in Studio, you need to use a third-party modeling application like Blender or Maya to create meshes, then import them into Studio as `Class.MeshPart` objects.
After importing a mesh into Studio, you can customize its rendering properties, such as textures, level of detail, and collision fidelity. In addition to importing your own meshes, you can also browse and select from user-uploaded meshes using the [Creator Store](../production/creator-store.md).
Roblox supports many types of meshes, as long as they adhere to the [general mesh specifications](../art/modeling/specifications.md). A basic 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 tree mesh object 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="The texture image map for the leaves of the tree in the previous image." />
<figcaption>A texture image map applies a surface appearance and color</figcaption>
</figure>
<figure>
<img src="../assets/art/Basic-Mesh-Combined-Example.png" alt="A tree mesh object with the leaves texture applied." />
<figcaption>The mesh and texture combine to make a unique custom 3D object</figcaption>
</figure>
</GridContainer>
Studio also supports meshes with components for creating avatar character models or accessories, such as [rigging and skinning](#rigging-and-skinning) data.
<Alert severity='info'>
You can sell `Class.MeshPart` assets as avatar bodies, accessories, and clothing on the Marketplace. See [Avatar](../avatar/index.md) for more information.
</Alert>
## Import meshes
You can import meshes into Studio using the [3D Importer](../art/modeling/3d-importer.md). With this tool, you can preview and examine meshes before importing them into your workspace or **Toolbox**, such as verifying texture, rigging, skinning, and animation data. It also flags issues and rejects meshes with error.
If the mesh file you are importing contains objects using specific naming conventions or contains facial animation data, the 3D Importer automatically detects and converts them into the following objects instead of `Class.MeshPart`:
- `Class.Attachment` — Objects with `_Att` at the end of their names.
- `Class.WrapTarget` — Objects with `_OuterCage` at the end of their names.
- `Class.WrapLayer` — Objects with both `_InnerCage` `_OuterCage` at the end of their names.
- `Class.FaceControls` — Objects containing avatar character heads and the appropriate facial animation data.
If you want to bulk-import meshes along with non-3D assets, such as images and audio, you can use the [Asset Manager](../projects/assets/manager.md); note, however, that it doesn't support importing meshes with rigging, skinning, and animation data, accessories, or characters with facial animations.
## Customize meshes
Unlike basic parts, meshes have more customization options that you can adjust for advanced rendering fidelity.
### Texture
**Textures** contribute to the visual appearance of meshes by adding 2D details such as color and patterns. Studio allows you to either apply one texture using the `Class.MeshPart.TextureID` property, or apply up to four physically-based rendering (PBR) textures within a `Class.SurfaceAppearance` child object of the mesh or made with a `Class.MaterialVariant` and set in the mesh's `Class.MeshPart.MaterialVariant` property. PBR textures allow you to represent realistic shading and lighting by using multiple types of texture images, or maps, on a single object.
<Tabs>
<TabItem label="PBR Textures">
Studio supports four PBR texture maps, each corresponding to a visual characteristic of an object's surface appearance. Combining multiple texture maps can more accurately simulate color, roughness, and reflectivity in any lighting environment, and enhance the visual elements of your assets and environment. For more information on PBR textures and the texture maps, see [PBR Textures](../art/modeling/surface-appearance.md).
<GridContainer numColumns="2">
<img src="../assets/modeling/surface-appearance/SurfaceAppearance-Example-1.jpg" alt="Example of SurfaceAppearance applied to a Bush Mesh" />
<img src="../assets/modeling/surface-appearance/SurfaceAppearance-Example-3.jpg" alt="Example of SurfaceApperance applied to a Rock Mesh" />
</GridContainer>
You can apply PBR textures using one of the following objects:
- `Class.SurfaceAppearance` — Applies PBR textures to the mesh surface and doesn't affect its geometry.
- `Class.MaterialVariant` — Represents a custom material that not only applies PBR textures to the mesh surface but also adds physical properties.
To add PBR textures to a mesh:
<Tabs>
<TabItem label="SurfaceAppearance">
1. In the [Explorer](../studio/explorer.md) window, hover over the `Class.MeshPart` object. Click the **⊕** button and select `Class.SurfaceAppearance`.
2. In the [Properties](../studio/properties.md) window, edit the properties corresponding to the PBR texture maps.
</TabItem>
<TabItem label="MaterialVariant">
1. In the [Explorer](../studio/explorer.md) window, hover over the `Class.MaterialService`. Click the **⊕** button and select `Class.MaterialVariant`.
2. In the [Properties](../studio/properties.md) window, edit the properties corresponding to the PBR texture maps.
3. Name the new `Class.MaterialVariant` to a name of your choice.
4. Select the `Class.MeshPart` and, in the [Properties](../studio/properties.md) window, set the `Class.MaterialVariant` to the one you just created.
</TabItem>
</Tabs>
<Alert severity="info">
If you both add `Class.SurfaceAppearance` as a child object and set the `Class.MaterialVariant` in the mesh's properties, Studio only applies the texture map settings of the `Class.SurfaceAppearance` object to the mesh. The mesh still has all other settings of the `Class.MaterialVariant` object, such as custom physical properties.
</Alert>
</TabItem>
<TabItem label="Single Texture">
If the mesh you import to Studio doesn't come with texture data, or you want to change the existing texture, use the following steps to add a single texture:
1. [Import the texture file](../projects/assets/manager.md#asset-import). The file must follow the [texture specifications](../art/modeling/texture-specifications.md). Upon completion, Studio automatically assigns and prompts an asset ID.
2. Copy the asset ID.
3. In the **Explorer** window, select the **MeshPart** object.
4. In the **Properties** window, select the **TextureID** field and paste the asset ID of the texture.
<Alert severity="warning">
If your mesh has existing PBR textures, setting a Texture ID can't override the PBR textures.
</Alert>
</TabItem>
</Tabs>
### Level of detail
You can dynamically control a mesh's level of detail using its `Enum.RenderFidelity` property. The default value is `Enum.RenderFidelity.Automatic|Automatic`, meaning the mesh's detail is based on its distance from the camera as outlined in the following table.
<table>
<thead>
<tr>
<th>Distance&nbsp;from&nbsp;camera</th>
<th>Render fidelity</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td>Less than 250 studs</td>
<td>Highest</td>
<td><img src="../assets/modeling/meshes/Render-Fidelity-High.jpg" alt="A potion mesh object that is rendered in the highest level of detail." width="200" /></td>
</tr>
<tr>
<td>250-500 studs</td>
<td>Medium</td>
<td><img src="../assets/modeling/meshes/Render-Fidelity-Medium.jpg" alt="A potion mesh object that is rendered in a medium level of detail. Its edges are more jagged than the previous image." width="200" /></td>
</tr>
<tr>
<td>500 or more studs</td>
<td>Lowest</td>
<td><img src="../assets/modeling/meshes/Render-Fidelity-Low.jpg" alt="A potion mesh object that is rendered in the lowest level of detail. Its edges are more jagged than the previous image, and the liquid is no longer shiny." width="200" /></td>
</tr>
</tbody>
</table>
### Collision fidelity
**Collision fidelity** determines how closely the visual representation of a mesh matches its physical bounds. The `Class.MeshPart.CollisionFidelity` property has the following options, in order of fidelity and performance impact from lowest to highest:
- **Box** — Creates a bounding collision box, ideal for small or non‑interactive objects.
- **Hull** — Generates a convex hull, suitable for objects with less pronounced indentations or cavities.
- **Default** — Produces an approximate collision shape that supports concavity, suitable for complex objects with semi-detailed interaction needs.
- **PreciseConvexDecomposition** — Offers the most precise fidelity but still not a 1:1 representation of the visual. This option has the most expensive performance cost and takes longer for the engine to compute.
<Tabs>
<TabItem label="Original Mesh">
<img src="../assets/physics/collisions/Collision-Fidelity-MeshPart.jpg" width="600" height="500" alt="Original mesh of castle tower" />
</TabItem>
<TabItem label="Default">
<img src="../assets/physics/collisions/Collision-Fidelity-Default.jpg" width="600" height="500" alt="Collision fidelity of Default shown for mesh" />
</TabItem>
<TabItem label="Box">
<img src="../assets/physics/collisions/Collision-Fidelity-Box.jpg" width="600" height="500" alt="Collision fidelity of Box shown for mesh"/>
</TabItem>
<TabItem label="Hull">
<img src="../assets/physics/collisions/Collision-Fidelity-Hull.jpg" width="600" height="500" alt="Collision fidelity of Hull shown for mesh" />
</TabItem>
<TabItem label="Precise">
<img src="../assets/physics/collisions/Collision-Fidelity-Precise.jpg" width="600" height="500" alt="Collision fidelity of PreciseConvexDecomposition shown for mesh" />
</TabItem>
</Tabs>
<Alert severity="success">
To view collision fidelity in Studio, toggle on **Collision&nbsp;fidelity** from the [Visualization&nbsp;Options](../studio/ui-overview.md#visualization-options) widget in the upper‑right corner of the 3D viewport.
</Alert>
For more information on the performance impact of collision fidelity options and how to mitigate them, see [Improve performance](../performance-optimization/improve.md#physics-computation). For an in-depth walkthrough on how to choose a collision fidelity option that balances your precision and performance requirements, see [Set physics and rendering parameters](../tutorials/curriculums/environmental-art/optimize-your-experience.md#review-physics-and-rendering-parameters).
## Rigging and skinning
**Rigging** is the process of connecting a mesh with an internal poseable skeleton rig. Rigged meshes allow mesh surfaces to rotate and move using internal bones within a model, such as a character's knee or elbow. **Skinning** a rigged mesh allows the rigged mesh object to deform, stretch, and bend in a more realistic manner.
<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). After rigging a mesh, you can add animation and poses to it using the **Animation Editor**. See [Create an animation](../animation/editor.md#create-an-animation) for more information. Marketplace 3D assets, such as avatar clothing and bodies, also require rigging and skinning. See [Avatar](../avatar/index.md) for more information on requirements for Marketplace assets.

156
.cursor/rules/roblox/parts/models.md Normal file
View file

@ -0,0 +1,156 @@
---
title: Models
description: Models are container objects for geometric groupings like parts, Motor6D objects, and other models.
---
**Models** are containers for physical objects that you can use to organize your workspace and group your assets, such as parts, welds, or joints. While models often contain connected parts known as an [assembly](../physics/assemblies.md), they can also contain any number of individual parts or objects, such as scripts, attachments, or other models.
To demonstrate, avatar characters are a single `Class.Model` containing the appropriate humanoid parts, joints, and scripts necessary for runtime behavior:
<GridContainer numColumns="2">
<figure>
<img src="../assets/modeling/model-objects/Model-Example-3D.jpg" width="80%" alt="An example character model of a humanoid monster girl in a dark purple dress." />
<figcaption>A model named Octavia</figcaption>
</figure>
<figure>
<img src="../assets/modeling/model-objects/Model-Example-Hierarchy.png" width="68%" alt="The groupings which comprise the Octavia model in Studio's Explorer window." />
<figcaption>The groupings that comprise the model</figcaption>
</figure>
</GridContainer>
## Create models
<Alert severity="warning">
You can create models using any open use or restricted asset, but any restricted assets that you don't have [explicit permission](../projects/assets/privacy.md#view-permissions) to use are **not** visible or audible at runtime unless the experience itself has permission to use those assets.
</Alert>
There are two ways to create models:
- Group objects together to automatically form a `Class.Model` object.
- Insert an empty `Class.Model` object into the Workspace, then manually add child objects to the model.
To create a model using the grouping method:
1. In the **Explorer** window or 3D viewport, select every object that you want to group into a model.
1. Right-click on one of the objects and select **Group**, or press <kbd>Ctrl</kbd><kbd>G</kbd> on Windows or <kbd>⌘</kbd><kbd>G</kbd> on Mac. A new `Class.Model` object displays with all of the objects that make up the model nested underneath.
<img src="../assets/modeling/model-objects/Model-Group-Simple.png" width="320" alt="A close up view of the Explorer window. A Model object is highlighted with three nested children." />
<Alert severity="info">
To completely ungroup a model back to its original objects, right-click it and select **Ungroup**, or press <kbd>Ctrl</kbd><kbd>U</kbd> on Windows or <kbd>⌘</kbd><kbd>U</kbd> on Mac.
</Alert>
### Set a primary part
If you have a model with parts that are joined together through physical joints like `Class.WeldConstraint|WeldConstraints` or `Class.Motor6D|Motor6Ds`, you should specify a `Class.BasePart` within the model to become a `Class.Model.PrimaryPart|PrimaryPart`. A model's `Class.Model.PrimaryPart|PrimaryPart` is the physical reference that specifies which `Class.BasePart` the pivot point and bounding box should move with when the model changes position or orientation.
To set a primary part:
1. In the **Explorer** window, select a model.
1. In the **Properties** window, select the **PrimaryPart** property. Your cursor changes.
1. Back in the **Explorer** window, select the part that you want to become your primary part.
## Select models
As you hover over models in the viewport, they are outlined to indicate their potential selection. You can select an outlined model by clicking it, or you can select multiple models by holding <kbd>Shift</kbd>, <kbd>Ctrl</kbd>, or <kbd>⌘</kbd> as you hover over and click them.
<img src="../assets/studio/general/Editor-Window-Object-Selection.jpg" width="800" alt="A warehouse view in the 3D viewport. Multiple models are selected and highlighted with a light blue outline."/>
As models typically contain multiple child [parts](../parts/index.md) or [meshes](../parts/meshes.md), some children may be hidden from view. To select a specific child without moving the camera around or locating the child in the [Explorer](../studio/explorer.md) hierarchy, click while holding <kbd>Alt</kbd> on Windows or <kbd>⌥</kbd> on Mac to perform [selection cycling](../studio/ui-overview.md#selection-cycling).
<figure>
<video src="../assets/studio/general/Selection-Cycling.mp4" controls width="80%" alt="Video showing selection cycling through a model"></video>
<figcaption>Selection cycling</figcaption>
</figure>
## Transform models
You can move, scale, or rotate a model using the Studio [transform](../parts/index.md#transform-parts) tools. Unless you've set a [primary part](#set-a-primary-part), a model transforms based on the center of its bounding box.
Additionally, within a `Class.Script` or `Class.LocalScript`, you can move or rotate a model through the following methods:
<table>
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.Model:MoveTo()|MoveTo()`</td>
<td>Moves the model's `Class.Model.PrimaryPart|PrimaryPart` to the given position. If a primary part has not been specified, the root part of the model will be used.</td>
</tr>
<tr>
<td>`Class.PVInstance:PivotTo()|PivotTo()`</td>
<td>Transforms the model along with all of its descendant `Class.PVInstance|PVInstances` such that the pivot is located at the specified `Datatype.CFrame`.</td>
</tr>
<tr>
<td>`Class.Model:TranslateBy()|TranslateBy()`</td>
<td>Shifts a model by the given `Datatype.Vector3` offset, preserving the model's orientation.</td>
</tr>
</tbody>
</table>
## Model behaviors
While models act similarly to `Class.Folder` objects for most purposes in your experience, they also exhibit some unique behaviors.
### Character models
When a `Class.Humanoid` is present inside a model that contains a `Class.Part` named **Head**, Roblox displays a name and/or health bar above that part. For more information, see [Character Name/Health Display](../characters/name-health-display.md).
<img src="../assets/avatar/name-health-display/Display-Indicated.jpg" width="800" alt="Character display information above an in-experience avatar." />
### Destroy height
To prevent parts that have fallen off of an experience's map from continuing to fall forever, Studio automatically destroys parts that fall below the `Class.Workspace.FallenPartsDestroyHeight` value. If a part destroyed due to this behavior is the last part in a model, then that model will also be destroyed.
## Model streaming
Instance [streaming](../workspace/streaming.md) dynamically loads and unloads `Class.Model|Models` on a player's device as their character explores the 3D world. With streaming enabled, you can specify the way each model should be treated under streaming behavior. For example, a model set to [Persistent](../workspace/streaming.md#persistent) will never stream out, or a model set to [Atomic](../workspace/streaming.md#atomic) will stream in and out as a single unit with all of its descendants. For more information, see [Per-model streaming controls](../workspace/streaming.md#per-model-streaming-controls).
Because the 3D content that exists on the client changes dynamically in a streaming-enabled experience, models might suddenly disappear, which can be visually jarring for the player. To avoid this situation, you can set specific models to render as optimized "SLIM" meshes or as lower resolution "imposter" meshes when streamed out. See [Model level of detail](../workspace/streaming.md#model-level-of-detail).
## Upload models
When you upload or import a `.gltf`, `.fbx` and `.obj` model file to the cloud using the [3D Importer](../art/accessories/creating-rigid/importing.md), Roblox represents it as a cloud-based asset with a unique corresponding ID. This cloud-based asset system allows you to store models through Roblox and reuse them across the platform in various contexts without maintaining local copies as part of each saved Studio experience.
To upload a model you made in Studio:
1. In the **Explorer** window, right-click your model. A contextual menu displays.
2. Select **Save to Roblox**. The **Asset Configuration** window displays.
3. In the **Asset Configuration** window,
1. Set **Content Type** to **Development Item**.
1. Set **Asset Category** to **Model**.
1. Complete the following fields:
- **Title** - The name of your model.
- **Description** - A short description of your model.
- **Creator** - Use the dropdown to select if you'd like to publish this asset as an individual or as part of an associated group.
- **Genre** - The genre of your model.
1. Click the **Save** button. After a moment, the **Asset Configuration** window displays your model's asset ID that you can use in your projects or share with other creators, groups, or experiences. For more information on granting permission to collaborators and experiences so that they can use your models, see [Asset privacy](../projects/assets/privacy.md)
## Distribute models
You can distribute models with less than 15,000 dependencies to the [Creator Store](../production/creator-store.md) for other creators to use within their own experiences as long as each model only references:
- Open use assets.
- Restricted assets that you created, excluding audio and video.
- Audio and video assets from the Creator Store.
If you are in a supported country, you can sell models you created on the Creator Store for **United States Dollars** (USD). Eligible Creators must complete an application form through Stripe to create their seller account, set prices, and receive payouts. For more information and to start onboarding, see [Sell on the Creator Store](../production/sell-on-creator-store.md).
<Alert severity="warning">
If you want to distribute a model with a child audio asset that you created, you must distribute the audio asset on the Creator Store **_before_** making it a child of the model in order for the audio to be audible at runtime.
</Alert>
As with any asset, all models must adhere to the [Community Rules](https://en.help.roblox.com/hc/articles/203313410), [Terms of Use](https://en.help.roblox.com/hc/articles/115004647846), the [DMCA Guidelines](../production/publishing/dmca-guidelines.md) regarding copyright, and Creator Store [asset moderation](../production/creator-store.md#asset-moderation) rules. If you suspect a rights violation involving your asset, you can submit the content for removal using the [Rights Manager](../production/publishing/rights-manager.md).
When creating models for the Creator Store:
- Read about Roblox [texture specifications and limits](../art/modeling/texture-specifications.md).
- Limit each mesh to a maximum of 20,000 triangles.
- Read and address any warnings shown during the import process.
- Scale and orient your model appropriately during import so that it's usable out of the box when inserted from the Creator Store.

254
.cursor/rules/roblox/parts/solid-modeling.md Normal file
View file

@ -0,0 +1,254 @@
---
title: Solid modeling
description: Solid modeling is the process of joining parts together to form complex shapes.
---
**Solid modeling** is the process of joining [parts](../parts/index.md)
together in unique ways to form more complex shapes known as **unions** or **intersections**. You can perform four solid modeling operations using the tools within the **Model** tab toolbar.
<img src="../assets/studio/general/Toolbar-Solid-Modeling.png" alt="Solid modeling tools highlighted in Studio's toolbar." width="800" />
<table>
<thead>
<tr>
<th>Tool</th>
<th>Shortcut</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[Union](#union-parts)</td>
<td><kbd>Shift</kbd><kbd>Ctrl</kbd><kbd>G</kbd>&nbsp;(Windows)<br /><kbd>Shift</kbd><kbd>⌘</kbd><kbd>G</kbd> (Mac)</td>
<td>Join two or more parts together to form a single solid union.</td>
</tr>
<tr>
<td>[Intersect](#intersect-parts)</td>
<td><kbd>Shift</kbd><kbd>Ctrl</kbd><kbd>I</kbd>&nbsp;(Windows)<br /><kbd>Shift</kbd><kbd>⌘</kbd><kbd>I</kbd> (Mac)</td>
<td>Intersect overlapping parts into a single solid intersection.</td>
</tr>
<tr>
<td>[Negate](#negate-parts)</td>
<td><kbd>Shift</kbd><kbd>Ctrl</kbd><kbd>N</kbd>&nbsp;(Windows)<br /><kbd>Shift</kbd><kbd>⌘</kbd><kbd>N</kbd> (Mac)</td>
<td>Negate parts, useful for making holes and indentations.</td>
</tr>
<tr>
<td>[Separate](#separate-unions-or-intersections)</td>
<td><kbd>Shift</kbd><kbd>Ctrl</kbd><kbd>U</kbd>&nbsp;(Windows)<br /><kbd>Shift</kbd><kbd>⌘</kbd><kbd>U</kbd> (Mac)</td>
<td>Separate the union or intersection back into its individual parts.</td>
</tr>
</tbody>
</table>
## Union parts
The **Union** tool joins two or more parts together to form a single solid `Class.UnionOperation`. By default, a new union respects the `Class.BasePart.Color|Color` property of each of its parts, although you can enable its `Class.PartOperation.UsePartColor|UsePartColor` property to change the entire union to a specific color.
<Tabs>
<TabItem label="Separate Parts">
<img src="../assets/modeling/solid-modeling/Separate-Parts-To-Union.jpg" width="720" height="375" alt="Block and cylinder parts overlapping" />
</TabItem>
<TabItem label="Unioned">
<img src="../assets/modeling/solid-modeling/Union-Result.jpg" width="720" height="375" alt="Parts joined together into a single solid union" />
</TabItem>
</Tabs>
To combine parts together into a union:
1. Select all parts that you want to join together.
2. Click the **Union** button. All of the parts combine into one solid `Class.UnionOperation` with the name **Union**.
## Intersect parts
The **Intersect** tool intersects overlapping parts into a single solid `Class.IntersectOperation`. By default, the face colors of the resulting intersection are borrowed from the `Class.BasePart.Color|Color` property of the original parts, although you can enable its `Class.PartOperation.UsePartColor|UsePartColor` property to change the entire intersection to a specific color.
<Tabs>
<TabItem label="Separate Parts">
<figure>
<img src="../assets/modeling/solid-modeling/Separate-Parts-To-Intersect.jpg" width="720" height="375" alt="Block and cylinder parts overlapping" />
</figure>
</TabItem>
<TabItem label="Intersected">
<figure>
<img src="../assets/modeling/solid-modeling/Intersect-Result.jpg" width="720" height="375" alt="Parts intersected into a new solid model" />
</figure>
</TabItem>
</Tabs>
To intersect overlapping parts together:
1. Select all parts that you want to intersect.
2. Click the **Intersect** button. All of the parts combine into one solid `Class.IntersectOperation` with the name **Intersection**.
## Negate parts
The **Negate** tool negates a part so that when it's [unioned with another part](#union-parts), the shape of the negated part is **subtracted** from the other part.
<Tabs>
<TabItem label="Separate Parts">
<figure>
<img src="../assets/modeling/solid-modeling/Negated-Part-To-Union.jpg" width="720" height="375" alt="Negated block overlapping a cylinder" />
</figure>
</TabItem>
<TabItem label="Negated">
<figure>
<img src="../assets/modeling/solid-modeling/Negate-Result.jpg" width="720" height="375" alt="Negated part subtracted from cylinder" />
</figure>
</TabItem>
</Tabs>
To subtract a part from other overlapping parts:
1. Select the part you want to negate from other parts.
1. Click **Negate**. The part becomes a `Class.NegateOperation` with the name **NegativePart** and turns pink and translucent to indicate its state.
1. Select both the negated part and the parts you want to subtract it from.
1. Click **Union**. The negated part is cut out from the included overlapping parts.
## Separate unions or intersections
The **Separate** tool separates a `Class.UnionOperation` back into its individual parts, essentially serving as an "undo" tool for unions and intersections.
To separate a union or intersection back into individual parts:
1. Select the union or intersection.
1. Click **Separate**. The parts separate back into their original form.
## Render fidelity
By default, new solid modeled operations will always be shown in `Enum.RenderFidelity.Automatic|Automatic` render fidelity, meaning the part's detail is based on its distance from the camera as outlined in the following table.
<table>
<thead>
<tr>
<th>Distance from camera</th>
<th>Render fidelity</th>
</tr>
</thead>
<tbody>
<tr>
<td>Less than 250 studs</td>
<td>Highest</td>
</tr>
<tr>
<td>250-500 studs</td>
<td>Medium</td>
</tr>
<tr>
<td>500 or more studs</td>
<td>Lowest</td>
</tr>
</tbody>
</table>
## Smoothing angle
A solid modeled part's `Class.PartOperation.SmoothingAngle|SmoothingAngle` property smooths angles between adjacent surfaces of the same color or material. A higher value produces a smoother appearance while a lower value produces a rougher appearance with more sharp edges.
While a value between 30 and 70 degrees usually produces a good result, values between 90 and 180 are not recommended as they may cause a "shadowing" effect on unions and intersections with sharp edges.
<GridContainer numColumns="2">
<figure>
<img src="../assets/modeling/solid-modeling/CSG-SmoothingAngle-0.jpg" alt="Solid modeled part with SmoothingAngle of 0" />
<figcaption>`Class.PartOperation.SmoothingAngle|SmoothingAngle` = 0</figcaption>
</figure>
<figure>
<img src="../assets/modeling/solid-modeling/CSG-SmoothingAngle-50.jpg" alt="Solid modeled part with SmoothingAngle of 50" />
<figcaption>`Class.PartOperation.SmoothingAngle|SmoothingAngle` = 50</figcaption>
</figure>
</GridContainer>
## In-experience solid modeling
In addition to the **Union**, **Intersect**, and **Negate** tools in Studio, you can allow players to use solid modeling operations while inside an experience through `Class.BasePart:UnionAsync()|UnionAsync()`, `Class.BasePart:IntersectAsync()|IntersectAsync()`, and `Class.BasePart:SubtractAsync()|SubtractAsync()`. All of these methods must be called on a `Class.BasePart` and they all require an array of one or more parts to union with, intersect with, or subtract from the calling part.
<Alert severity="warning">
In-experience solid modeling operations are asynchronous, meaning they can impact performance. For best results, you should not perform a large series of `Class.BasePart:UnionAsync()|UnionAsync()`, `Class.BasePart:IntersectAsync()|IntersectAsync()`, or `Class.BasePart:SubtractAsync()|SubtractAsync()` calls in quick succession.
</Alert>
<Alert severity="info">
When performing a `Class.BasePart:UnionAsync()|UnionAsync()`, `Class.BasePart:IntersectAsync()|IntersectAsync()`, or `Class.BasePart:SubtractAsync()|SubtractAsync()` operation, the following properties from the calling part are applied to the resulting union: `Class.BasePart.Color|Color`, `Class.BasePart.Material|Material`, `Class.BasePart.MaterialVariant|MaterialVariant`, `Class.BasePart.Reflectance|Reflectance`, `Class.BasePart.Transparency|Transparency`, `Class.BasePart.Anchored|Anchored`, `Class.BasePart.CanCollide|CanCollide`, `Class.BasePart.Density|Density`, `Class.BasePart.Elasticity|Elasticity`, `Class.BasePart.ElasticityWeight|ElasticityWeight`, `Class.BasePart.Friction|Friction`, and `Class.BasePart.FrictionWeight|FrictionWeight`.
</Alert>
### UnionAsync()
To demonstrate `Class.BasePart:UnionAsync()|UnionAsync()`, the following `Class.Script` uses the **Part1** `Class.BasePart` from the workspace, unions it together with the **Part2**, **Part3**, and **Part4** `Class.BasePart|BaseParts`, then parents the resulting `Class.UnionOperation` to the workspace at the original position of **Part1**.
```lua highlight="6"
local Workspace = game:GetService("Workspace")
local mainPart = Workspace.Part1
local otherParts = {Workspace.Part2, Workspace.Part3, Workspace.Part4}
-- Perform union operation
local success, newUnion = pcall(function()
return mainPart:UnionAsync(otherParts)
end)
-- If operation succeeds, position it at the same location and parent it to the workspace
if success and newUnion then
newUnion.Position = mainPart.Position
newUnion.Parent = Workspace
end
-- Destroy original parts which remain intact after operation
mainPart:Destroy()
for _, part in otherParts do
part:Destroy()
end
```
### IntersectAsync()
To demonstrate `Class.BasePart:IntersectAsync()|IntersectAsync()`, the following `Class.Script` uses the **Part1** `Class.BasePart` from the workspace, intersects it with the **Part2** and **Part3** `Class.BasePart|BaseParts`, then parents the resulting `Class.IntersectOperation` to the workspace at the original position of **Part1**.
```lua highlight="6"
local Workspace = game:GetService("Workspace")
local mainPart = Workspace.Part1
local otherParts = {Workspace.Part2, Workspace.Part3}
-- Perform intersect operation
local success, newIntersect = pcall(function()
return mainPart:IntersectAsync(otherParts)
end)
-- If operation succeeds, position it at the same location and parent it to the workspace
if success and newIntersect then
newIntersect.Position = mainPart.Position
newIntersect.Parent = Workspace
end
-- Destroy original parts which remain intact after operation
mainPart:Destroy()
for _, part in otherParts do
part:Destroy()
end
```
### SubtractAsync()
To demonstrate `Class.BasePart:SubtractAsync()|SubtractAsync()`, the following `Class.Script` uses the **Part1** `Class.BasePart` from the workspace, negates the **Part2**, **Part3**, and **Part4** `Class.BasePart|BaseParts` from it, then parents the resulting `Class.UnionOperation` to the workspace at the original position of **Part1**.
```lua highlight="6"
local Workspace = game:GetService("Workspace")
local mainPart = Workspace.Part1
local otherParts = {Workspace.Part2, Workspace.Part3, Workspace.Part4}
-- Perform subtract operation
local success, newSubtract = pcall(function()
return mainPart:SubtractAsync(otherParts)
end)
-- If operation succeeds, position it at the same location and parent it to the workspace
if success and newSubtract then
newSubtract.Position = mainPart.Position
newSubtract.Parent = Workspace
end
-- Destroy original parts which remain intact after operation
mainPart:Destroy()
for _, part in otherParts do
part:Destroy()
end
```

686
.cursor/rules/roblox/parts/terrain.md Normal file
View file

@ -0,0 +1,686 @@
---
title: Environmental terrain
description: Explore how to generate and sculpt realistic terrain environments such as mountains, bodies of water, grass-covered hills, or a flat desert.
---
import BetaAlert from '../includes/beta-features/beta-alert.md'
Studio's [Terrain Editor](../studio/terrain-editor.md) lets you generate and sculpt detailed and realistic terrain environments such as mountains, bodies of water, grass-covered hills, or a flat desert. Terrain is made up of grids of **voxels** which are 4&times;4&times;4 stud regions in the 3D world with a set material.
<img src="../assets/studio/general/Toolbar-Terrain-Editor.png" width="800" alt="Terrain Editor indicated in Studio's toolbar" />
<img src="../assets/modeling/terrain/Showcase.jpg" width="100%" alt="Desert terrain with mountains in the distance" />
Using the editor tools, you can easily [generate](#generate-terrain) and edit terrain either at a [voxel](#detailed-editing) or [region](#large-scale-editing) level with the option of importing a [heightmap](#heightmaps-and-colormaps) and [colormap](#heightmaps-and-colormaps). For more precise, dynamic, or procedural terrain editing, you can also [script](#scripting) terrain creation.
## Terrain materials
The following default materials are available for terrain, and you can also apply [custom materials](../parts/materials.md#custom-materials). Materials affect both the shape and appearance of terrain in the world; for example, [animated grass](#grass-animation) renders only on the `Enum.Material.Grass|Grass` material and the `Enum.Material.Water|Water` material [ripples and shimmers](#water-appearance) with a subtle motion.
<GridContainer numColumns="4">
<figure>
<img src="../assets/modeling/terrain/Material-Asphalt.jpg" alt="Appearance of Asphalt material" />
<figcaption>Asphalt</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Basalt.jpg" alt="Appearance of Basalt material" />
<figcaption>Basalt</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Brick.jpg" alt="Appearance of Brick material" />
<figcaption>Brick</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Cobblestone.jpg" alt="Appearance of Cobblestone material" />
<figcaption>Cobblestone</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Concrete.jpg" alt="Appearance of Concrete material" />
<figcaption>Concrete</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Cracked-Lava.jpg" alt="Appearance of Cracked Lava material" />
<figcaption>Cracked Lava</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Glacier.jpg" alt="Appearance of Glacier material" />
<figcaption>Glacier</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Grass.jpg" alt="Appearance of Grass material" />
<figcaption>Grass</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Ground.jpg" alt="Appearance of Ground material" />
<figcaption>Ground</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Ice.jpg" alt="Appearance of Ice material" />
<figcaption>Ice</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Leafy-Grass.jpg" alt="Appearance of Leafy Grass material" />
<figcaption>Leafy Grass</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Limestone.jpg" alt="Appearance of Limestone material" />
<figcaption>Limestone</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Mud.jpg" alt="Appearance of Mud material" />
<figcaption>Mud</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Pavement.jpg" alt="Appearance of Pavement material" />
<figcaption>Pavement</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Rock.jpg" alt="Appearance of Rock material" />
<figcaption>Rock</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Salt.jpg" alt="Appearance of Salt material" />
<figcaption>Salt</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Sand.jpg" alt="Appearance of Sand material" />
<figcaption>Sand</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Sandstone.jpg" alt="Appearance of Sandstone material" />
<figcaption>Sandstone</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Slate.jpg" alt="Appearance of Slate material" />
<figcaption>Slate</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Snow.jpg" alt="Appearance of Snow material" />
<figcaption>Snow</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Water.jpg" alt="Appearance of Water material" />
<figcaption>Water</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Wood-Planks.jpg" alt="Appearance of Wood Planks material" />
<figcaption>Wood Planks</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Material-Air.png" alt="Air material icon (no visual appearance)" />
<figcaption>Air</figcaption>
</figure>
</GridContainer>
### Water appearance
By default, terrain water ripples, oscillates, and shimmers with a subtle motion.
<video src="../assets/modeling/terrain/Water-Appearance.mp4" controls width="800" alt="Terrain water rippling, oscillating, and shimmering with a subtle motion"></video>
To customize the color and motion of water:
1. In the **Explorer** window, navigate to the `Class.Workspace`, then select the `Class.Terrain` object.
<img src="../assets/studio/explorer/Workspace-Terrain.png" width="320" alt="Terrain object shown in Explorer window of Studio" />
1. In the **Properties** window, customize the appearance of water through the following properties:
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.Terrain.WaterColor|WaterColor`</td>
<td>Adjusts the overall hue of all terrain water in the experience.</td>
</tr>
<tr>
<td>`Class.Terrain.WaterReflectance|WaterReflectance`</td>
<td>Adjusts how much water surfaces reflect the sky and surrounding objects from a value of 1 (high) to 0 (none).</td>
</tr>
<tr>
<td>`Class.Terrain.WaterTransparency|WaterTransparency`</td>
<td>Adjusts how transparent water is from a value of 1 (clear) to 0 (opaque).</td>
</tr>
<tr>
<td>`Class.Terrain.WaterWaveSize|WaterWaveSize`</td>
<td>Adjusts the size of waves from a value of 1 (large) to 0 (none).</td>
</tr>
<tr>
<td>`Class.Terrain.WaterWaveSpeed|WaterWaveSpeed`</td>
<td>Adjusts the speed of waves from a value of 100 (turbulent) to 0 (still).</td>
</tr>
</tbody>
</table>
<Alert severity="info">
Some water properties are only visible while playtesting. To preview all properties while editing, open [Studio Settings](../studio/setup.md#customization), search for **Editor&nbsp;Quality&nbsp;Level**, and set it to the highest level.
</Alert>
### Grass animation
While most materials are static, you can add animated blades of grass to the `Enum.Material.Grass|Grass` terrain material. By default, grass sways gently in a simulated wind, and you can adjust the direction/strength of its animation through [global wind](../environment/global-wind.md).
<video src="../assets/lighting-and-effects/aero-fluid-dynamics/Global-Wind-Showcase.mp4" controls width="800" alt="Video of wind blowing clouds and grass across rolling hills in the 3D world"></video>
<Alert severity="info">
Note that the speed of animated grass — but not its vector direction&nbsp;— will be reduced if the player has toggled on the **Reduce&nbsp;Motion** [accessibility](../production/publishing/accessibility.md#reduced-motion) setting from the Roblox or in‑experience **Settings** menu.
</Alert>
To add animated grass to the `Enum.Material.Grass|Grass` material:
1. In the **Explorer** window, navigate to the `Class.Workspace`, then select the `Class.Terrain` object.
<img src="../assets/studio/explorer/Workspace-Terrain.png" width="320" alt="Terrain object shown in Explorer window of Studio" />
2. In the **Properties** window, toggle on the `Class.Terrain.Decoration|Decoration` property.
<img src="../assets/studio/properties/Terrain-Decoration.png" width="320" alt="Decoration property of Terrain object in Properties window of Studio" />
3. Adjust the grass length by entering a value between `0.1` and `1` for the `Class.Terrain.GrassLength|GrassLength` property.
<img src="../assets/studio/properties/Terrain-GrassLength.png" width="320" alt="GrassLength property of Terrain object in Properties window of Studio" />
<img src="../assets/modeling/terrain/Terrain-GrassLength.jpg" width="720" alt="GrassLength comparison depicted on rolling grassland hills." />
4. Adjust the direction and strength of its animation through [global wind](../environment/global-wind.md).
### Custom terrain colors
Each terrain material is assigned a default color, but you can customize any material's color to better fit your experience.
<Tabs>
<TabItem label="Default">
<img src="../assets/modeling/terrain/Showcase.jpg" width="800" height="450" alt="Default terrain colors used in desert landscape" />
</TabItem>
<TabItem label="Fantasy">
<img src="../assets/modeling/terrain/Custom-Colors-Fantasy.jpg" width="800" height="450" alt="Custom terrain colors applied for fantasy landscape" />
</TabItem>
<TabItem label="Tundra">
<img src="../assets/modeling/terrain/Custom-Colors-Tundra.jpg" width="800" height="450" alt="Custom terrain colors applied for tundra landscape" />
</TabItem>
</Tabs>
To customize any material color other than water:
1. In the **Explorer** window, navigate to the `Class.Workspace`, then select the `Class.Terrain` object.
<img src="../assets/studio/explorer/Workspace-Terrain.png" width="320" alt="Terrain object shown in Explorer window of Studio" />
2. In the **Properties** window, expand `Class.Terrain.MaterialColors|MaterialColors`. All materials display with their RGB code.
<img src="../assets/studio/properties/Terrain-MaterialColors-Expand.png" width="320" alt="MaterialColors property shown in Properties window of Studio" />
3. For any material, either input a new RGB code or click the color box to open the [colors popup](../parts/index.md#color).
## Generate terrain
Using the following tools and methods, you can generate large
areas of terrain procedurally through tooling or scripting, or automatically based on a heightmap and colormap.
### Generate tool
The **Generate** tool allows you to procedurally generate terrain in seconds. This is useful if you want to create a large map and fine-tune [terrain details](#detailed-editing).
1. In the editor window, navigate to the **Create** tab and select the **Generate** tool.
<img src="../assets/studio/terrain-editor/Create-Tab-Generate.png" width="360" alt="Generate tool indicated in Create tab of Terrain Editor" />
2. In the 3D viewport, move/resize the **selection region** in which to generate terrain. Alternatively, expand the tool's **Selection&nbsp;Settings** and enter values into the **X**/**Y**/**Z** inputs to set a specific size and position.
3. In the tool's **Biome Settings** section, choose the following biomes to include in the new terrain:
<Grid container spacing={1}>
<Grid item>
<ul>
<li>Arctic</li>
<li>Dunes</li>
<li>Canyons</li>
</ul>
</Grid>
<Grid item>
<ul>
<li>Lavascape</li>
<li>Water</li>
<li>Mountains</li>
</ul>
</Grid>
<Grid item>
<ul>
<li>Hills</li>
<li>Plains</li>
<li>Marsh</li>
</ul>
</Grid>
</Grid>
4. Click the **Generate** button.
<video src="../assets/studio/terrain-editor/Generate-Tool.mp4" controls width="800" alt="Video of terrain generating procedurally via the Generate tool"></video>
### Heightmaps and colormaps
A **heightmap** is a 2D representation of a 3D terrain map, as viewed directly from above. Brighter areas of a heightmap result in higher terrain, like mountains, while darker areas result in lower regions, like valleys.
An optional **colormap**, along with a heightmap, converts colors to terrain materials using a **color key**.
<GridContainer numColumns="3">
<figure>
<img src="../assets/modeling/terrain/Terrain-Heightmap.png" alt="Example heightmap image" />
<figcaption>Heightmap</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Terrain-Colormap.png" alt="Example colormap image" />
<figcaption>Colormap</figcaption>
</figure>
<figure>
<img src="../assets/modeling/terrain/Terrain-Colormap-Result.jpg" alt="Terrain generated from the example heightmap and colormap" />
<figcaption>Generated terrain</figcaption>
</figure>
</GridContainer>
1 pixel in a heightmap represents 4 studs in Studio, and Studio supports a maximum of 4096&times;4096 pixels in either `.jpg` or `.png` format.
To import a heightmap and optional colormap:
1. In the editor window, navigate to the **Create** tab and select the **Import** tool.
<img src="../assets/studio/terrain-editor/Create-Tab-Import.png" width="360" alt="Import tool indicated in Create tab of Terrain Editor" />
2. In the tool's **Map Settings** section, click the import button and choose the image you want to import as a heightmap.
3. In the tool's **Material Settings** section, select a terrain material or, alternatively, upload a colormap.
<Tabs>
<TabItem label="Material">
To apply one consistent material across all of the generated terrain, select the **Material** tab and pick a terrain material.
</TabItem>
<TabItem label="Colormap">
To apply a colormap, click the **Colormap** tab, click its import button, and choose the file to import. Colors on the image should match the following RGB/hex values and use hard edges, since anti‑aliasing or edge smoothing may create pixel colors outside the expected value ranges.
The following table describes color mapping to a corresponding material. If your colormap contains a color that's not in the table, Studio chooses the closest matching material; for this reason, it is best to download the <a href="../assets/modeling/terrain/RobloxColorMapIndex.png" target="_blank" rel="noopener">`RobloxColorMapIndex`</a> file and directly sample its colors, or type the exact RGB/hex values into the color picker of your image editing application.
<table size="small">
<thead>
<tr>
<th>Material</th>
<th>RGB Value</th>
<th>Hex Value</th>
<th>Color</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Enum.Material.Air|Air`</td>
<td>`[255, 255, 255]`</td>
<td>`FFFFFF`</td>
<td><ColorSwatch value="rgb(255,255,255)" /></td>
</tr>
<tr>
<td>`Enum.Material.Asphalt|Asphalt`</td>
<td>`[115, 123, 107]`</td>
<td>`737B6B`</td>
<td><ColorSwatch value="rgb(115,123,107)" /></td>
</tr>
<tr>
<td>`Enum.Material.Basalt|Basalt`</td>
<td>`[30, 30, 37]`</td>
<td>`1E1E25`</td>
<td><ColorSwatch value="rgb(30,30,37)" /></td>
</tr>
<tr>
<td>`Enum.Material.Brick|Brick`</td>
<td>`[138, 86, 62]`</td>
<td>`8A563E`</td>
<td><ColorSwatch value="rgb(138,86,62)" /></td>
</tr>
<tr>
<td>`Enum.Material.Cobblestone|Cobblestone`</td>
<td>`[132, 123, 90]`</td>
<td>`847B5A`</td>
<td><ColorSwatch value="rgb(132,123,90)" /></td>
</tr>
<tr>
<td>`Enum.Material.Concrete|Concrete`</td>
<td>`[127, 102, 63]`</td>
<td>`7F663F`</td>
<td><ColorSwatch value="rgb(127,102,63)" /></td>
</tr>
<tr>
<td>`Enum.Material.CrackedLava|CrackedLava`</td>
<td>`[232, 156, 74]`</td>
<td>`E89C4A`</td>
<td><ColorSwatch value="rgb(232,156,74)" /></td>
</tr>
<tr>
<td>`Enum.Material.Glacier|Glacier`</td>
<td>`[101, 176, 234]`</td>
<td>`65B0EA`</td>
<td><ColorSwatch value="rgb(101,176,234)" /></td>
</tr>
<tr>
<td>`Enum.Material.Grass|Grass`</td>
<td>`[106, 127, 63]`</td>
<td>`6A7F3F`</td>
<td><ColorSwatch value="rgb(106,127,63)" /></td>
</tr>
<tr>
<td>`Enum.Material.Ground|Ground`</td>
<td>`[102, 92, 59]`</td>
<td>`665C3B`</td>
<td><ColorSwatch value="rgb(102,92,59)" /></td>
</tr>
<tr>
<td>`Enum.Material.Ice|Ice`</td>
<td>`[129, 194, 224]`</td>
<td>`81C2E0`</td>
<td><ColorSwatch value="rgb(129,194,224)" /></td>
</tr>
<tr>
<td>`Enum.Material.LeafyGrass|LeafyGrass`</td>
<td>`[115, 132, 74]`</td>
<td>`73844A`</td>
<td><ColorSwatch value="rgb(115,132,74)" /></td>
</tr>
<tr>
<td>`Enum.Material.Limestone|Limestone`</td>
<td>`[206, 173, 148]`</td>
<td>`CEAD94`</td>
<td><ColorSwatch value="rgb(206,173,148)" /></td>
</tr>
<tr>
<td>`Enum.Material.Mud|Mud`</td>
<td>`[58, 46, 36]`</td>
<td>`3A2E24`</td>
<td><ColorSwatch value="rgb(58,46,36)" /></td>
</tr>
<tr>
<td>`Enum.Material.Pavement|Pavement`</td>
<td>`[148, 148, 140]`</td>
<td>`94948C`</td>
<td><ColorSwatch value="rgb(148,148,140)" /></td>
</tr>
<tr>
<td>`Enum.Material.Rock|Rock`</td>
<td>`[102, 108, 111]`</td>
<td>`666C6F`</td>
<td><ColorSwatch value="rgb(102,108,111)" /></td>
</tr>
<tr>
<td>`Enum.Material.Salt|Salt`</td>
<td>`[198, 189, 181]`</td>
<td>`C6BDB5`</td>
<td><ColorSwatch value="rgb(198,189,181)" /></td>
</tr>
<tr>
<td>`Enum.Material.Sand|Sand`</td>
<td>`[143, 126, 95]`</td>
<td>`8F7E5F`</td>
<td><ColorSwatch value="rgb(143,126,95)" /></td>
</tr>
<tr>
<td>`Enum.Material.Sandstone|Sandstone`</td>
<td>`[137, 90, 71]`</td>
<td>`895A47`</td>
<td><ColorSwatch value="rgb(137,90,71)" /></td>
</tr>
<tr>
<td>`Enum.Material.Slate|Slate`</td>
<td>`[63, 127, 107]`</td>
<td>`3F7F6B`</td>
<td><ColorSwatch value="rgb(63,127,107)" /></td>
</tr>
<tr>
<td>`Enum.Material.Snow|Snow`</td>
<td>`[195, 199, 218]`</td>
<td>`C3C7DA`</td>
<td><ColorSwatch value="rgb(195,199,218)" /></td>
</tr>
<tr>
<td>`Enum.Material.WoodPlanks|WoodPlanks`</td>
<td>`[139, 109, 79]`</td>
<td>`8B6D4F`</td>
<td><ColorSwatch value="rgb(139,109,79)" /></td>
</tr>
<tr>
<td>`Enum.Material.Water|Water`</td>
<td>`[12, 84, 92]`</td>
<td>`0C545C`</td>
<td><ColorSwatch value="rgb(12,84,92)" /></td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>
4. In the 3D viewport, move/resize the **selection region** in which to generate terrain. Alternatively, enter values into the **Select** tool fields to set a more specific position and size.
<Alert severity="info">
Minimum and maximum terrain heights depend on the darkest and lightest areas of the heightmap image in relation to the **Y** size (height) of the selection region. For instance, if you choose a height of 128, pure black areas are 64 studs below the center position and pure white areas are 64 studs above the center position.
</Alert>
5. Click the **Generate** button.
<video src="../assets/studio/terrain-editor/Import-Tool.mp4" controls width="800" alt="Video of terrain generating automatically via the Import tool"></video>
### Scripting
You can script terrain generation using the `Class.Terrain` class. For example, to create terrain with grass material that fills a volume, you can use methods such as `Class.Terrain:FillBall()|FillBall()`, `Class.Terrain:FillBlock()|FillBlock()`, `Class.Terrain:FillCylinder()|FillCylinder()`, `Class.Terrain:FillRegion()|FillRegion()`, or `Class.Terrain:FillWedge()|FillWedge()`.
```lua title="Fill Block Volume"
local Workspace = game:GetService("Workspace")
Workspace.Terrain:FillBlock(CFrame.new(0, 0, 0), Vector3.new(4, 4, 4), Enum.Material.Grass)
```
## Large-scale editing
The editor's **Edit** tab contains tools for large-scale editing.
### Select regions
The **Select** tool is the universal tool for selecting rectangular regions of terrain.
<img src="../assets/studio/terrain-editor/Edit-Tab-Select.png" width="360" alt="Select tool indicated in Edit tab of Terrain Editor" />
Select a region by clicking and dragging in the 3D viewport, reposition it with the **move** draggers, and edit its size with the **scale** handles. Alternatively, enter values into the tool's **X**/**Y**/**Z** inputs to set a specific position and size.
<figure>
<img src="../assets/studio/terrain-editor/Select-Region-Labeled.jpg" width="800" alt="Move draggers and scale handles on a selected region" />
<figcaption>Move draggers and scale handles on a selected region</figcaption>
</figure>
Studio also supports the following keyboard and mouse shortcuts, assuming the Select tool is active and nothing is selected in the **Explorer** window.
<table size="small">
<thead>
<tr>
<th>Windows</th>
<th>Mac</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><kbd>Ctrl</kbd><kbd>C</kbd></td>
<td><kbd>⌘</kbd><kbd>C</kbd></td>
<td>Copy terrain within the selected region to the clipboard.</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd><kbd>V</kbd></td>
<td><kbd>⌘</kbd><kbd>V</kbd></td>
<td>Paste terrain that has been copied to the clipboard and swap to the Transform tool so that the new terrain can be transformed.</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd><kbd>X</kbd></td>
<td><kbd>⌘</kbd><kbd>X</kbd></td>
<td>Cut terrain within the selected region to the clipboard.</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd><kbd>D</kbd></td>
<td><kbd>⌘</kbd><kbd>D</kbd></td>
<td>Duplicate terrain within the selected region and swap to the Transform tool so that the new terrain can be transformed.</td>
</tr>
<tr>
<td><kbd>Delete</kbd></td>
<td><kbd>Delete</kbd></td>
<td>Delete terrain within the selected region.</td>
</tr>
<tr>
<td><kbd>Shift</kbd></td>
<td><kbd>Shift</kbd></td>
<td>When held down while dragging any **scale** handle, scales the region proportionally across all other axes.</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd></td>
<td><kbd>⌘</kbd></td>
<td>When held down while dragging any **scale** handle, scales the region equally in both the positive and negative direction along that axis.</td>
</tr>
</tbody>
</table>
### Transform regions
The **Transform** tool lets you manipulate entire selected regions to a new position, size, or orientation.
To transform a region:
1. Select a region and then activate the **Transform** tool. Note that the tool will be automatically activated if you paste or duplicate terrain.
<img src="../assets/studio/terrain-editor/Edit-Tab-Transform.png" width="360" alt="Transform tool indicated in Edit tab of Terrain Editor" />
1. In the 3D viewport, transform the region with the **move** draggers, **rotate** rings, and **scale** handles. Alternatively, enter values into the tool's **X**/**Y**/**Z** inputs to set a specific position, size, and rotation.
<img src="../assets/studio/terrain-editor/Transform-Region-Labeled.jpg" width="780" alt="Move draggers, scale handles, and rotate rings on the Y axis of a selected region" />
<Alert severity="info">
Holding <kbd>Shift</kbd> while dragging any **scale** handle scales the region proportionally across all other axes, and holding <kbd>Ctrl</kbd> or <kbd>⌘</kbd> while dragging scales the region equally in both the positive and negative direction along that axis.
Holding <kbd>Shift</kbd> while dragging any **rotate** ring toggles between rotation snapping or free‑form rotation.
</Alert>
<Alert severity="success">
By default, this tool uses **Live Edit** mode to constantly update terrain as you transform it. To view only a wireframe preview of the terrain as you transform it, disable live edit mode and then, while transforming, press <kbd>Enter</kbd>/<kbd>Return</kbd> or click the **Apply** button to apply the changes.
</Alert>
### Fill and replace regions
The **Fill** tool lets you fill an entire selected region with a specific material, or replace all material within the region with another material.
1. Select a region, then activate the **Fill** tool.
<img src="../assets/studio/terrain-editor/Edit-Tab-Fill.png" width="360" alt="Fill tool indicated in Edit tab of Terrain Editor" />
1. In the tool's **Material Settings** section:
- To fill the region with a specific material, select **Fill** and choose the desired material.
- To replace all terrain of one material with another material, select **Replace**, then choose a **source** material and **target** material.
1. Click the **Apply** button or press <kbd>Enter</kbd>/<kbd>Return</kbd>.
<figure>
<img src="../assets/studio/terrain-editor/Fill-Region.jpg" width="780" alt="Region filled with Salt material" />
<figcaption>Selected region filled with Salt material</figcaption>
</figure>
### Set sea level
The **Sea Level** tool lets you create a consistent water level or remove all water within a region.
1. Activate the **Sea Level** tool.
<img src="../assets/studio/terrain-editor/Edit-Tab-Sea-Level.png" width="360" alt="Sea Level tool indicated in Edit tab of Terrain Editor" />
1. Select the intended region by clicking and dragging the **move** draggers and **scale** handles in the 3D viewport. Alternatively, enter values into the tool's **X**/**Y**/**Z** inputs to set a specific position and size.
1. Click the **Evaporate** button to remove water inside the selected region, or click the **Create** button to fill the selected region with water.
<video src="../assets/studio/terrain-editor/Sea-Level-Tool.mp4" controls width="800" alt="Video of sea level being created and modified using the Sea Level tool"></video>
## Detailed editing
The **Edit** tab also contains tools for precision editing using a "brush" tool to draw, sculpt, smooth, flatten, or paint terrain.
<img src="../assets/studio/terrain-editor/Edit-Tab-Detail-Tools.png" width="360" alt="Detailed editing tools indicated in Edit tab of Terrain Editor" />
Each tool lets you choose from a **sphere**, **box**, or **cylinder** brush shape and a base size between 1–64 studs.
<img src="../assets/studio/terrain-editor/Brush-Shape-Size.png" width="360" alt="Brush shape and size controls in the Terrain Editor" />
For tools which use the brush, Studio supports the following keyboard and mouse shortcuts.
<table size="small">
<thead>
<tr>
<th>Windows</th>
<th>Mac</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><kbd>Ctrl</kbd></td>
<td><kbd>⌘</kbd></td>
<td>When held down while using the [Draw](../studio/terrain-editor.md#draw) and [Sculpt](../studio/terrain-editor.md#sculpt) tools, toggles on the alternate brush mode. For example, toggles on "subtract" mode instead of the default "add" mode.</td>
</tr>
<tr>
<td><kbd>Shift</kbd></td>
<td><kbd>Shift</kbd></td>
<td>When held down while using the [Draw](../studio/terrain-editor.md#draw) and [Sculpt](../studio/terrain-editor.md#sculpt) tools, temporarily activates the [Smooth](../studio/terrain-editor.md#smooth) tool.</td>
</tr>
<tr>
<td><kbd>B</kbd></td>
<td><kbd>B</kbd></td>
<td>When held down while dragging the mouse or using the scroll wheel, adjusts the brush's **base size**.</td>
</tr>
<tr>
<td><kbd>Ctrl</kbd><kbd>B</kbd></td>
<td><kbd>⌘</kbd><kbd>B</kbd></td>
<td>When held down while dragging the mouse or using the scroll wheel, adjusts the brush's **height**. Only applies if the brush's shape is set to **box** or **cylinder**.</td>
</tr>
<tr>
<td><kbd>Shift</kbd><kbd>B</kbd></td>
<td><kbd>Shift</kbd><kbd>B</kbd></td>
<td>When held down while dragging the mouse or using the scroll wheel, adjusts the brush's **strength**. Only applies when using the [Sculpt](../studio/terrain-editor.md#sculpt), [Smooth](../studio/terrain-editor.md#smooth), or [Flatten](../studio/terrain-editor.md#flatten) tool.</td>
</tr>
<tr>
<td><kbd>Alt</kbd></td>
<td><kbd>⌥</kbd></td>
<td>When held down on mouse click, shows the material picker.</td>
</tr>
</tbody>
</table>
### Draw
The **Draw** tool **adds** or **subtracts** terrain using the brush. This tool functions in a dual mode where holding down <kbd>Ctrl</kbd> or <kbd>⌘</kbd> toggles on "subtract" mode instead of the default "add" mode. Additionally, holding down <kbd>Shift</kbd> temporarily activates the [Smooth](../studio/terrain-editor.md#smooth) tool.
<video src="../assets/studio/terrain-editor/Draw-Tool.mp4" controls width="800" alt="Video of terrain being added and subtracted using the Draw tool"></video>
### Sculpt
The **Sculpt** tool **adds** or **subtracts** terrain using the brush. Unlike the Draw tool, this tool includes a **strength** slider to allow for more gentle manipulation of terrain.
Similar to the Draw tool, the Sculpt tool functions in a dual mode where holding down <kbd>Ctrl</kbd> or <kbd>⌘</kbd> toggles on "subtract" mode instead of the default "add" mode. Additionally, holding down <kbd>Shift</kbd> temporarily activates the Smooth tool.
<video src="../assets/studio/terrain-editor/Sculpt-Tool.mp4" controls width="800" alt="Video of terrain being added and subtracted using the Sculpt tool"></video>
### Smooth
The **Smooth** tool smoothes out abrupt edges in terrain using the brush. This tool can be used in standalone mode, or you can toggle it on by holding <kbd>Shift</kbd> while using the Draw or Sculpt tools.
<video src="../assets/studio/terrain-editor/Smooth-Tool.mp4" controls width="800" alt="Video of terrain being smoothed using the Smooth tool"></video>
### Flatten
The **Flatten** tool flattens terrain to a consistent level across a visualized plane. By default, the tool lowers terrain above the plane **and** raises terrain below to the plane, but you can opt to selectively lower **or** raise through the tool's **Flatten&nbsp;Mode** option.
<video src="../assets/studio/terrain-editor/Flatten-Tool.mp4" controls width="800" alt="Video of terrain being flattened to a plane using the Flatten tool"></video>
### Paint
The **Paint** tool, using the brush, **paints** a terrain material over an existing material or **replaces** one material with another material.
<video src="../assets/studio/terrain-editor/Paint-Tool.mp4" controls width="800" alt="Video of terrain being painted and replaced using the Paint tool"></video>

157
.cursor/rules/roblox/parts/textures-decals.md Normal file
View file

@ -0,0 +1,157 @@
---
title: Textures and decals
description: Textures and decals are images you can place on object surfaces.
---
A `Class.Texture` is an image you can place on any face of a [part](../parts/index.md) or [union](./solid-modeling.md) that **repeats** both horizontally and vertically on the size of the surface. In contrast, a `Class.Decal` is an image that **stretches** to fit the area of a part or union's surface. After you
add a `Class.Texture` or `Class.Decal` object to a part or union, you can:
- Change the texture or decal `Class.Decal.Color3|Color3` property to set a color tint using RGB color codes.
- Change the texture or decal `Class.Decal.Transparency|Transparency` property to a value between the default of **0** (fully visible) and **1** (invisible).
- For a texture, set its [scale](#scale-textures) and [offset](#offset-textures).
<Grid container spacing={4}>
<Grid item>
<figure>
<img src="../assets/modeling/textures-decals/Decal-Texture-Sample-2.png" alt="An example texture image of a light blue hexagon on top of a dark blue background." width="324" />
<figcaption>Texture image</figcaption>
</figure>
</Grid>
<Grid item>
<figure>
<img src="../assets/modeling/textures-decals/Texture-On-Surface.jpg" alt="The same blue texture repeated eight times on a block part." width="450" />
<figcaption>Texture applied to a part (repeating)</figcaption>
</figure>
</Grid>
</Grid>
<Grid container spacing={4}>
<Grid item>
<figure>
<img src="../assets/modeling/textures-decals/Decal-Texture-Sample-1.png" alt="An example decal image of a light purple hexagon on top of a dark purple background." width="324" />
<figcaption>Texture image</figcaption>
</figure>
</Grid>
<Grid item>
<figure>
<img src="../assets/modeling/textures-decals/Decal-On-Surface.jpg" alt="The same blue texture repeated eight times on a block part." width="450" />
<figcaption>Texture applied to a part (repeating)</figcaption>
</figure>
</Grid>
</Grid>
## Create textures or decals
To create a texture or decal, you must add either a `Class.Texture` or `Class.Decal` object to a part or union. You can [import](../projects/assets/manager.md#asset-import) images for textures and decals to Studio for use between experiences, and [distribute](../production/creator-store.md) them to the [Creator Store](../production/creator-store.md). Once you import the image, Studio assigns it a unique asset ID.
<Alert severity="info">
Every texture or decal image that you create and import to Roblox must adhere to the <a href='https://en.help.roblox.com/hc/articles/203313410'>Community Rules</a> and <a href='https://en.help.roblox.com/hc/articles/115004647846'>Terms of Use</a>.
</Alert>
To add a texture or decal to a [part](../parts/index.md) or [union](./solid-modeling.md):
1. In the [Explorer](../studio/explorer.md) window, add a `Class.Texture` or `Class.Decal` to the part or union. An empty texture or decal object displays on the part or union with orange outlining.
2. In the [Properties](../studio/properties.md) window, navigate to the `Class.FaceInstance.Face|Face` property and choose a face (`Enum.NormalId|Top`, `Enum.NormalId|Bottom`, `Enum.NormalId|Front`, `Enum.NormalId|Back`, `Enum.NormalId|Left`, or `Enum.NormalId|Right`).
- <Chip label="OPTIONAL" size="small" variant="outlined" /> To assist in choosing the correct face, right-click the part/union and select **Show Orientation Indicator**. This displays a circle **🅕**, a blue line attached to the object's front face, and a green arrow that points in the direction of the object's top face.
<img src="../assets/modeling/textures-decals/Orientation-Indicator.jpg" alt="" width="600" />
3. Select the `Class.Decal.ColorMapContent|ColorMapContent` property and apply an image through any of the following methods:
- Select any texture or decal you've uploaded previously.
- Enter an [asset ID](../projects/assets/index.md) into the field.
4. <Chip label="OPTIONAL" size="small" variant="outlined" /> Set a color tint by clicking the small box to the left of the `Class.Decal.Color3|Color3` property or by entering a RGB color code.
<Grid container spacing={2}>
<Grid item>
<img src="../assets/studio/properties/Appearance-Color3-Picker.png" alt="A close of view of the Color3 property with the small color box highlighted." width="320" />
</Grid>
<Grid item>
<img src="../assets/studio/properties/Appearance-Color3-RGB-Entry.png" alt="A close of view of the Color3 property with the RGB code highlighted." width="320" />
</Grid>
</Grid>
<GridContainer numColumns="2">
<figure>
<img src="../assets/modeling/textures-decals/Texture-On-Surface.jpg" alt="A block part with a repeating blue hexagon texture on its top face." />
<figcaption>`Class.Decal.Color3|Color3`: [255, 255, 255]</figcaption>
</figure>
<figure>
<img src="../assets/modeling/textures-decals/Texture-Color3-255-0-100.jpg" alt="The same block part with a repeating hexagon texture on its top face, but the hexagons are pink against on dark purple background." />
<figcaption>`Class.Decal.Color3|Color3`: [255, 0, 100]</figcaption>
</figure>
</GridContainer>
5. <Chip label="OPTIONAL" size="small" variant="outlined" /> Set the `Class.Decal.Transparency|Transparency` property to any value between the default of `0` (fully visible) and `1` (invisible).
<GridContainer numColumns="2">
<figure>
<img src="../assets/modeling/textures-decals/Texture-On-Surface.jpg" alt="A block part with a repeating blue hexagon texture on its top face." />
<figcaption>`Class.Decal.Transparency|Transparency`: 0</figcaption>
</figure>
<figure>
<img src="../assets/modeling/textures-decals/Texture-Transparency-0.4.jpg" alt="The same block part with a repeating hexagon texture on its top face, but the hexagons are semi-transparent." />
<figcaption>`Class.Decal.Transparency|Transparency`: 0.6</figcaption>
</figure>
</GridContainer>
## Customize textures
Unlike decals, **textures** provide further functionality to scale, offset, and animate the source image.
### Scale textures
The size of the part doesn't affect the texture. Instead, scaling a part only increases or decreases the number of times the texture repeats.
The `Class.Texture.StudsPerTileU|StudsPerTileU` and `Class.Texture.StudsPerTileV|StudsPerTileV` properties determine the size of each "tile" in studs. `Class.Texture.StudsPerTileU|StudsPerTileU` determines the texture's horizontal size while `Class.Texture.StudsPerTileV|StudsPerTileV` determines the texture's vertical size.
<Tabs>
<TabItem label="StudsPerTileU & StudsPerTileV = 2">
<img src="../assets/modeling/textures-decals/Texture-Sample-Scale-1.png" alt="Texture on a surface of 8x6 studs with size of each tile in 2x2." width="512" height="384" />
</TabItem>
<TabItem label="StudsPerTileU & StudsPerTileV = 4">
<img src="../assets/modeling/textures-decals/Texture-Sample-Scale-2.png" alt="Texture on a surface of 8x6 studs with size of each tile in 4x4." width="512" height="384" />
</TabItem>
</Tabs>
### Offset textures
If you want more control over a texture's position, offset the texture by adjusting the `Class.Texture.OffsetStudsU|OffsetStudsU` (horizontal) and `Class.Texture.OffsetStudsV|OffsetStudsV` (vertical) properties. This is also helpful for [animation](#animate-textures).
<Tabs>
<TabItem label="OffsetStudsU & OffsetStudsV = 0">
<img src="../assets/modeling/textures-decals/Texture-Sample-Offset-1.png" alt="2x2 texture on a surface of 8x6 studs with no offset." width="512" height="384" />
</TabItem>
<TabItem label="OffsetStudsU & OffsetStudsV = 0.5">
<img src="../assets/modeling/textures-decals/Texture-Sample-Offset-2.png" alt="2x2 texture on a surface of 8x6 studs with offset of 0.5x0.5 studs." width="512" height="384" />
</TabItem>
</Tabs>
### Animate textures
Using `Class.TweenService`, you can tween texture properties like `Class.Texture.OffsetStudsU|OffsetStudsU` and `Class.Texture.StudsPerTileV|StudsPerTileV` to achieve animated surfaces. For example, if you apply two fog textures to one container and animate them with the following script, you can achieve the appearance of a layered moving fog.
<figure>
<video src="../assets/modeling/textures-decals/Animated-Textures.mp4" controls width="80%"></video>
<figcaption>Two animated textures near the floor to simulate a moving fog effect</figcaption>
</figure>
```lua
local TweenService = game:GetService("TweenService")
local texture1 = script.Parent.Texture1
local texture2 = script.Parent.Texture2
local tweenInfo1 = TweenInfo.new(8, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, -1)
local tween1 = TweenService:Create(texture1, tweenInfo1, {OffsetStudsV=50})
local tweenInfo2 = TweenInfo.new(7, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, -1, true)
local tween2 = TweenService:Create(texture2, tweenInfo2, {OffsetStudsU=50, StudsPerTileU=55, StudsPerTileV=45})
tween1:Play()
tween2:Play()
```