roblox-characters

Roblox キャラクター

Player は永続するアイデンティティとして扱い、各 Character は固有の参照、接続、アニメーショントラック、クリーンアップを持つ、置き換え可能なセッションとして扱います。Roblox のローリングプラットフォーム API を対象とします。

使用する場面

• プレイヤーキャラクターのライフサイクル、Humanoid の状態や移動、リグ、アニメーション、ツール、アクセサリー、カスタムキャラクター、死亡、リスポーンに関する不具合に使用します。
• コードが Character/Humanoid/root の参照を、スポーンをまたいで保持する場合に使用します。

使用しない場面： 一般的な物理クエリと拘束には roblox-physics を使用します。リモートの信頼性には roblox-networking を使用します。カメラロジックには camera-systems を使用します。

ワークフロー

1. キャラクターの契約を確認します。 アバター設定、StarterCharacter、StarterCharacterScripts、CharacterAutoLoads、R6/R15 のサポート、既存の Animate/controller スクリプト、ツール、タグ、衝突グループ、サーバー／クライアントの所有権を確認します。
2. スコープを分離します。 プレイヤースコープの状態はリスポーン後も維持されますが、キャラクタースコープの状態は維持されません。キャラクターの接続／トラック／リソースを単一のクリーンアップスコープにまとめ、キャラクターの削除時に破棄します。
3. 既存および今後のキャラクターをバインドします。 CharacterAdded に接続し、その後、存在する場合は player.Character をバインドします。イベントの購読だけで、すでにスポーンしたキャラクターも検出できるとは限りません。
4. 必要なコンポーネントを慎重に取得します。 レプリケーションの状況に応じてタイムアウト付きで待機し、Humanoid、root、Animator、リグに関する前提条件を検証します。遅延処理を適用する前に、そのキャラクターがまだ現在のキャラクターか確認し、そうでなければ中断します。
5. 移動の所有者を選択します。 標準的なアバターには Humanoid による移動を使用します。物理的な制御が必要な仕組みに限り、AssemblyLinearVelocity、BasePart:ApplyImpulse()、または LinearVelocity／AlignPosition の拘束を使用します。ゲームプレイの権限とネットワーク所有権への影響を明確にします。
6. アニメーションのライフサイクルを管理します。 リグの Animator 経由で読み込み、トラック／接続を保持します。ゲームプレイのタイミングに名前付きマーカーを使用する場合は、サーバー側で検証します。キャラクターのクリーンアップ時に停止／切断します。
7. ライフサイクルの負荷テストを行います。 スポーン、死亡、リセット、短時間での再スポーン、サポートしている場合はリグの切り替え、ツールの装備／ドロップ、セットアップ中の退出をテストします。キャラクターの相互作用が重要な場合は、少なくとも2人のプレイヤーで実行します。

パターン：置き換え可能なキャラクタースコープ

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local generation = 0
local connections: {RBXScriptConnection} = {}
local currentCharacter: Model? = nil

local function clearCharacter()
    generation += 1
    for _, connection in connections do connection:Disconnect() end
    table.clear(connections)
    currentCharacter = nil
end

local function bindCharacter(character: Model)
    -- Guard BEFORE teardown. A stale invocation (see the CharacterAdded/defer race below) must not
    -- clear a binding that is already current, or nothing ends up bound at all.
    if player.Character ~= character then return end
    clearCharacter()
    currentCharacter = character
    local thisGeneration = generation
    local humanoid = character:WaitForChild("Humanoid", 10)
    local root = character:WaitForChild("HumanoidRootPart", 10)
    -- Re-check after the yields: a respawn during WaitForChild bumps generation and makes this call stale.
    if not humanoid or not root or generation ~= thisGeneration then return end

    table.insert(connections, humanoid.Died:Connect(function()
        if generation ~= thisGeneration then return end
        setCharacterUiEnabled(false)
    end))
    attachCurrentCharacterSystems(character, humanoid, root)
end

player.CharacterRemoving:Connect(function(character)
    if currentCharacter == character then clearCharacter() end
end)
player.CharacterAdded:Connect(bindCharacter)
if player.Character then task.defer(bindCharacter, player.Character) end

プロジェクトにクリーンアップユーティリティがある場合は、それを使用します。接続が3つあるだけで新しいフレームワークを導入しないでください。サーバーシステムでは Player ごとにこのバインドを繰り返し、PlayerRemoving 時にプレイヤースコープのテーブルをクリアします。

パターン：Animator とマーカーを使ったアニメーション

