roblox-core

roblox-core

主な情報源： https://create.roblox.com/docs/en-us/scripting/services, https://create.roblox.com/docs/en-us/luau, https://create.roblox.com/docs/en-us/luau/tables, https://create.roblox.com/docs/en-us/luau/type-checking, https://create.roblox.com/docs/en-us/scripting/locations, https://create.roblox.com/docs/en-us/projects/data-model, https://create.roblox.com/docs/en-us/projects/client-server, https://create.roblox.com/docs/en-us/workspace/streaming, https://create.roblox.com/docs/en-us/scripting/multithreading, https://create.roblox.com/docs/en-us/scripting/attributes

スクリプトの初期化

1. local Service = game:GetService("ServiceName")。一度だけ実行し、変数名にはサービス名を使います。
2. local Module = require(ReplicatedStorage:WaitForChild("Module"))
3. ローカルヘルパー関数。
4. イベントに接続します。

サービスは、従来の標準ライブラリの代わりにエンジン機能へアクセスする主な手段です。

最新の task ライブラリ

最新の task API を使用してください。従来のグローバル関数 wait()、spawn()、delay() は非推奨、または非推奨化が進んでいます。

• task.wait(n?)：約 n 秒間（デフォルトでは1フレーム）待機し、経過時間を返します。
• task.spawn(f, ...)：f を非同期で実行するようスケジュールします。
• task.defer(f, ...)：現在のイベントサイクルの後まで f の実行を延期します。
• task.cancel(thread)：task.spawn／task.defer が返したスレッドをキャンセルします。

並列コードでは、task.desynchronize() と task.synchronize() により、現在のスレッドを並列フェーズと直列フェーズの間で切り替えます。

用途別サービス

コンテナ／階層サービス（Explorer に表示され、DataModel の一部です）：

• Workspace（3D コンテンツ）
• Lighting（環境、大気、ポストエフェクト）
• ReplicatedStorage／ReplicatedFirst（共有コードとアセット）
• ServerScriptService（サーバー専用ロジック）
• StarterGui／StarterPlayer／StarterPack（プレイヤーに複製されるテンプレート）
• Players、Teams、SoundService など

コアランタイムとスクリプティングのサービス：

• RunService：Heartbeat は両側で物理演算後に発生します。PreSimulation は両側で物理演算前に発生します。PreRender はクライアント専用で、レンダリング前に発生します。
• TweenService（アニメーションのスキルを参照）
• CollectionService（タグ）
• ContextActionService、UserInputService、GuiService
• ContentProvider（事前読み込み）

クラウド／永続化／サーバー間通信：

• DataStoreService、MemoryStoreService、MessagingService（roblox-datastores スキルを参照）

収益化：

• MarketplaceService（ゲームパス、開発者製品。専用スキルを参照）
• BadgeService など

その他の重要なサービス： TeleportService、AnalyticsService、HttpService（送信のみ＋JSONEncode／Decode）、PathfindingService など。

サービスの確認には game:GetService（既知のサービス）または game:FindService（任意）を使用します。サービスの確認に game:GetChildren() を使うのは避けてください。DataModel の子要素すべてがサービスとは限らず、サービスは遅延作成される場合があります。各スクリプト／モジュールでサービスを取得するのは一度だけにしてください。

インスタンス作成のベストプラクティス

不要な複製や変更イベントの追加発生を避けるため、インスタンスは親に設定する前に構成します。

local part = Instance.new("Part")
part.Anchored = true
part.Size = Vector3.new(4, 1, 2)
part.Position = Vector3.new(0, 10, 0)
part.Parent = workspace

Parent は最後に設定してください。2引数形式の Instance.new("Part", parent) は使用しないでください。

型とシリアル化

永続化する値を設計する前、またはシリアル化の問題をデバッグする前に、luau-data-types-and-serialization.md をお読みください。DataStore、JSON、リモートでは、それぞれ対応する型が異なります。JSONEncode が成功すれば有用な確認にはなりますが、その値が DataStore のすべての制約を満たすとは限りません。

型チェック

段階的かつオプトインで利用できます。ファイルの先頭に --!strict を指定すると（ファイル単位）、またはプロジェクト全体の型チェックには .luaurc のプロジェクト設定を使えます。大規模なモジュールには型注釈（local x: number、関数シグネチャ）を追加してください。多くの処理は型推論が担います。実行時コストゼロで、編集時にバグを検出できます。

スクリプトの配置場所と実行コンテキスト

