Deneyimde Avatar Oluşturma | Dokümantasyon

Aşağıdaki kılavuz, betimleme ile ilgili bilgisi olan ve kullanıcı tarafından üretilen avatar öğelerine izin veren deneyimler geliştirmeyi hedefleyen yaratıcılar için geçerlidir.

Deneyiminiz, oyuncuların avatar bedenlerini gerçek zamanlı olarak oluşturmasına, özelleştirmesine ve satın almasına izin veren bir yayın yapabilirsiniz. Satın alındığında, bu özel bedenler doğrudan oyuncunun Roblox envanterine kaydedilir ve böylece oyuncular, özel avatarları diğer deneyimlerde giyebilir.

Deneyim sahipleri, deneyim içinde avatar oluşturmayı uygularsa, hem avatar öğesi yaratıcısı hem de deneyim sahibi olarak Pazar komisyonlarından yararlanır. Deneyim içinde oluşturulan bir varlık incelendiğinde, öğe oluşturulduğu orijinal deneyime bir bağlantı sağlar.

Deneyim içi oluşturmayı Roblox'un Avatar Oluşturucu demosunda test edebilirsiniz.

Deneyim içinde oluşturulan avatar varlıkları Pazar'da listelenmez ve yeniden satılamaz veya takas edilemez. Bu zamanda, deneyim içinde oluşturma yalnızca özel avatar bedenlerinin oluşturulmasına izin verir.

Deneyim içinde oluşturmayı uygulama

İlk deneyim içi avatar oluşturma projenizi oluşturmak için aşağıdaki talimatları ve kod referanslarını kullanın. Aşağıdaki talimatlar, oyuncuların yayınlamadan önce değiştirebilecekleri ve özelleştirebilecekleri temel bir beden olan Model'ı kullanır.

Başlamadan önce aşağıdakilerle tanışın:

Avatar modelleri — Aşağıdaki uygulama, Roblox'un 15 parçalı spesifikasyonlarına uyan bir temel bedenin içe aktarılmasını gerektirir. Bu Model, kullanıcı özelleştirmesi ve değişikliği için bir temel olarak hizmet eder.
- Temel beden, Roblox'un Avatar beden yönergelerine uymalıdır; bu, yüz riggingi için gereken minimum FACS kontrol sayısını içerir.
Avatar oluşturma jetonları — Avatar oluşturmayı uygulayan deneyimler, en az bir oluşturma jetonu gerektirir. Bu jetonlar Robux ile satın alınır ve deneyim içinde yapılan satın alımlar için fiyatları ve diğer satış ayarlarını ayarlamanıza olanak tanır.
API sınıfları
- AvatarCreationService — Avatar oluşturma istemlerini ve doğrulamayı yönetir.
- EditableImage — Doku oluşturma ve manipülasyonu ile ilgilenir.
- EditableMesh — Mesh geometrisinin runtime manipülasyonu ile ilgilenir.
- WrapDeformer — Avatar karakterlerinin 3D giyim giymelerini sağlayan görünmez dış kafes geometrisinin runtime manipülasyonuyla ilgilenir.

Temel beden içe aktarımı

Temel beden, kullanıcıların özelleştirip düzenleyebileceği ilk temeli oluşturur. Kendi Model'ınızı kullanabilir veya İçe Aktarıcı ile bir özel varlık içe aktarabilir ve Avatar Ayarı aracılığıyla kurabilirsiniz.

Temel bedenler, Roblox'un avatar spesifikasyonlarına uymalıdır ve şu gibi bileşenleri içermelidir: 6 beden parçasını oluşturan 15 MeshPart örneği: baş, gövde, sol kol, sol bacak, sağ kol ve sağ bacak, ayrıca diğer avatar bileşenleri.

Eğer tek parçalı bir bedeniniz varsa, gerekli tüm avatar bileşenlerini otomatik olarak eklemek için Avatar Otomatik Kurulum kullanmayı deneyebilirsiniz.

Doğru yapılandırılmış avatar bedenlerine ilişkin referanslar ve örnekler için Avatar referansları sayfasına bakın.

Düzenleme API'lerini uygulama

Kullanıcıların deneyiminizde bir avatardaki MeshPart örneklerini düzenleyebileceği bir sistem geliştirmek için, doku düzenlemesi için EditableImage, mesh düzenlemesi için EditableMesh ve mesh düzenlemeleri sırasında skin-şemalarını ve FACS verilerini korumak için WrapDeformer kullanın.

Temel bedeninizi içe aktardıktan sonra, EditableImages, EditableMeshes ve WrapDeformers ayarlamak için aşağıdaki script'i kullanın.

