표면 예술 | 설명서 - Roblox 크리에이터 허브

플레이어들은 종종 자신이 있는 공간을 구성하는 일에 참여하고 있다고 느끼는 것을 즐깁니다. SurfaceArt 개발자 모듈은 플레이어가 경험에서 실제로 자신의 흔적을 남길 수 있도록 해줍니다.

기본적으로, 플레이어는 작업 공간의 모든 태그가 지정된 표면에 걸쳐 2개의 예술 작품을 배치할 수 있습니다. 플레이어가 경험을 떠날 때 모든 예술 작품은 제거됩니다.

모듈 사용법

설치

경험에서 SurfaceArt 모듈을 사용하려면:

스튜디오의 창 메뉴 또는 홈 탭 툴바에서 툴박스를 열고 Creator Store 탭을 선택합니다.
모델 정렬이 선택되어 있는지 확인한 후 카테고리의 모두 보기 버튼을 클릭합니다.
패키지 타일을 찾아 클릭합니다.
표면 예술 모듈을 찾아 클릭하거나 3D 뷰로 드래그 앤 드롭합니다.
탐색기 창에서 전체 SurfaceArt 모델을 ReplicatedStorage로 이동합니다. 경험을 실행하면 모듈이 실행되기 시작합니다.

캔버스의 위치 지정

모듈에는 3D 세계에서 배치할 수 있는 하나의 SurfaceCanvas 모델이 포함되어 있습니다. 이 모델은 플레이어가 표면에 예술을 배치하는 데 상호작용하는 부분입니다.

모듈의 주 폴더 내 작업 공간 폴더 안에 있는 SurfaceCanvas 메시를 찾습니다.
그것을 최상위 작업 공간 계층으로 이동시키고 원하는 위치에 배치합니다.
게시/테스트 세션을 실행하면 플레이어는 ProximityPrompt를 통해 해당 객체와 상호작용하고 정의된 표면에 예술을 배치할 수 있습니다.

예술을 배치하기 위해 패키지된 메시를 사용할 필요는 없습니다. 이 모듈은 CollectionService를 사용하여 SurfaceCanvas로 태그된 부품을 찾아 캔버스로 작동하도록 합니다. 태그가 지정된 캔버스는 반드시 BasePart여야 하며, 캔버스 면 변경에서 설명한 대로 표면 면을 정의하는 속성이 있어야 합니다.

캔버스 면 변경하기

모듈의 내부에서는 예술 항목을 표시하기 위해 SurfaceGui를 사용합니다. 예술이 나타나는 면을 구성하려면:

SurfaceCanvas 메시를 선택합니다.
속성 창의 하단에서 기본값이 오른쪽인 SurfaceCanvasFace 속성을 찾습니다.
속성을 클릭하고 Enum.NormalId를 설명하는 여섯 가지 값 중 하나를 입력합니다.

속성 값	해당하는 노말 ID
앞	Enum.NormalId.Front
뒤	Enum.NormalId.Back
오른쪽	Enum.NormalId.Right
왼쪽	Enum.NormalId.Left
상단	Enum.NormalId.Top
하단	Enum.NormalId.Bottom

사용자 정의 예술 자산 사용하기

현재 표면 예술 모듈은 모든 태그가 지정된 캔버스에 대해 동일한 자산 세트만 사용하는 것을 지원합니다.

경험의 테마에 더 잘 맞추기 위해 기본값 대신 자신의 사용자 정의 자산 세트를 사용할 수 있습니다. 이는 ServerScriptService의 Script에서 호출하는 configure 함수를 통해 수행할 수 있습니다.

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

local customAssets = {
	CustomAsset1 = {
		name = "사용자 정의 자산 1",
		assetId = "rbxassetid://7322508294",
	},
	CustomAsset2 = {
		name = "사용자 정의 자산 2",
		assetId = "rbxassetid://7322547665",
	},
}

SurfaceArt.configure({
	assets = customAssets,
})

모든 캔버스 지우기

모든 캔버스에서 모든 기존 예술을 제거하려면 Script에서 removeAllArt 함수를 호출합니다.

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.removeAllArt()

사용자 정의 효과 표시하기

예술 작품을 배치할 때 추가적인 시각 효과를 포함하고 싶을 수 있습니다. 이 모듈은 클라이언트에서 연결하여 자신의 논리를 추가할 수 있는 artChanged라는 이벤트를 노출합니다.

