Surface Art

Players often enjoy feeling like they’re a part of constructing the space they’re in. The SurfaceArt developer module lets players literally leave their mark in an experience.

If you're using developer modules in your experiences and would like to help build the future of co-experience on Roblox, fill out this form to request access to a private DevForum category. You can also submit feedback here.

By default, a player can place 2 pieces of art across all of the tagged surfaces in the workspace. All of a player's art will be removed when they leave the game.

Module Usage

Installation

To use the SurfaceArt module in an experience:

Visit the SurfaceArt marketplace page, click the green Get button, and confirm the transaction.
In Studio, open the toolbox (View → Toolbox).
Select your toolbox Inventory section.

Locate the module item and click it or drag-and-drop it into the 3D view.
In the Explorer window, move the entire SurfaceArt folder into ServerScriptService. Upon running the experience, the module will distribute itself to various services and begin running.

Advanced Installation Options »

This and other developer modules come with an Install script that runs the installer and distributes the contents of the module to the same services that the folders are named after.

The Install script can be utilized as follows:

EnableLogging — Set to true to enable debug logging for the current developer module. This lets you see how the module gets distributed, along with how each package is linked.

			
				Script - Install
			
				Expected Output
			
				Expand
				
			local DevModuleInstaller = require(script.Parent.DevModuleInstaller)

DevModuleInstaller.EnableLogging = true

DevModuleInstaller:Install(script.Parent)
		
				Copy Code
			
				Light Theme

InstallStarted — Fires when the installer first starts up. You can hook into this event to run any pre-install steps.

			
				Script - Install
			
				Expected Output
			
				Expand
				
			local DevModuleInstaller = require(script.Parent.DevModuleInstaller)

DevModuleInstaller.InstallStarted:Connect(function()
	print("This is run before installation")
end)

DevModuleInstaller:Install(script.Parent)
		
				Copy Code
			
				Light Theme

InstallFinished — Fires when the installer has finished installing the module. By this point, the contents of each service folder has been distributed. You can also hook into this event to run any post-install steps.

The source developer module (parent of the Install script) has Instance/Destroy|Destroy() run on it immediately after this event is fired.

			
				Script - Install
			
				Expected Output
			
				Expand
				
			local DevModuleInstaller = require(script.Parent.DevModuleInstaller)

DevModuleInstaller.InstallFinished:Connect(function()
	print("This is run after installation")
end)

DevModuleInstaller:Install(script.Parent)
		
				Copy Code
			
				Light Theme

Install() — Installs the given developer module by overlaying each of the service folders over existing services. For example, a folder named ReplicatedStorage containing a SurfaceArt script will be distributed to game.ReplicatedStorage.SurfaceArt when installing.

			
				Script - Install
			
				Expected Output
			
				Expand
				
			local DevModuleInstaller = require(script.Parent.DevModuleInstaller)

DevModuleInstaller:Install(script.Parent)
		
				Copy Code
			
				Light Theme

Positioning the Canvas

The module comes with one SurfaceCanvas model that you can position in the 3D world. This model is what players will interact with to place art on its surface.

Locate the SurfaceCanvas mesh inside the Workspace folder of the module’s main folder.

Move it into the top-level Workspace hierarchy and position it where desired.

Upon publishing/running a test session, players will be able to interact with the object via a ProximityPrompt and place art on the defined surface.

It is not required that you use the packaged mesh for placing art. The module uses CollectionService to locate parts tagged as SurfaceCanvas and make them operate as canvases. Any tagged canvas must be a BasePart and it should have an articles/instance attributes|attribute defining the surface face as outlined in Changing the Canvas Face.

Changing the Canvas Face

Currently, the surface art module only supports parts with flat surfaces.

Under the hood, the module uses a SurfaceGui to display art items. To configure which surface the art appears on:

Select the SurfaceCanvas mesh.
At the bottom of the Properties window, locate the SurfaceCanvasFace attribute with a default value of Right.

Click the attribute and enter one of six values that describe a Enum/NormalId.

Attribute Value	Corresponding Normal ID
Front	Enum.NormalId.Front
Back	Enum.NormalId.Back
Right	Enum.NormalId.Right
Left	Enum.NormalId.Left
Top	Enum.NormalId.Top
Bottom	Enum.NormalId.Bottom