local AssetService = game:GetService("AssetService")

local function setupBodyPart(meshPart, wrapTarget)
	-- MeshPart'a bir WrapDeformer oluştur ve ekle
	local wrapDeformer = Instance.new("WrapDeformer")
	wrapDeformer.Parent = meshPart

	-- Sarma hedefinin kafes oklu için bir editable mesh oluştur
	local cageEditableMesh: EditableMesh =
		AssetService:CreateEditableMeshAsync(Content.fromUri(wrapTarget.CageMeshId), {
			FixedSize = true,
		})

	-- Kafes oklu WrapDeformer'a atayın
	wrapDeformer:SetCageMeshContent(Content.fromObject(cageEditableMesh))
end

local function setupRigidMesh(meshPart)
	-- Orijinal MeshPart'tan bir editable mesh oluştur
	local editableMesh = AssetService:CreateEditableMeshAsync(Content.fromUri(meshPart.MeshId), {
		FixedSize = true,
	})

	-- Editable mesh'ten yeni bir MeshPart oluştur
	local newMeshPart = AssetService:CreateMeshPartAsync(Content.fromObject(editableMesh))

	-- Orijinal MeshPart'tan boyut, konum ve doku kopyalayın
	newMeshPart.Size = meshPart.Size
	newMeshPart.CFrame = meshPart.CFrame
	newMeshPart.TextureContent = meshPart.TextureContent

	-- Yeni MeshPart'ı orijinaline uygulayın
	meshPart:ApplyMesh(newMeshPart)
end

local function setupMeshTexture(meshPart, textureIdToEditableImageMap)
	-- Eğer bu TextureID için EditableImage zaten varsa, yeni bir tane oluşturmamak için kullan
	if textureIdToEditableImageMap[meshPart.TextureID] then
		meshPart.TextureContent =
			Content.fromObject(textureIdToEditableImageMap[meshPart.TextureID])
		return
	end

	-- Yeni bir EditableImage oluşturun ve dokuyu içerik olarak uygulayın
	local editableImage = AssetService:CreateEditableImageAsync(Content.fromUri(meshPart.TextureID))
	textureIdToEditableImageMap[meshPart.TextureID] = editableImage
	meshPart.TextureContent = Content.fromObject(editableImage)
end

local function setupModel(model)
	-- Doku ID'sine göre EditableImage örneklerini tekrar kullanmak için bir harita
	local textureIdToEditableImageMap = {}
	for _, descendant in model:GetDescendants() do
		if not descendant:IsA("MeshPart") then
			continue
		end

		-- MeshPart'a WrapTarget mevcut olup olmadığını kontrol ederek yapılandırın
		-- Eğer WrapTarget mevcutsa, içine EditableMesh ekleyerek bir WrapDeformer çocuğu ekleyin
		-- Aksi takdirde, doğrudan MeshPart'a EditableMesh uygulayın
		local wrapTarget = descendant:FindFirstChildOfClass("WrapTarget")
		if wrapTarget then
			setupBodyPart(descendant, wrapTarget)
		else
			setupRigidMesh(descendant)
		end

		-- MeshPart için EditableImage'i yapılandırın
		setupMeshTexture(descendant, textureIdToEditableImageMap)
	end
end

Oyuncuların temel bedeninize yeniden boyama, çizim yapma veya çıkartmalar eklemelerini sağlayan EditableImage araçları oluşturun. DrawImage(), DrawRectangle(), WritePixelsBuffer() gibi API'leri kullanabilirsiniz.

Gelişmiş dönüşümler için, DrawImageTransformed() kullanılabilir ve bir EditableImage'yi diğerinin üzerine çizerken pozisyon, döndürme ve ölçeği belirtebilirsiniz. Benzer şekilde, DrawImageProjected() kullanımı, DrawImage()'e benzer, ancak çizilen resmi doğru şekilde projenler.

local function recolorTexture(
	meshPart: MeshPart,
	color: Color3
)
	local bodyPartTexture = AssetService:CreateEditableImageAsync(meshPart.TextureID)
	meshPart.TextureContent = Content.fromObject(bodyPartTexture)

	bodyPartTexture:DrawRectangle(
		Vector2.new(0, 0),
		bodyPartTexture.Size,
		color,
		0,
		Enum.ImageCombineType.Overwrite
	)
end

local function applySticker(
	meshPart: MeshPart,
	textureCoordinate: Vector2,
	stickerId: TextureId
)
	local bodyPartTexture = AssetService:CreateEditableImageAsync(meshPart.TextureID)
	meshPart.TextureContent = Content.fromObject(bodyPartTexture)

	local stickerTexture = AssetService:CreateEditableImageAsync(stickerId)
	bodyPartTexture:DrawImage(textureCoordinate, stickerTexture, Enum.ImageCombineType.BlendSourceOver)