로컬 스크립트
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
		-- 3초 동안 반짝임 효과 표시
		task.spawn(function()
			local emitterAttachment = createParticleEmitter(canvas, spotPosition)
			task.wait(3)
			emitterAttachment:Destroy()
		end)
	end
end)

API 참조

유형

SurfaceArtAsset

캔버스에서 사용되는 이미지는 두 개의 값으로 구성된 테이블로 표현됩니다.

키	설명
name	메타데이터 표시 이름.
assetId	포함할 이미지의 자산 ID.

함수

configure

configure(config: table)

config 테이블의 다음 키/값을 통해 기본 구성 옵션을 덮어씁니다. 이 함수는 Script에서만 호출할 수 있습니다.

키	설명	기본값
enabled	모듈 기능을 켜거나 끕니다.	true
assets	SurfaceArtAsset 유형의 목록입니다.	(아래 코드 참조)
quotaPerPlayer	각 플레이어가 배치할 수 있는 최대 예술 작품 수.	2

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

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

getCanvases

getCanvases(): table

SurfaceCanvas 태그가 지정된 모든 캔버스를 반환합니다.

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

local canvases = SurfaceArt.getCanvases()

placeArt

placeArt(player: Player, canvas: BasePart)

플레이어를 대신하여 프로그래밍 방식으로 예술 작품을 배치합니다. canvas 객체는 서버가 초기화될 때 SurfaceCanvas 태그가 붙어 있어야 합니다. 이는 getCanvases에서 반환된 캔버스와 함께 사용하는 것이 좋습니다.

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

local remoteEvent = ReplicatedStorage:WaitForChild("SurfaceArtRemoteEvent")

remoteEvent.OnServerEvent:Connect(function(player)
	-- 기본 예술 자산에서 Bloxy Award를 첫 번째 캔버스에 배치합니다
	local canvases = SurfaceArt.getCanvases()
	SurfaceArt.placeArt(player, canvases[1], "BloxyAward")
end)

removeAllArt

removeAllArt()

모든 표면에서 모든 예술 작품을 제거합니다.

스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.removeAllArt()

이벤트

artChanged

캔버스의 특정 위치에서 예술 작품이 변경될 때 발생합니다. 예술 작품이 제거될 때는 artId가 nil이 됩니다. 이벤트 핸들러에 세 번째 매개변수로 Vector3 값이 전달되어 예술 작품이 배치된 정확한 위치에 사용자 정의 효과를 위치시킬 수 있습니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

매개변수
canvas: BasePart	예술 작품이 변경된 캔버스입니다.
spot: Frame	예술 작품 ImageLabel을 포함하는 내부 Frame입니다.
spotPosition: Vector3	예술 작품이 배치된 정확한 위치입니다.
artId: string	새로운 예술 작품의 자산 ID입니다.
ownerUserId: number	예술을 배치한 플레이어의 UserId입니다.

로컬 스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.artChanged:Connect(function(canvas, spot, spotPosition, artId, ownerId)
	print("위치에 배치된 예술:", spotPosition)
	print("예술 자산 ID:", artId)
	print("예술을 배치한 사람:", ownerId)
end)

promptShown

캔버스 상호작용 프롬프트가 플레이어에게 표시될 때 발생합니다. 연결된 함수는 프롬프트가 표시되는 캔버스를 받습니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

매개변수
canvas: BasePart	프롬프트가 표시되는 캔버스입니다.

로컬 스크립트
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

캔버스 상호작용 프롬프트가 숨겨질 때 발생합니다. 연결된 함수는 프롬프트가 표시되었던 캔버스를 받습니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

매개변수
canvas: BasePart	프롬프트가 표시되었던 캔버스입니다.

로컬 스크립트
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

표면 예술 선택기 UI가 플레이어에게 표시될 때 발생합니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

로컬 스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.selectorShown:Connect(function()
	print(Players.LocalPlayer, "표면 예술 선택기가 열렸습니다.")
end)

selectorHidden

표면 예술 선택기 UI가 플레이어에게 숨겨질 때 발생합니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

로컬 스크립트
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local SurfaceArt = require(ReplicatedStorage.SurfaceArt)

SurfaceArt.selectorHidden:Connect(function()
	print(Players.LocalPlayer, "표면 예술 선택기가 닫혔습니다.")
end)