Arte della Superficie | Documentazione

I giocatori spesso amano 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 gioco.

Per impostazione predefinita, un giocatore può posizionare 2 opere d'arte su tutte le superfici contrassegnate nel workspace. Tutte le opere d'arte di un giocatore verranno rimosse quando lasceranno il gioco.

Utilizzo del Modulo

Installazione

Per utilizzare il modulo SurfaceArt in un gioco:

Dal menu Finestra di Studio o dalla barra degli strumenti della scheda Home, apri il Toolbox e seleziona la scheda Creator Store.
Assicurati che sia selezionato l'ordinamento Modelli, quindi fai clic sul pulsante Vedi Tutti per le Categorie.
Individua e fai clic sulla tessera Pacchetti.
Individua il modulo Arte della Superficie e fai clic su di esso, oppure trascinalo nella vista 3D.
Nella finestra Explorer, sposta l'intero modello SurfaceArt in ReplicatedStorage. Una volta avviato il gioco, 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 opere d'arte sulla sua superficie.

Individua il mesh SurfaceCanvas all'interno della cartella Workspace della cartella principale del modulo.
Spostalo nella gerarchia di Workspace di livello superiore e posizionalo dove desiderato.
Una volta pubblicata/avviata una sessione di test, i giocatori potranno interagire con l'oggetto tramite un ProximityPrompt e posizionare opere d'arte sulla superficie definita.

Non è necessario utilizzare il mesh confezionato per posizionare opere d'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 deve avere un attributo che definisce la faccia della superficie come descritto in Cambiamento della Faccia della Tela.

Cambiare la Faccia della Tela

Sotto il cofano, il modulo utilizza un SurfaceGui per visualizzare gli elementi d'arte. Per configurare su quale superficie appare l'arte:

Seleziona il mesh SurfaceCanvas.
In fondo alla finestra Proprietà, individua l'attributo SurfaceCanvasFace con un valore predefinito di Destra.
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 d'Arte Personalizzate

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

Per adattarsi meglio al tema del tuo gioco, puoi utilizzare il tuo set di risorse personalizzate invece dei valori 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 tutte le opere d'arte esistenti 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 effetti visivi aggiuntivi quando un'opera d'arte viene 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 dei 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 di tipi SurfaceArtAsset.	(vedi codice sotto)
quotaPerPlayer	Numero massimo di opere d'arte che possono essere posizionate da ciascun giocatore.	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'opera d'arte programmaticamente per conto di un giocatore. Nota che l'oggetto canvas deve essere contrassegnato con il tag SurfaceCanvas quando il server viene 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 dagli asset d'arte predefiniti 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

Si attiva quando un'opera d'arte viene cambiata in una posizione particolare 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 personalizzato esattamente nella posizione in cui è stata posizionata l'opera d'arte. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	Canvas su cui è stata cambiata l'opera d'arte.
spot: Frame	Interno Frame che contiene l'opera d'arte ImageLabel.
spotPosition: Vector3	Posizione esatta in cui è stata posizionata l'opera d'arte.
artId: string	ID 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

Si attiva quando un prompt di interazione con la tela viene mostrato a un giocatore. La funzione connessa riceve la tela su cui viene mostrato il prompt. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	Canvas su cui viene mostrato il prompt.

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

Si attiva quando un prompt di interazione con la tela viene nascosto. La funzione connessa riceve la tela su cui era mostrato il prompt. Questo evento può essere connesso solo in uno LocalScript.

Parametri
canvas: BasePart	Canvas su cui era mostrato il prompt.

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

Si attiva quando l'interfaccia utente del selettore di arte della 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 di arte della superficie")
end)

selectorHidden

Si attiva quando l'interfaccia utente del selettore di arte della 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 di arte della superficie")
end)