Arte sulla Superficie | Documentazione

I giocatori spesso apprezzano sentirsi parte della costruzione dello spazio in cui si trovano. Il modulo SurfaceArt developer module consente ai giocatori di lasciare letteralmente il proprio segno in un'esperienza.

Per impostazione predefinita, un giocatore può posizionare 2 opere d'arte su tutte le superfici contrassegnate nello spazio di lavoro. Tutte le opere d'arte di un giocatore verranno rimosse quando lasceranno l'esperienza.

Utilizzo del Modulo

Installazione

Per utilizzare il modulo SurfaceArt in un'esperienza:

Dal menu Finestra di Studio o dalla barra degli strumenti della scheda Home, apri il Toolbox e seleziona la scheda Negozio Creatore.
Assicurati che il filtro Modelli sia selezionato, quindi fai clic sul pulsante Vedi Tutti per Categorie.
Individua e fai clic sulla piastrella Pacchetti.
Individua il modulo Arte sulla Superficie e fai clic su di esso, oppure trascinalo nel visuale 3D.
Nella finestra Esplora, sposta l'intero modello SurfaceArt in ReplicatedStorage. Una volta avviata l'esperienza, il modulo inizierà a funzionare.

Posizionamento della Tela

Il modulo viene fornito con un modello SurfaceCanvas che puoi posizionare nel mondo 3D. Questo modello è quello con cui i giocatori interagiranno per posizionare arte sulla sua superficie.

Individua il modello SurfaceCanvas all'interno della cartella Workspace della cartella principale del modulo.
Spostalo nella gerarchia di Workspace a livello superiore e posizionalo dove desiderato.
Pubblicando/avviando una sessione di test, i giocatori potranno interagire con l'oggetto tramite un ProximityPrompt e posizionare arte sulla superficie definita.

Non è obbligatorio utilizzare la mesh in bundle per posizionare arte. Il modulo utilizza CollectionService per individuare le parti contrassegnate come SurfaceCanvas e farle funzionare come tele. Qualsiasi tela contrassegnata deve essere un BasePart e dovrebbe avere un attributo che definisce la faccia della superficie come descritto in Cambiamento della Faccia della Tela.

Cambiare la Faccia della Tela

Nel backend, il modulo utilizza un SurfaceGui per visualizzare gli oggetti d'arte. Per configurare quale superficie l'arte appare:

Seleziona la mesh SurfaceCanvas.
In fondo alla finestra Proprietà, individua l'attributo SurfaceCanvasFace con un valore predefinito di Right.
Fai clic sull'attributo e inserisci uno dei sei valori che descrivono un Enum.NormalId.

Valore dell'Attributo	ID Normale Corrispondente
Frente	Enum.NormalId.Front
Retro	Enum.NormalId.Back
Destra	Enum.NormalId.Right
Sinistra	Enum.NormalId.Left
Alto	Enum.NormalId.Top
Basso	Enum.NormalId.Bottom

Utilizzo di Risorse Artistiche Personalizzate

Attualmente, il modulo per l'arte sulla superficie supporta solo l'uso dello stesso set di risorse per tutte le tele contrassegnate.

Per adattare meglio il tema della tua esperienza, puoi utilizzare un tuo set di risorse personalizzate invece dei predefiniti. Questo può essere fatto tramite la funzione configure, chiamata da uno Script in ServerScriptService.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

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

SurfaceArt.configure({
	assets = customAssets,
})

Cancellare Tutte le Tele

Per rimuovere tutta l'arte esistente da tutte le tele nel mondo, chiama la funzione removeAllArt da uno Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.removeAllArt()

Mostrare Effetti Personalizzati

Potrebbero esserci casi in cui desideri includere ulteriori effetti visivi quando un'opera è posizionata. Questo modulo espone un evento chiamato artChanged sul client a cui puoi connetterti e aggiungere la tua logica.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.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
		-- Mostra alcune scintille per 3 secondi
		task.spawn(function()
			local emitterAttachment = createParticleEmitter(canvas, spotPosition)
			task.wait(3)
			emitterAttachment:Destroy()
		end)
	end
