roblox-characters-animation

キャラクターとアニメーション

キャラクターの基本

• プレイヤーキャラクターは、Humanoid、HumanoidRootPart（ルート。character:PivotTo(cframe) でキャラクターを移動します）、R15 のボディパーツ、および Animate LocalScript を持つ Model です。
• デフォルト値（歩行速度、ジャンプ、ヘルス、R6/R15、衝突、ボディのスケーリング）は、Studio の Avatar Settings ウィンドウと StarterPlayer（CharacterWalkSpeed、CharacterJumpHeight、または CharacterUseJumpPower + CharacterJumpPower）で設定します。
• カスタムキャラクター: StarterPlayer に StarterCharacter という名前の Model を配置します。プレイヤーごとのカスタムスポーン: Players.CharacterAutoLoads = false に設定し、準備ができたとき（たとえばデータの読み込み後）に player:LoadCharacterAsync() を呼び出します。LoadCharacter（非 Async）は非推奨です。
• キャラクターは死亡/リスポーン時に破棄され再生成されます。キャラクターごとのロジックは CharacterAdded でバインドします。
• クライアントが設定した WalkSpeed/JumpHeight は容易に悪用されます。サーバーで制限を強制するか、サーバー権限（roblox-security、roblox-physics）を使用してください。

ヘルスとダメージ（サーバー）

--!strict
local Players = game:GetService("Players")

local function damage(target: Model, amount: number, source: Player?)
	local humanoid = target:FindFirstChildOfClass("Humanoid")
	if not humanoid or humanoid.Health <= 0 then
		return
	end
	humanoid:SetAttribute("LastDamagedBy", if source then source.UserId else 0)
	humanoid:TakeDamage(amount) -- respects ForceField; use Health -= amount to bypass
end

Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function(character)
		local humanoid = character:WaitForChild("Humanoid") :: Humanoid
		humanoid.MaxHealth = 150
		humanoid.Health = 150
		humanoid.Died:Once(function()
			local killerId = humanoid:GetAttribute("LastDamagedBy")
			print(`{player.Name} died (killer {killerId})`)
		end)
	end)
end)

return damage

• StarterCharacterScripts 経由で Health スクリプトを削除または置き換えることで、デフォルトの再生を無効にします。
• ラグドールには Humanoid.BreakJointsOnDeath = false とラグドール拘束を使用します。
• 状態: humanoid:ChangeState(Enum.HumanoidStateType.Jumping)、SetStateEnabled(state, false)、StateChanged。MoveDirection、FloorMaterial、RootPart、SeatPart は読み取り専用のヘルパーです。
• humanoid:MoveTo(position) は NPC を歩かせます（8 秒でタイムアウトします。長い経路の場合は再発行してください。roblox-npc-ai を参照）。

外見

--!strict
local Players = game:GetService("Players")

local function applyUniform(player: Player)
	local character = player.Character
	local humanoid = character and character:FindFirstChildOfClass("Humanoid")
	if not humanoid then
		return
	end
	local ok, description = pcall(function()
		return Players:GetHumanoidDescriptionFromUserIdAsync(player.UserId)
	end)
	if not ok then
		return
	end
	description.Shirt = 123456 -- asset ids
	description.Pants = 654321
	description.HeightScale = 1.05
	pcall(function()
		humanoid:ApplyDescriptionAsync(description) -- server-side; replicates
	end)
end

return applyUniform

Player:LoadCharacterWithHumanoidDescriptionAsync(description) は、装備を指定して直接スポーンします。非 Async のバリアント（ApplyDescription、GetHumanoidDescriptionFromUserId など）はすべて非推奨です。

アニメーションの再生

--!strict
local function playAttack(character: Model, animation: Animation): AnimationTrack?
	local humanoid = character:FindFirstChildOfClass("Humanoid")
	local animator = humanoid and humanoid:FindFirstChildOfClass("Animator")
	if not animator then
		return nil
	end
	local track = animator:LoadAnimation(animation) -- Humanoid:LoadAnimation is deprecated
	track.Priority = Enum.AnimationPriority.Action
	track.Looped = false
	track:GetMarkerReachedSignal("Hit"):Connect(function(param)
		print("hit frame reached", param) -- apply damage window, play sound, etc.
	end)
	track:Play(0.1) -- fade time
	return track
