roblox-npcs

roblox-npcs

公式ソース：

• https://create.roblox.com/docs/en-us/characters/pathfinding
• https://create.roblox.com/docs/en-us/workspace/streaming
• エンジンクラス：PathfindingService、Path、PathWaypoint、PathfindingModifier、PathfindingLink、Humanoid

Roblox のナビゲーションメッシュ上での移動には、PathfindingService を使用します。計算されたパスをもとに、巡回、追跡などの動作を構築してください。

PathfindingService の基本

パスを作成します：

local PathfindingService = game:GetService("PathfindingService")

local path = PathfindingService:CreatePath({
    AgentRadius = 2,
    AgentHeight = 5,
    AgentCanJump = true,
    AgentCanClimb = false,
    WaypointSpacing = 4,
    Costs = {
        Water = 20,
        DangerZone = math.huge,
    }
})
path.CalculationSecondsTimeout = 1

計算して追従します：

local humanoid = character:WaitForChild("Humanoid")
local rootPart = character:WaitForChild("HumanoidRootPart")

local success, err = pcall(function()
    path:ComputeAsync(rootPart.Position, endPos)
end)

if success and path.Status == Enum.PathStatus.Success then
    local waypoints = path:GetWaypoints()
    -- follow waypoints with Humanoid:Move()
end

エージェントのパラメーター

パラメーター	デフォルト	用途
AgentRadius	2 studs	障害物から確保する最小距離
AgentHeight	5 studs	垂直方向のクリアランス
AgentCanJump	true	ジャンプするウェイポイントを許可します
AgentCanClimb	false	はしご状のパーツを登れるようにします
WaypointSpacing	4 studs	中間ウェイポイント間の距離
Costs	nil	マテリアル／領域／リンクの通行コスト

Path.CalculationSecondsTimeout は、ComputeAsync の呼び出しごとにソルバーが実行できる時間を制限します。CreatePath の後、計算の前に設定してください。

PathWaypoint のアクション

各ウェイポイントには Position と Action があります：

• Enum.PathWaypointAction.Walk：通常の移動です。
• Enum.PathWaypointAction.Jump：ジャンプを実行します。
• "Climb" や "UseBoat" などのカスタムラベル（PathfindingModifier／Links から指定）。

PathfindingModifier

アンカー付きの非衝突パーツに PathfindingModifier インスタンスを配置すると、パスのコストに影響を与えられます：

• Label：Costs テーブルで使用するキーです。
• PassThrough：true の場合、ナビゲーションメッシュはそのボリュームを無視し、通行可能な空間として扱います（例：ゾンビがドア越しに「音を聞く」場合）。

例：

local path = PathfindingService:CreatePath({
    Costs = {
        Water = 20,
        DangerZone = math.huge,
        UseBoat = 2,
    }
})

PathfindingLink

PathfindingLink は、カスタムラベルとコストを指定して 2 つの Attachment を接続し、通常は通行できない隙間を越えるパスを可能にします。

用途：

• 水上を渡るボート
• テレポーター
• はしご
• 一方向のジャンプ

移動コードでウェイポイントのラベルを確認し、カスタムの通行処理を実行します。

移動パターン

追従

移動するターゲットへのパスを継続的に再計算します。再計算の頻度を制限し（例：0.5～1 秒ごと）、ターゲットが十分に移動した場合にのみ再計算してください。

巡回

固定地点のリストを順番に巡ります。通行できなくなった場合は再計算します。

追跡

追従と同様ですが、視線が通っていることと距離をサーバー側で検証します。信頼性が求められる AI では、クライアントが報告した位置を信用しないでください。

ステートマシン

一般的な NPC の状態には、Idle、Patrol、Chase、Attack、Return があります。各状態で独自にパスの計算と Humanoid の制御を行います。

ストリーミングとの互換性

• サーバー側のスクリプトはワールド全体の状態を把握でき、任意のパーツへのパスを計算できます。
• クライアント側のスクリプトでは、目的地がストリーミングで読み込まれていない場合、失敗することがあります。クライアント側のパスの目的地には、workspace.PersistentLoaded と永続モデルを使用してください。
• 動的な障害物やストリーミングされた障害物が進路を塞いだ場合は、パスを再計算してください。

