要点
各プレイヤーのアイテムは、サーバーの ServerScriptService の ModuleScript の中の表に入れておき、アイテムの追加、削除、スタックはこのコードだけが行うようにします。アイテムは ReplicatedStorage の ModuleScript に一度だけ定義します(id、名前、最大スタック数)。変更のたびに、サーバーはそのプレイヤーにインベントリのコピーを RemoteEvent で送り、LocalScript が ScrollingFrame と UIGridLayout でそれをグリッドとして描きます。
- クライアントがアイテムを追加することは決してありません。できるのは「剣を装備して」のようなお願いだけで、サーバーは何かをする前に、プレイヤーがそれを持っているかを確認します。
- アイテムが現れるのは、あなたが管理するサーバーのコードを通したときだけです。拾ったとき、サーバーで確認したショップでの購入、報酬などです。
- DataStoreService で保存するのは Tool ではなくアイテムの id と個数で、プレイヤーが抜けたとき、サーバーが終了するとき、そして数分ごとに保存します。データが読み込めなかったプレイヤーは決して保存しません。
このページの内容
インベントリの仕組み
このシステムは6つの小さな部品でできていて、それぞれに仕事が1つあります。アイテムに関するルールはすべて1つのサーバーモジュールにあるので、何かが壊れたときに探す場所はちょうど1か所です。
| 部品 | 種類と場所 | 仕事 |
|---|---|---|
ItemCatalog | ReplicatedStorage の ModuleScript | 各アイテムが何であるか。名前、説明、最大スタック数、装備や使用ができるか。サーバーとすべてのクライアントが読みます。 |
InventoryService | ServerScriptService の ModuleScript | 全プレイヤーのスロットを持ちます。アイテムの追加、削除、スタックを行う唯一のコードです。 |
InventoryData | ServerScriptService の Script | 参加時にプレイヤーのアイテムを読み込み、保存します。 |
InventoryActions | ServerScriptService の Script | 装備と使用のリクエストを確認して実行します。 |
ItemPickup | Part の中の Script | 拾った人にアイテムを渡します。 |
InventoryClient | StarterPlayerScripts の LocalScript | グリッドを描いてリクエストを送ります。自分では何も変えません。 |
データは一方向に流れます。サーバーがインベントリを変え、そのプレイヤーにインベントリ全体を付けて InventoryUpdated を送り、クライアントがそれを描き直します。プレイヤーがスロットをクリックすると、クライアントはアイテムの id を付けて EquipItem か UseItem を送ります。サーバーはリクエストを確認して変更を加え、新しいコピーが同じ道を通って届きます。変更分だけを送るより、インベントリ全体を送るほうがシンプルで、スロットが数十個程度ならメッセージは小さいままです。
クライアントにアイテムを追加させない理由
アイテムを表示している LocalScript の中で、そのままアイテムを追加したくなります。プレイヤーがクリックしたら、スロットが埋まる、という具合です。これは2つの点で破綻します。
- ほかの誰にも見えません。LocalScript での変更は、そのプレイヤーのデバイスの中にしか存在しません。サーバーはそれを知らないので保存されず、どのサーバースクリプトもそれを使えません。
- 誰でも偽装できます。
AddItem(itemId, amount)のようなリモートで直そうとすると、チーターがそのイベントを自分で、好きな引数で、好きなだけ呼べてしまいます。Roblox のセキュリティのガイドには、サーバーはクライアントから送られたものを使う前にすべて確認しなければならないと書かれています。
そのためこのガイドでは、クライアントにできるのは、プレイヤーがすでに持っているアイテムについて何かをお願いすることだけです。「これを装備して」と「これを使って」です。どのリクエストにもアイテムの id が1つだけ入っていて個数はなく、サーバーでは1つの確認を通ります。文字列であること、そのアイテムが存在すること、プレイヤーが少なくとも1つ持っていること、プレイヤーが1秒に4回より多くリクエストを送っていないことです。それからサーバーが自分でカタログから Tool を見つけます。同じガイドが注意しているとおり、クライアントから Tool、パス、インスタンスを受け取ることは決してありません。
アイテムがインベントリに入るのは、サーバーのコードを通したときだけです。サーバーが確認した拾得、サーバーがお金を引いた購入(ショップのガイドで作っています)、クエストの報酬やドロップです。ほかの種類の引数の確認も含めたリモート全般については、RemoteEvent のガイドを読んでください。
ステップ1: Explorer を準備する
次のオブジェクトを手で作ります。この先のステップのスクリプトは名前でこれらを探すので、どの名前もここに書いてあるとおりに付けてください。
- ReplicatedStorage に
InventoryRemotesという名前の Folder を挿入します。その中に、InventoryUpdated、EquipItem、UseItemという名前の RemoteEvent を3つ挿入します。 - ServerStorage に
ItemToolsという名前の Folder を挿入します。その中にSwordという名前の Tool を、Tool の中にHandleという名前の Part を挿入します(1 x 4 x 1 スタッドで十分です)。Handle の Anchored のチェックが外れていることを確認してください。Roblox は、Anchored のパーツがあるツールを持つとキャラクターがその場から動けなくなると注意しています。名前がステップ2のカタログと一致していれば、すでに持っている Tool を使ってもかまいません。 - スクリプトはステップを進めながら追加します。それぞれの置き場所はツリーに示してあります。
ReplicatedStorage
ItemCatalog ModuleScript new
InventoryRemotes Folder new
InventoryUpdated RemoteEvent new
EquipItem RemoteEvent new
UseItem RemoteEvent new
ServerScriptService
InventoryService ModuleScript new
InventoryData Script new
InventoryActions Script new
ServerStorage
ItemTools Folder new
Sword Tool new
Handle Part new
StarterPlayer
StarterPlayerScripts
InventoryClient LocalScript new
Workspace
Apple Part new
ItemPickup Script new
ステップ2: カタログにアイテムを定義する
カタログは、存在しうるすべてのアイテムを一度だけ定義します。インベントリが持つのはアイテムの id と個数だけです。こうすると保存データは小さいままで、あとでアイテムの名前を変えたり説明を書き直したりしても、誰の保存データにも触れずに済みます。
ReplicatedStorage に ModuleScript を挿入し、名前を ItemCatalog にして、中身を次のものに置き換えます:
-- ゲームに存在しうるすべてのアイテム。このリストはサーバーとすべての
-- クライアントが読みます。誰が何を持っているかを決めるのはサーバーだけです。
export type Item = {
id: string, -- 下のキーと一致させます
name: string,
description: string,
maxStack: number, -- このアイテムが1つのスロットにいくつ入るか
icon: string?, -- 任意の画像: "rbxassetid://" に画像の ID を付けたもの
toolName: string?, -- ServerStorage.ItemTools の Tool: このアイテムは装備できます
heal: number?, -- 回復する体力: このアイテムは消耗品です
}
local items: { [string]: Item } = {
sword = {
id = "sword",
name = "Sword",
description = "Equip it to put it in your hand.",
maxStack = 1,
toolName = "Sword",
},
apple = {
id = "apple",
name = "Apple",
description = "Use it to restore 25 health.",
maxStack = 10,
heal = 25,
},
wood = {
id = "wood",
name = "Wood",
description = "A building material.",
maxStack = 50,
},
}
local ItemCatalog = {}
-- この id のアイテムを返します。そのアイテムがなければ nil です
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
任意のフィールドで、アイテムが何をするかが決まります。toolName があれば装備でき、heal があれば使えます。木材のようにどちらもないアイテムは、ほかのサーバーのコード(クラフト、売却)が取り除くまでインベントリに入ったままです。
アイテムを追加するには、キーと id が一致するエントリを追加します。id は大文字と小文字を区別し、保存されるのは id なので、プレイヤーがすでに持っているアイテムの id は決して変えないでください。変えるのは name にします。
ステップ3: インベントリをサーバーで持つ
この ModuleScript が全プレイヤーのインベントリを持ちます。各インベントリはスロットのリストで、各スロットにはアイテムの id と個数が入り、容量は 20 スロットです。ほかのサーバースクリプトはこの関数を呼び、ほかには誰も表を編集しません。
ServerScriptService に ModuleScript を挿入し、名前を InventoryService にします:
-- インベントリを変える唯一のコード。ServerScriptService にあるので、
-- クライアントは見ることも実行することもできません。
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- strict モードは WaitForChild 経由の require が何を返すかわからないので、
-- このスクリプトが使うモジュールの部分を書いておきます
type Item = { id: string, maxStack: number }
type Catalog = { get: (id: string) -> Item? }
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local inventoryUpdated = remotes:WaitForChild("InventoryUpdated") :: RemoteEvent
export type Slot = { id: string, count: number }
type Inventory = { slots: { Slot }, capacity: number, equipped: string? }
local CAPACITY = 20 -- プレイヤー1人あたりのスロット数
local STARTER_ITEMS: { Slot } = { -- まったく新しいプレイヤーが最初に持つもの
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- 持ち主にインベントリのコピーを送ります。変更のたびに呼ばれます。
local function sync(player: Player)
local inventory = inventories[player]
if inventory then
inventoryUpdated:FireClient(player, {
capacity = inventory.capacity,
slots = inventory.slots,
equipped = inventory.equipped,
})
end
end
-- スタックのルール: まず満杯でないスタックを埋め、それから空いたスロットで
-- 新しいスタックを始めます。追加した数を返します。頼まれた数より少ないこともあります。
local function addToInventory(inventory: Inventory, item: Item, amount: number): number
local remaining = amount
for _, slot in inventory.slots do
if remaining == 0 then
break
end
if slot.id == item.id and slot.count < item.maxStack then
local moved = math.min(item.maxStack - slot.count, remaining)
slot.count += moved
remaining -= moved
end
end
while remaining > 0 and #inventory.slots < inventory.capacity do
local moved = math.min(item.maxStack, remaining)
table.insert(inventory.slots, { id = item.id, count = moved })
remaining -= moved
end
return amount - remaining
end
function InventoryService.count(player: Player, itemId: string): number
local inventory = inventories[player]
local total = 0
if inventory then
for _, slot in inventory.slots do
if slot.id == itemId then
total += slot.count
end
end
end
return total
end
-- そのアイテムがあといくつ入るか: 既存のスタックの空きと空いたスロットの合計
function InventoryService.spaceFor(player: Player, itemId: string): number
local inventory = inventories[player]
local item = ItemCatalog.get(itemId)
if not inventory or not item then
return 0
end
local space = (inventory.capacity - #inventory.slots) * item.maxStack
for _, slot in inventory.slots do
if slot.id == itemId then
space += item.maxStack - slot.count
end
end
return space
end
-- アイテムを最大 amount 個まで追加します。追加した数を返します(アイテムが
-- 存在しない、インベントリが満杯、またはまだ読み込まれていないときは 0)。
function InventoryService.add(player: Player, itemId: string, amount: number): number
local inventory = inventories[player]
local item = ItemCatalog.get(itemId)
local wanted = math.floor(amount)
if not inventory or not item or wanted < 1 then
return 0
end
local added = addToInventory(inventory, item, wanted)
if added > 0 then
sync(player)
end
return added
end
-- アイテムをちょうど amount 個、最後のスタックから取り除きます。
-- プレイヤーの持っている数が足りなければ、何も取り除かずに false を返します。
function InventoryService.remove(player: Player, itemId: string, amount: number): boolean
local inventory = inventories[player]
local wanted = math.floor(amount)
if not inventory or wanted < 1 or InventoryService.count(player, itemId) < wanted then
return false
end
local remaining = wanted
-- table.remove でスロットを飛ばさないように、後ろから進みます
for index = #inventory.slots, 1, -1 do
local slot = inventory.slots[index]
if slot.id == itemId then
local taken = math.min(slot.count, remaining)
slot.count -= taken
remaining -= taken
if slot.count == 0 then
table.remove(inventory.slots, index)
end
if remaining == 0 then
break
end
end
end
sync(player)
return true
end
function InventoryService.getEquipped(player: Player): string?
local inventory = inventories[player]
return if inventory then inventory.equipped else nil
end
function InventoryService.setEquipped(player: Player, itemId: string?)
local inventory = inventories[player]
if inventory then
inventory.equipped = itemId
sync(player)
end
end
-- プレイヤーの保存データが読み込まれたときに呼ばれます。saved はデータストアが
-- 返したもので、新しいプレイヤーなら nil です。各エントリはスタックのルールを
-- もう一度通るので、削除したアイテムや古いスタック数があっても壊れません。
function InventoryService.load(player: Player, saved: any)
local inventory: Inventory = { slots = {}, capacity = CAPACITY }
local entries: { Slot } = STARTER_ITEMS
if type(saved) == "table" and type(saved.slots) == "table" then
entries = {}
for _, entry in saved.slots do
if type(entry) == "table" and type(entry.id) == "string" and type(entry.count) == "number" then
table.insert(entries, { id = entry.id, count = math.floor(entry.count) })
end
end
end
for _, entry in entries do
local item = ItemCatalog.get(entry.id)
if item and entry.count > 0 then
addToInventory(inventory, item, entry.count)
end
end
inventories[player] = inventory
sync(player)
end
-- 保存用のシンプルなコピー。プレイヤーのデータが読み込まれなかったときは nil
function InventoryService.serialize(player: Player): { version: number, slots: { Slot } }?
local inventory = inventories[player]
if not inventory then
return nil
end
local slots: { Slot } = {}
for index, slot in inventory.slots do
slots[index] = { id = slot.id, count = slot.count }
end
return { version = 1, slots = slots }
end
function InventoryService.unload(player: Player)
inventories[player] = nil
end
return InventoryService
type の行と、require のあとの :: のキャストは、WaitForChild で見つけたモジュールが何を返すかわからない Luau の型チェッカーのためだけにあります。ゲーム中には何も変わりません。このガイドのほかのスクリプトも同じようにしています。
リンゴが 10 までスタックできる上のカタログで、スタックのルールがどう働くか:
- 7個のスタックを持つプレイヤーに15個のリンゴを追加すると、そのスタックが 10 まで埋まり、それから 5 個の新しいスタックが始まります。
- スロットが足りなくなると、
addは入った分だけ追加してその数を返します。全部か無しかにしたいときは、ステップ5の拾得のように、先にspaceForを呼んでください。 removeは全部か無しかで動きます。リンゴを2個持っているプレイヤーから3個取ろうとすると何も取り除かずにfalseを返すので、代わりに何かを渡す前に結果を確認してください。- スロットに穴はできません。スロットが空になると、残りが上に詰まります。こうするとリストを送ったり保存したりするのが簡単になります。位置を保つスロットについては、最後の質問で説明しています。
| 関数 | 返り値 | 用途 |
|---|---|---|
add(player, itemId, amount) | 追加した数 | 拾得、報酬、購入 |
remove(player, itemId, amount) | 全部取り除けたら true | 使用、売却、クラフト |
count(player, itemId) | すべてのスタックの合計 | プレイヤーが何を持っているかの確認 |
spaceFor(player, itemId) | あといくつ入るか | 全部か無しかで追加する前の確認 |
getEquipped、setEquipped | 装備中のアイテムの id または nil | 装備、ステップ6で使用 |
load、serialize、unload | 保存できる形のコピー(serialize) | 読み込みと保存、ステップ4で使用 |
ステップ4: インベントリを読み込んで保存する
インベントリはサーバーのメモリの中にあるので、プレイヤーが抜けると消えてしまいます。このスクリプトは、プレイヤーが参加したときにデータストアからスロットを読み込み、抜けたとき、サーバーが終了するとき、そしてサーバーのクラッシュに備えて3分ごとに書き戻します。保存するのはアイテムの id と個数だけです。データストアは Tool のような Instance を保存できません。
ServerScriptService に Script を挿入し、名前を InventoryData にします:
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local ServerScriptService = game:GetService("ServerScriptService")
type InventoryApi = {
load: (player: Player, saved: any) -> (),
serialize: (player: Player) -> any,
unload: (player: Player) -> (),
}
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local STORE_NAME = "PlayerInventory_v1"
local LOAD_ATTEMPTS = 3
local AUTOSAVE_SECONDS = 180
-- 保存するのはデータが読み込めたプレイヤーだけです。読み込みに失敗したあとに
-- 保存すると、空のインベントリが本物を上書きしてしまいます。
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- 1回のリクエストの失敗で誰かのアイテムが消えてはいけないので、何回か試します。
-- GetDataStore も pcall の中なので、データストアにアクセスできない Studio の
-- セッションでは、このスクリプトが止まらずに警告が出ます。
local function loadSaved(player: Player): (boolean, any)
for attempt = 1, LOAD_ATTEMPTS do
local ok, result = pcall(function()
return DataStoreService:GetDataStore(STORE_NAME):GetAsync(keyFor(player))
end)
if ok then
return true, result
end
warn(`Inventory load failed for {player.Name} (attempt {attempt}): {result}`)
if attempt < LOAD_ATTEMPTS then
task.wait(attempt * 2)
end
end
return false, nil
end
local function onPlayerAdded(player: Player)
local ok, saved = loadSaved(player)
if player.Parent ~= Players then
return -- 読み込み中にプレイヤーが抜けました
end
if ok then
InventoryService.load(player, saved) -- 新しいプレイヤーなら saved は nil
canSave[player] = true
elseif RunService:IsStudio() then
-- たいていは Studio の API services へのアクセスがオフになっています。テスト
-- できるようにスターターアイテムで遊びますが、それは決して保存しません。
warn("Inventory not loaded: playing with starter items that will not be saved")
InventoryService.load(player, nil)
else
player:Kick("Your inventory could not be loaded. Please rejoin in a minute.")
end
end
local function save(player: Player)
if not canSave[player] then
return -- データが読み込まれなかったので、安全に書き込めるものがありません
end
local data = InventoryService.serialize(player)
if not data then
return
end
activeSaves += 1
local ok, err = pcall(function()
DataStoreService:GetDataStore(STORE_NAME):SetAsync(keyFor(player), data, { player.UserId })
end)
activeSaves -= 1
if not ok then
warn(`Inventory save failed for {player.Name}: {err}`)
end
end
Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
task.spawn(onPlayerAdded, player)
end
Players.PlayerRemoving:Connect(function(player: Player)
save(player)
canSave[player] = nil
InventoryService.unload(player)
end)
-- サーバーが終了するとき、まだいる全員を保存し、PlayerRemoving が始めたものも
-- 含めて、進行中の保存がすべて終わるのを待ちます
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- 数分ごとに全員を保存し、サーバーがクラッシュしても失うのはセッション全体ではなく数分にします
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
スクリプトがしていることと、その理由:
- 初期値付きで読み込む。新しいプレイヤーには保存された値がないので、
GetAsyncは nil を返し、プレイヤーはスターターアイテムを受け取ります。保存されたスロットはスタックのルールをもう一度通るので、カタログから削除したアイテムや、小さくした最大スタック数があっても読み込みは壊れません。入りきらなくなったものや、id がもうカタログにないものは捨てられ、次の保存でそれが確定するので、プレイヤーが持っている可能性のある id はすべてカタログに残しておいてください。 - 読み込みに失敗したら決して保存しない。書き込まれるのは
canSaveにいるプレイヤーだけです。本番のサーバーでは、3回試してもデータが読み込めなかったプレイヤーに入り直してもらいます。Studio ではその代わりに、保存されないスターターアイテムを受け取ります。再試行があるので数秒遅れます。プレイスを API へのアクセスを有効にして公開するまでは、こうなります。 - 抜けるときと終了するときに保存する。
BindToCloseはサーバーにまだいる全員を保存し、すでに進行中の保存を待ちます。Roblox はバインドされた関数に最大30秒を与えます。 - 上限を超えない。プレイヤー1人につき3分ごとに1回と、抜けるときの1回の書き込みは、サーバーの標準の予算である1分あたり60回とプレイヤー1人あたり40回(2026年9月30日時点のドキュメントによる)よりずっと少ない回数です。キーの形式
User_は Roblox の推奨に従ったもので、SetAsyncにユーザー ID を渡すとデータがそのプレイヤーに結び付きます。データ削除のリクエストに対応するため、Roblox はこれを強く勧めています。
小さなゲームなら、これで信頼できる土台になります。すばやくサーバーを移ったプレイヤーが、古いサーバーが保存する前にデータを読み込んでしまうのを防ぐセッションロックや、SetAsync の代わりに UpdateAsync を使うべき場面については、DataStore のチュートリアルで解説しています。
ステップ5: ワールドからアイテムを渡す
拾得は、アイテムがインベントリに入るいちばんシンプルな方法です。ProximityPrompt の付いたパーツで、プレイヤーがそれを使うとアイテムが追加されます。スクリプトはサーバーでその Triggered イベントを聞くので、アイテムはクライアントが手を出せない場所で追加されます。
- Workspace に Part を追加し、名前を
Appleにして赤く塗ります。Anchored をオンにし、見えない間に誰もぶつからないように CanCollide をオフにします。プロンプトにはパーツの名前が表示されます。 - パーツを選んだまま Properties ウィンドウを Attributes の項目までスクロールし、+ を押します。型を string にして
ItemIdを追加し、Save を押してから、値をappleにします。同じように、型が number で値が1のAmountを追加します。 - パーツに Script を挿入し、名前を
ItemPickupにして、このコードを貼り付けます:
-- この Script を Part の中に入れ、Part に2つの属性を付けます:
-- ItemId(文字列、たとえば apple)と Amount(数値、たとえば 1)。
local ServerScriptService = game:GetService("ServerScriptService")
type InventoryApi = {
add: (player: Player, itemId: string, amount: number) -> number,
spaceFor: (player: Player, itemId: string) -> number,
}
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local part = script.Parent :: BasePart
local RESPAWN_SECONDS = 15
local itemId = part:GetAttribute("ItemId")
local amount = part:GetAttribute("Amount")
if typeof(itemId) ~= "string" or typeof(amount) ~= "number" or amount < 1 then
error(`{part:GetFullName()} needs an ItemId (string) and an Amount (number, 1 or more) attribute`)
end
local prompt = Instance.new("ProximityPrompt")
prompt.ActionText = "Pick up"
prompt.ObjectText = part.Name
prompt.Parent = part
local visibleTransparency = part.Transparency
prompt.Triggered:Connect(function(player: Player)
if not prompt.Enabled then
return -- たった今、ほかの誰かが拾いました
end
-- リクエストを信じずに、サーバーで距離を確認します
local character = player.Character
if not character then
return
end
local distance = (character:GetPivot().Position - part.Position).Magnitude
if distance > prompt.MaxActivationDistance + 5 then
return
end
if InventoryService.spaceFor(player, itemId) < amount then
return -- 空きが足りない: アイテムはその場に残します
end
InventoryService.add(player, itemId, amount)
prompt.Enabled = false
part.Transparency = 1
task.wait(RESPAWN_SECONDS)
part.Transparency = visibleTransparency
prompt.Enabled = true
end)
アイテムをもっと置くには、パーツをコピーします。属性を変えれば、木材、もう1本の剣、リンゴのスタックを渡せます。
Roblox は Triggered の距離を確認しますが、それでもセキュリティのガイドはプロンプトをサーバーで確認するよう指示しています。チーターは Enabled が false のときでもプロンプトのイベントを呼べますし、Anchored でないパーツを自分のキャラクターに引き寄せることもできます。だからスクリプトは自分で Enabled と距離を確認し、パーツは Anchored にしてあります。
ほかのサーバースクリプトも同じ方法でアイテムを渡します。購入、クエスト、敵を倒したあとに、上のスクリプトのように InventoryService を require して、InventoryService.add(player, "wood", 5) を呼びます。失ってはいけないアイテムなら、先に spaceFor を確認します。NPC も入手先になります。NPC の会話のガイドでは返答がサーバーでアクションを起こし、そのアクションも同じように InventoryService.add を呼べます。
ステップ6: Tool の装備とアイテムの使用
クライアントが送れる唯一のリクエストを、2つの RemoteEvent が運びます。EquipItem はアイテムの Tool のコピーを ServerStorage からプレイヤーの Backpack(画面下のホットバー)と手に入れ、もう一度リクエストするとしまいます。UseItem は使えるアイテムを1つ取り除いて、その効果(ここでは回復)を与えます。
ServerScriptService に Script を挿入し、名前を InventoryActions にします:
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerScriptService = game:GetService("ServerScriptService")
local ServerStorage = game:GetService("ServerStorage")
type Item = { id: string, toolName: string?, heal: number? }
type Catalog = { get: (id: string) -> Item? }
type InventoryApi = {
count: (player: Player, itemId: string) -> number,
remove: (player: Player, itemId: string, amount: number) -> boolean,
getEquipped: (player: Player) -> string?,
setEquipped: (player: Player, itemId: string?) -> (),
}
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local equipItem = remotes:WaitForChild("EquipItem") :: RemoteEvent
local useItem = remotes:WaitForChild("UseItem") :: RemoteEvent
local itemTools = ServerStorage:WaitForChild("ItemTools")
local COOLDOWN_SECONDS = 0.25
local lastRequest: { [Player]: number } = {}
-- すべてのリクエストはここから始まります。クライアントはいつでも何でも送れるので、
-- 型、アイテムが存在するか、プレイヤーが持っているか、頻度を確認します。
local function ownedItem(player: Player, itemId: unknown): Item?
if typeof(itemId) ~= "string" then
return nil
end
local now = os.clock()
if now - (lastRequest[player] or 0) < COOLDOWN_SECONDS then
return nil
end
lastRequest[player] = now
local item = ItemCatalog.get(itemId)
if not item or InventoryService.count(player, itemId) < 1 then
return nil
end
return item
end
-- このアイテムの Tool を、コピーがどこにあっても破棄します: ホットバー、手、StarterGear
local function destroyTools(container: Instance?, itemId: string)
if not container then
return
end
for _, child in container:GetChildren() do
if child:IsA("Tool") and child:GetAttribute("InventoryItem") == itemId then
child:Destroy()
end
end
end
local function unequip(player: Player)
local equippedId = InventoryService.getEquipped(player)
if equippedId then
destroyTools(player:FindFirstChildOfClass("Backpack"), equippedId)
destroyTools(player.Character, equippedId)
destroyTools(player:FindFirstChildOfClass("StarterGear"), equippedId)
InventoryService.setEquipped(player, nil)
end
end
local function equip(player: Player, item: Item, toolName: string)
local template = itemTools:FindFirstChild(toolName)
local backpack = player:FindFirstChildOfClass("Backpack")
if not template or not template:IsA("Tool") or not backpack then
warn(`Cannot equip {item.id}: no Tool named {toolName} in ServerStorage.ItemTools`)
return
end
unequip(player) -- 装備できるツールは一度に1つ
local tool = template:Clone()
tool.CanBeDropped = false -- 落としたコピーはほかの誰かに拾われるおそれがあります
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- StarterGear の2つ目のコピーは、リスポーン後に Backpack へコピーし直されます
local starterGear = player:FindFirstChildOfClass("StarterGear")
if starterGear then
local gearCopy = tool:Clone()
gearCopy.Parent = starterGear
end
local character = player.Character
local humanoid = character and character:FindFirstChildOfClass("Humanoid")
if humanoid and humanoid.Health > 0 then
humanoid:EquipTool(tool) -- すぐに手に持たせます
end
InventoryService.setEquipped(player, item.id)
end
equipItem.OnServerEvent:Connect(function(player: Player, itemId: unknown)
local item = ownedItem(player, itemId)
if not item or not item.toolName then
return
end
if InventoryService.getEquipped(player) == item.id then
unequip(player) -- 装備中のアイテムをもう一度クリックするとしまいます
else
equip(player, item, item.toolName)
end
end)
useItem.OnServerEvent:Connect(function(player: Player, itemId: unknown)
local item = ownedItem(player, itemId)
if not item or not item.heal then
return
end
local heal = item.heal
local character = player.Character
local humanoid = character and character:FindFirstChildOfClass("Humanoid")
if not humanoid or humanoid.Health <= 0 or humanoid.Health >= humanoid.MaxHealth then
return -- 死んでいるか、体力が満タン: アイテムを無駄にしません
end
-- 先にアイテムを取り除き、それができたときだけ回復します
if InventoryService.remove(player, item.id, 1) then
humanoid.Health = math.min(humanoid.MaxHealth, humanoid.Health + heal)
end
end)
Players.PlayerRemoving:Connect(function(player: Player)
lastRequest[player] = nil
end)
| リクエスト | クライアントが送るもの | 実行前にサーバーが確認すること |
|---|---|---|
EquipItem | アイテムの id | 文字列であること、アイテムが存在すること、プレイヤーが持っていること、リクエストが1秒に4回以下であること、アイテムに toolName があること、その名前の Tool が ServerStorage.ItemTools にあること |
UseItem | アイテムの id | 型、所有、頻度の同じ確認、アイテムに heal の値があること、キャラクターが生きていてダメージを受けていること、体力を足す前にアイテムを1つ取り除いたこと |
3つの工夫で、Tool が増えたりなくなったりするのを防いでいます。コピーの CanBeDropped は false です。落とした Tool は Workspace に落ちてほかのプレイヤーに拾われるおそれがあり、そのうえ元のアイテムはインベントリに残ってしまうからです。どのコピーにも InventoryItem 属性が付いているので、装備を外すときに、どこにあってもすべてのコピーを見つけて破棄できます。そしてプレイヤーに StarterGear コンテナーがあれば、そこに2つ目のコピーを入れます。Roblox はキャラクターが現れるたびに StarterGear を Backpack にコピーするので、装備した剣はリスポーンのあとも戻ってきます。
一度に装備できる Tool は1つだけで、装備の状態は保存されないので、入り直したプレイヤーはホットバーが空の状態から始まります。あとで売却や捨てる機能を足すなら、アイテムの最後の1つがインベントリから出る前に装備を外してください。
仮の剣を、本当に戦える剣に変えることもできます。剣のガイドで Tool を作り、名前を Sword のままにして、仮の剣の代わりに ItemTools に入れます。そのガイドのサーバースクリプトが、プレイヤーがどうやって剣を手に入れたかに関係なく、すべての攻撃を確認します。
ステップ7: インベントリのグリッドを描く
LocalScript がウィンドウ全体をコードで組み立てるので、手で配置するものはありません。ScrollingFrame がスロットを入れ、その中の UIGridLayout がスロットを行に並べ、AutomaticCanvasSize が行が増えるにつれてスクロールできる範囲を広げます。
Explorer で StarterPlayer を開き、StarterPlayerScripts に LocalScript を挿入して、名前を InventoryClient にします:
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")
type Item = { name: string, description: string, icon: string?, toolName: string?, heal: number? }
type Catalog = { get: (id: string) -> Item? }
type Slot = { id: string, count: number }
type Snapshot = { capacity: number, slots: { Slot }, equipped: string? }
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local inventoryUpdated = remotes:WaitForChild("InventoryUpdated") :: RemoteEvent
local equipItem = remotes:WaitForChild("EquipItem") :: RemoteEvent
local useItem = remotes:WaitForChild("UseItem") :: RemoteEvent
local player = Players.LocalPlayer
local TOGGLE_KEY = Enum.KeyCode.B
local COLOURS = {
panel = Color3.fromRGB(24, 20, 36),
slot = Color3.fromRGB(44, 38, 64),
empty = Color3.fromRGB(34, 30, 48),
equipped = Color3.fromRGB(124, 77, 255),
text = Color3.fromRGB(240, 238, 245),
muted = Color3.fromRGB(170, 165, 185),
}
local function addCorner(parent: GuiObject, radius: number)
local corner = Instance.new("UICorner")
corner.CornerRadius = UDim.new(0, radius)
corner.Parent = parent
end
local function makeLabel(parent: GuiObject, text: string, textSize: number): TextLabel
local label = Instance.new("TextLabel")
label.BackgroundTransparency = 1
label.Font = Enum.Font.BuilderSansBold
label.TextColor3 = COLOURS.text
label.TextSize = textSize
label.Text = text
label.Parent = parent
return label
end
-- 1. ウィンドウを一度だけ組み立てます。ResetOnSpawn = false でリスポーン後も残ります。
local gui = Instance.new("ScreenGui")
gui.Name = "InventoryGui"
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")
local openButton = Instance.new("TextButton")
openButton.AnchorPoint = Vector2.new(0, 0.5)
openButton.Position = UDim2.new(0, 16, 0.5, 0)
openButton.Size = UDim2.fromOffset(140, 40)
openButton.BackgroundColor3 = COLOURS.panel
openButton.Font = Enum.Font.BuilderSansBold
openButton.TextColor3 = COLOURS.text
openButton.TextSize = 18
openButton.Text = "Inventory (B)"
addCorner(openButton, 8)
openButton.Parent = gui
local panel = Instance.new("Frame")
panel.AnchorPoint = Vector2.new(0.5, 0.5)
panel.Position = UDim2.fromScale(0.5, 0.5)
panel.Size = UDim2.fromScale(0.9, 0.8)
panel.BackgroundColor3 = COLOURS.panel
panel.Visible = false
addCorner(panel, 12)
panel.Parent = gui
local sizeLimit = Instance.new("UISizeConstraint")
sizeLimit.MaxSize = Vector2.new(440, 400)
sizeLimit.Parent = panel
local title = makeLabel(panel, "Inventory", 22)
title.Position = UDim2.fromOffset(16, 8)
title.Size = UDim2.new(1, -32, 0, 32)
title.TextXAlignment = Enum.TextXAlignment.Left
local slotCount = makeLabel(panel, "", 16)
slotCount.Position = UDim2.fromOffset(16, 8)
slotCount.Size = UDim2.new(1, -32, 0, 32)
slotCount.TextColor3 = COLOURS.muted
slotCount.TextXAlignment = Enum.TextXAlignment.Right
local grid = Instance.new("ScrollingFrame")
grid.Position = UDim2.fromOffset(12, 48)
grid.Size = UDim2.new(1, -24, 1, -100)
grid.BackgroundTransparency = 1
grid.BorderSizePixel = 0
grid.CanvasSize = UDim2.new() -- AutomaticCanvasSize がセルに合わせて広げます
grid.AutomaticCanvasSize = Enum.AutomaticSize.Y
grid.ScrollingDirection = Enum.ScrollingDirection.Y
grid.ScrollBarThickness = 6
grid.Parent = panel
local layout = Instance.new("UIGridLayout")
layout.CellSize = UDim2.fromOffset(72, 72)
layout.CellPadding = UDim2.fromOffset(8, 8)
layout.SortOrder = Enum.SortOrder.LayoutOrder
layout.Parent = grid
local info = makeLabel(panel, "Click an item to equip or use it.", 16)
info.AnchorPoint = Vector2.new(0, 1)
info.Position = UDim2.new(0, 16, 1, -8)
info.Size = UDim2.new(1, -32, 0, 40)
info.Font = Enum.Font.BuilderSans
info.TextColor3 = COLOURS.muted
info.TextWrapped = true
info.TextXAlignment = Enum.TextXAlignment.Left
-- 2. スロット1つにセル1つ。サーバーが送ってきたものを描くだけで、
-- インベントリそのものがここで変わることは決してありません。
local function makeCell(index: number, slot: Slot?, equippedId: string?)
local cell = Instance.new("TextButton")
cell.LayoutOrder = index
cell.Text = ""
cell.AutoButtonColor = slot ~= nil
cell.BackgroundColor3 = if slot then COLOURS.slot else COLOURS.empty
addCorner(cell, 8)
cell.Parent = grid
if not slot then
return -- 空のスロット
end
local itemId = slot.id
local item = ItemCatalog.get(itemId)
local name = if item then item.name else itemId
if item and item.icon then
local image = Instance.new("ImageLabel")
image.BackgroundTransparency = 1
image.Size = UDim2.fromScale(1, 1)
image.Image = item.icon
image.Parent = cell
else
local nameLabel = makeLabel(cell, name, 14)
nameLabel.Size = UDim2.fromScale(1, 1)
nameLabel.TextWrapped = true
end
if slot.count > 1 then
local countLabel = makeLabel(cell, `x{slot.count}`, 14)
countLabel.AnchorPoint = Vector2.new(1, 1)
countLabel.Position = UDim2.new(1, -6, 1, -4)
countLabel.Size = UDim2.fromOffset(40, 16)
countLabel.TextXAlignment = Enum.TextXAlignment.Right
end
if itemId == equippedId then
local outline = Instance.new("UIStroke")
outline.ApplyStrokeMode = Enum.ApplyStrokeMode.Border
outline.Color = COLOURS.equipped
outline.Thickness = 3
outline.Parent = cell
end
cell.MouseEnter:Connect(function()
info.Text = if item then `{item.name}: {item.description}` else name
end)
cell.Activated:Connect(function()
-- 命令ではなくお願い: サーバーがリクエストを確認して結果を送ってきます
if item and item.toolName then
equipItem:FireServer(itemId)
elseif item and item.heal then
useItem:FireServer(itemId)
end
end)
end
local function render(snapshot: Snapshot)
for _, child in grid:GetChildren() do
if child:IsA("GuiButton") then
child:Destroy()
end
end
for index = 1, snapshot.capacity do
makeCell(index, snapshot.slots[index], snapshot.equipped)
end
slotCount.Text = `{#snapshot.slots} / {snapshot.capacity} slots`
end
-- サーバーは読み込みのあとと、変更のたびにこれを送ります
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. ボタンか B キーで開いたり閉じたりします
local function toggle()
panel.Visible = not panel.Visible
end
openButton.Activated:Connect(toggle)
UserInputService.InputBegan:Connect(function(input: InputObject, gameProcessedEvent: boolean)
if not gameProcessedEvent and input.KeyCode == TOGGLE_KEY then
toggle()
end
end)
StarterPlayerScripts の LocalScript はセッションごとに1回だけ動き、ResetOnSpawn = false でキャラクターがリスポーンしても ScreenGui が残るので、グリッドはサーバーが送ってきた最後のコピーを表示し続けます。
クライアントは空いているものも含めてスロットごとにセルを描くので、20 スロットのインベントリはいつも 20 スロットに見えます。更新のたびに古いセルを破棄して新しく作ります。シンプルな方法で、スロットが数十個なら十分です。このスクリプトが接続する前にサーバーが InventoryUpdated を送っても、Roblox はメッセージをキューに入れ、ハンドラーが接続されしだい届けるので、最初のインベントリがなくなることはありません。
ウィンドウを Studio で描きたいですか?テンプレートのスロットを1つ入れた ScreenGui を作り、makeCell でそれを Clone します。アイコンを付けるには、カタログのアイテムに、アップロードした画像を指す icon を設定すると、そのセルには名前の代わりに画像が表示されます。
インベントリをテストする
- Play を押します。左のボタンか B キーでインベントリを開きます。新しいプレイヤーは Sword と Apple を3つ持っていて、カウンターには 2 / 20 slots と表示されます。Studio がデータストアにアクセスできない間は、Output に読み込みの警告が出たあと数秒してアイテムが現れ、保存はされません。
- Sword をクリックします。剣が手とホットバーに現れ、そのスロットに紫の枠が付きます。もう一度クリックするとしまいます。
- Apple のパーツに近づいて、そのプロンプトを使います。リンゴのスタックが 4 に増え、パーツは15秒間消えます。
- 回復をテストするには、先に体力を減らします。Client/Server を Server に切り替え、Explorer で自分のキャラクターの
Humanoidを選んで Health を 50 にし、Client に戻して Apple をクリックします。 - Studio の API services へのアクセスをオンにした状態で、ゲームを止めてもう一度始めます。拾ったリンゴがそのまま残っています。読み込みや保存に失敗した場合は、Output にそう表示されます。
複数プレイヤーでテストするには、テストの設定で Server & Clients をクライアント 2 で選びます。各プレイヤーには自分のインベントリしか見えませんが、相手が手に持っている剣は両方に見えます。
よくあるエラーと対処法
ほとんどの問題は、Output ウィンドウに警告か赤いエラーの行として現れます。最初のものを読んでください。そのあとのエラーは、たいていそこから続いて起きています。
WaitForChild の呼び出しで Infinite yield possible
スクリプトが、ちょうどその名前では存在しないオブジェクトを待っています。あなたの Explorer をステップ1のツリーと比べてください。ReplicatedStorage に3つの RemoteEvent が入った InventoryRemotes、ServerStorage に ItemTools、そして2つのモジュールです。名前は大文字と小文字を区別します。この警告についてはスクリプトのエラーのガイドで詳しく解説しています。
グリッドは開くが、空のまま
クライアントはサーバーが送ってきたものしか描きません。Output で Inventory load failed の警告を探し、InventoryData が ServerScriptService にある LocalScript ではなく Script であること、その隣に ModuleScript の InventoryService があることを確認してください。Output に Remote event invocation のエラーが出ている場合は、クライアントで誰も InventoryUpdated を聞いていません。InventoryClient から出ている、もっと前のエラーを探してください。
Studio で遊ぶたびにアイテムがリセットされる
Output に Inventory not loaded: playing with starter items that will not be saved と出ている場合は、プレイスが公開されていないか、Studio の API services へのアクセスがオフになっています。ゲームのテスト用のコピーで、ステップ4のとおりにオンにしてください。
剣をクリックしても何も起きない
Output で Cannot equip sword を探してください。ServerStorage.ItemTools の Tool の名前は、カタログの toolName とまったく同じでなければなりません。また、RequiresHandle を false にしていない限り、持てるようにするには Tool に Handle という名前のパーツが必要です。
拾得のプロンプトは出るが、何も追加されない
ItemId 属性は、大文字と小文字も含めてカタログの id と完全に一致しなければなりません。Apple ではなく apple です。プレイヤーのインベントリがまだ読み込み中のときや、全部の数が入る空きがないときも、何も追加されません。
保存するものを変えたら、保存が壊れた
データストアが受け付けるのはシンプルなデータです。文字列、数値、真偽値、そしてそれらでできた表です。Tool、Part、そのほかの Instance を保存しようとすると失敗するか、値が nil として保存されます。serialize がしているように、アイテムの id と個数を保存し、それ以外はすべてカタログから復元してください。
RoCode で作る
システムを手で組み立てるより説明するほうが楽なら、RoCode があなたの開いているプレイスで組み立てられます。RoCode は Roblox Studio 向けの AI エージェントです。ウェブチャットで機能を説明すると、Studio プラグインが貼り付け用のコードを出すのではなく、あなたの Explorer にスクリプトとオブジェクトを作ります。
スタックできるアイテムの入る20スロットのインベントリ、B で開くグリッドの UI、プレイヤーが装備できる ServerStorage の剣、回復するリンゴ、そして DataStoreService での保存を追加して。
- ステップに必要なときは Search Game と Search Scripts であなたのプレイスを見て、2つ目のシステムを足すのではなく、すでにあるアイテム、リモート、保存のコードを土台にできます
- Create Instance でフォルダーと RemoteEvent を、Create Script で ModuleScript、Script、LocalScript を作ります
- Build UI でウィンドウのひな形を作れます。仮のスロットが入ったインベントリのレイアウトが付きます。サーバーからスロットを埋めるコードは、別のスクリプトとして書きます
- Check Script で各スクリプトが Studio でコンパイルできるかを確認します。コンパイルのエラーといくつかの危険なパターンは見つけますが、型のチェック、lint、コードの実行はしません
変更のまとまりごとに Studio の取り消しポイントになります。RoCode は Studio の API services へのアクセスをオンにできないので、それはあなたが行います。プラグイン 3.9 以降では短いプレイテストを実行してエラーを読め、プラグイン 3.9.15 以降ではテスト用のキャラクターがキーを押したりアイテムを装備したりできますが、確認するのは自分でテストすると決めた部分だけなので、保存は自分でプレイテストして確かめてください。インベントリは保存やツールなどほかの仕組みの上に乗るもので、あなた自身の Studio のプレイスで作る AI ゲームメーカーは、それらを1回のプロンプトにつき1つずつ追加していきます。RoCode が Studio につながる仕組み。
よくある質問
自作のインベントリの代わりに Roblox の Backpack を使ってもいいですか?
Backpack は Roblox に組み込まれたインベントリで、その中の Tool はそれぞれホットバーのボタンとして表示されます。ゲームのアイテムがすべて Tool で、スタック、個数、スロットの上限がいらないなら、それで足りるかもしれません。ただし、各プレイヤーがどの Tool を持っているかの保存は、やはり必要です。素材や消耗品のように Tool ではないアイテムには、自作のインベントリが必要です。このガイドでは両方を使っています。インベントリがすべてを持ち、Backpack が装備中の Tool を持ちます。
Roblox の標準のホットバーを隠すには?
LocalScript から StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false) を呼びます。ホットバーを隠すと、プレイヤーには装備中の Tool を持ったりしまったりする別の方法が必要になります。たとえば、サーバーに Humanoid:EquipTool や Humanoid:UnequipTools を呼ぶよう頼むボタンです。
ドラッグ アンド ドロップのためにスロットの位置を保つには?
スロット1つにつき1つのエントリがある固定長のリストを持ち、空のスロットは nil ではなく空の id のような値で示します。Roblox は nil の入った表を RemoteEvent で送ることを勧めていないからです。それから2つのスロット番号を送る MoveItem の RemoteEvent を追加し、入れ替える前に、サーバーで両方が 1 から容量までの整数であることを確認します。
保存するインベントリはどれくらいの大きさにできますか?
データストアの1つの値は、シリアライズしたあとで最大 4,194,304 文字まで使えます(2026年9月30日時点のドキュメントによる)。id と個数のリストは、そのごく一部しか使いません。保存のサイズを大きくするのは、アイテムごとのテキストです。たとえば独自の名前や、アイテムごとに保存した長い説明などです。
コインでアイテムを売り買いするには?
すべてサーバーで行います。売るときは InventoryService.remove を呼び、true が返ったときだけ支払います。買うときは価格と spaceFor を確認し、コインを引いてから add を呼びます。購入側はショップのガイドで作っています。
参考資料
- Roblox Creator Docs: Remote events and callbacks(英語). FireClient、OnServerEvent、引数の制限、受け取り手のいないメッセージがキューに入る仕組み
- Roblox Creator Docs: Securing the client-server boundary(英語). リモートの入力の確認、ProximityPrompt の確認、データストアのデータの改ざん
- Roblox Creator Docs: Data stores(英語). GetAsync、SetAsync、Studio からのアクセスを有効にする方法
- Roblox Creator Docs: Best practices for data stores(英語). プレイヤーごとに1つのキー、キーの形式、定期的な保存
- Roblox Creator Docs: Data store error codes and limits(英語). サーバーごとのリクエストの上限と、1つの値のサイズの上限
- Roblox Creator Docs: In-game tools(英語). Handle、Anchored、Backpack、StarterGear
- Roblox Creator Docs: Grid and table layouts(英語). UIGridLayout のセルのサイズ、間隔、並び順
コードの検証方法: このページのスクリプトはすべて、Roblox API の型定義(luau-lsp、2026年11月20日)を使った Luau の strict 型チェックを通っています。型チェックで見つかるのは API 名の誤りや型の不一致であり、ゲームロジックの誤りは見つかりません。公開する前に必ず Studio でテストしてください。