Component:SpriteProvider: Difference between revisions

Latest revision as of 11:03, 19 June 2025

Component image

**SpriteProvider** component as seen in the Scene Inspector

A SpriteProvider defines a slice of a Texture2D as a Sprite that may be used by other components e.g. UIX Images to display graphics or produce backgrounds.

Fields

Fields
Name	Type	Description
`persistent`	Bool	Determines whether or not this item will be saved to the server.
`UpdateOrder`	Int	Controls the order in which this component is updated.
`Enabled`	Bool	Controls whether or not this component is enabled. Some components stop their functionality when this field is disabled, but some don't.
`HighPriorityIntegration`	Bool	If true, integrating this asset (e.g. processing procedural assets) gets higher priority than assets with this flag off. An example is user laser procedural meshes.
`Texture`	ITexture2D	The sprite to provide.
`Rect`	Rect	The rectangle within the sprite to render. Note that the second x and y are actually the width and height of the Rect. The values are proportions of the width and height of the image in the Texture property.
`Borders`	Float4	Border widths for 9-slice scaling. The XYZW components set the left, bottom, right, and top borders respectively.
`Scale`	Float	Effects the center size when 9 slicing.
`FixedSize`	Float	Effects the center size when 9 slicing.

Behavior

Sprite providers due to the current Unity implementation at the time of writing this have issues with switching images very quickly. They will often flash white, causing a health hazard to photo sensitive users. Having all the sprites on UIX elements at once and switching their OrderOffset to change which element renders on top will remove the flashing and is currently the only way to combat this issue.

Using SpriteProvider to break up a sprite-sheet of iconography:

By combining multiple icons/elements in a grid-like texture, you can reduce the size of your objects and improve load performance by reusing the same texture for multiple sprites. Please note that the Rect values are floating point percentages of the texture were 1 would equal 100%, so 1/4 or 25% would be 0.25 in floating point value.

The Rect first x,y values are from the LOWER LEFT of the texture being 0.0, 0.0, where the total inclusion of the cut out texture sprite is a percentage of the width and height in the second x,y values.

Example: Given if you take a 1024x1024 px sprite sheet texture.

Divide the height and width by 4 to make 12 equal sprite slots of 256x256 px chunks
A sprite texture on the second column from the left and on the third row from the bottom would be Rect: x: 0.25 y: 0.50 x: 0.25 y: 0.25

See attached example diagram for help.

Examples

ProbablePrime's video on Sprites

@@ Line 15: / Line 15: @@
 |Rect|Rect|The rectangle within the sprite to render. Note that the second x and y are actually the width and height of the Rect. The values are proportions of the width and height of the image in the Texture property.
 |Borders|Float4|Border widths for [[9-slice scaling]]. The XYZW components set the left, bottom, right, and top borders respectively.
-|Scale|Float| Does nothing.
+|Scale|Float| Effects the center size when 9 slicing.
-|FixedSize|Float| Does nothing.
+|FixedSize|Float| Effects the center size when 9 slicing.
 }}
@@ Line 23: / Line 23: @@
 Sprite providers due to the current Unity implementation at the time of writing this have issues with switching images very quickly. They will often flash white, causing a health hazard to photo sensitive users. Having all the sprites on UIX elements at once and switching their <code>OrderOffset</code> to change which element renders on top will remove the flashing and is currently the only way to combat this issue.
+<b>Using SpriteProvider to break up a sprite-sheet of iconography:</b>
+By combining multiple icons/elements in a grid-like texture, you can reduce the size of your objects and improve load performance by reusing the same texture for multiple sprites.  Please note that the <code>Rect</code> values are floating point percentages of the texture were 1 would equal 100%, so 1/4 or 25% would be 0.25 in floating point value.
+The <code>Rect</code> first x,y values are from the LOWER LEFT of the texture being 0.0, 0.0, where the total inclusion of the cut out texture sprite is a percentage of the width and height in the second x,y values.
+Example: Given if you take a 1024x1024 px sprite sheet texture.
+* Divide the height and width by 4 to make 12 equal sprite slots of 256x256 px chunks
+* A sprite texture on the second column from the left and on the third row from the bottom would be <code>Rect</code>: x: 0.25 y: 0.50 x: 0.25 y: 0.25
+See attached example diagram for help.
 <!--T:5-->
 == Examples ==
 ProbablePrime's video on Sprites <youtube>FUUSjTwhvHk</youtube>
-<!--T:6-->
+[[File:SpriteSheetDiagram.png|caption]]<!--T:6-->
 == See Also ==
 </translate>
 [[Category:Components{{#translation:}}|Sprite Provider]]
 [[Category:Components:Assets{{#translation:}}|Sprite Provider]]