制限事項

• 視線が直接通る距離は 3,000 studs 以下です。
• 計算ノードの上限は約 20,000 ノードです。
• ウェイポイントの Y 座標は -65,536～+65,536 studs の範囲でなければなりません。
• パラメーターに互換性がない場合（例：ジャンプのみで到達できる目的地に対して AgentCanJump = false を指定）は失敗します。

大規模運用時のパフォーマンス

• 毎フレームではなく、時間をずらしたスケジュールでパスを再計算します。
• 可能であれば、同種の NPC 間でターゲットの位置を共有します。
• 長い直線経路で中間ウェイポイントを減らすには、WaypointSpacing = math.huge を使用します。
• エージェントの形状を簡略化するか、アクティブなエージェントの数を減らすことを検討してください。
• 非常に広大なワールドでは、領域に分割するか、ローカルな巡回パスを使用してください。

よくある間違い

• 毎フレーム、パスを計算する。
• パスが塞がれたイベントを無視し、NPC が壁に向かって歩き続ける。
• 信頼性が求められる AI で、クライアントの位置を信用する。
• ComputeAsync を pcall で囲むのを忘れる。
• Costs でマテリアル名を誤って指定する（文字列として Enum.Material の名前と一致させる必要があります）。

スクリプト

• scripts/NPCPathFollower.lua：Humanoid ベースのパスフォロワーです。ブロックされたパスの再計算、カスタムラベルのサポート、接続のクリーンアップに対応しています。
• scripts/PatrolBehavior.lua：空間検出と再計算の頻度制限に対応した、状態駆動型の巡回／追跡動作です。
• scripts/PathfindingUtility.lua：再計算の頻度制限とウェイポイントのフォーマット用ヘルパーです。

ベストプラクティス

• CreatePath の後に Path.CalculationSecondsTimeout を設定し、ソルバーの処理時間を制限します。
• Humanoid:MoveTo には必ず明示的なタイムアウトを設定し、ウェイポイントに到達したとき、またはフォロワーを停止したときにキャンセルします。
• 各フレームですべてのプレイヤーを走査する代わりに、workspace:GetPartBoundsInRadius のような空間クエリでターゲットを検出します。
• Humanoid が死亡したとき、または NPC が破棄されたときは、パスフォロワーを停止し、Heartbeat 接続をクリーンアップします。
• リスポーンする NPC では、新しいキャラクターモデルに対して新しい動作インスタンスを作成し、古いインスタンスを Destroy します。
• PathfindingLink のラベルを使って、カスタムの移動ロジック（ボート、テレポーター、はしごなど）を起動します。フォロワーは登録済みのハンドラーを呼び出します。登録されていない場合、ウェイポイントは通常の移動にフォールバックします。
• 登る動作を有効にするには、AgentCanClimb = true を設定し、TrussPart の表面を用意します。登りウェイポイントの Label は "Climb" です。
• PathfindingModifier のパーツは、Anchored = true および CanCollide = false にする必要があります。

進め方

1. エージェントのサイズと移動能力を定義します。
2. 特殊な領域用のモディファイアー／リンクを使ってワールドを構築します。
3. ウェイポイント、ジャンプ、ブロックイベントに対応するパスフォロワーを実装します。
4. 複雑な動作のためにステートマシンを組み合わせます。
5. 権威性のある AI を実現するためサーバーで実行し、ビジュアルの予測にはクライアントのみを使用します。
6. MicroProfiler でプロファイリングし、多数のエージェントの再計算を時間的に分散させます。

リファレンス一覧

• modifiers-links-and-streaming.md：NPC を特殊な領域に誘導する方法や、ストリーミングされたジオメトリを処理する方法を説明します。
• npc-behavior-patterns.md：巡回、追跡、戦闘、または状態遷移を実装する方法を説明します。
• pathfinding-service-details.md：エージェントの設定、パスの計算、またはブロックされたウェイポイントの処理方法を説明します。
• performance-and-scaling.md：NPC の数が増えるにつれて、パスファインディングとシミュレーションのコストを抑える方法を説明します。