تتيح خدمة محرر الأفاتار الوصول إلى وإجراء تغييرات على أفاتار المستخدم داخل اللعبة. يمكن أيضًا لخدمة محرر الأفاتار الوصول إلى محتويات المستخدم و السوق لحفظ الملابس وشراء عناصر الأفاتار لحساب المستخدم.
نوصي بتنفيذ خدمة محرر الأفاتار مع محرر أفاتار داخل اللعبة لتجربة تخصيص شخصية كاملة. راجع مثال على محرر الأفاتار البسيط كمرجع لمثال على هذه الميزة.
لبدء استخدام خدمة محرر الأفاتار، يجب عليك أولاً طلب الوصول إلى محتويات المستخدم. بعد منح الوصول بنجاح، يمكنك إجراء الإجراءات التالية:
- قراءة محتويات المستخدم للحصول على قائمة بالعناصر المملوكة من قبل المستخدم.
- البحث في السوق، باستخدام مجموعة متنوعة من الخصائص لتصفية وترتيب النتائج.
- تجهيز عناصر الأفاتار وحفظ الملابس إلى أفاتار المستخدم.
- مطالبة المستخدم بالشراء عنصر من السوق.
طلب الوصول
لبدء الوصول إلى محتويات المستخدم، تحتاج إلى مطالبة المستخدم بالسماح بالوصول من خلال PromptAllowInventoryReadAccess(). تحتاج إلى تنفيذ هذا الطلب مرة واحدة لكل جلسة.
استخدم نموذج الشيفرة التالي لبدء مطالبة الوصول والاستماع لاستجابة المستخدم:
local AvatarEditorService = game:GetService("AvatarEditorService")AvatarEditorService:PromptAllowInventoryReadAccess()local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()if result == Enum.AvatarPromptResult.Success then-- تم منح الوصول!end
سيتلقى المستخدم المطالبة التالية:

بمجرد أن يقبل المستخدم المطالبة، يمكن لـ AvatarEditorService البدء في الوصول إلى محتويات المستخدم.
قراءة محتويات المستخدم
بمجرد منح الوصول من قبل المستخدم، يمكنك قراءة محتوياتهم باستخدام دالة GetInventory()، مع توفير مصفوفة من AvatarAssetTypes للتصفية. تُعيد هذه الدالة كائن InventoryPages يحتوي على العناصر المملوكة من قبل المستخدم.
استخدم نموذج الشيفرة التالي لطباعة قائمة بالملحقات المحددة في محتويات المستخدم:
local AvatarEditorService = game:GetService("AvatarEditorService")AvatarEditorService:PromptAllowInventoryReadAccess()local result = AvatarEditorService.PromptAllowInventoryReadAccessCompleted:Wait()if result == Enum.AvatarPromptResult.Success then-- تم منح الوصول!local assetTypes = {Enum.AvatarAssetType.BackAccessory,Enum.AvatarAssetType.ShoulderAccessory,Enum.AvatarAssetType.WaistAccessory}local pagesObject = AvatarEditorService:GetInventory(assetTypes)local currentPage = pagesObject:GetCurrentPage()for _, item in currentPage doprint(item)endend
البحث في السوق
تتضمن AvatarEditorService دوالًا وأحداثًا تتيح لك البحث في كتالوج Roblox. للبحث، قدم استعلامك باستخدام كائن CatalogSearchParams الذي يتضمن واحدة أو أكثر من الخصائص التالية:
| الخاصية | الوصف |
|---|---|
| AssetTypes | مصفوفة من Enum.AvatarAssetType مثل Enum.AvatarAssetType.BackAccessory. |
| BundleTypes | مصفوفة من Enum.BundleType مثل Enum.BundleType.BodyParts. |
| CategoryFilter | Enum.CatalogCategoryFilter تصف الفئات المختلفة في الكتالوج مثل "البراعم" أو "إنشاءات المجتمع". بشكل افتراضي، يتم تعيين هذا إلى Enum.CatalogCategoryFilter.None |
| MaxPrice | عدد صحيح يصف الحد الأقصى للسعر للتصفية. |
| MinPrice | عدد صحيح يصف الحد الأدنى للسعر للتصفية. بشكل افتراضي، يكون الحد الأدنى للسعر 0. |
| SearchKeyword | سلسلة للاستعلام ضد أوصاف العناصر في الكتالوج. |
| SortType | Enum.CatalogSortType يصف كيفية ترتيب النتائج. بشكل افتراضي، يتم تعيين هذا إلى Enum.CatalogSortType.Relevance. |
| IncludeOffSale | قيمة منطقية تصف ما إذا كانت نتائج البحث تتضمن عناصر غير متاحة للبيع. بشكل افتراضي، يتم تعيين ذلك على false. |
| CreatorId | عدد صحيح لتحديد منشئ محدد. يمكنك استخدام إما UserId أو GroupId. |
| CreatorName | سلسلة تستخدم للبحث عن العناصر التي أنشأها منشئ معين. يمكنك استخدام إما اسم المستخدم أو اسم المجموعة. |
نموذج الشيفرة التالي ينشئ كائن CatalogSearchParams لأنواع الأصول خلفية وكتف، ويمرر ذلك من خلال مكالمة SearchCatalog():
local AvatarEditorService = game:GetService("AvatarEditorService")local catalogSearchParams = CatalogSearchParams.new()local assetTypes = {Enum.AvatarAssetType.BackAccessory,Enum.AvatarAssetType.ShoulderAccessory}catalogSearchParams.AssetTypes = assetTypeslocal pagesObject =--تُعيد هذه الدالة كائن CatalogPages يحتوي على النتائج.AvatarEditorService:SearchCatalog(catalogSearchParams)local currentPage = pagesObject:GetCurrentPage()for _, item in currentPage doprint(item)end
حفظ الأفاتار والملابس
عند استخدامها جنبًا إلى جنب مع محرر الأفاتار داخل اللعبة، يمكن لـ AvatarEditorService حفظ وتحديث عناصر الأفاتار والملابس على منصة Roblox. لا يتلقى المستخدم عناصر كتالوج لا يمتلكها عند حفظ أفاتار أو ملابس.
يمكن حفظ أي HumanoidDescription إلى أفاتار المستخدم الحالي باستخدام PromptSaveAvatar(). قد تشمل:
- تكوينات أفاتار محددة مسبقًا قمت ببنائها باستخدام عناصر كتالوج موجودة.
- أي تكوين اختاره المستخدم من خلال محرر الأفاتار داخل اللعبة.