Using Custom Art Assets

Currently, the surface art module only supports using the same set of assets for all tagged canvases.

To better fit the theme of your experience, you may use your own set of custom assets instead of the defaults. This can be done via the configure() function, called from a Script in ServerScriptService.

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

local customAssets = {
	CustomAsset1 = {
		name = "Custom Asset 1",
		assetId = "rbxassetid://7322508294",
	},
	CustomAsset2 = {
		name = "Custom Asset 2",
		assetId = "rbxassetid://7322547665",
	},
}

SurfaceArt.configure({
	assets = customAssets,
})
		
				Copy Code
			
				Light Theme

Clearing All Canvases

To remove all existing art from all canvases in the world, call the removeAllArt() function from a Script.

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.removeAllArt()
		
				Copy Code
			
				Light Theme

Showing Custom Effects

There may be cases where you’d like to include additional visual effects when an artwork is placed. This module exposes an event called artChanged on the client that you can connect to and add your own logic.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

local function createParticleEmitter(canvas, position)
	local attachment = Instance.new("Attachment")
	attachment.Position = canvas.CFrame:PointToObjectSpace(position)
	attachment.Axis = Vector3.new(0, 0, 1)
	attachment.SecondaryAxis = Vector3.new(1, 0, 0)
	attachment.Parent = canvas

	local particleEmitter = Instance.new("ParticleEmitter")
	particleEmitter.Speed = NumberRange.new(50)
	particleEmitter.Rate = 50
	particleEmitter.Color = ColorSequence.new(Color3.fromRGB(128, 254, 7))
	particleEmitter.SpreadAngle = Vector2.new(35, 35)
	particleEmitter.Parent = attachment

	return attachment
end

SurfaceArt.artChanged:Connect(function(canvas, spot, spotPosition, artId, ownerId)
	if artId then
		-- Show some sparkles for 3 seconds
		task.spawn(function()
			local emitterAttachment = createParticleEmitter(canvas, spotPosition)
			task.wait(3)
			emitterAttachment:Destroy()
		end)
	end
end)
		
				Copy Code
			
				Light Theme

API Reference

Types

SurfaceArtAsset

Images to be used as art for the canvas are represented by a table with two values.

Key	Description
name	Metadata display name.
assetId	Asset ID of the image to include.

Functions

configure()

void


configure

(

	
		
			table
		
	
	config

)

Overrides default configuration options. This function can only be called from a Script.

Key	Description	Default
enabled	Toggles the module's functionality on or off.	true
assets	List of SurfaceArtAsset types.	(see code)
quotaPerPlayer	Maximum number of art pieces that can be placed by each player.	2
rowsPerCanvas	Number of rows in the canvas grid.	2
colsPerCanvas	Number of columns in the canvas grid.	5
itemsPerPage	Number of items to skip when paging left and right.	3
promptImage	Icon shown in the proximity prompt to enter art selection view.	"rbxassetid://8076723774"
promptKeyCode	Keyboard shortcut used to activate the prompt to enter art selection.	Enum.KeyCode.E
promptRequiresLineOfSight	Boolean value that determines if the proximity prompt has to be in line of sight between user and canvas.	true
promptMaxActivationDistance	The maximum distance a player's character can be from the canvas for the prompt to appear.	10
promptExclusivity	Determines which prompts can be shown at the same time. See `ProximityPrompt/Exclusivity` for details.	OnePerButton
canvasPaddingLeft	Left padding for the surface canvas.	UDim.new(0, 8)
canvasPaddingRight	Right padding for the surface canvas.	UDim.new(0, 8)
canvasPaddingTop	Top padding for the surface canvas.	UDim.new(0, 8)
canvasPaddingBottom	Bottom padding for the surface canvas.	UDim.new(0, 8)
leftArrowPageImage	Image for the left arrow to flip to the previous page.	"rbxassetid://6998633654"
leftArrowItemImage	Image for the left arrow to select the previous art item.	"rbxassetid://8072765021"
rightArrowPageImage	Image for the right arrow to flip to the next page.	"rbxassetid://6998635824"
rightArrowItemImage	Image for the right arrow to select the next art item.	"rbxassetid://8072764852"
usePageHotkeys	Whether page hotkeys are used. If true, nextPageKey and prevPageKey are used to cycle between pages.	true
nextPageKey	Key used to cycle to the next page of artwork.	Enum.KeyCode.E
nextItemKey	Key used to cycle to the next item of artwork.	Enum.KeyCode.Right
prevPageKey	Key used to cycle to the previous page of artwork.	Enum.KeyCode.Q
prevItemKey	Key used to cycle to the previous item of artwork.	Enum.KeyCode.Left

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.configure({
	quotaPerPlayer = 4,
	promptKeyCode = Enum.KeyCode.T,
	promptMaxActivationDistance = 8,
})
		
				Copy Code
			
				Light Theme

