@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.7

package/plugin/src/handlers/Assets.luau

@@ -13,6 +13,7 @@
 ]]
 
 local AssetService = game:GetService("AssetService")
+local InsertService = game:GetService("InsertService")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
@@ -101,6 +102,54 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 		end
 	end
 
+	--[[
+		Scripts stripped BEFORE anything is parented.
+
+		The order is the whole point. A free model's scripts run the moment the
+		place is played, and one that is parented first and cleaned up a
+		fraction of a second later has already been given a foothold -- a
+		`Script` with `RunContext = Legacy` will not execute in edit mode, but
+		`Plugin` run context does, and nothing here should depend on knowing
+		which one an unknown model used.
+
+		This is the most-requested missing piece in Studio's own Toolbox: there
+		is no way to insert a model without its code, so people take the
+		geometry they want and the scripts they did not ask for together.
+	]]
+	local stripped = 0
+	if params.stripScripts == true then
+		for _, child in children do
+			if child:IsA("LuaSourceContainer") then
+				child:Destroy()
+				stripped += 1
+			else
+				for _, descendant in child:GetDescendants() do
+					if descendant:IsA("LuaSourceContainer") then
+						descendant:Destroy()
+						stripped += 1
+					end
+				end
+			end
+		end
+		-- A model that was nothing BUT scripts is now empty, and parenting
+		-- nothing silently is worse than saying so.
+		local remaining: { Instance } = {}
+		for _, child in children do
+			if child.Parent ~= nil or child:IsDescendantOf(game) or child.Name ~= "" then
+				if not child:IsA("LuaSourceContainer") then
+					table.insert(remaining, child)
+				end
+			end
+		end
+		children = remaining
+		if #children == 0 then
+			Dispatch.fail(
+				"EMPTY_ASSET",
+				string.format("Asset %d was nothing but scripts, and stripScripts removed them all.", assetId)
+			)
+		end
+	end
+
 	local inserted: { string } = {}
 	local _, undoable = Undo.record("MCPInsertAsset", "MCP insert asset", function()
 		for _, child in children do
@@ -132,8 +181,9 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 	return {
 		inserted = inserted,
 		assetId = assetId,
-		scriptCount = scriptCount,
-		scripts = if scriptCount > 0 then scriptNames else nil,
+		scriptCount = if params.stripScripts == true then 0 else scriptCount,
+		scripts = if scriptCount > 0 and params.stripScripts ~= true then scriptNames else nil,
+		strippedScripts = if params.stripScripts == true then stripped else nil,
 		undoable = undoable,
 	}
 end
@@ -342,8 +392,242 @@ function Assets.bake(params: { [string]: any }): { [string]: any }
 	}
 end
 
