👕

【Roblox】character アバターアイテムの着用

2024/09/23に公開

はじめに

プロジェクトで作成したアバターアイテムの着用に関する処理についてまとめました。

バージョン:0.641.0.6410737

HumanoidDescriptionについて


エクスプローラー上
HumanoidDescriptionは主にキャラクターの外見の情報を決定するインスタンスです。

StarterPlayerのプロパティであるLoadCharacterAppearanceがtrueになっている場合(初期状態)、ゲーム外で設定したアバターに応じたHumanoidDescriptionをキャラクター生成時に自動で読み込みます。

次の関数を使用してHumanoidDescriptionを取得できます。

  • Humanoid:GetAppliedDescription()Humanoidが現在反映している衣装
  • Players:GetHumanoidDescriptionFromUserId()、Roblox のユーザーが現在着用している衣装。
  • Players:GetHumanoidDescriptionFromOutfitId()、Roblox のユーザーが作成した衣装セット用。

HumanoidDescriptionのプロパティ


HumanoidDescriptionのプロパティ
この画像はHumanoidDescriptionのプロパティです。

ボディの色やパーツの項目から素体を変更できますが、今回は衣装に絞った記述をしていきます。

衣装プロパティ

  • GraphicTShirt
  • Pants
  • Shirt

この3項目があります。
ゲーム外では”定番の〇〇”と称される、素体にテクスチャを張り付けることで服を表現するタイプのアバターアイテムが入ります。

アクセサリプロパティ

メッシュで構成されたアバターアイテムはここに分類されます。

このプロパティはAccessoryBlobかその他かで、大きく二つに分けられ、重ね着仕様の装備の場合にはAccessoryBlob側に加えられます。

local accessories = Description:GetAccessories(true)

HumanoidDescriptionGetAccessories(boolean)を呼ぶことでこのアクセサリーを配列で取得することができます。
引数のboolean値が偽の場合AccessoryBlobのアクセサリーだけを、真の場合は他も含めたものが戻り値の配列に入っています。

戻り値の配列のエントリには以下の要素が含まれています。

{
  AccessoryType,    --アクセサリーの分類
  AssetId,          --アセットID
  IsLayered,        --重ね着装備機能を利用するか
  Order,            --重ね着する場合のレイヤー深度の値
  Puffines          --重ね着した服のふくらみ
}

IsLayeredがtrueの場合にのみOrdernilではない値を返しました。

アクセサリーが装備されたHumanoidDescription

HumanoidDescription:SetAccessories(Accessories, includeRigidAccessories)

HumanoidDescriptionSetAccessories(array, boolean)を呼ぶことでアクセサリーを更新できます。

引数
Accessories:設定したいアクセサリーの配列
includeRigidAccessories:アクセサリーの保存箇所を定める為のboolean値(HumanoidDescription:GetAccessoriesで使用したboolean値と一致)

HumanoidDescription:GetAccessories(boolean)で取得したアクセサリー配列に要素を足して、戻すという流れになります。
Orderの要素が存在しない(nil)アクセサリーの場合AccessoryTypeの要素の次第でどこのプロパティに値が代入されるは関数側で適切に対応されます。

Orderの値が存在するアクセサリーは、重ね着装備である為AccessoryBlobに加えられます。
昇順に外側へと着込んでいく為の値です。

これで更新するべき外見を纏めたHumanoidDescriptionが完成しました。

ゲーム内に反映する

Humanoid:ApplyDescription(humanoidDescription)
--Humanoid:ApplyDescriptionReset(humanoidDescription)

引数
humanoidDescription:上記で作成したキャラクターに適応させる為のhumanoidDescription

HumanoidApplyDescription(humanoidDescription)か、ApplyDescriptionReset(humanoidDescription)を呼ぶことでキャラクターの見た目を更新することが出来ます。

ApplyDescriptionとApplyDescriptionResetの違いについて

ApplyDescriptionは、これら2つの関数以外の手段での外見の変更が行われていない前提で最適化がなされています。
逆に、他の手段で変更されていた際にも対応可能なのが後者のApplyDescriptionResetです。

どちらもサーバー側でのみ機能し、クライアント側から呼ぶとエラーを吐きます。
Characterの元についているインスタンスの為、再構築する際に再度反映させる必要があります。

ゲーム外に反映する

ゲーム外アバター変更ダイアログを表示する

Roblox側が管理しているゲーム外のアバターの更新はAvatarEditorServiceが必要です。

AvatarEditorService:PromptSaveAvatar(HumanoidDescription, RigType)

引数
humanoidDescription:上記までで活用したキャラクターに適応させる為のhumanoidDescription
RigType:キャラクターのリグの種類列挙Humanoid.RigTypeから取得できる

AvatarEditorServicePromptSaveAvatar(HumanoidDescription, RigType)を呼ぶことで衣装変更のダイアログが出せます。


アバター変更ダイアログ
Playerを表す引数が無い通り、こちらはクライアント側からしか行えません
追加するアバターアイテムをプレイヤーが所有していない場合正しく反映されません(ダイアログ側にの”追加中”には表示されるが実際には適応されない)
Studio環境で画面サイズ次第では警告文が表示されるようです
ゲーム外の装備ルールに準拠するようです(重ね着装備の上限を超えられない、同一項目の複数装備は基本出来ない、等)

ゲーム外アバター変更ダイアログの結果

local function SaveCompletedFunction(promptResult)
  --承認しなかった場合関数を返す
  if promptResult ~= Enum.AvatarPromptResult.Success then
	return
  end
      --承認した場合の処理
end
AvatarEditorService.PromptSaveAvatarCompleted:Connect(SaveCompletedFunction)

登録したメソッドの引数
promptResultEnum.AvatarPromptResult。ダイアログの承認の結果
こちらもPlayerを表す引数が無い通り、クライアント側からしか行えません

今回の開発では、このダイアログの承認時の処理でゲーム内の装備着用の処理を行いました。
ゲーム内アイテムによる装備品ではないアバターは、セーブの処理を行っていない為、キャラクター再構築の度にゲーム外アカウントのアバターが反映されてしまいます。なので可能な限り同期させる方針で対処致しました。

まとめ

  • HumanoidDescriptionは主にキャラクターの外見を纏めたインスタンスである
  • HumanoidDescription:GetAccessoriesHumanoidDescription:SetAccessoriesの利用、プロパティの直接の干渉を行い、キャラクターに適応したい外見のHumanoidDescriptionを作る必要がある
  • Humanoid:ApplyDescriptionを使い、ゲーム内のアバターにHumanoidDescriptionを適応する
  • AvatarEditorService:PromptSaveAvatarを使い、ゲーム外のアバターの変更を促すことができる
  • AvatarEditorService.PromptSaveAvatarCompletedイベントを使用し、変更が承認されたかを所得することができる

参考

https://create.roblox.com/docs/reference/engine/classes/Humanoid
https://create.roblox.com/docs/reference/engine/classes/HumanoidDescription
https://create.roblox.com/docs/reference/engine/classes/AvatarEditorService
https://create.roblox.com/docs/players/avatar-editor

ランド・ホー Roblox開発チーム

Discussion