載入遊戲中的內容(資產)的服務。
Roblox 伺服器在執行階段行時向客戶端傳送所有資產:工作區中的對象、網格資產、紋理資產等等。網格視覺數據、紋理、貼花和聲音等資產,根據需要進行串流,無論 串流 是否啟用。
在某些情況下,這種行為不適合,因為它可能會導致內容在體驗中載入前的延遲。
ContentProvider 讓您使用 ContentProvider:PreloadAsync() 方法將資產預加載到體驗中。您可能想顯示載入屏幕、預加載關鍵資產,然後才允許玩家進入體驗。
預載最佳實踐
- 只預加載必要資產, 不 整個Workspace。您可能會收到時不時的跳出,但它會降低載入時間並一般不會干擾玩家體驗。預載候選資產包括需要用於載入屏幕、使用者介面或起始區域的資產。
- 讓玩家跳過載入屏幕,或在一定時間後自動跳過。
範例程式碼
In this example a Decal and Sound are preloaded into a game. Once they have finished loading the script will print a message to the output.
local ContentProvider = game:GetService("ContentProvider")
local LOGO_ID = "rbxassetid://658743164"
local PAGE_TURN_ID = "rbxassetid://12222076"
local decal = Instance.new("Decal")
decal.Texture = LOGO_ID
local sound = Instance.new("Sound")
sound.SoundId = PAGE_TURN_ID
local assets = { decal, sound }
ContentProvider:PreloadAsync(assets)
print("All assets loaded.")
概要
屬性
由 ContentProvider 使用下載 Roblox 網站上的資產。
提供需要下載的 ContentProvider 請求隊列中項目數量。
方法
獲得提供的 Enum.AssetFetchStatus 的當前 contentId。
一個信號,當提供的內容的 Enum.AssetFetchStatus 發生變更時發射。
直到所有與給定的 Instances 相關的資產都載入完畢為止。
屬性
BaseUrl
由 ContentProvider 使用下載 Roblox 網站上的資產。
這個URL指向一個Roblox主機的網站,從中下載資產並從版本哈希文件夾中拉取,位於版本哈希文件夾中。
使用指令欄中的 ContentProvider:SetBaseUrl() 函數覆蓋此屬性是可能的,但不建議這樣做,可能會導致資產載入問題。
RequestQueueSize
提供需要下載的 ContentProvider 請求隊列中項目數量。
當資產首次使用或 ContentProvider:PreloadAsync() 被呼叫時,項目將被添加到客戶端的請求隊列中。
建議開發人員不要使用 RequestQueueSize 來創建載入條件。這是因為隨著新資產被添加和下載,隊列大小可以增加或減少過時。想要顯示載入進度的開發人員應該一次載入資產(見下面的範例)。
範例程式碼
This code sample demonstrates how ContentProvider:PreloadAsync() can be used to create a simple loading bar in a game, by loading the assets one at a time.
local ContentProvider = game:GetService("ContentProvider")
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local playerGui = localPlayer:WaitForChild("PlayerGui")
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = playerGui
-- create a basic loading bar
local frame = Instance.new("Frame")
frame.Size = UDim2.new(0.5, 0, 0.1, 0)
frame.Position = UDim2.new(0.5, 0, 0.5, 0)
frame.AnchorPoint = Vector2.new(0.5, 0.5)
frame.Parent = screenGui
local bar = Instance.new("Frame")
bar.Size = UDim2.new(0, 0, 1, 0)
bar.Position = UDim2.new(0, 0, 0, 0)
bar.BackgroundColor3 = Color3.new(0, 0, 1)
bar.Parent = frame
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
local sound2 = Instance.new("Sound")
sound2.SoundId = "rbxassetid://9120385974"
local assets = {
sound,
sound2,
}
task.wait(3)
for i = 1, #assets do
local asset = assets[i]
ContentProvider:PreloadAsync({ asset }) -- 1 at a time, yields
local progress = i / #assets
bar.Size = UDim2.new(progress, 0, 1, 0)
end
print("loading done")
方法
GetAssetFetchStatus
獲得提供的 Enum.AssetFetchStatus 當前的 contentId 。使用 GetAssetFetchStatusChangedSignal() 來聆聽此值的變更。
參數
要取得狀態的內容ID。
返回
範例程式碼
擷取資產的初始 Enum.AssetFetchStatus ,並聆聽未來更新。
local ContentProvider = game:GetService("ContentProvider")
-- 要載入的範例資產
local ASSET_ID = "rbxassetid://9120386436"
local exampleAsset = Instance.new("Sound")
exampleAsset.SoundId = ASSET_ID
-- 輸出資產的當前資產擷取狀態
local initialAssetFetchStatus = ContentProvider:GetAssetFetchStatus(ASSET_ID)
print("Initial AssetFetchStatus:", initialAssetFetchStatus)
-- 聆聽更新
local assetFetchStatusChangedSignal = ContentProvider:GetAssetFetchStatusChangedSignal(ASSET_ID)
local function onAssetFetchStatusChanged(newAssetFetchStatus: Enum.AssetFetchStatus)
print(`New AssetFetchStatus: {newAssetFetchStatus}`)
end
assetFetchStatusChangedSignal:Connect(onAssetFetchStatusChanged)
-- 觸發資產預加載
local function onAssetRequestComplete(contentId: string, assetFetchStatus: Enum.AssetFetchStatus)
print(`Preload status {contentId}: {assetFetchStatus.Name}`)
end
ContentProvider:PreloadAsync({ exampleAsset }, onAssetRequestComplete)
GetAssetFetchStatusChangedSignal
一個信號,當提供的內容的 Enum.AssetFetchStatus 發生變更時發射。使用回調函數,其中一個參數類型為 Enum.AssetFetchStatus 來連接到此信號。這對於可能自動更新的資產,例如用戶更換衣服時的縮略圖來說特別有用。
參數
返回
範例程式碼
擷取資產的初始 Enum.AssetFetchStatus ,並聆聽未來更新。
local ContentProvider = game:GetService("ContentProvider")
-- 要載入的範例資產
local ASSET_ID = "rbxassetid://9120386436"
local exampleAsset = Instance.new("Sound")
exampleAsset.SoundId = ASSET_ID
-- 輸出資產的當前資產擷取狀態
local initialAssetFetchStatus = ContentProvider:GetAssetFetchStatus(ASSET_ID)
print("Initial AssetFetchStatus:", initialAssetFetchStatus)
-- 聆聽更新
local assetFetchStatusChangedSignal = ContentProvider:GetAssetFetchStatusChangedSignal(ASSET_ID)
local function onAssetFetchStatusChanged(newAssetFetchStatus: Enum.AssetFetchStatus)
print(`New AssetFetchStatus: {newAssetFetchStatus}`)
end
assetFetchStatusChangedSignal:Connect(onAssetFetchStatusChanged)
-- 觸發資產預加載
local function onAssetRequestComplete(contentId: string, assetFetchStatus: Enum.AssetFetchStatus)
print(`Preload status {contentId}: {assetFetchStatus.Name}`)
end
ContentProvider:PreloadAsync({ exampleAsset }, onAssetRequestComplete)
UnregisterDefaultEncryptionKey
返回
UnregisterEncryptedAsset
參數
返回
PreloadAsync
直到所有與給定的 Instances 相關的資產都載入完畢為止。這可以用來暫停一個腳本並在確定內容已加載到體驗中之前不使用內容。
當呼叫時,引擎會為列表中的每個項目找到內容的鏈接。對於任何具有定義內容鏈接的屬性的 Instances,例如 Decal 或 Sound,引擎會嘗試從 Roblox 載入這些資產。對於每個請求的素材,回調功能運行,指示素材的最後 Enum.AssetFetchStatus 。
如果任何資產無法載入,輸出中會出現錯誤訊息。方法本身不會發生錯誤,直到它已處理每個請求的實個體、實例為止。
限制
SurfaceAppearance 和 MaterialVariant 不支持 PreloadAsync() ,因為這些對象依靠處理的紋理包資產而不是直接載入個別紋理。在 SurfaceAppearance 實例上呼叫它不會做任何事情,但相關的紋理仍然會在執行階段時傳輸。
參數
要載入的一組實例。
當每個資產請求完成時,呼叫的函數。返回 content 字串和素材的最後 Enum.AssetFetchStatus 。
返回
範例程式碼
In this code sample, a sound and a texture are preloaded using Sound and Decal instances.
local ContentProvider = game:GetService("ContentProvider")
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
local decal = Instance.new("Decal")
decal.Texture = "rbxassetid://5447528495"
local assets = {
decal,
sound,
}
-- This will be hit as each asset resolves
local callback = function(assetId, assetFetchStatus)
print("PreloadAsync() resolved asset ID:", assetId)
print("PreloadAsync() final AssetFetchStatus:", assetFetchStatus)
end
-- Preload the content and time it
local startTime = os.clock()
ContentProvider:PreloadAsync(assets, callback)
local deltaTime = os.clock() - startTime
print(("Preloading complete, took %.2f seconds"):format(deltaTime))