نظرًا لأن AvatarEditorService:PromptSaveAvatar() لا ينتظر، يمكنك الحصول على النتيجة من خلال الاستماع لحدث AvatarEditorService.PromptSaveAvatarCompleted.
سوف تقوم الشيفرة التالية بحفظ HumanoidDescription الحالي باستخدام PromptSaveAvatar() وتتحقق من نجاح حدث AvatarEditorService.PromptSaveAvatarCompleted:
local AvatarEditorService = game:GetService("AvatarEditorService")local Players = game:GetService("Players")local player = Players.LocalPlayerlocal character = player.Character or player.CharacterAdded:Wait()local humanoid = character:WaitForChild("Humanoid")local currentDescription = humanoid:GetAppliedDescription()AvatarEditorService:PromptSaveAvatar(currentDescription, humanoid.RigType)local result = AvatarEditorService.PromptSaveAvatarCompleted:Wait()if result == Enum.AvatarPromptResult.Success then-- تم حفظ الأفاتار!end
لحفظ أي HumanoidDescription كملابس (دون الكتابة فوق الأفاتار الحالي للمستخدم)، استخدم AvatarEditorService:PromptCreateOutfit().

بمجرد استدعائها، يمكنك الحصول على نتيجة AvatarEditorService:PromptCreateOutfit() بالاستماع لحدث AvatarEditorService.PromptCreateOutfitCompleted.
نموذج الشيفرة التالي ينشئ ملابس باستخدام AvatarEditorService:PromptCreateOutfit() ويستمع لنجاح حدث AvatarEditorService.PromptCreateOutfitCompleted:
local AvatarEditorService = game:GetService("AvatarEditorService")local Players = game:GetService("Players")local player = Players.LocalPlayerlocal character = player.Character or player.CharacterAdded:Wait()local humanoid = character:WaitForChild("Humanoid")local currentDescription = humanoid:GetAppliedDescription()AvatarEditorService:PromptCreateOutfit(currentDescription, humanoid.RigType)local result = AvatarEditorService.PromptCreateOutfitCompleted:Wait()if result == Enum.AvatarPromptResult.Success then-- تم حفظ الملابس!end
شراء العناصر
عند حفظ أفاتار أو ملابس تستخدم عناصر كتالوج، لا يتلقى المستخدم أي عناصر لا يمتلكها. قبل حفظ أفاتار أو ملابس، تحقق مما إذا كان المستخدم يمتلك الأصل باستخدام MarketplaceService:PlayerOwnsAsset() وقدم لهم خيار شراء العنصر باستخدام MarketplaceService:PromptPurchase().
إذا لم ترغب في تنفيذ شراء العناصر، يمكنك بدلاً من ذلك السماح للمستخدمين بتفضيل العناصر غير المملوكة باستخدام AvatarEditorService:PromptSetFavorite().