UIImage
A UIControl for displaying an image. Inherits from UIControl.
Properties
Property Name | Return Type | Description | Tags |
---|---|---|---|
isTeamColorUsed | boolean | If true , the image will be tinted blue if its team matches the Player, or red if not. | Read-Write |
team | integer | the team of the image, used for isTeamColorUsed . | Read-Write |
shouldClipToSize | boolean | Whether or not the image and its shadow should be clipped when exceeding the bounds of this control. | Read-Write |
isFlippedHorizontal | boolean | Whether or not the image is flipped horizontally. | Read-Write |
isFlippedVertical | boolean | Whether or not the image is flipped vertically. | Read-Write |
sourceImageAspectRatio | number | The aspect ratio of the image. | Read-Only |
isHittable | boolean | When set to true , this control can receive input from the cursor and blocks input to controls behind it. When set to false , the cursor ignores this control and can interact with controls behind it. | Read-Write |
Functions
Function Name | Return Type | Description | Tags |
---|---|---|---|
GetColor() | Color | Returns the current color of the UIImage. | None |
SetColor(Color) | None | Sets the UIImage to a color. | None |
GetShadowColor() | Color | Returns the color of the image's drop shadow. | None |
SetShadowColor(Color) | None | Sets the color of the image's drop shadow. | None |
GetShadowOffset() | Vector2 | Returns the offset of the image's drop shadow in UI space. | None |
GetSourceImageSize() | Vector2 | Returns the size of the image. | None |
SetShadowOffset(Vector2) | None | Sets the offset of the image's drop shadow in UI space. | None |
GetImage() | string | Returns the imageId assigned to this UIImage control. Note: As of 1.0.211, this function returns nil instead of "0BADBADBADBADBAD" when no image asset has been set. | Breaking-Change |
SetImage(string imageId) | None | Sets the UIImage to a new image asset ID. You can get this ID from an Asset Reference. | None |
SetImage(Player) | None | Downloads and sets a Player's profile picture as the texture for this UIImage control. | Deprecated |
SetPlayerProfile(Player) | None | Downloads and sets a Player's profile picture as the texture for this UIImage control. | None |
SetPlayerProfile(CorePlayerProfile) | None | Downloads and sets a player's profile picture as the texture for this UIImage control. | None |
SetPlayerProfile(CoreFriendCollectionEntry) | None | Downloads and sets a player's profile picture as the texture for this UIImage control. | None |
SetPlayerProfile(string playerId) | None | Downloads and sets a player's profile picture as the texture for this UIImage control. | None |
SetGameEvent(CoreGameEvent event) | None | Downloads and sets a game event image as the texture for this UIImage control. | None |
SetGameScreenshot(string gameId, [integer screenshotIndex]) | None | Downloads and sets a game screenshot as the texture for this UIImage control. The screenshot may come from a different game. | None |
SetCameraCapture(CameraCapture) | None | Sets the UIImage to display the given camera capture. If the given capture is not valid, it will be ignored. If the capture is released while in use, this UIImage will revert to its default image. | Client-Only |
SetBlockchainToken(BlockchainToken token) | None | Downloads and sets a blockchain token image as the texture for this UIImage control. | None |
GetCurrentTouchIndex() | integer | Returns the touch index currently interacting with this image. Returns nil if the image is not currently being interacted with. | Client-Only |
Events
Event Name | Return Type | Description | Tags |
---|---|---|---|
touchStartedEvent | Event <UIImage , Vector2 location, integer touchIndex> | Fired when the player starts touching the control on a touch input device. Parameters are the screen location of the touch and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
touchStoppedEvent | Event <UIImage , Vector2 location, integer touchIndex> | Fired when the player stops touching the control on a touch input device. Parameters are the screen location from which the touch was released and a touch index used to distinguish between separate touches on a multitouch device. | Client-Only |
tappedEvent | Event <UIImage , Vector2 location, integer touchIndex> | Fired when the player taps the control on a touch input device. Parameters are the screen location of the tap and the touch index with which the tap was performed. | Client-Only |
flickedEvent | Event <UIImage , number angle> | Fired when the player performs a quick flicking gesture on the control on a touch input device. The angle parameter indicates the direction of the flick. 0 indicates a flick to the right. Values increase in degrees counter-clockwise, so 90 indicates a flick straight up, 180 indicates a flick to the left, etc. | Client-Only |
pinchStartedEvent | Event <UIImage > | Fired when the player begins a pinching gesture on the control on a touch input device. Input.GetPinchValue() may be polled during the pinch gesture to determine how far the player has pinched. | Client-Only |
pinchStoppedEvent | Event <UIImage > | Fired when the player ends a pinching gesture on a touch input device. | Client-Only |
rotateStartedEvent | Event <UIImage > | Fired when the player begins a rotating gesture on the control on a touch input device. Input.GetRotateValue() may be polled during the rotate gesture to determine how far the player has rotated. | Client-Only |
rotateStoppedEvent | Event <UIImage > | Fired when the player ends a rotating gesture on a touch input device. | Client-Only |
Examples
Example using:
GetTouchPosition
GetPinchValue
GetRotateValue
pinchStartedEvent
pinchStoppedEvent
rotateStartedEvent
rotateStoppedEvent
In this example we manipulate a UI object with a multi-touch pinching gesture. The pinch gesture is used to move, scale and rotate a the UI Text on screen.
-- Client Script as a child of the UI Text.
local UI_OBJECT = script.parent
-- Make the UI Control hittable
UI_OBJECT.isHittable = true
local isPinching = false
local isRotating = false
local startingWidth
local startingHeight
local startingAngle
function Tick()
-- Position
local touch1 = Input.GetTouchPosition(1)
local touch2 = Input.GetTouchPosition(2)
if touch1 ~= nil and touch2 ~= nil then
local position = (touch1 + touch2) / 2
UI_OBJECT:SetAbsolutePosition(position)
end
-- Scale
if isPinching then
local pinchPercent = Input.GetPinchValue()
UI_OBJECT.width = CoreMath.Round(startingWidth * pinchPercent)
UI_OBJECT.height = CoreMath.Round(startingHeight * pinchPercent)
end
-- Rotate
if isRotating then
local angle = Input.GetRotateValue()
UI_OBJECT.rotationAngle = startingAngle + angle
end
end
local function OnPinchStarted()
isPinching = true
startingWidth = UI_OBJECT.width
startingHeight = UI_OBJECT.height
end
local function OnPinchStopped()
isPinching = false
end
-- Detect pinch gesture start/end
UI_OBJECT.pinchStartedEvent:Connect(OnPinchStarted)
UI_OBJECT.pinchStoppedEvent:Connect(OnPinchStopped)
local function OnRotateStarted()
isRotating = true
startingAngle = UI_OBJECT.rotationAngle
end
local function OnRotateStopped()
isRotating = false
end
-- Detect rotation gesture start/end
UI_OBJECT.rotateStartedEvent:Connect(OnRotateStarted)
UI_OBJECT.rotateStoppedEvent:Connect(OnRotateStopped)
See also: UIControl.SetAbsolutePosition | UIImage.isHittable | CoreObject.parent | CoreMath.Round
Example using:
tappedEvent
flickedEvent
In this example we listen for the tapped and flicked touch gestures on the UI object. When one of those events is triggered, the pertinent information is printed to the screen.
-- Client Script as a child of the UI object.
local UI_OBJECT = script.parent
-- Make the UI Control hittable
UI_OBJECT.isHittable = true
function OnTappedEvent(control, location, touchIndex)
UI.PrintToScreen("Tap ".. touchIndex ..": ".. tostring(location))
end
function OnFlickedEvent(control, angle)
UI.PrintToScreen("Flick: " .. angle)
end
UI_OBJECT.tappedEvent:Connect(OnTappedEvent)
UI_OBJECT.flickedEvent:Connect(OnFlickedEvent)
See also: UI.PrintToScreen | Event.Connect | UIImage.isHittable
Example using:
touchStartedEvent
touchStoppedEvent
In this example, the touch inputs on the UI object are tracked in two different ways, with a counter and with a table. Each time the amount of touches change a summary of the touch information is printed to screen.
-- Client Script as a child of the UI object.
local UI_OBJECT = script.parent
-- Make the UI Control hittable
UI_OBJECT.isHittable = true
local touchCount = 0
local activeTouches = {}
function PrintTouchInfo()
local str = touchCount .. ": ["
local addComma = false
for id,_ in pairs(activeTouches) do
if addComma then
str = str .. ", "
end
addComma = true
str = str .. id
end
str = str .. "]"
UI.PrintToScreen(str)
end
local function OnTouchStarted(control, location, touchId)
touchCount = touchCount + 1
activeTouches[touchId] = true
PrintTouchInfo()
end
local function OnTouchStopped(control, location, touchId)
touchCount = touchCount - 1
activeTouches[touchId] = nil
PrintTouchInfo()
end
UI_OBJECT.touchStartedEvent:Connect(OnTouchStarted)
UI_OBJECT.touchStoppedEvent:Connect(OnTouchStopped)
See also: UI.PrintToScreen | Event.Connect | UIImage.isHittable
Example using:
GetSourceImageSize
In this example we can set the width and height of an image to the source image size of the blockchain token. This allows for the image to be at the correct width, height, and aspect ratio.
-- Client Script
local UI_IMAGE = script:GetCustomProperty("UIImage"):WaitForObject()
local token = Blockchain.GetToken("0x950599037fe15c5a6499506c1fad5cf91457ef62", "1")
UI_IMAGE:SetBlockchainToken(token)
local size = UI_IMAGE:GetSourceImageSize()
UI_IMAGE.width = size.x
UI_IMAGE.height = size.y
See also: script.GetCustomProperty | CoreObjectReference.WaitForObject | Blockchain.GetToken | UIImage.SetBlockchainToken
Example using:
SetBlockchainToken
MekaVerse is an NFT collection with 8,888 unique mechas. The following example shows how to remotely load the image for Meka #1. The script sits in the hierarchy as a child of a UI Image
, which is used for visualizing the NFT's artwork.
-- Address to the NFT #1 in the MekaVerse collection
-- https://opensea.io/assets/ethereum/0x9a534628b4062e123ce7ee2222ec20b86e16ca8f/1
local UI_IMAGE = script.parent
local NFT_CONTRACT_ADDRESS = "0x9a534628b4062e123ce7ee2222ec20b86e16ca8f"
local TOKEN_ID = "1"
local token = Blockchain.GetToken(NFT_CONTRACT_ADDRESS, TOKEN_ID)
UI_IMAGE:SetBlockchainToken(token)
See also: Blockchain.GetToken | CoreObject.parent
Example using:
SetGameScreenshot
Similar to portals, it's possible to show screenshots from another game inside 2D UI. In this example, we have a UI Image added as a custom property of the script. The script asks Core for the list of featured games and scrolls through all the screenshots for those games. In the end, the image is cleared back to normal.
local IMAGE = script:GetCustomProperty("UIImage"):WaitForObject()
local featuredGames = CorePlatform.GetGameCollection("featured")
for _,entry in ipairs(featuredGames) do
print("Showing screenshots for " .. entry.name)
local gameInfo = CorePlatform.GetGameInfo(entry.id)
local count = gameInfo.screenshotCount
-- Show each of the game's screenshots
for i = 1,count do
IMAGE:SetGameScreenshot(entry.id, i)
Task.Wait(1)
end
end
-- Clear it
IMAGE:SetGameScreenshot("")
See also: CorePlatform.GetGameCollection | CoreGameCollectionEntry.id | CoreGameInfo.screenshotCount | Task.Wait
Example using:
SetPlayerProfile
Player icons are a staple among online games. Player icons allow players to identify themselves within a game. This example will show you how to display your Core profile picture in a UI Image object.
-- Get the UI Image object
local propUIImage = script:GetCustomProperty("UIImage"):WaitForObject()
-- Get the local player
local player = Game.GetLocalPlayer()
-- Replaces the UI Image with your Core profile picture
propUIImage:SetPlayerProfile(player)
See also: Game.GetLocalPlayer()
Example using:
SetPlayerProfile
Often to identify players you will want to use their Core profile picture. This example will demonstrate how to display the Core profile pictures of your friends by using the SetPlayerProfile
method of a UI Image.
-- Get the local player
local player = Game.GetLocalPlayer()
-- Get the UI Image object
local propUIImage = script:GetCustomProperty("UIImage"):WaitForObject()
-- Get an array of friends of the local player
local friends = CoreSocial.GetFriends(player):GetResults()
-- Stores the current index in the friend list that is being used (starts at 1)
local currentIndex = 1
-- Represents the number of seconds left until the UI Image is updated with the profile picture of the next friend
local timer = 0
function Tick(deltaTime)
-- Decrement the "deltaTime" number of seconds from the "timer"
timer = timer - deltaTime
-- If 2 seconds have passed, show the profile picture of the next friend, and reset the "timer" to 2 seconds
if(timer <= 0) then
-- If you have no friends on your Core friend list, then the rest of the code will be skipped
-- Doing this prevents the script from trying to read an empty Core friend list.
if(#friends == 0) then
-- Exit this function before updating UI Image
return
end
-- Reset the "timer" to 2 seconds
timer = 2
-- Get the id of the friend at the current index of the array
local friend_id = friends[currentIndex].id
-- Update the image with the friend's profile picture
propUIImage:SetPlayerProfile(friend_id)
-- Increment the "currentIndex" to select the next friend from the list
currentIndex = currentIndex + 1
-- If the "currentIndex" has reached the end of the list, reset it back to the start of the friend list
if(currentIndex > #friends) then
currentIndex = 1
end
end
end
See also: CoreSocial.GetFriends | CoreObject.GetCustomProperty | CoreFriendCollection.GetResults | Game.GetLocalPlayer | Player.id
Example using:
SetShadowOffset
SetShadowColor
Shadows provide a great way to make your UI Image stand out. This example will show you how to change the position and color of the shadow of a UI Image by using the SetShadowOffset
and SetShadowColor
methods.
-- Get the UI Image object
local propUIImage = script:GetCustomProperty("UIImage"):WaitForObject()
-- Keep track of the number of seconds that have passed since the script began running
local timePassed = 0
-- The relative position of the center of the circle
local circleCenterPosition = Vector2.New(30, 30)
function Tick(deltaTime)
-- Update the "timePassed" to keep track of the number of seconds that have passed
timePassed = timePassed + deltaTime
-- Store the x and y position of the shadow
local offset = Vector2.New(0, 0)
-- Calculate the x and y position based on the time that has passed
offset.x = (math.sin(timePassed) * 20) + circleCenterPosition.x
offset.y = (math.cos(timePassed) * 20) + circleCenterPosition.y
-- Update the position of the shadow
propUIImage:SetShadowOffset(offset)
-- The color will be stored in this variable
local shadowColor = Color.New(0, 0, 1)
-- Calculate the amount of blue that the shadow color will have
local BlueChannel = (math.sin(timePassed) * 0.5) + 0.5
-- Update the amount of blue the color "shadowColor" should have
shadowColor.b = BlueChannel
-- Update the color of the shadow of the UI Image
propUIImage:SetShadowColor(shadowColor)
end
See also: CoreObject.GetCustomProperty
Example using:
sourceImageAspectRatio
In this example we can work out what the height of the image needs to be based on the aspect ratio given to us from the property sourceImageAspectRatio
. This allows images such as Blockchain images to be scaled with the correct aspect ratio using a specific width set in the properties window for the UI Image. The same can be done for the width by doing UI_IMAGE.height * ratio
.
-- Client Script
local UI_IMAGE = script:GetCustomProperty("UIImage"):WaitForObject()
local token = Blockchain.GetToken("0x950599037fe15c5a6499506c1fad5cf91457ef62", "1")
UI_IMAGE:SetBlockchainToken(token)
-- Get the source image aspect radio (0.8125 for the token image).
local ratio = UI_IMAGE.sourceImageAspectRatio
-- Work out the height based on the width of the image.
UI_IMAGE.height = math.floor(UI_IMAGE.width / ratio)
See also: script.GetCustomProperty | CoreObjectReference.WaitForObject | Blockchain.GetToken | UIImage.SetBlockchainToken