end)

Riferimento API

Tipi

SurfaceArtAsset

Le immagini da utilizzare come arte per la tela sono rappresentate da una tabella con due valori.

Chiave	Descrizione
name	Nome visualizzato nei metadati.
assetId	ID dell'asset dell'immagine da includere.

Funzioni

configure

configure(config: table)

Sovrascrive le opzioni di configurazione predefinite tramite le seguenti chiavi/valori nella tabella config. Questa funzione può essere chiamata solo da uno Script.

Chiave	Descrizione	Predefinito
enabled	Attiva o disattiva la funzionalità del modulo.	true
assets	Elenco dei tipi di SurfaceArtAsset.	(vedi codice sotto)
quotaPerPlayer	Numero massimo di opere d'arte che ogni giocatore può posizionare.	2

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

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

getCanvases

getCanvases(): table

Restituisce tutte le tele contrassegnate con il tag SurfaceCanvas.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

local canvases = SurfaceArt.getCanvases()

placeArt

placeArt(player: Player, canvas: BasePart)

Posiziona un pezzo d'arte programmaticamente per conto di un giocatore. Nota che l'oggetto canvas deve essere contrassegnato con il tag SurfaceCanvas quando il server è inizializzato. Si consiglia di utilizzare questo solo con una tela restituita da getCanvases.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

local remoteEvent = ReplicatedStorage:WaitForChild("SurfaceArtRemoteEvent")

remoteEvent.OnServerEvent:Connect(function(player)
	-- Posiziona il Bloxy Award dai risorse artistiche predefinite nella prima tela
	local canvases = SurfaceArt.getCanvases()
	SurfaceArt.placeArt(player, canvases[1], "BloxyAward")
end)

removeAllArt

removeAllArt()

Rimuove tutte le opere d'arte da tutte le superfici.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.removeAllArt()

Eventi

artChanged

Viene attivato quando un'opera d'arte viene cambiata in un particolare punto su una tela. Quando un'opera d'arte viene rimossa, artId sarà nil. Nota che un valore Vector3 viene passato come terzo parametro al gestore dell'evento in modo da poter posizionare un effetto custom esattamente nella posizione in cui è stata posizionata l'opera d'arte. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	La tela sulla quale l'opera d'arte è stata cambiata.
spot: Frame	Internal Frame che contiene l' ImageLabel dell'opera d'arte.
spotPosition: Vector3	Posizione esatta in cui è stata posizionata l'opera d'arte.
artId: string	ID dell'asset della nuova opera d'arte.
ownerUserId: number	UserId del giocatore che ha posizionato l'arte.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.artChanged:Connect(function(canvas, spot, spotPosition, artId, ownerId)
	print("Arte posizionata a:", spotPosition)
	print("ID asset dell'arte:", artId)
	print("Arte posizionata da:", ownerId)
end)

promptShown

Viene attivato quando un prompt di interazione della tela viene mostrato a un giocatore. La funzione connessa riceve la tela sulla quale viene mostrato il prompt. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	La tela sulla quale il prompt è mostrato.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.promptShown:Connect(function(canvas)
	print(Players.LocalPlayer, canvas)
end)

promptHidden

Viene attivato quando un prompt di interazione della tela viene nascosto. La funzione connessa riceve la tela sulla quale il prompt era mostrato. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	La tela sulla quale il prompt era mostrato.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.promptClosed:Connect(function(canvas)
	print(Players.LocalPlayer, canvas)
end)

selectorShown

Viene attivato quando l'interfaccia utente del selettore dell'arte sulla superficie viene mostrata a un giocatore. Questo evento può essere connesso solo in uno LocalScript.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.selectorShown:Connect(function()
	print(Players.LocalPlayer, "ha aperto il selettore dell'arte sulla superficie")
end)

selectorHidden

Viene attivato quando l'interfaccia utente del selettore dell'arte sulla superficie viene nascosta per un giocatore. Questo evento può essere connesso solo in uno LocalScript.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.selectorHidden:Connect(function()
	print(Players.LocalPlayer, "ha chiuso il selettore dell'arte sulla superficie")
end)