end

local function applyStickerProjected(
  meshPart: MeshPart,
  targetMesh: EditableMesh,
  stickerId: TextureId,
  raycastHitPos: Vector3
)
  local bodyPartTexture = AssetService:CreateEditableImageAsync(meshPart.TextureID)

  local relativePos = meshPart.CFrame:PointToWorldSpace(raycastHitPos)
  local direction = (workspace.CurrentCamera.CFrame.Position - relativePos).Unit

  local projectionParams: ProjectionParams = {
      Direction = meshPart.CFrame:VectorToObjectSpace(direction),
      Position = meshPart.CFrame:PointToObjectSpace(relativePos),
      Size = Vector3.new(1, 1, 1),
      Up = meshPart.CFrame:VectorToObjectSpace(Vector3.new(0, 1, 0)),
  }

  local stickerTexture = AssetService:CreateEditableImageAsync(stickerId)
  local localBrushConfig: BrushConfig = {
      Decal = stickerTexture,
      ColorBlendType = Enum.ImageCombineType.BlendSourceOver,
      AlphaBlendType = Enum.ImageAlphaType.Default,
      BlendIntensity = 1,
      FadeAngle = 90.0
  }

  bodyPartTexture:DrawImageProjected(targetMesh, projectionParams, localBrushConfig)
end

WrapDeformer ve EditableMesh kullanarak bedeninizde mesh deformasyonlarını düzenlemek için araçlar oluşturun.

WrapDeformer, render edilen MeshPart geometrisindeki canlı deformasyonları, altındaki skinning ve FACS verilerini koruyarak yönetir.

EditableMesh, WrapDeformer'ın tepki verdiği kafes ağını değiştirmenizi sağlar.

WrapDeformer:SetCageMeshContent() kullanarak, WrapDeformer'a ilgili kafes ağını temsil eden EditableMesh örneğini uygulayın.
EditableMesh kullanarak, SetPosition() gibi, düğümlerin şeklini değiştirebilir ve MeshPart'ın şeklini düzenleyebilirsiniz.

local function deformBodyPart(
	meshPart: MeshPart,
	controlPointCenter: Vector3,
	controlPointRadius: number,
	controlPointDeformation: Vector3
)
	local wrapTarget = meshPart:FindFirstChildWhichIsA("WrapTarget")
	local cageMeshId = wrapTarget.CageMeshId
	local wrapDeformer = Instance.new("WrapDeformer")
	wrapDeformer.Parent = meshPart

	local cageEditableMesh = AssetService:CreateEditableMeshAsync(cageMeshId)
	local verticesWithinSphere =
		cageEditableMesh:FindVerticesWithinSphere(controlPointCenter, controlPointRadius)
	for _, vertexId in verticesWithinSphere do
		local vertexPosition = cageEditableMesh:GetPosition(vertexId)
		cageEditableMesh:SetPosition(vertexId, vertexPosition + controlPointDeformation)
	end

	wrapDeformer:SetCageMeshContent(Content.fromObject(cageEditableMesh))
end

Oluşturma istemi oluşturma

Temel bedeninizi ve düzenleme API'lerinizi kurduktan sonra, kullanıcıların deneyimden avatar oluşturmalarına ve satın almalarına olanak tanıyan bir istem oluşturun. Bu işlem için AvatarCreationService:PromptCreateAvatarAsync() kullanılır.

export type BodyPartInfo = {
	bodyPart: Enum.BodyPart,
	instance: Instance -- Oluşturulan MeshParts ile Klasör
}
export type BodyPartList = {BodyPartInfo}

local function publishAvatar(bodyPartInstances: BodyPartList, player: Player, tokenId: string)
	local humanoidDescription = Instance.new("HumanoidDescription")
	for _, bodyPartInfo in bodyPartInstances do
		local bodyPartDescription = Instance.new("BodyPartDescription")
		bodyPartDescription.Instance = bodyPartInfo.instance
		bodyPartDescription.BodyPart = bodyPartInfo.bodyPart
		bodyPartDescription.Parent = humanoidDescription
	end

	local success, result, bundleIdOrErrorMessage, outfitId = pcall(function()
		return AvatarCreationService:PromptCreateAvatarAsync(tokenId, player, humanoidDescription)
	end)
	if success then
		if result == Enum.PromptCreateAvatarResult.Success then
			print("Başarıyla BundleId ile yüklendi: ", bundleIdOrErrorMessage)
      print("Başarıyla OutfitId ile yüklendi: ", outfitId)
		else
			print("Hata mesajı ile başarısız yükleme:", bundleIdOrErrorMessage)
		end
	else
		print("Avatar oluşturma başarısız")
	end
