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

update rules

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

209
.cursor/rules/roblox/en-us/effects/beams.md Normal file
View file

@ -0,0 +1,209 @@
---
title: Beams
description: Beams create a visual, animatable effect between two attachments.
---
A `Class.Beam` is an object that renders a `Class.Texture` between two `Class.Attachment` objects. By setting beam properties, you can:
- Add a [texture](#texture) and [color gradient](#color) to create interesting visuals like waterfalls and force fields.
- Modify a beam's [transparency](#transparency) so that it fades over time.
- Warp its shape by changing the [width](#width) or [curve](#curve) of each attachment point.
- Specify the texture's [length and mode](#texture-lengthmode) to affect how it repeats across the beam's length.
<video src="../assets/lighting-and-effects/beam/Showcase.mp4" controls
width="100%"></video>
## Create beams
Before you begin to create a beam, it's useful to toggle on visibility of attachments so you can see where the beam starts and ends. You can do so by enabling **Show Constraint Details** from Studio's **View** menu.
To create a beam:
1. Create two parts and position them a short distance from each other. One will act as the start of the beam and the other as the end of the beam. Group the parts into a `Class.Model`.
2. In the **Explorer** window, add an `Class.Attachment` object to each part:
1. Hover over one part and click the &CirclePlus; button. A contextual menu displays.
2. From the contextual menu, insert an **Attachment**.
3. Repeat for the other part.
3. In the **Explorer** window, add a `Class.Beam` object to the model:
1. Hover over the model and click the &CirclePlus; button. A contextual menu displays.
2. From the contextual menu, insert a **Beam**.
<img src="../assets/studio/explorer/Model-Beam-Setup.png" width="320" />
4. Select the new **Beam** object and assign its attachments. Ensure you assign each attachment property to a different `Class.Attachment` object.
1. In the **Properties** window, select the **Attachment0** property. Your cursor changes.
2. In the **Explorer** window, select the attachment of the part you want to be the start of your beam.
3. Back in the **Properties** window, select the **Attachment1** property. Your cursor changes.
4. In the **Explorer** window, select the attachment of the part you want to be the end of your beam.
<figure>
<img src="../assets/lighting-and-effects/beam/Default-Beam.png" width="800" />
<figcaption>Default beam between two attachments</figcaption>
</figure>
<Alert severity="warning">
Beams require attachments to function properly. If you remove either attachment object from step 4, the beam stops rendering its texture.
</Alert>
## Customize beams
By experimenting with the following properties, you can customize a beam's visual appearance to make unique gameplay elements like force fields, waterfalls, and pathway obstacles.
<video controls loop muted>
<source src="../assets/tutorials/laser-traps-with-beams/laserTrap_beamExamples.mp4" width="80%" />
</video>
<Alert severity="info">
The visual quality of your beams can change depending on the graphics settings on the player's device. To review your beam across quality levels, it's recommended to open [Studio Settings](../studio/setup.md#customization), search for **Editor Quality Level**, and set it to the both the lowest and highest level after you finish customizing your beam.
</Alert>
### Texture
The `Class.Beam.Texture|Texture` property renders that texture across the length of the beam. You can set a beam's `Class.Beam.Texture|Texture` property to any asset ID. For more information, including how to add or upload your own textures, see [here](../projects/assets/manager.md#asset-import).
<img src="../assets/lighting-and-effects/beam/Texture-Applied.png" alt="A texture of dark gray circles against a grey background emits between two attachments." width="800" />
A beam renders its texture using two triangles drawn between `Class.Beam.Segments|Segments`, and the segments are laid out between the two attachment points' orientation. When you rotate attachment points in different directions, segments also rotate.
<img src="../assets/lighting-and-effects/beam/Attachments-Rotated.png" alt="The same texture from the previous image is now curved because the attachments are in different orientations." width="800" />
### Color
The `Class.Beam.Color|Color` property tints the beam's texture to either a specific hue, or to a gradient `Datatype.ColorSequence` across its entire span.
<Tabs>
<TabItem label="Constant Color">
1. In the **Explorer** window, select the beam.
2. In the **Properties** window, select the **Color** property. You can either:
1. Click on the color square to open the **Colors** pop-up window and select a color.
2. Input three numbers into the RGB color value field.
<img src="../assets/studio/properties/Color-Input-Options.png" alt="" width="320" />
</TabItem>
<TabItem label="Color Gradient">
1. In the **Explorer** window, select the beam.
1. In the **Properties** window, click inside the **Color** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Color-Open-Sequence.png" width="320" alt="Button to open color sequence popup" />
In the color sequence popup, each triangle on the bottom axis is a
**keypoint** that determines the color value of the beam at that
point along its span.
<img src="../assets/studio/general/ColorSequence-White-Keypoints-Labeled.png" width="640" alt="Keypoints labeled in color sequence popup" />
1. Click the keypoint at the start of the color sequence, click the
small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-White.png" width="640" alt="Color sequence popup from red to white" />
1. If you want the beam to change color near the end of its span, click the keypoint at the end of the color sequence, click the small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-Purple.png" width="640" alt="Color sequence popup from red to purple" />
1. For more customization, you can:
- Add another keypoint by clicking anywhere on the graph.
- Make a color change sooner or later within the gradient by dragging an intermediary keypoint to a new position.
- Delete an intermediary keypoint by selecting it and clicking the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
<img src="../assets/studio/general/ColorSequence-Red-Cyan-Purple.png" width="640" alt="Color sequence popup from red to cyan to purple" />
<img src="../assets/lighting-and-effects/beam/ColorSequence-Applied.png" width="800" />
</TabItem>
</Tabs>
### Transparency
The `Class.Beam.Transparency|Transparency` property sets the transparency of the beam as a consistent value or as a `Datatype.NumberSequence` with ranges from **0** (totally opaque) to **1** (fully clear).
<Tabs>
<TabItem label="Constant Opacity">
1. In the **Explorer** window, select the beam.
1. In the **Properties** window, select the **Transparency** property.
1. Input the desired opacity for the beam.
</TabItem>
<TabItem label="Number Sequence">
1. In the **Explorer** window, select the beam.
1. In the **Properties** window, click inside the **Transparency** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Transparency-Open-Sequence.png" width="320" alt="Button to open number sequence popup" />
In the number sequence popup, each square at the start and end of the graph is a **keypoint** that determines the opacity value of the beam at that
point along its span. By default, the graph defaults to a straight line and the beam is of consistent opacity.
<img src="../assets/studio/general/NumberSequence-0.5-0.5-Keypoints-Labeled.png" width="746" alt="Keypoints labeled in number sequence popup" />
1. Perform any of the following actions:
- To change the opacity at a point, click on a keypoint and either
drag it up or down, or enter a value in the **Value** field.
- To insert a new keypoint, click on any point in the graph.
- To delete a keypoint, select it and click the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
<img src="../assets/studio/general/NumberSequence-0-1-0.png" width="746" alt="Number sequence popup from 0 to 1 to 0" />
<img src="../assets/lighting-and-effects/beam/Transparency-Applied.png" width="800" />
</TabItem>
</Tabs>
### Width
You can set the beam's width in studs at each endpoint by configuring the
`Class.Beam.Width0|Width0` and `Class.Beam.Width1|Width1` properties. A higher value equates to a larger width and a lower value equates to a smaller width. If you set either value to smaller than 0, Studio sets it back to **0**.
The beam below has a `Class.Beam.Width0|Width0` value of **0.5** and a
`Class.Beam.Width1|Width1` value of **3**.
<img src="../assets/lighting-and-effects/beam/Width-Adjusted.png" alt="A texture emits between two attachments. The texture starts with a small width and ends with a large width." width="800" />
### Texture length/mode
A beam's `Class.Beam.TextureLength|TextureLength` and `Class.Beam.TextureMode|TextureMode` determine how its [texture](#texture) repeats across its length.
When `Class.Beam.TextureMode|TextureMode` is set to `Enum.TextureMode.Wrap` or `Enum.TextureMode.Static`, the texture repetitions will equal the beam's overall length (in&nbsp;studs) divided by its `Class.Beam.TextureLength|TextureLength`.
<img src="../assets/engine-api/enums/TextureMode/Wrap-Static.png" width="720" alt="TextureMode diagram with Wrap or Static mode" />
<figure>
When `Class.Beam.TextureMode|TextureMode` is set to `Enum.TextureMode.Stretch`, the texture will repeat `Class.Beam.TextureLength|TextureLength` times across the beam's overall length.
<img src="../assets/engine-api/enums/TextureMode/Stretch.png" width="720" alt="TextureMode diagram with Stretch mode" />
</figure>
### Facing
A beam is a 2D projection existing in 3D space, meaning that it may not be visible from every angle. The `Class.Beam.FaceCamera|FaceCamera` property, when set to `true`, ensures that the beam always faces the `Class.Workspace.CurrentCamera|CurrentCamera`, regardless of its orientation.
<figure>
<video src="../assets/lighting-and-effects/beam/FaceCamera.mp4" controls width="800"></video>
<figcaption>Default vs. FaceCamera</figcaption>
</figure>
### Curve
Beams are configured to use a cubic Bézier curve formed by four control points. This means they are not constrained to straight lines and the curve of the beam can be modified by changing `Class.Beam.CurveSize0|CurveSize0`, `Class.Beam.CurveSize1|CurveSize1`, and the orientation of the beam's `Class.Attachment|Attachments`.
- **P0** — The start of the beam; position of `Class.Beam.Attachment0|Attachment0`.
- **P1** — `Class.Beam.CurveSize0|CurveSize0` studs away from `Class.Beam.Attachment0|Attachment0`, in the positive **X** direction of `Class.Beam.Attachment0|Attachment0`.
- **P2** — `Class.Beam.CurveSize1|CurveSize1` studs away from `Class.Beam.Attachment1|Attachment1`, in the negative **X** direction of `Class.Beam.Attachment1|Attachment1`.
- **P3** — The end of the beam; position of `Class.Beam.Attachment1|Attachment1`.
<img src="../assets/engine-api/classes/Beam/Curvature-Diagram.png" width="800" alt="Beam curvature diagram" />
<img src="../assets/lighting-and-effects/beam/Curves-Applied.png" alt="" width="800" />

162
.cursor/rules/roblox/en-us/effects/highlighting.md Normal file
View file

@ -0,0 +1,162 @@
---
title: Highlighting objects
description: Highlighting objects lets you call attention to specific objects within your experience.
---
The `Class.Highlight` instance is a visual effect which you can use to call attention to a specific object within an experience. Every highlight effect has a silhouette **outline** that surrounds the object and a solid overlay
**interior** that displays over the object. You can customize both of these components independently to modify the highlight's visual appearance.
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/OutlineTransparency-1.jpg" alt="A tree mesh against a grey background." />
<figcaption>Base object</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/Overview-Yellow-Outline.jpg" alt="The same tree mesh with a yellow outline and a black highlight interior." />
<figcaption>Yellow outline and black interior</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/Overview-Yellow-Interior.jpg" alt="The same tree mesh with a black outline and a yellow highlight interior." />
<figcaption>Black outline and yellow interior</figcaption>
</figure>
</GridContainer>
Useful applications of the highlight effect include:
- Providing visual feedback that an object is important and/or interactable.
- Making distant objects visible through objects that are closer to the user.
- Indicating the current position and status of other characters.
## Add highlights
As a performance limit, Studio only displays 31 simultaneous `Class.Highlight` instances on the client-side at a time. If you add more than this limit, the additional `Class.Highlight` instances are silently ignored.
Note also that highlights on low-end devices may be more pixelated but will otherwise look the same as on other devices with any combination of settings.
### Parent to objects
To add a highlight effect to an object, you can parent a new `Class.Highlight` directly to the object.
1. In the **Explorer** window, hover over either a `Class.Model` or a `Class.BasePart`, then click the &CirclePlus; button. A contextual menu displays.
2. From the menu, insert a **Highlight**. The highlight displays on the object with its default property values that create a white outline and a red tint overlay.
<img src="../assets/ui/highlighting-objects/Adding-Highlight.jpg" alt="" width="320" />
### Set the adornee
Alternatively, you can place the `Class.Highlight` instance outside of a child/parent relationship either within the workspace, `Class.StarterPlayer`, `Class.StarterGui`, `Class.StarterPack`, or `Class.ReplicatedStorage`, then set its `Class.Highlight.Adornee|Adornee` property to the `Class.Model` or `Class.BasePart` that you want to highlight.
## Customize highlights
You can change the properties of a `Class.Highlight` instance to create interesting visual effects that properly highlight objects in theme with your experience.
### OutlineColor
The `Class.Highlight.OutlineColor|OutlineColor` property sets the `Datatype.Color3` value of the highlight's outline.
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/OutlineColor-Red.jpg" alt="A tree mesh with red outline." />
<figcaption>OutlineColor = [255, 100, 50]</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/OutlineColor-Green.jpg" alt="A tree mesh with green outline." />
<figcaption>OutlineColor = [0, 255, 125]</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/OutlineColor-Blue.jpg" alt="A tree mesh with blue outline." />
<figcaption>OutlineColor = [75, 150, 255]</figcaption>
</figure>
</GridContainer>
### OutlineTransparency
The `Class.Highlight.OutlineTransparency|OutlineTransparency` property sets the visibility of the highlight's outline to any value between the default value of **0** (opaque) and **1** (invisible).
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/OutlineTransparency-0.jpg" alt="A tree mesh with black opaque outline."/>
<figcaption>OutlineTransparency = 0</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/OutlineTransparency-1.jpg" alt="A tree mesh with transparent outline." />
<figcaption>OutlineTransparency = 1</figcaption>
</figure>
</GridContainer>
### FillColor
The `Class.Highlight.FillColor|FillColor` property sets the `Datatype.Color3` value of the highlight's interior.
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/FillColor-Red.jpg" alt="A tree mesh with a red fill." />
<figcaption>FillColor = [255, 100, 50]</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/FillColor-Green.jpg" alt="A tree mesh with a red fill." />
<figcaption>FillColor = [0, 255, 125]</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/FillColor-Blue.jpg" alt="A tree mesh with a blue fill." />
<figcaption>FillColor = [75, 150, 255]</figcaption>
</figure>
</GridContainer>
### FillTransparency
The `Class.Highlight.FillTransparency|FillTransparency` property sets the visibility of the highlight's interior to any value between the default value of **0** (opaque) and **1** (invisible). You can use this property to determine how much of the object's existing color you want viewers to see.
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/FillTransparency-0.jpg" alt="A tree mesh with an opaque black fill." />
<figcaption>FillTransparency = 0</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/FillTransparency-Half.jpg" alt="A tree mesh with an semi-transparent black fill." />
<figcaption>FillTransparency = 0.5</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/FillTransparency-1.jpg" alt="A tree mesh with a transparent black fill." />
<figcaption>FillTransparency = 1</figcaption>
</figure>
</GridContainer>
### DepthMode
The `Class.Highlight.DepthMode|DepthMode` property controls how the effect displays with respect to other objects in the world.
- `Enum.HighlightDepthMode.AlwaysOnTop|AlwaysOnTop` — Allows the highlight to display regardless if there are objects between the camera and the highlighted object. This means the viewer is always able to see the highlight regardless of what is between the highlighted object and the camera.
- `Enum.HighlightDepthMode.Occluded|Occluded` — Hides the highlight if there are objects between the camera and the highlighted object. This means the viewer is only able to see the object if there are no obstructing objects between the highlighted object and the camera's view.
<Tabs>
<TabItem label="AlwaysOnTop">
<img src="../assets/ui/highlighting-objects/DepthMode-AlwaysOnTop.jpg" alt="Two objects are behind pillars, but because their AlwayOnTop property is set to true, you can still see the objects and their highlight." width="800" height="450" />
</TabItem>
<TabItem label="Occluded">
<img src="../assets/ui/highlighting-objects/DepthMode-Occluded.jpg" alt="Two objects are behind pillars, but because their Occuluded property is set to true, you can only see the objects and their highlight in areas where they are unobstructed." width="800" height="450" />
</TabItem>
</Tabs>
### Enabled
The `Class.Highlight.Enabled|Enabled` property allows you to quickly enable or disable the highlight **without any impact on performance**.
<Alert severity="warning">
While a disabled `Class.Highlight` doesn't display, it still takes one of the 31 available `Class.Highlight` slots. If you plan to permanently disable a `Class.Highlight` instance, it's best to delete the highlight rather than disable it.
</Alert>
## Performance tips
While you have a lot of options to customize `Class.Highlight` instances, the following tips are recommended to increase your experience's performance on all devices:
- Adding or removing a `Class.Highlight` can cause a geometry rebuilding step that might lead to performance spikes and extra draw calls. If you want to change a `Class.Highlight` instance's appearance or temporarily hide/display it on an object, it's best to customize the properties of the `Class.Highlight` instance directly, as changing any property of the `Class.Highlight` instance is lightweight and doesn't impact performance.
- Roblox draws objects in a back to front order, which can cause problems if you embed objects with a child `Class.Highlight` inside other objects that also have children `Class.Highlight` instances. For this reason, it's best to keep objects with `Class.Highlight` instances outside of a parent/child relationship with other objects with `Class.Highlight` instances.
- The first `Class.Highlight` rendered on the screen incurs most of the performance cost (up to 1 millisecond of GPU time on mobile devices). For additional highlights beyond the first, you should not see a significant performance impact on any platform.
- On mobile devices, highlights are more costly on performance when they cover more of the screen. On other platforms, highlights have the same performance cost regardless of their screen coverage.
- On all platforms, highlights that are not visible on the screen (whether disabled or fully transparent) incur no performance cost.

89
.cursor/rules/roblox/en-us/effects/index.md Normal file
View file

@ -0,0 +1,89 @@
---
title: Effects
description: Learn how to add visual effects to your experiences.
---
You can create special effects by parenting special effect objects to other
objects or attachments.
## Light sources
Light sources let you attach lighting effects to objects or attachments. There
are three types of light sources:
- A `Class.PointLight`
emits light spherically from a single point. This object is ideal for
non-directional lights like bulbs, torches, and fireballs.
- A `Class.SpotLight`
emits light in the shape of a cone with a spherical base. This object is ideal
for directional lights like street lamps, flashlights, and headlights.
- A `Class.SurfaceLight` emits light from the face of a BasePart. This object is
ideal for lighting from TV or computer screens, billboards, and fluorescent
panels.
<GridContainer numColumns="3">
<figure>
<img src="../assets/lighting-and-effects/light-sources/PointLight-Range-8.jpg" alt="" />
<figcaption>Point lights</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/light-sources/SpotLight-Face-Bottom.jpg" alt="" />
<figcaption>Spotlights</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/light-sources/SurfaceLight-Angle-0.jpg" alt="" />
<figcaption>Surface lights</figcaption>
</figure>
</GridContainer>
## Particle emitters
A [particle emitter](../effects/particle-emitters.md) is an object that emits customizable 2D images (particles) into the world, useful for simulating special effects like fire, smoke, and sparks.
<video src="../assets/lighting-and-effects/particle-emitter/Showcase.mp4"
controls width="100%"></video>
## Beams
A [beam](../effects/beams.md) is an object that renders a texture between two
`Class.Attachment` objects `Class.Beam.Attachment0` and
`Class.Beam.Attachment1`. By setting beam properties, you can:
- Add a [texture](../effects/beams.md#texture) and [color gradient](../effects/beams.md#color) to create interesting visuals like waterfalls and force fields.
- Modify a beam's [transparency](/effects/beams#transparency) so that it fades over time.
- Warp its shape by changing the [width](../effects/beams.md#width) or [curve](../effects/beams.md#curve) of each attachment point.
<video src="../assets/lighting-and-effects/beam/Showcase.mp4" controls
width="100%"></video>
## Trails
A [trail](../effects/trails.md) is an object that creates a trail between and behind two `Class.Attachment` objects as they move through space. Trails can help players visualize movement, such as a sword slashing through the air, projectiles flying to their target, or footprints walking away.
By setting trail properties, you can:
- Add a [texture](../effects/trails.md#texture) to create interesting visuals.
- Set a constant or gradient [color](../effects/trails.md#color).
- Modify a trail's [lifetime](../effects/trails.md#lifetime).
<video src="../assets/lighting-and-effects/trail/Showcase.mp4" controls
width="100%"></video>
## Highlighting
`Class.Highlight` is a visual effect which you can use to call attention to a specific object within an experience, such as to provide visual feedback that the object is important and/or interactable. See [Highlighting Objects](../effects/highlighting.md) for details.
<GridContainer numColumns="3">
<figure>
<img src="../assets/ui/highlighting-objects/OutlineTransparency-1.jpg" alt="A tree mesh against a grey background." />
<figcaption>Base object</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/Adding-Highlight.jpg" alt="The same tree mesh with a white outline and a red highlight interior." />
<figcaption>White outline, 50% red interior</figcaption>
</figure>
<figure>
<img src="../assets/ui/highlighting-objects/Overview-Yellow-Outline.jpg" alt="The same tree mesh with a yellow outline and a black highlight interior." />
<figcaption>Yellow outline, black interior</figcaption>
</figure>
</GridContainer>

156
.cursor/rules/roblox/en-us/effects/light-sources.md Normal file
View file

@ -0,0 +1,156 @@
---
title: Light sources
description: Light sources simulate realistic lighting from objects such as torches, spotlights, and screens.
---
Local light sources simulate realistic lighting from objects such as
lamps, torches, spotlights, and TV screens. By using the different types of
light sources instead of just general global lighting through the `Class.Lighting`
service, you can create immersive environments such as cyberpunk cities,
traditional light festivals, and moody detective scenes.
<img src="../assets/lighting-and-effects/light-sources/Showcase.jpg" alt="A far out view of a diner bulding in the middle of a nighttime city. The diner is utilizing several local light sources." width="800" />
<Alert severity="info">
The `Class.Lighting.LightingStyle|LightingStyle` property, modifiable only in the [Properties](../studio/properties.md) window for the global `Class.Lighting` object, sets your experience's lighting style. For more information, see [Appearance](../environment/lighting.md#appearance).
</Alert>
<Alert severity="success">
To view **light guides** that indicate the color and field of effect from light sources, such as the angle of light emission from the cone's apex of a `Class.SpotLight`, open [Studio Settings](../studio/setup.md#customization) and toggle on **Show Light Guides**.
</Alert>
## Light types
Local light sources include [PointLight](#pointlight), [SpotLight](#spotlight), and [SurfaceLight](#surfacelight). Each [shares various properties](#shared-properties) from the `Class.Light` class, including `Class.Light.Color|Color`, `Class.Light.Brightness|Brightness`, and `Class.Light.Shadows|Shadows`.
### PointLight
A `Class.PointLight` emits light spherically from a single point. This object is ideal for **non-directional** lights like bulbs, torches, and fireballs.
To create a point light in Studio, insert a `Class.PointLight` into an `Class.Attachment` or a `Class.BasePart` (`Class.Attachment` is recommended for point‑specific light emission). Then adjust the object's `Class.PointLight.Range|Range` as well as [shared properties](#shared-properties) like `Class.PointLight.Brightness|Brightness` and `Class.PointLight.Color|Color`.
#### Range
A point light's `Class.PointLight.Range|Range` property defines the radial distance of illumination from the light's position, measured in studs.
<Tabs>
<TabItem label="8">
<img src="../assets/lighting-and-effects/light-sources/PointLight-Range-8.jpg" alt="A street lamp point light with a small range." width="800" height="450" />
</TabItem>
<TabItem label="12">
<img src="../assets/lighting-and-effects/light-sources/PointLight-Range-12.jpg" alt="The same street lamp point light with a larger range." width="800" height="450" />
</TabItem>
</Tabs>
### SpotLight
A `Class.SpotLight` emits light in the shape of a cone with a spherical base. This object is ideal for directional lights like street lamps, flashlights, and headlights.
To create a spotlight in Studio, insert a `Class.SpotLight` into an `Class.Attachment` or a `Class.BasePart` and set its `Class.SpotLight.Face|Face` property to specify which direction light emits from. Then adjust the `Class.SpotLight.Angle|Angle` and `Class.SpotLight.Range|Range`, as well as [shared properties](#shared-properties) like `Class.SpotLight.Brightness|Brightness` and `Class.SpotLight.Color|Color`.
#### Face
A spotlight's `Class.SpotLight.Face|Face` property determines which face/axis light emits from, as shown from the following streetlamp's glowing light part:
<Tabs>
<TabItem label="Bottom">
<img src="../assets/lighting-and-effects/light-sources/SpotLight-Face-Bottom.jpg" alt="A street lamp spotlight that emits light from its bottom face." width="800" height="450" />
</TabItem>
<TabItem label="Left">
<img src="../assets/lighting-and-effects/light-sources/SpotLight-Face-Left.jpg" alt="A street lamp spotlight that emits light from its left face." width="800" height="450" />
</TabItem>
</Tabs>
#### Angle
A spotlight's `Class.SpotLight.Angle|Angle` property defines the angle of light emission from the cone's apex. The maximum value is `180` which illuminates a full half sphere from the apex.
<Tabs>
<TabItem label="30">
<img src="../assets/lighting-and-effects/light-sources/SpotLight-Angle-30.jpg" alt="A street lamp spotlight with a 30 degree angle of emission." width="800" height="450" />
</TabItem>
<TabItem label="75">
<img src="../assets/lighting-and-effects/light-sources/SpotLight-Angle-75.jpg" alt="The same street lamp spotlight with a 75 degree angle of emission." width="800" height="450" />
</TabItem>
</Tabs>
### SurfaceLight
A `Class.SurfaceLight` emits light from the face of a `Class.BasePart`. This object is ideal for lighting from computer screens, billboards, signs, and fluorescent panels.
To create a surface light in Studio, insert a `Class.SurfaceLight` into a `Class.BasePart` and set its `Class.SurfaceLight.Face|Face` property to specify which surface light emits from. Then adjust the `Class.SurfaceLight.Angle|Angle` and `Class.SurfaceLight.Range|Range`, as well as [shared properties](#shared-properties) like `Class.SurfaceLight.Brightness|Brightness` and `Class.SurfaceLight.Color|Color`.
#### Face
A surface light's `Class.SurfaceLight.Face|Face` property determines the face of the `Class.BasePart` from which light emanates. Notice that light emits from the entire surface, not just a point on the surface.
<Tabs>
<TabItem label="Bottom">
<img src="../assets/lighting-and-effects/light-sources/SurfaceLight-Face-Bottom.jpg" alt="A sign surface light that emits light from its bottom face." width="800" height="450" />
</TabItem>
<TabItem label="Right">
<img src="../assets/lighting-and-effects/light-sources/SurfaceLight-Face-Right.jpg" alt="A sign surface light that emits light from its right face." width="800" height="450" />
</TabItem>
</Tabs>
#### Angle
A surface light's `Class.SurfaceLight.Angle|Angle` property defines the angle of light emission from the part's surface. An angle of `0` means that light travels directly outward from the surface while an angle of `180` means light travels outward perpendicular to the surface.
<Tabs>
<TabItem label="0">
<img src="../assets/lighting-and-effects/light-sources/SurfaceLight-Angle-0.jpg" alt="A sign surface light with a 0 degree angle of emission." width="800" height="450" />
</TabItem>
<TabItem label="60">
<img src="../assets/lighting-and-effects/light-sources/SurfaceLight-Face-Right.jpg" alt="A sign surface light with a 60 degree angle of emission." width="800" height="450" />
</TabItem>
</Tabs>
## Shared properties
All light sources share various properties from the `Class.Light` class, including [color](#color), [brightness](#brightness), and [shadows](#shadows).
### Color
The `Class.Light.Color|Color` property sets the `Datatype.Color3` value of the emitted light.
<Tabs>
<TabItem label="[255, 100, 50]">
<img src="../assets/lighting-and-effects/light-sources/Light-Color-255-100-50.jpg" alt="A torch that emits red light." width="600" height="337" />
</TabItem>
<TabItem label="[0, 255, 125]">
<img src="../assets/lighting-and-effects/light-sources/Light-Color-0-255-125.jpg" alt="A torch that emits green light." width="600" height="337" />
</TabItem>
<TabItem label="[75, 150, 255]">
<img src="../assets/lighting-and-effects/light-sources/Light-Color-75-150-255.jpg" alt="A torch that emits blue light." width="600" height="337" />
</TabItem>
</Tabs>
### Brightness
The `Class.Light.Brightness|Brightness` property sets the light's brightness with maximum effect at the center of the light. Note that `Class.Light.Brightness|Brightness` is still limited to the light's defined range, so a higher `Class.Light.Brightness|Brightness` value doesn't light up a larger region around the light.
<Tabs>
<TabItem label="2">
<img src="../assets/lighting-and-effects/light-sources/Light-Brightness-2.jpg" alt="A torch that emits low light." width="600" height="337" />
</TabItem>
<TabItem label="10">
<img src="../assets/lighting-and-effects/light-sources/Light-Brightness-10.jpg" alt="A torch that emits medium light." width="600" height="337" />
</TabItem>
<TabItem label="50">
<img src="../assets/lighting-and-effects/light-sources/Light-Brightness-50.jpg" alt="A torch that emits bright light." width="600" height="337" />
</TabItem>
</Tabs>
### Shadows
The `Class.Light.Shadows|Shadows` property projects shadows where light is blocked by an obstacle.
<Tabs>
<TabItem label="Enabled">
<img src="../assets/lighting-and-effects/light-sources/Light-Shadows-True.jpg" alt="A corner view of the diner with shadows enabled." width="800" height="450" />
</TabItem>
<TabItem label="Disabled">
<img src="../assets/lighting-and-effects/light-sources/Light-Shadows-False.jpg" alt="A corner view of the diner with shadows disabled." width="800" height="450" />
</TabItem>
</Tabs>

534
.cursor/rules/roblox/en-us/effects/particle-emitters.md Normal file
View file

@ -0,0 +1,534 @@
---
title: Particle emitters
description: Particle emitters emit 2D images to simulate special effects like fire, smoke, and sparks.
---
A `Class.ParticleEmitter` is an object that emits customizable 2D images (particles) into the world, useful for simulating special effects like fire, smoke, and sparks.
<video src="../assets/lighting-and-effects/particle-emitter/Showcase.mp4" controls width="100%" alt="Video of particles emitting from a MeshPart in the 3D world"></video>
## Create particle emitters
You can parent a `Class.ParticleEmitter` to an `Class.Attachment` or an object of the `Class.BasePart` class. When parented to a `Class.BasePart`, particles spawn randomly within the part's bounding box or [shape](#shape); when parented to an `Class.Attachment`, particles spawn from the attachment's position.
Additionally, the `Class.ParticleEmitter.EmissionDirection|EmissionDirection` property determines the face (`Enum.NormalId`) of emission when the emitter is parented to a `Class.BasePart`. When you change this property, you consequently change the particle emission direction as well.
<Alert severity="info">
When you rotate an emitter's parent `Class.BasePart`, the orientation of its
face also changes, altering the direction of particle emission. Alternatively,
if you add an emitter to an `Class.Attachment`, you can rotate the attachment
itself instead of using `Class.ParticleEmitter.EmissionDirection|EmissionDirection`.
</Alert>
<video src="../assets/lighting-and-effects/particle-emitter/Emission-Direction.mp4" controls width="800" alt="Video of the particle emission direction changing faces on a parent MeshPart"></video>
To create a particle emitter on a part or attachment:
1. In the **Explorer** window, hover over the part or attachment and click the &CirclePlus; button. A contextual menu displays.
2. From the menu, insert a **ParticleEmitter**. The particle emitter immediately emits particles within the part's area or from the attachment's position.
<img src="../assets/studio/explorer/MeshPart-ParticleEmitter.png" width="320" alt="ParticleEmitter object as child of MeshPart in Explorer hierarchy" />
## Customize particles
By experimenting with the following properties, you can customize a particle's visual appearance to make unique gameplay elements like bursting volcanos, magical dust, and dust motes.
<Alert severity="info">
The visual quality of your particles can change depending on the graphic settings on the player's device. To review your particles across quality levels, it's recommended to open [Studio Settings](../studio/setup.md#customization), search for **Editor Quality Level**, and set it to the both the lowest and highest level after you finish customizing your particles.
</Alert>
### Texture
The `Class.ParticleEmitter.Texture|Texture`
property renders the image that each particle displays. By default,
particle emitters have particles with a white sparkle texture, but you
can change it to any texture to achieve interesting effects.
<figure>
<video src="../assets/lighting-and-effects/particle-emitter/Texture-Examples.mp4" controls width="800" alt="Three similar particle emitters with different Texture assets"></video>
<figcaption>Three similar particle emitters with different `Class.ParticleEmitter.Texture|Texture` assets</figcaption>
</figure>
If you're creating an image to use as a particle texture, it's best to use `.png` format with a transparent background. If your texture is grayscale with no alpha channel, try setting the particle emitter's `Class.ParticleEmitter.LightEmission|LightEmission` property to **1** to hide the darker regions.
<Alert severity="info">
For steps on how to import an image for use as a particle texture,
see [here](../projects/assets/manager.md#asset-import).
</Alert>
To insert an image into a particle emitter:
1. From Studio's **Window** menu or **Home** tab toolbar, open the [Toolbox](../projects/assets/toolbox.md).
2. If you want to insert an image that you have previously imported, click the **Inventory** tab. If you want to insert an image from another creator, click the **Creator Store** tab.
<img src="../assets/studio/toolbox/Inventory-Tab.png" width="360" alt="Inventory tab indicated in Studio's Toolbox" />
<img src="../assets/studio/toolbox/Creator-Store-Tab.png" width="360" alt="Creator Store tab indicated in Studio's Toolbox" />
3. Right-click on the image you want to insert into a particle emitter and select **Copy&nbsp;Asset&nbsp;ID**.
4. In the **Explorer** window, select a `Class.ParticleEmitter`.
5. In the **Properties** window, paste the asset ID into the **Texture** property.
### Color
The `Class.ParticleEmitter.Color|Color` property tints each particle's texture to either a specific hue, or to a gradient `Datatype.ColorSequence` across its [lifetime](#lifetime).
<Tabs>
<TabItem label="Constant Color">
1. In the **Explorer** window, select the `Class.ParticleEmitter`.
1. In the **Properties** window, select the **Color** property. You can either:
1. Click on the color square to open the **Colors** pop-up window and select a color.
2. Input three numbers into the RGB color value field.
<figure>
<img src="../assets/studio/properties/Color-Input-Options.png" width="320" />
<img src="../assets/lighting-and-effects/particle-emitter/Color-Examples.jpg" width="720" alt="Similar particle emitters with different colored particles" />
<figcaption>Similar particle emitters with different colored particles</figcaption>
</figure>
</TabItem>
<TabItem label="Color Gradient">
1. In the **Explorer** window, select the `Class.ParticleEmitter`.
1. In the **Properties** window, click inside the **Color** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Color-Open-Sequence.png" width="320" alt="Button to open color sequence popup" />
In the color sequence popup, each triangle on the bottom axis is a
**keypoint** that determines the color value of the property at that point in
the particle's lifetime.
<img src="../assets/studio/general/ColorSequence-White-Keypoints-Labeled.png" width="640" alt="Keypoints labeled in color sequence popup" />
1. Click the keypoint at the start of the color sequence, click the
small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-White.png" width="640" alt="Color sequence popup from red to white" />
1. If you want particles to change their color near the end of their
lifetime, click the keypoint at the end of the color sequence, click the small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-Purple.png" width="640" alt="Color sequence popup from red to purple" />
1. For more customization, you can:
- Add another keypoint by clicking anywhere on the graph.
- Make a color change sooner or later within the gradient by dragging an intermediary keypoint to a new position.
- Delete an intermediary keypoint by selecting it and clicking the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
</TabItem>
</Tabs>
### Size
The `Class.ParticleEmitter.Size|Size` property sets the size of each particle to a consistent size, or to a `Datatype.NumberSequence` across its [lifetime](#lifetime).
<Tabs>
<TabItem label="Constant Size">
1. In the **Explorer** window, select the `Class.ParticleEmitter`.
1. In the **Properties** window, select the **Size** property.
1. Input the size that you want each particle to be.
</TabItem>
<TabItem label="Number Sequence">
1. In the **Explorer** window, select the `Class.ParticleEmitter`.
1. In the **Properties** window, click inside the **Size** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Size-Open-Sequence.png" width="320" alt="Button to open number sequence popup" />
In the number sequence popup, each square at the start and end of the graph is a **keypoint** that determines the size value of the property at that
point in the particle's lifetime. By default, the graph defaults to a straight line and a particle remains the same size throughout its lifetime.
<img src="../assets/studio/general/NumberSequence-0.5-0.5-Keypoints-Labeled.png" width="746" alt="Keypoints labeled in number sequence popup" />
1. Perform any of the following actions:
- To change the size at a point, click on a keypoint and either
drag it up or down, or enter a value in the **Value** field.
- To insert a new keypoint, click on any point in the graph.
- To delete a keypoint, select it and click the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
- To add a random range for size, click on any keypoint and
drag the **envelope lines** up or down. At that time, particles
generate at a random size between the pink envelope.
<figure>
<img src="../assets/studio/general/NumberSequence-Envelope.png" width="440" alt="Envelope lines indicated in number sequence popup" />
<video src="../assets/lighting-and-effects/particle-emitter/Size-Envelope.mp4" controls width="720" alt="Video of emitter with large size envelope toward end of its lifetime"></video>
<figcaption>Emitter with large size envelope toward end of its lifetime</figcaption>
</figure>
</TabItem>
</Tabs>
<Alert severity="warning">
Particle size can impact performance due to fill-rate. The more pixels particles occupy on a player's screen, the more costly it is on the GPU.
</Alert>
### Transparency
The `Class.ParticleEmitter.Transparency|Transparency` property sets the opacity of each particle as a consistent value, or as a `Datatype.NumberSequence` opacity across its [lifetime](#lifetime). Opacity can range from **0** (totally opaque) to **1** (fully clear). For details on how to set particles to either a specific opacity or to a number sequence, follow the process in customizing [Size](#size) but use the emitter's **Transparency** property field instead.
<Alert severity="success">
The `Class.ParticleEmitter.Transparency|Transparency` property is one of the most vital properties of a particle emitter. Fading particles near the start and/or end of their lifetime avoids a popping in/out effect and provides a more realistic effect.
</Alert>
<figure>
<video src="../assets/lighting-and-effects/particle-emitter/Transparency.mp4" controls width="800" alt="Video of static transparency vs. fading in/out"></video>
<figcaption>Static transparency vs. fading in/out</figcaption>
</figure>
### Lifetime
The `Class.ParticleEmitter.Lifetime|Lifetime`
property sets the lifetime of a particle in seconds. You can set this
property either as a consistent value, or provide a **Min** and **Max**
range from which a random lifetime will be chosen for each particle.
<Alert severity="info">
Particles have a maximum lifetime of 20 seconds. `Class.ParticleEmitter.Lifetime|Lifetime` values higher than this will be internally capped at 20.
</Alert>
### Speed
The `Class.ParticleEmitter.Speed|Speed` property determines a random range of velocities (minimum to maximum) at which new particles will emit, measured in studs per second. Each particle's velocity is chosen upon emission and it applies in the `Class.ParticleEmitter.EmissionDirection|EmissionDirection`. Negative values cause particles to travel in reverse.
Note that changing `Class.ParticleEmitter.Speed|Speed` does not affect active particles and they retain whatever speed they already have. However, `Class.ParticleEmitter.Acceleration|Acceleration`, `Class.ParticleEmitter.Drag|Drag`, and `Class.ParticleEmitter.VelocityInheritance|VelocityInheritance` can be used to affect the speed of active particles over their lifetime.
<video src="../assets/lighting-and-effects/particle-emitter/Speed.mp4" controls width="800" alt="Video of emission speeds set to 0-1 vs. 2-15"></video>
### Rate
The `Class.ParticleEmitter.Rate|Rate` property sets the number of particles that emit per second. A single particle emitter can create up to 400 particles per second (100 per second on mobile). For best performance, keep the particle rate as low as possible and experiment with [size](#size) and [other properties](#other-properties) to achieve the desired visual effect.
<Alert severity="warning">
Particle count can impact performance due to overdraw, especially when particles are overlapping. The more layers of transparent effects on screen, the more costly it is on the GPU.
</Alert>
### Orientation
The `Class.ParticleEmitter.Orientation|Orientation` property determines which
orientation mode to use for an emitter's particle geometry.
<table>
<thead>
<tr>
<td>Orientation</td>
<td>Particle behavior</td>
</tr>
</thead>
<tbody>
<tr>
<td>**FacingCamera**</td>
<td>Standard camera-facing billboard quad; default behavior.</td>
</tr>
<tr>
<td>**FacingCameraWorldUp**</td>
<td>Facing the camera, but rotating only on the vertical upward world **Y** axis.</td>
</tr>
<tr>
<td>**VelocityParallel**</td>
<td>Aligned parallel to their direction of movement.</td>
</tr>
<tr>
<td>**VelocityPerpendicular**</td>
<td>Aligned perpendicular to their direction movement.</td>
</tr>
</tbody>
</table>
<figure>
<video src="../assets/lighting-and-effects/particle-emitter/Orientation.mp4" controls width="800" alt="Video of expected outcome of particle emission Orientation property"></video>
<figcaption>Expected outcome of particle orientation</figcaption>
</figure>
### LightEmission
The `Class.ParticleEmitter.LightEmission|LightEmission` property determines the blending of particle `Class.ParticleEmitter.Texture|Texture` colors with the colors behind them. A value of 0 uses normal blending mode while a value of 1 uses additive blending. Higher values can make particles glow even in environments with low lighting.
<video src="../assets/lighting-and-effects/particle-emitter/LightEmission.mp4" controls width="800" alt="Video showing light emission values of 0 vs. 1"></video>
### SpreadAngle
The `Class.ParticleEmitter.SpreadAngle|SpreadAngle` property has an **X** and a **Y** value which determine the range of angles from which a particle can emit. The range is calculated from both sides around the axes; for example, a value of `(45, 0)` emits particles in a range of 0&deg; to 45&deg; away from the `Class.ParticleEmitter.EmissionDirection|EmissionDirection` across the **X** axis.
<video src="../assets/lighting-and-effects/particle-emitter/SpreadAngle.mp4" controls width="800" alt="Video of X axis spread angle 0° vs. 45°"></video>
### WindAffectsDrag
If you've enabled [global wind](../environment/global-wind.md) in an experience, particles will follow the global wind vector as long as the emitter's `Class.ParticleEmitter.WindAffectsDrag|WindAffectsDrag` property is enabled and its `Class.ParticleEmitter.Drag|Drag` property is greater than 0.
<img src="../assets/studio/properties/ParticleEmitter-WindAffectsDrag.png" width="320" alt="Drag and WindAffectsDrag properties shown in Properties window of Studio" />
### Shape
The `Class.ParticleEmitter.Shape|Shape` property sets the shape of the particle emitter to either a **Box**, **Sphere**, **Cylinder**, or **Disc**.
<GridContainer numColumns="4">
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Shape-Box.jpg" alt="Emitter of Box shape" />
<figcaption>Box</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Shape-Sphere.jpg" alt="Emitter of Sphere shape" />
<figcaption>Sphere</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Shape-Cylinder.jpg" alt="Emitter of Cylinder shape" />
<figcaption>Cylinder</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Shape-Disc.jpg" alt="Emitter of Disc shape" />
<figcaption>Disc</figcaption>
</figure>
</GridContainer>
After you select a shape for your particle emitter, you can experiment
with the [ShapeStyle](#shapestyle), [ShapeInOut](#shapeinout), and
[ShapePartial](#shapepartial) properties to further customize particle
emission.
<Alert severity="warning">
If you parent a particle emitter to an `Class.Attachment`, the **Sphere** and **Cylinder** shapes will not display correctly. These shapes should only be used if the emitter is parented to a `Class.BasePart`.
</Alert>
#### ShapeStyle
The
`Class.ParticleEmitter.ShapeStyle|ShapeStyle`
property sets the emission type to either:
- **Volume** &mdash; Particles emit anywhere within the shape.
- **Surface** &mdash; Particles only emit from the outside of the shape.
<GridContainer numColumns="3">
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Cylinder-Volume.jpg" alt="Emitter of Cylinder shape with Volume shape style" />
<figcaption>Cylinder + Volume</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Cylinder-Surface.jpg" alt="Emitter of Cylinder shape with Surface shape style" />
<figcaption>Cylinder + Surface</figcaption>
</figure>
</GridContainer>
#### ShapeInOut
The `Class.ParticleEmitter.ShapeInOut|ShapeInOut` property sets the emission as follows:
- **Inward** &mdash; Particles emit toward the shape.
- **Outward** &mdash; Particles emit away from the shape.
- **InAndOut** &mdash; Particles randomly behave as both **Inward** and **Outward**.
<video src="../assets/lighting-and-effects/particle-emitter/ShapeInOut.mp4" controls width="800" alt="Particles emitting with different ShapeInOut settings"></video>
#### ShapePartial
The `Class.ParticleEmitter.ShapePartial|ShapePartial` property is a factor you can use to further modify **Cylinder**, **Disc**, and **Sphere** shapes.
<Tabs>
<TabItem label="Cylinder">
For cylinders, `Class.ParticleEmitter.ShapePartial|ShapePartial` multiplies the radius of the cylinder on the side of its **EmissionDirection**.
<GridContainer numColumns="3">
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Cylinder-ShapePartial-0.5.jpg" alt="Emitter of Cylinder shape with ShapePartial value of 0.5" />
<figcaption>ShapePartial = 0.5</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Cylinder-ShapePartial-0.jpg" alt="Emitter of Cylinder shape with ShapePartial value of 0" />
<figcaption>ShapePartial = 0</figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Disc">
For discs, `Class.ParticleEmitter.ShapePartial|ShapePartial` inversely multiplies the **inner radius** of the disc.
<GridContainer numColumns="3">
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Disc-ShapePartial-0.5.jpg" alt="Emitter of Disc shape with ShapePartial value of 0.5" />
<figcaption>ShapePartial = 0.5</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Disc-ShapePartial-0.1.jpg" alt="Emitter of Disc shape with ShapePartial value of 0.1" />
<figcaption>ShapePartial = 0.1</figcaption>
</figure>
</GridContainer>
</TabItem>
<TabItem label="Sphere">
For spheres, `Class.ParticleEmitter.ShapePartial|ShapePartial` multiplies the **hemispherical angle**.
<GridContainer numColumns="3">
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Shape-Sphere.jpg" alt="Emitter of Sphere shape with ShapePartial value of 1" />
<figcaption>ShapePartial = 1</figcaption>
</figure>
<figure>
<img src="../assets/lighting-and-effects/particle-emitter/Sphere-ShapePartial-0.5.jpg" alt="Emitter of Sphere shape with ShapePartial value of 0.5" />
<figcaption>ShapePartial = 0.5</figcaption>
</figure>
</GridContainer>
</TabItem>
</Tabs>
### Squash
The `Class.ParticleEmitter.Squash|Squash` property allows for non-uniform scaling of particles, curve-controlled over their lifetime. Values greater than 0 cause particles to both shrink horizontally and grow vertically, while values less than 0 cause particles to both grow horizontally and shrink vertically. For details on how to set the squash amount to either a constant or to a `Datatype.NumberSequence`, follow the process in customizing [Size](#size) but use the emitter's **Squash** property field instead.
<video src="../assets/lighting-and-effects/particle-emitter/Squash.mp4" controls width="800" alt="Video of particles being gradually squashed over their lifetime"></video>
### Flipbooks
Particle flipbook textures let you animate a particle's texture over its lifetime.
<video src="../assets/lighting-and-effects/particle-emitter/Flipbook.mp4" controls width="800" alt="Flipbook looping over the four particles in its texture"></video>
The flipbook texture can have a frame layout of 2×2, 4×4, 8×8, or custom. For example, the following 1024×1024 image has an 8×8 layout, so it's suitable for a 64‑frame animation.
<img src="../assets/lighting-and-effects/particle-emitter/8x8-Explosion.png" width="512" alt="Sample texture for particle flipbooks" />
<Alert severity="error">
When you create a flipbook texture, include spacing between each of the particle frames. In some cases, mip filtering might require even more spacing. The previous image has transparent spacing around each frame for the flipbook texture.
</Alert>
<Alert severity="warning">
Features with custom textures such as flipbooks cost memory to render. If you use many flipbooks with other features that use high memory, then clients automatically deactivate flipbooks when they are low on memory, which is likely for older mobile phones. To reduce the memory usage of flipbooks, use fewer unique animated particle effects or choose a texture of smaller resolution when possible. Reusing textures costs less memory than using unique textures.
</Alert>
Once you've specified a valid flipbook [texture](#texture) for the emitter's `Class.ParticleEmitter.Texture|Texture` property, the `Class.ParticleEmitter.FlipbookLayout|FlipbookLayout` property determines the layout of the texture. It can be any value of the `Enum.ParticleFlipbookLayout` enum:
- `Enum.ParticleFlipbookLayout|None` &mdash; Disable flipbook features and use the texture as a single static texture over the particle's lifetime.
- `Enum.ParticleFlipbookLayout|Grid2x2` &mdash; 2&times;2 frames for a 4-frame animation.
- `Enum.ParticleFlipbookLayout|Grid4x4` &mdash; 4&times;4 frames for a 16-frame animation.
- `Enum.ParticleFlipbookLayout|Grid8x8` &mdash; 8&times;8 frames for a 64-frame animation.
- `Enum.ParticleFlipbookLayout|Custom` &mdash; A custom grid size defined by `Class.ParticleEmitter.FlipbookSizeX|FlipbookSizeX` and `Class.ParticleEmitter.FlipbookSizeY|FlipbookSizeY`.
To further customize the flipbook behavior, you can adjust the following properties:
<Tabs>
<TabItem label="FlipbookFramerate">
The `Class.ParticleEmitter.FlipbookFramerate|FlipbookFramerate` property determines how fast the flipbook texture animates in frames per second. Like `Class.ParticleEmitter.Lifetime|Lifetime`, you can set a minimum and maximum range to randomize the framerate of the flip book, with a maximum of 30 frames per second.
</TabItem>
<TabItem label="FlipbookMode">
The `Class.ParticleEmitter.FlipbookMode|FlipbookMode` property determines the type of the flipbook animation. The property can be any value of the `Enum.ParticleFlipbookMode` enum:
- **Loop** &mdash; Continuously play through all frames, starting back at the first frame after playing the last.
- **OneShot** &mdash; Play through the animation only once across the particle's lifetime. With this setting, the `Class.ParticleEmitter.FlipbookFramerate|FlipbookFramerate` property doesn't apply; instead, the framerate is determined by the particle's `Class.ParticleEmitter.Lifetime|Lifetime` divided evenly by the number of frames in the animation. **OneShot** animations are useful for clear non-repeating animations, such as an explosion that creates a puff of smoke and then fades out.
- **PingPong** &mdash; Play from the first to the last frame, then in reverse from the last to the first, repeating throughout the `Class.ParticleEmitter.Lifetime|Lifetime` of the particle.
- **Random** &mdash; Play the frames in a random order, blending/crossfading from one frame to the next. This can be useful for organic particle textures at low framerates, such as stars slowly twinkling between subtly different shapes.
</TabItem>
<TabItem label="FlipbookStartRandom">
The `Class.ParticleEmitter.FlipbookStartRandom|FlipbookStartRandom` property determines whether each particle begins at a random frame of the animation instead of always starting at the first frame. One use case is to enable this property and also set `Class.ParticleEmitter.FlipbookFramerate|FlipbookFramerate` to zero, causing each emitted particle to be a static frame chosen randomly from the flipbook texture.
</TabItem>
</Tabs>
### Other properties
To further customize particles, consider the following emitter properties, and click through to the `Class.ParticleEmitter` reference page for more details.
<Tabs>
<TabItem label="Appearance">
The following appearance properties are in addition to [color](#color), [light emission](#lightemission), [orientation](#orientation), [size](#size), [texture](#texture), [transparency](#transparency), [squash](#squash), and [flipbooks](#flipbooks).
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.ParticleEmitter.LightInfluence|LightInfluence`</td>
<td>Determines how much environmental light affects the color of individual particles.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.Brightness|Brightness`</td>
<td>Scales the light emitted from the emitter when `Class.ParticleEmitter.LightInfluence|LightInfluence` is 0.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.ZOffset|ZOffset` </td>
<td>Determines the forward-backward render position of particles, in studs, without changing their size on the screen. This allows for multiple emitters to be layered, or to render particles in front of or behind the parent object.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Emission">
The following emission properties are in addition to [emission direction](#create-particle-emitters), [lifetime](#lifetime), [speed](#speed), [rate](#rate), [spread angle](#spreadangle), and [shape](#shape).
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.ParticleEmitter.Enabled|Enabled` </td>
<td>Determines if particles emit from the emitter. Setting this to `false` stops further particles from spawning, but any existing particles remain active until they expire or the `Class.ParticleEmitter:Clear()|Clear()` method is called.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.Rotation|Rotation`</td>
<td>Determines the angle of rotation for newly-emitted particles. Single numbers create particles at that angle, while two numbers (minimum, maximum) set a random rotation for each particle.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.RotSpeed|RotSpeed`</td>
<td>Determines the angular speed in degrees per second for particles. This can be a single number or a number range for a randomized speed. Negative values cause particles to rotate counter-clockwise.</td>
</tr>
</tbody>
</table>
</TabItem>
<TabItem label="Motion">
The following motion properties are in addition to [wind influence](#windaffectsdrag).
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.ParticleEmitter.Acceleration|Acceleration`</td>
<td>Determines by how much the velocity of particles changes per second. You can use this property to create effects such as particles being affected by gravity.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.Drag|Drag`</td>
<td>Determines the rate in seconds that particles lose half their speed.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.LockedToPart|LockedToPart`</td>
<td>Determines if particles will "stick" to the emission source to which the emitter is parented.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.TimeScale|TimeScale`</td>
<td>A value between 0 and 1 that controls the speed of the particle effect.</td>
</tr>
<tr>
<td>`Class.ParticleEmitter.VelocityInheritance|VelocityInheritance`</td>
<td>Determines how much of the parent object's velocity is inherited by particles when they are emitted.</td>
</tr>
</tbody>
</table>
</TabItem>
</Tabs>

190
.cursor/rules/roblox/en-us/effects/trails.md Normal file
View file

@ -0,0 +1,190 @@
---
title: Trails
description: Trails create visual motion effects as an object moves through space.
---
A `Class.Trail` is an object that creates a trail between and behind two `Class.Attachment` objects as they move through space. Trails are useful to help players visualize movement, such as a sword slashing through the air, projectiles flying to their target, or footprints walking away.
<video src="../assets/lighting-and-effects/trail/Showcase.mp4" controls width="100%"></video>
After you [create a trail](#create-trails), you can:
- Add a [texture](#texture) to create interesting visuals.
- Set a constant or gradient [color](#color) and/or [transparency](#transparency).
- Modify a trail's [lifetime](#lifetime).
- Specify the texture's [length and mode](#texture-lengthmode) to affect how it scales, repeats, and moves along with the trail's attachments.
## Create trails
Before you begin to create a trail, it's useful to toggle on visibility of attachments so you can more easily discern how their spacing affects the trail's width. You can do so by enabling **Show Constraint Details** from Studio's **View** menu.
The following video demonstrates how attachments that are closer to each other create a trail with a smaller width:
<video src="../assets/lighting-and-effects/trail/Attachment-Width-Between.mp4" controls width="800"></video>
To create a trail on a part:
1. In the **Explorer** window, insert two `Class.Attachment|Attachments` and a `Class.Trail` object into the part.
1. Hover over the part and click the **&CirclePlus;** button. A contextual menu displays.
2. From the menu, insert two **Attachments** and one **Trail**.
<img src="../assets/studio/explorer/Part-Trail-Setup.png" alt="" width="320" />
2. Select the new **Trail** object and assign its attachments. Ensure you assign each attachment property to a different `Class.Attachment` object.
1. In the **Properties** window, select the **Attachment0** property. Your cursor changes.
2. In the **Explorer** window, select the first attachment you created.
3. Back in the **Properties** window, select the **Attachment1** property. Your cursor changes.
4. In the **Explorer** window, select the second attachment you created.
3. Using the [Move](../parts/index.md#move) tool, position both attachments within the part according to how wide you want the trail to be.
4. To see the trail, move the part in any direction and the trail follows.
<Alert severity="warning">
Trails require attachments to function properly. If you remove either `Class.Attachment` object from step 2, the trail stops rendering its texture.
</Alert>
## Customize trails
By experimenting with the following properties, you can customize a trail's visual appearance to make unique gameplay elements like wind gusts, sword slashes, and tire marks from fast cars.
<Alert severity="info">
The visual quality of your trails can change depending on the graphics settings on the player's device. To review your trail across quality levels, it's recommended to open [Studio Settings](../studio/setup.md#customization), search for **Editor Quality Level**, and set it to the both the lowest and highest level after you finish customizing your trail.
</Alert>
### Texture
The `Class.Trail.Texture|Texture` property renders a texture across the length of the trail. You can set a trail's `Class.Trail.Texture|Texture` property to any asset ID. For more information, including how to add or import your own textures, see [here](../projects/assets/manager.md#asset-import).
<video src="../assets/lighting-and-effects/trail/Textures.mp4" controls width="800"></video>
### Color
The `Class.Trail.Color|Color` property tints the trail's texture to either a specific hue or a `Datatype.ColorSequence`. The video below shows how a constant color compares with a gradient color across the trail's [lifetime](#lifetime).
<video src="../assets/lighting-and-effects/trail/Color-Static-Gradient.mp4" controls width="800"></video>
<Tabs>
<TabItem label="Constant Color">
1. In the **Explorer** window, select the trail.
2. In the **Properties** window, select the **Color** property. You can either:
1. Click on the color square to open the **Colors** pop-up window and select a color.
2. Input three numbers into the RGB color value field.
<img src="../assets/studio/properties/Color-Input-Options.png" alt="" width="320" />
</TabItem>
<TabItem label="Color Gradient">
1. In the **Explorer** window, select the trail.
1. In the **Properties** window, click inside the **Color** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Color-Open-Sequence.png" width="320" alt="Button to open color sequence popup" />
In the color sequence popup, each triangle on the bottom axis is a
**keypoint** that determines the color value of the trail at that
point in its lifetime.
<img src="../assets/studio/general/ColorSequence-White-Keypoints-Labeled.png" width="640" alt="Keypoints labeled in color sequence popup" />
1. Click the keypoint at the start of the color sequence, click the
small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-White.png" width="640" alt="Color sequence popup from red to white" />
1. If you want the trail to change color near the end of its lifetime, click the keypoint at the end of the color sequence, click the small square next to **Color**, and select a color from the popup window.
<img src="../assets/studio/general/ColorSequence-Red-Purple.png" width="640" alt="Color sequence popup from red to purple" />
1. For more customization, you can:
- Add another keypoint by clicking anywhere on the graph.
- Make a color change sooner or later within the gradient by dragging an intermediary keypoint to a new position.
- Delete an intermediary keypoint by selecting it and clicking the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
</TabItem>
</Tabs>
### Transparency
The `Class.Trail.Transparency|Transparency` property sets the transparency of the trail's segments over its `Class.Trail.Lifetime|Lifetime`. It can be a consistent value or a `Datatype.NumberSequence` with ranges from **0** (totally opaque) to **1** (fully clear).
<Tabs>
<TabItem label="Constant Opacity">
1. In the **Explorer** window, select the trail.
2. In the **Properties** window, select the **Transparency** property.
3. Input the desired opacity for the trail.
</TabItem>
<TabItem label="Number Sequence">
1. In the **Explorer** window, select the trail.
1. In the **Properties** window, click inside the **Transparency** property field, then click the **&ctdot;** button.
<img src="../assets/studio/properties/Transparency-Open-Sequence.png" width="320" alt="Button to open number sequence popup" />
In the number sequence popup, each square at the start and end of the graph is a **keypoint** that determines the opacity value of the trail at that
point along its span. By default, the graph defaults to a straight line and the trail is of consistent opacity.
<img src="../assets/studio/general/NumberSequence-0.5-0.5-Keypoints-Labeled.png" width="746" alt="Keypoints labeled in number sequence popup" />
1. Perform any of the following actions:
- To change the opacity at a point, click on a keypoint and either
drag it up or down, or enter a value in the **Value** field.
- To insert a new keypoint, click on any point in the graph.
- To delete a keypoint, select it and click the **Delete** button.
- Reset the entire sequence by clicking the **Reset** button.
<img src="../assets/studio/general/NumberSequence-0-1-0.png" width="746" alt="Number sequence popup from 0 to 1 to 0" />
</TabItem>
</Tabs>
### Lifetime
The `Class.Trail.Lifetime|Lifetime` property allows you to set the duration of the trail in seconds. When you decrease the value of this property, the trail moves through the space more quickly and consequently cuts down the length of the trail. This can provide the object with a faster, more animated visual
appearance.
<figure>
<video src="../assets/lighting-and-effects/trail/Lifetime.mp4" controls width="800"></video>
<figcaption>Trail with lifetime of 0.5 (left) vs. trail with lifetime of 3.0 (right)</figcaption>
</figure>
### Texture length/mode
A trail's `Class.Trail.TextureLength|TextureLength` and `Class.Trail.TextureMode|TextureMode` determine how its [texture](#texture) scales, repeats, and moves along with the trail's attachments.
<Tabs>
<TabItem label="Scaling and Repetition">
When `Class.Trail.TextureMode|TextureMode` is set to `Enum.TextureMode.Wrap` or `Enum.TextureMode.Static`, the `Class.Trail.TextureLength|TextureLength` property sets the length of the texture as it repeats across the trail's length.
<img src="../assets/engine-api/enums/TextureMode/Wrap-Static.png" width="720" alt="TextureMode diagram with Wrap mode" />
When `Class.Trail.TextureMode|TextureMode` is set to `Enum.TextureMode.Stretch`, the texture will repeat `Class.Trail.TextureLength|TextureLength` times across the trail's overall length.
<img src="../assets/engine-api/enums/TextureMode/Stretch.png" width="720" alt="TextureMode diagram with Stretch mode" />
</TabItem>
<TabItem label="Movement">
The `Class.Trail.TextureMode|TextureMode` property also affects the **movement** of the trail's texture as follows:
- If set to `Enum.TextureMode.Stretch`, the texture will stretch out based on the lifetime of the trail, and shrink inwards if the trail's attachments stop moving.
- If set to `Enum.TextureMode.Wrap`, the texture will be tiled as the length of the trail changes, but the textures will remain stationary relative to their attachments.
- If set to `Enum.TextureMode.Static`, the texture will be rolled out as the attachments move, and they will remain in place until their lifetime is met. This setting is ideal for trail textures that should appear "stamped" where rendered, such as paw prints or tire tracks.
</TabItem>
</Tabs>
### Facing
A trail is a 2D projection existing in 3D space, meaning that it may not be visible from every angle. The `Class.Trail.FaceCamera|FaceCamera` property, when set to `true`, ensures that the trail always faces the `Class.Workspace.CurrentCamera|CurrentCamera`, regardless of its orientation.