getCanvases()

table


getCanvases

()

Returns all of the canvases tagged with the SurfaceCanvas tag.

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

local canvases = SurfaceArt.getCanvases()
		
				Copy Code
			
				Light Theme

placeArt()

void


placeArt

(

	
		
			Player
		
	
	player,
	
		
			BasePart
		
	
	canvas

)

Places an art piece programmatically on behalf of a player. Note that the canvas object must be tagged with the SurfaceCanvas tag when the server is initialized. It is recommended to use this only with a canvas returned from getCanvases().

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

local remoteEvent = ReplicatedStorage:WaitForChild("SurfaceArtRemoteEvent")

remoteEvent.OnServerEvent:Connect(function(player)
	-- Place the Bloxy Award from default art assets into the first canvas
	local canvases = SurfaceArt.getCanvases()
	SurfaceArt.placeArt(player, canvases[1], "BloxyAward")
end)
		
				Copy Code
			
				Light Theme

removeAllArt()

void


removeAllArt

()

Removes all artwork from all surfaces.

			
				Script
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.removeAllArt()
		
				Copy Code
			
				Light Theme

Events

artChanged

RBXScriptConnection


artChanged

(

	
		
			BasePart
		
	
	canvas,
	
		
			Frame
		
	
	spot,
	
		
			Vector3
		
	
	spotPosition,
	
		
			string
		
	
	artId,
	
		
			number
		
	
	ownerId

)

Fires when an artwork is changed at a particular location on a canvas. When an artwork is removed, artId will be nil. Note that a datatype/Vector3 value is passed as the third parameter to the event handler so that you can position a custom effect at the exact position where the artwork is placed. This event can only be connected in a LocalScript.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.artChanged:Connect(function(canvas, spot, spotPosition, artId, ownerId)
	print("Art placed at:", spotPosition)
	print("Art asset ID:", artId)
	print("Art placed by:", ownerId)
end)
		
				Copy Code
			
				Light Theme

promptShown

RBXScriptConnection


promptShown

(

	
		
			BasePart
		
	
	canvas

)

Fires when a canvas interaction prompt is shown to a player. The connected function receives the canvas on which the prompt is showing. This event can only be connected in a LocalScript.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.promptShown:Connect(function(canvas)
	print(Players.LocalPlayer, canvas)
end)
		
				Copy Code
			
				Light Theme

promptHidden

RBXScriptConnection


promptHidden

(

	
		
			BasePart
		
	
	canvas

)

Fires when a canvas interaction prompt is hidden. The connected function receives the canvas on which the prompt was showing. This event can only be connected in a LocalScript.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.promptClosed:Connect(function(canvas)
	print(Players.LocalPlayer, canvas)
end)
		
				Copy Code
			
				Light Theme

selectorShown

RBXScriptConnection


selectorShown

()

Fires when the surface art selector UI is shown to a player. This event can only be connected in a LocalScript.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.selectorShown:Connect(function()
	print(Players.LocalPlayer, "opened surface art selector")
end)
		
				Copy Code
			
				Light Theme

selectorHidden

RBXScriptConnection


selectorHidden

()

Fires when the surface art selector UI is hidden for a player. This event can only be connected in a LocalScript.

			
				LocalScript
			
				Expected Output
			
				Expand
				
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage:WaitForChild("SurfaceArt"))

SurfaceArt.selectorHidden:Connect(function()
	print(Players.LocalPlayer, "closed surface art selector")
end)
		
				Copy Code
			
				Light Theme

Previous Photo Booth Next Scavenger Hunt