+--[[
+	The audio library, which the Creator Store index answers badly.
+
+	`assets op="search" category="audio"` used to go through the same public
+	index the model search uses, and it came back with a name, a creator and a
+	vote ratio -- none of which is how anyone chooses a sound. The engine has a
+	purpose-built search for this, and it returns the fields that actually
+	decide: how long the clip is, whether it is music or a sound effect, who
+	performed it, and whether Roblox endorses it.
+
+	Measured against a live session: "footstep" returns 30 results carrying
+	Title, Artist, Duration, AudioType, Tags and IsEndorsed. Duration alone is
+	the difference between a footstep and a three-minute track that happens to
+	mention footsteps in its description -- and the old path could not tell them
+	apart.
+]]
+function Assets.audio(params: { [string]: any }): { [string]: any }
+	local keyword = params.keyword
+	if typeof(keyword) ~= "string" or keyword == "" then
+		Dispatch.fail("BAD_PARAMS", "audio search needs a `keyword`.")
+	end
+	local limit = math.clamp(tonumber(params.limit) or 10, 1, 50)
+
+	local okParams, search = pcall(function()
+		local p = Instance.new("AudioSearchParams")
+		p.SearchKeyword = keyword
+		--[[
+			Both bounds are optional and both are worth passing through. A search
+			for a footstep wants something under two seconds; a search for
+			background music wants the opposite, and without a length filter the
+			two queries return the same list.
+		]]
+		local minimum = tonumber(params.minDuration)
+		local maximum = tonumber(params.maxDuration)
+		if minimum ~= nil then
+			(p :: any).MinDuration = math.max(0, minimum)
+		end
+		if maximum ~= nil then
+			(p :: any).MaxDuration = math.max(0, maximum)
+		end
+		--[[
+			Always set, never left to the engine.
+
+			`AudioSubType` defaults to Music, and that default is a trap rather
+			than a preference: measured, a search for "footstep" with the default
+			returns "Silent Footsteps II" at 153 seconds, "Footsteps in the Dark"
+			at 268, and thirty more like them -- ambient tracks whose titles
+			mention footsteps. The same search as SoundEffect returns
+			"JjBg_Grass_Footstep_6" at one second.
+
+			Nothing about the empty result said "you searched the music library".
+			So the default here is SoundEffect, which is what someone typing a
+			noise into a game engine means, and Music is something you ask for.
+		]]
+		local subType = if typeof(params.audioType) == "string" and params.audioType ~= ""
+			then params.audioType
+			else "SoundEffect"
+		;(p :: any).AudioSubType = (Enum :: any).AudioSubType[subType]
+		return p
+	end)
+	if not okParams then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("Those search parameters were refused: %s", tostring(search)),
+			'audioType must be one of the Enum.AudioSubType names, e.g. "Music" or "SoundEffect".'
+		)
+	end
+
+	local okSearch, pages = pcall(function()
+		return (AssetService :: any):SearchAudioAsync(search)
+	end)
+	if not okSearch then
+		Dispatch.fail(
+			"AUDIO_SEARCH_FAILED",
+			string.format("The audio search failed: %s", tostring(pages))
+		)
+	end
+
+	local items: { { [string]: any } } = {}
+	local page = pages:GetCurrentPage()
+	for _, entry in page do
+		if #items >= limit then
+			break
+		end
+		local row = entry :: { [string]: any }
+		table.insert(items, {
+			assetId = tostring(row.Id),
+			title = tostring(row.Title),
+			artist = if row.Artist ~= nil and tostring(row.Artist) ~= "" then tostring(row.Artist) else nil,
+			-- Seconds, rounded. The API returns a float and nobody picking a
+			-- sound effect cares about the third decimal place.
+			duration = math.round(tonumber(row.Duration) or 0),
+			audioType = (tostring(row.AudioType):gsub("Enum%.AudioSubType%.", "")),
+			endorsed = row.IsEndorsed == true,
+		})
+	end
+
+	return {
+		items = items,
+		count = #items,
+		keyword = keyword,
+		audioType = if typeof(params.audioType) == "string" and params.audioType ~= ""
+			then params.audioType
+			else "SoundEffect",
+	}
+end
+
+--[[
+	Looks inside a published asset without putting it in the place.
+
+	`insert` already reports what came in, and reporting it afterwards is one
+	Ctrl+Z too late to be reassuring: the scripts are in the data model by then,
+	and the model may have parented things outside itself on the way in.
+	`LoadAssetAsync` builds the asset in memory instead, which is where it can be
+	read and then dropped.
+
+	So this is the safe half of the existing script warning. The Creator Store
+	index says whether an asset has scripts at all; this says which ones, what
+	class they are, and what else is in there -- before anything is committed.
+
+	The loaded container is destroyed on every path. It is never parented, so it
+	is invisible to the data model, to undo history and to the user.
+]]
+function Assets.peek(params: { [string]: any }): { [string]: any }
+	local assetId = tonumber(params.assetId)
+	if assetId == nil or assetId <= 0 then
+		Dispatch.fail("BAD_PARAMS", "peek needs a numeric `assetId`.")
+	end
+
+	--[[
+		Loaded the way `insert` loads, not the way it is tempting to.
+
+		`AssetService:LoadAssetAsync` enforces ownership: it opens assets the
+		signed-in user owns or has been given, and refuses everything else with
+		"User is not authorized to access Asset". `InsertService:LoadAsset` does
+		not -- it is what the Toolbox itself uses, and it reaches any public
+		model.
+
+		Using the first one made this tool useless at the one job it exists for.
+		Measured: a free door from the Creator Store, two scripts inside it,
+		refused by `peek` and inserted by `insert` moments later. The SAFE
+		preview was weaker than the unsafe insert, so the only way to see what
+		was in a model was to put it in the place first -- which is precisely
+		what `peek` was written to avoid.
+
+		Nothing is parented here, so reaching further costs nothing: the model is
+		read in memory and destroyed before this function returns.
+	]]
+	--[[
+		`game:GetObjects`, the same loader `insert` uses -- see the note there.
+
+		Two wrong loaders were tried before this one, and both failed the same
+		way: `AssetService:LoadAssetAsync` and `InsertService:LoadAsset` each
+		enforce ownership and refuse any Creator Store model with "User is not
+		authorized to access Asset". That made the SAFE preview weaker than the
+		unsafe insert -- measured, a free door with two scripts in it was refused
+		by `peek` and inserted by `insert` moments later, so the only way to see
+		inside a model was to put it in the place first.
+
+		`GetObjects` is the plugin-security path Studio's own toolbox uses and it
+		reaches everything `insert` reaches, which is the only correct answer
+		here: a preview that cannot see what the insert would bring in is not a
+		preview of anything.
+
+		It returns top-level instances rather than a wrapper model, so they are
+		walked directly.
+	]]
+	local ok, loaded = pcall(function()
+		return game:GetObjects("rbxassetid://" .. assetId)
+	end)
+	if not ok then
+		Dispatch.fail(
+			"ASSET_UNAVAILABLE",
+			string.format("Could not load asset %d: %s", assetId, tostring(loaded)),
+			"The asset may be private, deleted, or not a model."
+		)
+	end
+
+	-- An array of roots, not one wrapper: `GetObjects` hands back whatever the
+	-- asset holds at its top level.
+	local roots = loaded :: { Instance }
+	local classes: { [string]: number } = {}
+	local scripts: { string } = {}
+	local total = 0
+
+	for _, root in roots do
+		total += 1
+		classes[root.ClassName] = (classes[root.ClassName] or 0) + 1
+		if root:IsA("LuaSourceContainer") and #scripts < 25 then
+			table.insert(scripts, string.format("%s (%s)", root.Name, root.ClassName))
+		end
+		for _, descendant in root:GetDescendants() do
+			total += 1
+			classes[descendant.ClassName] = (classes[descendant.ClassName] or 0) + 1
+			if descendant:IsA("LuaSourceContainer") and #scripts < 25 then
+				table.insert(scripts, string.format("%s (%s)", descendant:GetFullName(), descendant.ClassName))
+			end
+		end
+	end
+
+	local breakdown: { { [string]: any } } = {}
+	for className, count in classes do
+		table.insert(breakdown, { className = className, count = count })
+	end
+	table.sort(breakdown, function(a, b)
+		if a.count == b.count then
+			return a.className < b.className
+		end
+		return a.count > b.count
+	end)
+
+	local names: { string } = {}
+	for _, root in roots do
+		table.insert(names, string.format("%s (%s)", root.Name, root.ClassName))
+	end
+
+	-- Destroyed before returning, not after: the reply is built from plain
+	-- strings and numbers, so nothing in it outlives the instances it came from.
+	for _, root in roots do
+		root:Destroy()
+	end
+
+	return {
+		assetId = assetId,
+		roots = names,
+		descendants = total,
+		classes = breakdown,
+		scripts = scripts,
+		scriptCount = #scripts,
+	}
+end
+
 function Assets.register()
 	Dispatch.registerAll("assets", {
+		audio = Assets.audio,
+		peek = Assets.peek,
 		insert = Assets.insert,
 		bake = Assets.bake,
 	})