@quenty/studio-bridge 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/studio-bridge",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "WebSocket-based bridge for running Luau scripts in Roblox Studio",
   "type": "module",
   "main": "dist/src/index.js",
@@ -39,5 +39,5 @@
     "test:plugin": "lune run templates/studio-bridge-plugin-test/test/test-runner",
     "test:integration": "node dist/test/integration/smoke-test.js"
   },
-  "gitHead": "adebe068574c67bcef060e24600cb6e6f65bcbe7"
+  "gitHead": "0a4c7f67c4bd89a16d507c3ce2dd556291f16f6b"
 }

package/src/commands/process/launch/launch.test.ts

@@ -29,15 +29,38 @@ describe('launchHandlerAsync', () => {
       placePath: '/tmp/game.rbxl',
     });
 
-    expect(launchStudioAsync).toHaveBeenCalledWith('/tmp/game.rbxl');
+    expect(launchStudioAsync).toHaveBeenCalledWith({
+      placePath: '/tmp/game.rbxl',
+    });
     expect(result.launched).toBe(true);
     expect(result.summary).toBe('Studio launched with /tmp/game.rbxl');
   });
 
-  it('passes empty string when no place path', async () => {
+  it('passes cloud place + universe ids to launchStudioAsync', async () => {
+    const result = await launchHandlerAsync({
+      placeId: 84760113521251,
+      universeId: 9893751595,
+    });
+
+    expect(launchStudioAsync).toHaveBeenCalledWith({
+      placeId: 84760113521251,
+      universeId: 9893751595,
+    });
+    expect(result.summary).toBe(
+      'Studio launched with place 84760113521251 (universe 9893751595)'
+    );
+  });
+
+  it('summarizes a cloud place id without a universe id', async () => {
+    const result = await launchHandlerAsync({ placeId: 123 });
+
+    expect(result.summary).toBe('Studio launched with place 123');
+  });
+
+  it('passes an empty options object when nothing is specified', async () => {
     await launchHandlerAsync({});
 
-    expect(launchStudioAsync).toHaveBeenCalledWith('');
+    expect(launchStudioAsync).toHaveBeenCalledWith({});
   });
 
   it('returns correct summary without place path', async () => {

package/src/commands/process/launch/launch.ts

@@ -8,6 +8,8 @@ import { launchStudioAsync } from '../../../process/studio-process-manager.js';
 
 export interface LaunchOptions {
   placePath?: string;
+  placeId?: number;
+  universeId?: number;
 }
 
 export interface LaunchResult {
@@ -18,17 +20,23 @@ export interface LaunchResult {
 export async function launchHandlerAsync(
   options: LaunchOptions = {}
 ): Promise<LaunchResult> {
-  await launchStudioAsync(options.placePath ?? '');
+  await launchStudioAsync(options);
+  const target =
+    options.placeId != null
+      ? `place ${options.placeId}${
+          options.universeId != null ? ` (universe ${options.universeId})` : ''
+        }`
+      : options.placePath;
   return {
     launched: true,
-    summary: `Studio launched${
-      options.placePath ? ` with ${options.placePath}` : ''
-    }`,
+    summary: `Studio launched${target ? ` with ${target}` : ''}`,
   };
 }
 
 interface LaunchArgs {
   place?: string;
+  placeId?: number;
+  universeId?: number;
 }
 
 export const launchCommand = defineCommand<LaunchArgs, LaunchResult>({
@@ -40,6 +48,21 @@ export const launchCommand = defineCommand<LaunchArgs, LaunchResult>({
   scope: 'standalone',
   args: {
     place: arg.option({ description: 'Path to a .rbxl place file' }),
+    placeId: arg.option({
+      description:
+        'Cloud place id to open in Studio (edit mode, via the EditPlace deep-link)',
+      type: 'number',
+    }),
+    universeId: arg.option({
+      description:
+        'Cloud universe id for the place (recommended with --place-id)',
+      type: 'number',
+    }),
   },
-  handler: async (args) => launchHandlerAsync({ placePath: args.place }),
+  handler: async (args) =>
+    launchHandlerAsync({
+      placePath: args.place,
+      placeId: args.placeId,
+      universeId: args.universeId,
+    }),
 });

package/src/process/studio-process-manager.test.ts

@@ -1,5 +1,40 @@
 import { describe, it, expect, afterEach } from 'vitest';
-import { findPluginsFolder } from './studio-process-manager.js';
+import {
+  findPluginsFolder,
+  buildStudioLaunchArg,
+} from './studio-process-manager.js';
+
+describe('buildStudioLaunchArg', () => {
+  it('builds an EditPlace deep-link from place + universe ids', () => {
+    expect(
+      buildStudioLaunchArg({ placeId: 84760113521251, universeId: 9893751595 })
+    ).toBe(
+      'roblox-studio:1+launchmode:edit+task:EditPlace+placeId:84760113521251+universeId:9893751595'
+    );
+  });
+
+  it('omits universeId from the deep-link when not provided', () => {
+    expect(buildStudioLaunchArg({ placeId: 123 })).toBe(
+      'roblox-studio:1+launchmode:edit+task:EditPlace+placeId:123'
+    );
+  });
+
+  it('prefers the cloud place id over a local place path', () => {
+    expect(
+      buildStudioLaunchArg({ placeId: 5, placePath: '/tmp/game.rbxl' })
+    ).toContain('placeId:5');
+  });
+
+  it('returns the local place path when no place id is given', () => {
+    expect(buildStudioLaunchArg({ placePath: '/tmp/game.rbxl' })).toBe(
+      '/tmp/game.rbxl'
+    );
+  });
+
+  it('returns an empty string for no place at all', () => {
+    expect(buildStudioLaunchArg({})).toBe('');
+  });
+});
 
 describe('findPluginsFolder', () => {
   const originalPlatform = process.platform;

package/src/process/studio-process-manager.ts

@@ -125,24 +125,63 @@ export interface StudioProcess {
   killAsync: () => Promise<void>;
 }
 
+export interface LaunchStudioOptions {
+  /** Path to a local `.rbxl` place file to open. */
+  placePath?: string;
+  /** Cloud place id to open in Studio (via the `EditPlace` deep-link). */
+  placeId?: number;
+  /** Cloud universe id for the place (recommended alongside `placeId`). */
+  universeId?: number;
+}
+
 /**
- * Launch Roblox Studio with the given place file.
+ * Resolve the single argument handed to `RobloxStudioBeta`: a cloud
+ * `roblox-studio:` EditPlace deep-link when a `placeId` is given, otherwise
+ * the local `.rbxl` path (or `''` to open Studio with no place). The deep-link
+ * is exactly what the OS protocol handler passes to Studio, so Studio opens the
+ * cloud place in edit mode using the current logged-in session.
+ */
+export function buildStudioLaunchArg(options: LaunchStudioOptions): string {
+  if (options.placeId != null) {
+    const parts = [
+      'roblox-studio:1',
+      'launchmode:edit',
+      'task:EditPlace',
+      `placeId:${options.placeId}`,
+    ];
+    if (options.universeId != null) {
+      parts.push(`universeId:${options.universeId}`);
+    }
+    return parts.join('+');
+  }
+  return options.placePath ?? '';
+}
+
+/**
+ * Launch Roblox Studio with a local place file or a cloud place.
+ *
+ * Accepts a `LaunchStudioOptions` object (`{ placePath | placeId, universeId }`)
+ * or, for backward compatibility, a bare `.rbxl` path string.
  *
  * Uses Node's built-in `spawn` with `detached: true` + `unref()` so that
  * Studio survives after the CLI process exits. execa's internal Job Object
  * on Windows kills children on parent exit, so we avoid it here.
  */
 export async function launchStudioAsync(
-  placePath: string
+  options: LaunchStudioOptions | string = {}
 ): Promise<StudioProcess> {
+  const resolved: LaunchStudioOptions =
+    typeof options === 'string' ? { placePath: options } : options;
+  const launchArg = buildStudioLaunchArg(resolved);
+
   if (process.platform === 'linux') {
-    return launchStudioLinuxAsync(placePath);
+    return launchStudioLinuxAsync(launchArg);
   }
 
   const studioExe = await findStudioPathAsync();
-  OutputHelper.verbose(`[StudioBridge] ${studioExe} "${placePath}"`);
+  OutputHelper.verbose(`[StudioBridge] ${studioExe} "${launchArg}"`);
 
-  const proc = spawn(studioExe, placePath ? [placePath] : [], {
+  const proc = spawn(studioExe, launchArg ? [launchArg] : [], {
     detached: true,
     stdio: 'ignore',
   });