local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://1234567890"
local track = animator:LoadAnimation(animation)
local markerConnection = track:GetMarkerReachedSignal("Commit"):Connect(function(parameter)
    playLocalSwingEffect(parameter) -- presentation; server still validates any hit
end)

track:Play(0.1)
-- On character teardown:
markerConnection:Disconnect()
track:Stop(0.1)
animation:Destroy()

Humanoid のないリグでは、Animator を備えた AnimationController を使用します。実際の Animator とトラックのライフサイクルを管理する代わりに、非推奨の簡易メソッドを使用しないでください。

移動とリグのルール

• R6 に対応している場合は、R15 の四肢名をハードコードしないでください。アタッチメント、タグ、またはリグタイプのアダプターを優先し、トポロジーが実質的に異なる場合にのみ Humanoid.RigType に基づいて分岐してください。
• HumanoidRootPart は通常、キャラクターのアセンブリルートですが、すべてのカスタムモデルで保証されるわけではありません。カスタムリグの契約を定義し、スポーン時に検証してください。
• 通常のアバターの移動には、Humanoid:Move() や標準コントロールを優先してください。AssemblyLinearVelocity を直接変更するのは瞬間的な物理動作です。継続的または瞬間的な物理動作そのものが目的である場合は、力、拘束、またはインパルスを使用してください。
• 移動やジャンプの割り当てを変更したり、スプリントなどのアクションを追加したりする場合は、UserInputService に直接フックするよりも、入力アクションシステム（編集時に定義するデバイス共通の InputContext／InputAction／InputBinding）を優先してください。Workspace.PlayerScriptsUseInputActionSystem が有効な場合、デフォルトのプレイヤーおよびキャラクターのコントロールスクリプトはこのシステムで実行され、デフォルトの PlayerScripts コンテキストが公開されます。デフォルトのバインディングより優先させるには、独自の InputContext に高い Priority（および Sink）を設定してください。UI フォーカスに関する部分は、roblox-ui の入力とナビゲーションのリファレンスを参照してください。
• クライアントがキャラクターの物理演算を所有していることを理由に、ダメージや移動の権限を与えないでください。プレイヤー間に影響する処理はサーバーで検証してください。
• ツールは装備中に Backpack と Character の間を移動します。固定の親を前提にせず、ライフサイクルや状態を監視してください。アクセサリーや外見を変更する場合は、現在のキャラクター API を使用し、アバターの外見を編集する際は適用済みの HumanoidDescription を最新の状態に保ってください。

よくある失敗

症状	考えられる原因	対処法
一度は動作するが、リセット後に壊れる	キャラクター／Humanoid／ルートがキャッシュされている	CharacterAdded ごとに再構築し、削除時にクリアする
死亡後にコールバックが二度実行される	古いキャラクターの接続が残っている	キャラクター単位のクリーンアップと世代／現在のキャラクターのチェックを行う
遅延読み込みで誤ったリグが編集される	非同期処理がスポーン後も継続している	各 yield の後に現在の Character／世代と比較する
アニメーションがローカルでしか見えない、またはまったく表示されない	Animator／コンテキスト／アセット所有権が誤っている	リグの Animator、実行サイド、権限、レプリケーションを確認する
ヒットマーカーが不可能な命中を付与する	アニメーションマーカーを権限の根拠として扱っている	マーカーはタイミング／表示に使い、サーバーが戦闘状態を検証する
R6／カスタムリグでエラーが発生する	R15 の名前を前提にしている	リグの契約を定義し、アタッチメント／アダプターを使い、対応する各リグをテストする
ツールがシステムから消える	Backpack／Character の親が固定だと想定している	装備／解除時の階層変更とキャラクターの置き換えに対応する
カスタムの力が Humanoid と競合する	2 つのコントローラーが動きを制御している	状態ごとに移動の制御権を 1 つだけ選び、適切に復元する

リソース

• サーバーのバインド、死亡と削除の違い、リグとアニメーションの検証、カスタムキャラクター、ライフサイクルのストレステスト一覧については、references/lifecycle-and-animation.md を参照してください。

関連スキル

• roblox-physics — 力、拘束、アセンブリ、衝突、ネットワーク所有権。
• roblox-networking — キャラクターのアクションと古いリクエストのサーバー検証。
• input-systems — アクションの割り当てと応答性の高い移動意図。
• camera-systems — 置き換え可能なキャラクターに追従するカメラの動作。

主なリファレンス

• https://create.roblox.com/docs/characters
• https://create.roblox.com/docs/animation/using
• https://create.roblox.com/docs/characters/appearance