end

return playAttack

• 再生する場所: ローカルプレイヤー自身のキャラクター → クライアントで再生します（その Animator を通じて自動的にレプリケートされます）。NPC → サーバーで再生します（純粋に見た目だけの、数の多い NPC の場合はクライアントで再生してもかまいません）。
• 各 Animation は Animator ごとに一度読み込み、トラックを再利用してください。アクションが発生するたびに LoadAnimation を呼び出さないでください（Animator ごとのトラック数には上限があります）。例外: サーバー権限（ライブのトラックを問い合わせる）。
• 優先度: Core < Idle < Movement < Action < Action2 < Action3 < Action4。AdjustWeight でブレンドし、AdjustSpeed で速度を変更し、Stop(fadeTime) で停止します。
• イベント: track.Stopped、track.Ended、マーカーは GetMarkerReachedSignal 経由です（KeyframeReached は置き換えられました）。
• アニメーションアセットは、体験のオーナーが所有している（またはアセット権限を通じて共有されている）必要があります。そうでない場合、ライブサーバーでは再生に静かに失敗します。
• デフォルトを置き換えるには、CharacterAdded で Animate スクリプトの StringValue/Animation の子（animate.run.RunAnim.AnimationId）を編集するか、StarterCharacterScripts にカスタムの Animate を配置します。
• プロシージャル: 手書きのジョイント計算の代わりに IKControl（注視、フットプランティング、リーチング）を使用します。

トゥイーン

--!strict
local TweenService = game:GetService("TweenService")

local door = Instance.new("Part")
door.Anchored = true
door.Parent = workspace

local info = TweenInfo.new(0.6, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)
local open = TweenService:Create(door, info, { CFrame = door.CFrame * CFrame.new(0, 8, 0) })
open.Completed:Once(function(state)
	print("door tween finished:", state)
end)
open:Play()

• アンカーされたパーツまたは UI をトゥイーンします。アンカーされていない/物理オブジェクトには拘束を使用してください。
• サーバー上でのトゥイーンは毎フレームレプリケートされ、カクつきます。見た目だけの動きには、各クライアントでトゥイーンします（サーバーは最終状態、またはクライアントが反応する属性を設定します）。
• モデル: CFrameValue をトゥイーンし、その Changed ハンドラーで model:PivotTo(value) を呼び出すか、残りを溶接したプライマリパーツをトゥイーンします。
• カスタム補間には TweenService:GetValue(alpha, style, direction)、追従モーションには SmoothDamp を使用します。

ツール

Handle パーツを持つ（または RequiresHandle = false の）StarterPack/Backpack 内の Tool です。Equipped、Unequipped、Activated はクライアントとサーバーの両方で発火します（Activated はクライアントから送信されます。サーバーでレートと状態を検証してください）。武器のロジックはモジュールに保ち、すべてのツールのクローン内にスクリプトを置くのではなくタグを使用してください。

Character Controller Library (ベータ)

Roblox の CCL（require("@rbx/AvatarAbilities")）は、固定の Humanoid ステートマシンを、ラベル、センサー、 条件（All/Any/Not を伴う StartsWhen/RunsWhile）、競合（Blocks/Stops/Suspends）、 およびライフサイクルコールバックによって調整される、組み合わせ可能な アビリティ（Running、Jumping、Climbing、カスタム Dash など）に置き換えます。有効にするには、File → Beta Features および Avatar Settings → Movement → Abilities を使用します。プロジェクトがオプトインしている場合にのみ使用してください。ベータ版の間は API が変更される可能性があります。 スケッチ: references/character-controller-library.md。

関連スキル

roblox-npc-ai（NPC の移動）、roblox-physics（ラグドール、ノックバック）、roblox-input（アビリティの入力）、 roblox-security（移動/ダメージの検証）、roblox-game-systems（戦闘）。