• ServerScriptService + Script（RunContext.Server）→ サーバーのみで実行され、DataStores などのサーバー API にアクセスできます。
• ReplicatedStorage → 共有の ModuleScripts／アセットを格納します。ここにある Script は、RunContext が Client または Server に設定されている場合のみ実行されます。ロジックの共有には ModuleScripts を使用してください。
• StarterGui + LocalScript → プレイヤーごとのクライアントのみで実行されます（クローンされた PlayerGui 内）。
• ReplicatedFirst + LocalScript → クライアントで非常に早い段階に実行されます（ローディング画面など）。
• Actor + RunContext.Client/Server を指定した Script → コードで task.desynchronize() を呼び出すか、ConnectParallel() を使用すると、Parallel Luau を実行できます。Actor は DataModel の子にする必要があり、Script には明示的な RunContext が必要です。Script を Actor の中に置くだけでは並列化されません。require() は、モジュール自体が並列実行に対応している場合にのみ並列コンテキストから呼び出せます。ほとんどのエンジン API と多くのモジュールは対応していません。
• ツールには特殊な実行コンテキストがあります。HopperBins は非推奨のレガシー機能のため、新規の開発では使用しないでください。

最新の Roblox では、BaseScript.RunContext（Legacy、Server、Client、Plugin）を使用します。Legacy は後方互換性のためだけに存在し、配置場所によって動作が異なります。新しいコードでは、明示的な Server または Client を優先してください。RunContext は Studio の Properties ウィンドウで設定し、実行時は読み取り専用です。

実行時の権限は、常に RunService:IsServer() と IsClient() で判定してください。IsStudio() は環境（Studio か本番環境か）を検出するものであり、実行コンテキストを判定するものではありません。そのため、テスト／開発用のガードにのみ使用してください。

クライアントから直接影響を与えられる場所には、DataStore への書き込み、経済処理、または権威を持つゲームプレイロジックを絶対に配置しないでください。

Luau／Roblox における「ファイル」とデータ

実行中のエクスペリエンスからは、セキュリティ上、ファイルシステムに直接アクセスできません。任意のファイルを開いたり、プレイヤーに表示されるログを書き込んだりすることはできません。

代わりに、次のものを使用できます。

• 永続的または一時的な「セーブデータ」には、DataStores／MemoryStores を使用します。
• 再利用可能なコードには ModuleScripts を使用します（require はキャッシュ付きのモジュールシステムのように動作し、ModuleScript は一度実行され、その後の require では同じ値が返されます）。
• 外部とのデータ交換には、HttpService:JSONEncode/Decode と Web 呼び出しを使用します。
• Studio では、プラグインに限定的なファイル API があり、外部ツール（Rojo、Script Sync）を使ってファイルシステムからコードを同期できます。ただし、エクスペリエンスのスクリプトが任意のファイルシステムにアクセスすることはできません。

複雑なデータは、保存や転送のためにテーブルを JSON 文字列にシリアライズすることがよくあります。

追加の実行時の考慮事項

• Attributes：軽量なインスタンスごとのデータには :SetAttribute／GetAttribute を使用してください。レガシーの Value オブジェクトより優先してください。
• Random：グローバルな math.randomseed の代わりに、決定論的または独立した乱数ストリームを生成できる Random クラス（Random.new(seed)）を使用してください。
• StreamingEnabled：クライアントでは、インスタンスがストリーミングによって読み込まれたり、読み込み解除されたりします。常に WaitForChild／Instance.StreamingMode を使って安全に処理し、離れた場所にあるパーツへの直接参照は避けてください。
• table utilities：table.create(n, value)、table.find(t, value)、table.clone(t)、table.freeze(t)／table.isfrozen(t) は、最新のヘルパーです。
• BaseScript.Enabled：スクリプトを削除せずに無効化／有効化します。
• ModuleScript caching：require は各環境で ModuleScript を一度だけ実行し、返された値をキャッシュします。
• Sequence / physical types：NumberSequence、ColorSequence、PhysicalProperties は、パーティクル、ビーム、パーツのマテリアルによく使われる Roblox のデータ型です。

アーキテクチャの基礎

• 安全性を確保するため、サーバー権限をデフォルトとします。
• レプリケーションは選択的に行い、ストリーミングを考慮します。
• 共有モジュール／アセットには ReplicatedStorage、サーバーロジックには ServerScriptService、クライアント UI のエントリーポイントには StarterGui を使用します。
• 大規模な Instance 階層を使わずに軽量なグループ化やデータを扱うには、CollectionService のタグと Attributes を使用します。
• メインスレッド以外で CPU 負荷の高い処理を実行する必要がある場合は、Parallel Luau と Actor を使用します。

スクリプト

• scripts/ServiceHelper.lua：サービスを安全に取得し、タイムアウト付きでモジュールを require するための小さなユーティリティです。

リファレンス索引

• luau-data-types-and-serialization.md：データ型を選択したり、シリアライズの失敗を診断したりできます。
• script-locations-contexts-and-architecture.md：スクリプトの実行場所を決定したり、読み込みやレプリケーションの問題をデバッグしたりできます。
• services-catalog-and-usage.md：サービスを選択したり、サービスやモジュールを読み込んだりできます。