end

AvatarCreationService:PromptCreateAvatarAsync() bir HumanoidDescription parametresi alır ve bu, satın almayı veya oluşturmayı amaçlayan avatarı temsil eder. Avatar oluşturma işleminde, karakterin HumanoidDescription'u, 6 beden parçası için oluşturulması gereken yeni varlıkları içermelidir (Head, Torso, RightLeg, LeftLeg, RightArm, LeftArm). İsteğe bağlı olarak, yeni bir Hair aksesuarı da içerebilir.

Bunun desteklenmesi için, HumanoidDescription'un 6 BodyPartDescription çocuğu içermesi gerekir. Her BodyPartDescription.Instance özelliği, beden parçasını oluşturan tüm MeshPart örneklerini içeren bir Folder referansını içermelidir. Örneğin, LeftArm klasörü LeftHand, LeftUpperArm ve LeftLowerArm MeshParts'ı içerir. BodyPartDescription.BodyPart özelliği de ilgili Enum.BodyPart olarak ayarlanmalıdır.

15 MeshPart beden parçasının her biri şunları içermelidir:

Bir EditableImage.
Bir WrapDeformer ile birlikte bir EditableMesh.

Sağlanan HumanoidDescription, hedef oluşturma üzerindeki beden parçalarını veya aksesuarları temsil eden herhangi bir önceden var olan varlık ID'si içermemelidir. Öte yandan, HumanoidDescription , BodyTypeScale, HeadScale, HeightScale, WidthScale ve ProportionScale gibi humanoid oranlarını içerebilir. Bir temel bedenin içe aktarılmış olduğu oranları göz önünde bulundurmak önemli, böylece bunlar HumanoidDescription'a sağlanan oranlarla eşleştiğinden emin olmalısınız.

Aksesuarlar ekleyin

Bir aksesuar ekliyorsanız, örneğin saç, HumanoidDescription'un bir AccessoryDescription çocuğunu içermesi gerekmektedir. Burada:

AccessoryDescription.Instance özelliği, Accessory örneğini referans alır.
AccessoryDescription.AccessoryType özelliği, ilgili Enum.AccessoryType olarak ayarlanır.
- Oluşturduğunuz varlıklarda Enum.AccessoryType.Hair ekliyorsanız, MeshPart bir EditableImage içermelidir. Ancak, içinde bir WrapDeformer çocuğu olmamalıdır, bunun yerine MeshPart üzerinde bir EditableMesh set edilmiş olmalıdır.

Bir avatar oluşturma jetonu oluşturma

AvatarCreationService:PromptCreateAvatarAsync() bir Avatar Oluşturma Jetonu ID'si parametresi alır. Bu jeton, evreninizden oluşturmalara yönelik anahtardır ve deneyiminizden avatar oluşturmanın fiyatını ayarlamak için kullanabileceğiniz şeydir. Jetonların oluşturulması hakkında talimatlar ve ek detaylar için Avatar Oluşturma Jetonları sayfasına bakın.

Jetonunuzu satın aldıktan ve oluşturduktan sonra, sizi AvatarCreationService:PromptCreateAvatarAsync() API'si için kullandığınız ID'yi bulmak üzere Yaratıcı Merkezi'nde jetonu inceleyebilirsiniz.

Oyunlara katılan oyunculara yanıt verin

Deneyim içinde oluşturulan avatar paketleri, avatarlı oluşturulan orijinal deneyime bir atıf bağlantısı içerir. Avatar bir başka oyuncu tarafından incelendiğinde, avatarın oluşturulduğu deneyimi ziyaret etme seçeneği sunan bir istem gösterilir.

Bu atıf bağlantısını kullanarak deneyiminize katılan oyuncuları yönetmek için Player:GetJoinData() kullanın ve döndürülen tabloyu GameJoinContext için ayrıştırın.

GameJoinContext, aşağıdaki tablo değerlerini içerir:

JoinSource — Enum.JoinSource
- Bu atıf bağlantısından deneyiminize katılan bir Player, oluşturulmuş bir öğeden giriş yapıldığını gösteren Enum.JoinSource.CreatedItemAttribution ile etiketlenir.
ItemType — isteğe bağlı Enum.AvatarItemType
AssetId — isteğe bağlı string
OutfitId — isteğe bağlı string
AssetType — isteğe bağlı Enum.AssetType