dominus-cli 2.2.1 → 2.3.0

package/plugin/src/Building.lua

@@ -0,0 +1,427 @@
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Selection = game:GetService("Selection")
+
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local ValueCodec = require(script.Parent.ValueCodec)
+
+local Building = {}
+
+local MAX_ITEMS = 200
+local MAX_PROPERTIES = 100
+
+local ALLOWED_PART_CLASSES = {
+	Part = true,
+	WedgePart = true,
+	CornerWedgePart = true,
+	TrussPart = true,
+	MeshPart = true,
+	SpawnLocation = true,
+	Seat = true,
+	VehicleSeat = true,
+}
+
+local function resolve(target, label)
+	local instance, err = InstanceRegistry.resolve(target)
+	if not instance then
+		error(label .. ": " .. tostring(err))
+	end
+	return instance
+end
+
+local function cleanup(instances)
+	for _, instance in instances do
+		pcall(function()
+			if instance.Parent == nil then
+				instance:Destroy()
+			end
+		end)
+	end
+end
+
+local function record(name, callback, created)
+	local recording = ChangeHistoryService:TryBeginRecording(name)
+	if not recording then
+		return { success = false, error = "Another plugin recording is already active" }
+	end
+
+	local ok, result = pcall(callback)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		cleanup(created or {})
+		return { success = false, error = tostring(result), rolledBack = true }
+	end
+
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	result.success = true
+	return result
+end
+
+local function finiteNumber(value, label)
+	assert(type(value) == "number" and value == value and math.abs(value) < math.huge, label .. " must be finite")
+	return value
+end
+
+local function vector3(value, label, default)
+	if value == nil then
+		return default
+	end
+	assert(type(value) == "table", label .. " must be a Vector3 object")
+	return Vector3.new(
+		finiteNumber(value.X or value.x or value[1], label .. ".x"),
+		finiteNumber(value.Y or value.y or value[2], label .. ".y"),
+		finiteNumber(value.Z or value.z or value[3], label .. ".z")
+	)
+end
+
+local function rotation(value, label)
+	local degrees = vector3(value, label, Vector3.zero)
+	return CFrame.fromOrientation(math.rad(degrees.X), math.rad(degrees.Y), math.rad(degrees.Z))
+end
+
+local function setProperties(instance, properties)
+	if properties == nil then
+		return {}
+	end
+	assert(type(properties) == "table", "properties must be an object")
+	local count = 0
+	local applied = {}
+	for propertyName, value in properties do
+		count += 1
+		if count > MAX_PROPERTIES then
+			error("At most " .. MAX_PROPERTIES .. " properties are allowed per item")
+		end
+		applied[propertyName] = ValueCodec.setProperty(instance, propertyName, value)
+	end
+	return applied
+end
+
+local function validateItemCount(items, label, maximum)
+	assert(type(items) == "table" and #items > 0, label .. " must contain at least one item")
+	assert(#items <= maximum, label .. " is limited to " .. maximum .. " items")
+end
+
+local function assertMovable(instance, label)
+	assert(instance ~= game and instance.Parent ~= game, label .. " cannot be a DataModel service")
+end
+
+function Building.createParts(spec)
+	validateItemCount(spec.parts, "parts", MAX_ITEMS)
+	local parent = spec.parent and resolve(spec.parent, "parent") or workspace
+	local group = nil
+	local created = {}
+
+	return record("Dominus 2: Build parts", function()
+		if spec.groupName ~= nil then
+			assert(type(spec.groupName) == "string" and #spec.groupName > 0, "groupName must be a non-empty string")
+			local groupClass = spec.groupClass or "Model"
+			assert(groupClass == "Model" or groupClass == "Folder", "groupClass must be Model or Folder")
+			group = Instance.new(groupClass)
+			group.Name = spec.groupName
+			table.insert(created, group)
+		end
+
+		local parts = {}
+		for index, item in spec.parts do
+			assert(type(item) == "table", "Part " .. index .. " must be an object")
+			assert(type(item.name) == "string" and #item.name > 0, "Part " .. index .. ".name must be a non-empty string")
+			local className = item.className or "Part"
+			if item.shape == "Wedge" then
+				className = "WedgePart"
+			elseif item.shape == "CornerWedge" then
+				className = "CornerWedgePart"
+			end
+			assert(ALLOWED_PART_CLASSES[className] == true, "Part " .. index .. " uses an unsupported class: " .. tostring(className))
+
+			local part = Instance.new(className)
+			table.insert(created, part)
+			part.Name = item.name
+			if part:IsA("BasePart") then
+				part.Anchored = item.anchored ~= false
+			end
+			if item.position then
+				part.Position = vector3(item.position, "Part " .. index .. ".position")
+			end
+			if item.orientation then
+				part.Orientation = vector3(item.orientation, "Part " .. index .. ".orientation")
+			end
+			if item.size then
+				part.Size = vector3(item.size, "Part " .. index .. ".size")
+			end
+			if item.color then
+				ValueCodec.setProperty(part, "Color", item.color)
+			end
+			if item.material then
+				ValueCodec.setProperty(part, "Material", item.material)
+			end
+			if item.transparency ~= nil then
+				part.Transparency = finiteNumber(item.transparency, "Part " .. index .. ".transparency")
+			end
+			if item.canCollide ~= nil then
+				assert(type(item.canCollide) == "boolean", "Part " .. index .. ".canCollide must be a boolean")
+				part.CanCollide = item.canCollide
+			end
+			if item.shape and className == "Part" then
+				ValueCodec.setProperty(part, "Shape", item.shape)
+			end
+			setProperties(part, item.properties)
+			part.Parent = group or parent
+			table.insert(parts, part)
+		end
+
+		if group then
+			group.Parent = parent
+		end
+
+		local refs = {}
+		for _, part in parts do
+			table.insert(refs, InstanceRegistry.toRef(part))
+		end
+		return {
+			created = refs,
+			group = group and InstanceRegistry.toRef(group) or nil,
+			count = #refs,
+		}
+	end, created)
+end
+
+function Building.cloneInstances(spec)
+	validateItemCount(spec.requests, "requests", 100)
+	local created = {}
+
+	return record("Dominus 2: Clone instances", function()
+		local clones = {}
+		local totalCopies = 0
+		for requestIndex, request in spec.requests do
+			assert(type(request) == "table", "Clone request " .. requestIndex .. " must be an object")
+			local source = resolve(request.target, "Clone request " .. requestIndex .. " target")
+			assertMovable(source, "Clone source")
+			local parent = request.parent and resolve(request.parent, "Clone request " .. requestIndex .. " parent") or source.Parent
+			assert(parent ~= nil, "Clone request " .. requestIndex .. " source has no parent")
+			local count = request.count or 1
+			assert(type(count) == "number" and count % 1 == 0 and count >= 1 and count <= 50, "count must be an integer from 1 to 50")
+			totalCopies += count
+			assert(totalCopies <= MAX_ITEMS, "A clone batch is limited to " .. MAX_ITEMS .. " copies")
+			local offset = vector3(request.offset, "Clone request " .. requestIndex .. ".offset", Vector3.zero)
+			local stepOffset = vector3(request.stepOffset, "Clone request " .. requestIndex .. ".stepOffset", Vector3.zero)
+
+			for copyIndex = 1, count do
+				local clone = source:Clone()
+				assert(clone ~= nil, "Clone request " .. requestIndex .. " target is not Archivable")
+				table.insert(created, clone)
+				if request.name then
+					clone.Name = count == 1 and request.name or (request.name .. " " .. copyIndex)
+				end
+				setProperties(clone, request.properties)
+				if clone:IsA("PVInstance") then
+					local totalOffset = offset + stepOffset * (copyIndex - 1)
+					clone:PivotTo(clone:GetPivot() + totalOffset)
+				elseif offset.Magnitude > 0 or stepOffset.Magnitude > 0 then
+					error("Clone request " .. requestIndex .. " cannot offset a non-PVInstance")
+				end
+				clone.Parent = parent
+				table.insert(clones, InstanceRegistry.toRef(clone))
+			end
+		end
+		return { clones = clones, count = #clones }
+	end, created)
+end
+
+local function validateIndependentTargets(targets)
+	for leftIndex, left in targets do
+		for rightIndex = leftIndex + 1, #targets do
+			local right = targets[rightIndex]
+			assert(not left:IsAncestorOf(right) and not right:IsAncestorOf(left), "Targets " .. leftIndex .. " and " .. rightIndex .. " overlap")
+		end
+	end
+end
+
+function Building.groupInstances(spec)
+	validateItemCount(spec.targets, "targets", 100)
+	assert(type(spec.name) == "string" and #spec.name > 0, "name must be a non-empty string")
+	local className = spec.className or "Model"
+	assert(className == "Model" or className == "Folder", "className must be Model or Folder")
+	local targets = {}
+	for index, targetRef in spec.targets do
+		local target = resolve(targetRef, "Target " .. index)
+		assertMovable(target, "Target " .. index)
+		table.insert(targets, target)
+	end
+	validateIndependentTargets(targets)
+	local parent = spec.parent and resolve(spec.parent, "parent") or targets[1].Parent
+	assert(parent ~= nil, "The first target has no parent")
+	local created = {}
+
+	return record("Dominus 2: Group instances", function()
+		local group = Instance.new(className)
+		table.insert(created, group)
+		group.Name = spec.name
+		group.Parent = parent
+		for _, target in targets do
+			assert(not target:IsAncestorOf(group), "Cannot group an ancestor into its descendant")
+			target.Parent = group
+		end
+		return { group = InstanceRegistry.toRef(group), count = #targets }
+	end, created)
+end
+
+function Building.ungroupInstances(spec)
+	assert(spec.confirm == true, "confirm must be true")
+	validateItemCount(spec.targets, "targets", 20)
+
+	return record("Dominus 2: Ungroup instances", function()
+		local moved = {}
+		local removed = {}
+		for index, targetRef in spec.targets do
+			local group = resolve(targetRef, "Group " .. index)
+			assert(group:IsA("Model") or group:IsA("Folder"), "Group " .. index .. " must be a Model or Folder")
+			assertMovable(group, "Group " .. index)
+			local parent = spec.parent and resolve(spec.parent, "parent") or group.Parent
+			assert(parent ~= nil, "Group " .. index .. " has no parent")
+			for _, child in group:GetChildren() do
+				child.Parent = parent
+				table.insert(moved, InstanceRegistry.toRef(child))
+			end
+			table.insert(removed, { name = group.Name, className = group.ClassName })
+			group:Destroy()
+		end
+		return { moved = moved, removedGroups = removed, count = #moved }
+	end)
+end
+
+local function absolutePivot(current, operation)
+	if operation.cframe then
+		return ValueCodec.decodeForCurrent(current, operation.cframe)
+	end
+	local position = vector3(operation.position, "position", current.Position)
+	local x, y, z = current:ToOrientation()
+	if operation.orientation then
+		local degrees = vector3(operation.orientation, "orientation")
+		x, y, z = math.rad(degrees.X), math.rad(degrees.Y), math.rad(degrees.Z)
+	end
+	return CFrame.new(position) * CFrame.fromOrientation(x, y, z)
+end
+
+function Building.transformInstances(spec)
+	validateItemCount(spec.operations, "operations", 100)
+
+	return record("Dominus 2: Transform instances", function()
+		local results = {}
+		for index, operation in spec.operations do
+			local target = resolve(operation.target, "Operation " .. index .. " target")
+			assert(target:IsA("PVInstance"), "Operation " .. index .. " target must be a Model or BasePart")
+			local current = target:GetPivot()
+			local mode = operation.mode or "absolute"
+			local nextPivot
+			if mode == "absolute" then
+				nextPivot = absolutePivot(current, operation)
+			elseif mode == "relative" then
+				local offset = vector3(operation.offset, "Operation " .. index .. ".offset", Vector3.zero)
+				local rotate = rotation(operation.rotationOffset, "Operation " .. index .. ".rotationOffset")
+				if operation.space == "local" then
+					nextPivot = current * CFrame.new(offset) * rotate
+				else
+					nextPivot = CFrame.new(offset) * current * rotate
+				end
+			else
+				error("Operation " .. index .. ".mode must be absolute or relative")
+			end
+			target:PivotTo(nextPivot)
+			table.insert(results, { target = InstanceRegistry.toRef(target), pivot = ValueCodec.encode(target:GetPivot()) })
+		end
+		return { transformed = results, count = #results }
+	end)
+end
+
+function Building.createWelds(spec)
+	validateItemCount(spec.welds, "welds", MAX_ITEMS)
+	local created = {}
+
+	return record("Dominus 2: Create welds", function()
+		local welds = {}
+		for index, item in spec.welds do
+			local part0 = resolve(item.part0, "Weld " .. index .. " part0")
+			local part1 = resolve(item.part1, "Weld " .. index .. " part1")
+			assert(part0:IsA("BasePart") and part1:IsA("BasePart"), "Weld " .. index .. " endpoints must be BaseParts")
+			assert(part0 ~= part1, "Weld " .. index .. " endpoints must be different")
+			local parent = item.parent and resolve(item.parent, "Weld " .. index .. " parent") or part0
+			local weld = Instance.new("WeldConstraint")
+			table.insert(created, weld)
+			weld.Name = item.name or (part0.Name .. "_to_" .. part1.Name)
+			weld.Part0 = part0
+			weld.Part1 = part1
+			weld.Parent = parent
+			table.insert(welds, InstanceRegistry.toRef(weld))
+		end
+		return { welds = welds, count = #welds }
+	end, created)
+end
+
+local function overlapParams(spec)
+	local params = OverlapParams.new()
+	local maxParts = spec.maxParts or 200
+	assert(type(maxParts) == "number" and maxParts % 1 == 0 and maxParts >= 1 and maxParts <= 500, "maxParts must be an integer from 1 to 500")
+	params.MaxParts = maxParts
+	params.RespectCanCollide = spec.respectCanCollide == true
+	if spec.filter and #spec.filter > 0 then
+		local instances = {}
+		for index, targetRef in spec.filter do
+			table.insert(instances, resolve(targetRef, "Filter " .. index))
+		end
+		params.FilterDescendantsInstances = instances
+		params.FilterType = spec.filterType == "Include" and Enum.RaycastFilterType.Include or Enum.RaycastFilterType.Exclude
+	end
+	return params
+end
+
+function Building.queryParts(spec)
+	local root = spec.root and resolve(spec.root, "root") or workspace
+	assert(root:IsA("WorldRoot"), "root must be Workspace or a WorldModel")
+	local mode = spec.mode or "box"
+	local found
+	if mode == "box" then
+		local position = vector3(spec.position, "position")
+		local size = vector3(spec.size, "size")
+		assert(size.X > 0 and size.Y > 0 and size.Z > 0, "size components must be greater than zero")
+		local box = CFrame.new(position) * rotation(spec.orientation, "orientation")
+		found = root:GetPartBoundsInBox(box, size, overlapParams(spec))
+	elseif mode == "radius" then
+		local position = vector3(spec.position, "position")
+		local radius = finiteNumber(spec.radius, "radius")
+		assert(radius > 0, "radius must be greater than zero")
+		found = root:GetPartBoundsInRadius(position, radius, overlapParams(spec))
+	else
+		error("mode must be box or radius")
+	end
+
+	table.sort(found, function(left, right)
+		return InstanceRegistry.getDisplayPath(left) < InstanceRegistry.getDisplayPath(right)
+	end)
+	local parts = {}
+	for _, part in found do
+		table.insert(parts, {
+			name = part.Name,
+			className = part.ClassName,
+			ref = InstanceRegistry.toRef(part),
+			position = ValueCodec.encode(part.Position),
+			size = ValueCodec.encode(part.Size),
+		})
+	end
+	return { success = true, parts = parts, count = #parts, mode = mode }
+end
+
+function Building.setSelection(spec)
+	assert(type(spec.targets) == "table", "targets must be an array")
+	assert(#spec.targets <= 200, "At most 200 instances can be selected")
+	local targets = {}
+	for index, targetRef in spec.targets do
+		table.insert(targets, resolve(targetRef, "Target " .. index))
+	end
+	Selection:Set(targets)
+	local selected = {}
+	for _, target in targets do
+		table.insert(selected, InstanceRegistry.toRef(target))
+	end
+	return { success = true, selection = selected, count = #selected }
+end
+
+return Building

package/plugin/src/CommandRouter.lua

@@ -1,3 +1,4 @@
+local Building = require(script.Parent.Building)
 local Explorer = require(script.Parent.Explorer)
 local InstanceRegistry = require(script.Parent.InstanceRegistry)
 local Mutation = require(script.Parent.Mutation)
@@ -37,6 +38,30 @@ local handlers = {
 	["studio:v2:apply"] = function(payload)
 		return Mutation.apply(payload)
 	end,
+	["studio:v2:create_parts"] = function(payload)
+		return Building.createParts(payload)
+	end,
+	["studio:v2:clone_instances"] = function(payload)
+		return Building.cloneInstances(payload)
+	end,
+	["studio:v2:group_instances"] = function(payload)
+		return Building.groupInstances(payload)
+	end,
+	["studio:v2:ungroup_instances"] = function(payload)
+		return Building.ungroupInstances(payload)
+	end,
+	["studio:v2:transform_instances"] = function(payload)
+		return Building.transformInstances(payload)
+	end,
+	["studio:v2:create_welds"] = function(payload)
+		return Building.createWelds(payload)
+	end,
+	["studio:v2:query_parts"] = function(payload)
+		return Building.queryParts(payload)
+	end,
+	["studio:v2:set_selection"] = function(payload)
+		return Building.setSelection(payload)
+	end,
 	["studio:v2:delete"] = function(payload)
 		return Mutation.delete(payload)
 	end,

package/plugin/src/Mutation.lua

@@ -44,6 +44,7 @@ function Mutation.apply(spec)
 	end
 
 	local results = {}
+	local created = {}
 	local ok, err = pcall(function()
 		for index, operation in operations do
 			assert(type(operation) == "table", "Operation " .. index .. " must be an object")
@@ -59,12 +60,34 @@ function Mutation.apply(spec)
 				assert(type(operation.className) == "string", "create.className must be a string")
 				assert(type(operation.name) == "string", "create.name must be a string")
 				local instance = Instance.new(operation.className)
+				table.insert(created, instance)
 				instance.Name = operation.name
 				if operation.properties then
 					setProperties(instance, operation.properties)
 				end
 				instance.Parent = parent
 				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(instance) })
+			elseif operation.op == "clone" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				assert(target ~= game and target.Parent ~= game, "Services cannot be cloned")
+				local parent = operation.parent and resolve(operation.parent, "Operation " .. index .. " parent") or target.Parent
+				assert(parent ~= nil, "Clone target has no parent")
+				local clone = target:Clone()
+				assert(clone ~= nil, "Clone target is not Archivable")
+				table.insert(created, clone)
+				if operation.name then
+					clone.Name = operation.name
+				end
+				if operation.properties then
+					setProperties(clone, operation.properties)
+				end
+				if operation.offset then
+					assert(clone:IsA("PVInstance"), "Only Models and BaseParts can be spatially offset")
+					local offset = ValueCodec.decodeForCurrent(Vector3.zero, operation.offset)
+					clone:PivotTo(clone:GetPivot() + offset)
+				end
+				clone.Parent = parent
+				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(clone) })
 			elseif operation.op == "move" then
 				local target = resolve(operation.target, "Operation " .. index .. " target")
 				local parent = resolve(operation.parent, "Operation " .. index .. " parent")
@@ -79,6 +102,13 @@ function Mutation.apply(spec)
 
 	if not ok then
 		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		for _, instance in created do
+			pcall(function()
+				if instance.Parent == nil then
+					instance:Destroy()
+				end
+			end)
+		end
 		return { success = false, error = tostring(err), rolledBack = true }
 	end