2D
Sprite
Sprite is the core asset of 2D projects, driving rendering and interaction through:
- Data Source: Extracts graphic data from Texture2D
- Rendering Control: Customizes display effects via property configurations (e.g.,
region,pivot) - Component Integration:
- Powers SpriteRenderer: Renders 2D images in 3D space
- Powers SpriteMask: Implements masking effects
Properties
View and debug Sprite asset properties conveniently in the editor:
| Property | Type | Description | Default Value |
|---|---|---|---|
texture | Texture2D | Reference to the associated texture resource | null |
width | Number | Sprite width. Automatically calculated as texture pixel width / 100 (world space units) when unset | texture.width/100 |
height | Number | Sprite height. Automatically calculated as texture pixel height / 100 (world space units) when unset | texture.height/100 |
region | Rect | Texture sampling area (normalized coordinates, range 0~1) | (0,0,1,1) |
pivot | Vector2 | Pivot point relative to region (bottom-left: (0,0), top-right: (1,1)) | (0.5,0.5) |
border | Vector4 | Border distances for nine-slice/tiling modes (left, bottom, right, top) | (0,0,0,0) |
belongs to | SpriteAtlas | Atlas containing this sprite (read-only) | null |
Region Cropping
- Function: Crop a rectangular area from the texture for display
- Example:
region: (0.15, 0.3, 0.55, 0.5)crops an area starting at 15% width and 30% height of the texture, with 55% width and 50% height
Pivot Point
- Coordinate System: Bottom-left
(0,0)→ Top-right(1,1) - Use Cases: Control rotation/scaling anchors, align elements
Usage
Creating Sprite Assets
Generate from Uploaded Image
- Right-click in the Assets panel blank area
- Select Upload → Sprite
- Upload an image to auto-generate:
- Texture asset:
image-name.png - Sprite asset:
image-name-spr.png
- Texture asset:
Create Blank Sprite
- Right-click in Assets panel → Create → Sprite
- Manually bind a texture for usage
Scripted Creation
// Create blank sprite
const sprite = new Sprite(engine);
// Create from existing texture
const spriteWithTexture = new Sprite(engine, texture2D);Configuring Pivot
Use preset anchor configurations (e.g., center, corners) provided by the editor, or click Custom to input normalized coordinates.
