@quenty/studio-bridge 0.23.0 → 0.24.0

package/src/commands/playtest/playtest-sessions.ts

@@ -5,8 +5,14 @@
  * each connects to the bridge as its own session. Those sessions can't be
  * matched to the Studio that started them by instance id, since unpublished
  * places give every DataModel its own. Instead, `startPlaytestAsync` passes a
- * playtest id as the StudioTestService test args, and each new session is
- * asked for it back through `GetTestArgs`.
+ * playtest id as the StudioTestService test args, and each session registers
+ * with it.
+ *
+ * The playtest's server session is the plugin when Studio loads user plugins
+ * into playtests. Otherwise the edit session plants the same client into the
+ * playtest as an ordinary Script (see plugin/playtest-bridge.ts). That one can
+ * only run code compiled when the playtest started: the actions, and the
+ * scripts `startPlaytestAsync` is given.
  */
 
 import { randomUUID } from 'crypto';
@@ -20,6 +26,7 @@ import type {
 } from '../../bridge/index.js';
 import { ContextNotFoundError } from '../../bridge/index.js';
 import { getPluginBuildVersionAsync } from '../../plugin/plugin-build-version.js';
+import { buildPlaytestBridgeAsync } from '../../plugin/playtest-bridge.js';
 import { tryReadLoadUserPluginsOnPlaytestAsync } from '../../process/studio-settings.js';
 
 /** How long a started playtest may run before its pending start request is dropped. */
@@ -29,16 +36,19 @@ const SESSION_WAIT_TIMEOUT_MS = 30_000;
 /** Each player of a multiplayer test boots its own Studio process. */
 const MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS = 90_000;
 const SESSION_CLOSE_TIMEOUT_MS = 10_000;
-const READ_RETRY_DELAY_MS = 1_000;
-
-const PLAYTEST_PLUGINS_OFF_MESSAGE = `Studio's "Load user plugins on playtest" setting is off, so the studio-bridge plugin doesn't load into playtests and their sessions can't connect. Turn it on in Studio Settings, or run a script in a playtest's server with 'studio-bridge playtest run', which works without it.`;
 
-const READ_PLAYTEST_ID_SCRIPT = [
-  'local ok, args = pcall(function()',
-  '\treturn game:GetService("StudioTestService"):GetTestArgs()',
-  'end)',
-  'return if ok and type(args) == "table" then args.studioBridgePlaytestId else nil',
-].join('\n');
+const PLAYTEST_PLUGINS_OFF_MESSAGE = `Studio's "Load user plugins on playtest" setting is off, so the studio-bridge plugin doesn't load into a playtest's client. A playtest started with 'studio-bridge playtest start' gets a planted client session instead, which runs only code compiled when it started; turn the setting on to run any code.`;
+
+export interface StartPlaytestOptions {
+  /**
+   * Code the caller will run in the playtest's server session. A server
+   * session planted without plugin permissions can only run code compiled
+   * when the playtest starts.
+   */
+  scripts?: string[];
+  /** Wait for the server session only, so play mode needs no client plugin. */
+  serverOnly?: boolean;
+}
 
 export interface StartedPlaytest {
   playtestId: string;
@@ -68,19 +78,33 @@ export async function startPlaytestAsync(
   connection: BridgeConnection,
   editSession: BridgeSession,
   mode: PlaytestMode,
-  players?: number
+  players?: number,
+  options: StartPlaytestOptions = {}
 ): Promise<StartedPlaytest> {
   if (editSession.context !== 'edit') {
     throw new Error(
       `Playtests start from an edit session, but '${editSession.info.sessionId}' is a ${editSession.context} session`
     );
   }
-  if (await isPlaytestPluginsOffAsync(connection)) {
-    throw new Error(PLAYTEST_PLUGINS_OFF_MESSAGE);
-  }
+  const pluginsOnPlaytest = await tryReadPlaytestPluginsAsync(connection);
   if (players !== undefined) {
-    await assertCanStartMultiplayerAsync(editSession, mode, players);
+    assertValidMultiplayer(mode, players);
   }
+  // Plugin sessions in the playtest register with its id, which older plugins leave out
+  if (pluginsOnPlaytest !== false) {
+    await assertCurrentPluginAsync(editSession);
+  }
+
+  // A server plugin, when Studio does load one, stands down for a planted bridge
+  const bridge =
+    pluginsOnPlaytest === true
+      ? undefined
+      : await buildPlaytestBridgeAsync(options.scripts, {
+          withClient:
+            pluginsOnPlaytest === false &&
+            mode === 'play' &&
+            !options.serverOnly,
+        });
 
   const playtestId = randomUUID();
   const ended = editSession
@@ -89,7 +113,8 @@ export async function startPlaytestAsync(
       playtestId,
       connection.port,
       PLAYTEST_MAX_DURATION_MS,
-      players
+      players,
+      bridge
     )
     .catch(
       (err): PlaytestEndResult => ({
@@ -99,7 +124,9 @@ export async function startPlaytestAsync(
       })
     );
 
-  const clientCount = players ?? (mode === 'play' ? 1 : 0);
+  const clientCount = options.serverOnly
+    ? 0
+    : players ?? (mode === 'play' ? 1 : 0);
   const waitTimeoutMs =
     players !== undefined
       ? MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS
@@ -153,20 +180,14 @@ export async function startPlaytestAsync(
 
   // Without its server session the playtest can't be ended from here
   if (!server?.isConnected) {
-    throw new Error(
-      `Playtest started, but ${waited}, so stop it in Studio. Play sessions only connect with Studio's "Load user plugins on playtest" setting on.`
-    );
+    throw new Error(`Playtest started, but ${waited}, so stop it in Studio.`);
   }
 
   await endPlaytestAsync(connection, server);
   throw new Error(`Playtest started, but ${waited}, so it was stopped.`);
 }
 
-async function assertCanStartMultiplayerAsync(
-  editSession: BridgeSession,
-  mode: PlaytestMode,
-  players: number
-): Promise<void> {
+function assertValidMultiplayer(mode: PlaytestMode, players: number): void {
   if (!Number.isInteger(players) || players < 1) {
     throw new Error(
       `--players must be a whole number of at least 1, not ${players}`
@@ -175,12 +196,15 @@ async function assertCanStartMultiplayerAsync(
   if (mode !== 'play') {
     throw new Error('A multiplayer test runs in play mode');
   }
+}
 
-  // Older plugins give every client the same session id, so all but one drop off
+async function assertCurrentPluginAsync(
+  editSession: BridgeSession
+): Promise<void> {
   const expected = await getPluginBuildVersionAsync();
   if (editSession.info.pluginVersion !== expected) {
     throw new Error(
-      `Multiplayer tests need the current studio-bridge plugin, but '${editSession.info.placeName}' has an older one. Run 'studio-bridge plugin install' first.`
+      `Playtests with plugin sessions need the current studio-bridge plugin, but '${editSession.info.placeName}' has an older one. Run 'studio-bridge plugin install' first.`
     );
   }
 }
@@ -255,16 +279,15 @@ export async function explainMissingPlaytestContextAsync(
 }
 
 /**
- * Whether this machine's Studio has "Load user plugins on playtest" off. A
- * remote Studio's settings aren't on this machine, so they count as unknown.
+ * Whether this machine's Studio has "Load user plugins on playtest" on. A
+ * remote Studio's settings aren't on this machine, so they are unknown.
  */
-async function isPlaytestPluginsOffAsync(
+async function tryReadPlaytestPluginsAsync(
   connection: BridgeConnection
-): Promise<boolean> {
-  return (
-    !connection.isRemote &&
-    (await tryReadLoadUserPluginsOnPlaytestAsync()) === false
-  );
+): Promise<boolean | undefined> {
+  return connection.isRemote
+    ? undefined
+    : await tryReadLoadUserPluginsOnPlaytestAsync();
 }
 
 async function explainNoPlaytestAsync(
@@ -273,7 +296,10 @@ async function explainNoPlaytestAsync(
   context?: SessionContext
 ): Promise<string> {
   const of = studio ? ` of ${studio}` : '';
-  if (await isPlaytestPluginsOffAsync(connection)) {
+  if (
+    context === 'client' &&
+    (await tryReadPlaytestPluginsAsync(connection)) === false
+  ) {
     return `No playtest${of} is connected. ${PLAYTEST_PLUGINS_OFF_MESSAGE}`;
   }
   const missing = context ? `, so there is no ${context} session` : '';
@@ -307,7 +333,6 @@ async function waitForPlaytestSessionsAsync(
 ): Promise<PlaytestSessions> {
   return new Promise((resolve) => {
     const found: PlaytestSessions = { clients: [] };
-    const checked = new Set<string>();
 
     const cleanup = () => {
       clearTimeout(timer);
@@ -316,30 +341,22 @@ async function waitForPlaytestSessionsAsync(
     };
 
     const onSession = (session: BridgeSession) => {
-      const { sessionId } = session.info;
-      if (session.context === 'edit' || checked.has(sessionId)) {
+      if (session.info.playtestId !== playtestId) {
         return;
       }
-      checked.add(sessionId);
-
-      void readPlaytestIdAsync(connection, sessionId, signal).then((read) => {
-        if (signal.aborted || !read) return;
-        if (read.id !== playtestId) {
-          // The last playtest's session can linger under the same id; read its replacement too
-          checked.delete(sessionId);
-          return;
-        }
-
-        if (read.session.context === 'server') {
-          found.server = read.session;
-        } else {
-          found.clients.push(read.session);
-        }
-        if (found.server && found.clients.length >= clientCount) {
-          cleanup();
-          resolve(found);
-        }
-      });
+
+      if (session.context === 'server') {
+        found.server = session;
+      } else if (
+        session.context === 'client' &&
+        !found.clients.some((c) => c.info.sessionId === session.info.sessionId)
+      ) {
+        found.clients.push(session);
+      }
+      if (found.server && found.clients.length >= clientCount) {
+        cleanup();
+        resolve(found);
+      }
     };
 
     // Resolves with whichever sessions connected; the caller reports the rest
@@ -358,34 +375,6 @@ async function waitForPlaytestSessionsAsync(
   });
 }
 
-/**
- * Reads the playtest id a session was started under, retrying while the read
- * fails: a playtest's DataModels are slow to answer while their Studio boots,
- * and a session that reconnects is read again under the same id.
- */
-async function readPlaytestIdAsync(
-  connection: BridgeConnection,
-  sessionId: string,
-  signal: AbortSignal
-): Promise<{ session: BridgeSession; id: string | undefined } | undefined> {
-  while (!signal.aborted) {
-    const session = connection.getSession(sessionId);
-    if (session) {
-      try {
-        const result = await session.execAsync(READ_PLAYTEST_ID_SCRIPT, 5_000);
-        if (result.success) {
-          const value = result.returnValues?.[0];
-          return { session, id: typeof value === 'string' ? value : undefined };
-        }
-      } catch {
-        // Retried below
-      }
-    }
-    await new Promise((resolve) => setTimeout(resolve, READ_RETRY_DELAY_MS));
-  }
-  return undefined;
-}
-
 async function waitForSessionCloseAsync(
   connection: BridgeConnection,
   sessionId: string

package/src/commands/playtest/run/run.ts

@@ -5,26 +5,24 @@
  * `--context client`. Its output and return values come back the same way as
  * `console exec`.
  *
- * In the server, the edit session plants a runner script in the playtest
- * (playtest-runner.luau), so this works even when Studio does not load user
- * plugins into playtests. The client has no such path: it needs the
- * playtest's client session, so it needs that Studio setting on.
+ * Both run through the playtest's sessions. The server session works even
+ * when Studio does not load user plugins into playtests, since the edit
+ * session then plants it, with this code compiled ahead of time (see
+ * playtest-sessions.ts). The client session needs that Studio setting on.
  */
 
-import * as fs from 'fs/promises';
-import { resolvePackagePath } from '@quenty/nevermore-template-helpers';
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
 import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
 import {
   execHandlerAsync,
   formatExecText,
-  type ExecResult as CommandExecResult,
+  INPUT_ARG_DESCRIPTION,
+  readInputFilesAsync,
 } from '../../console/exec/exec.js';
 import type {
   BridgeConnection,
   BridgeSession,
-  ExecResult,
   PlaytestMode,
   SessionContext,
 } from '../../../bridge/index.js';
@@ -45,15 +43,15 @@ export interface PlaytestRunOptions {
   timeout?: number;
   /** Passed to the script as `...`. */
   args?: string[];
+  /** Passed to the script as buffers in `...`, before `args`. */
+  inputs?: Buffer[];
 }
 
-/** Matches `console exec`'s default execution timeout. */
-const DEFAULT_TIMEOUT_MS = 120_000;
+const PLAYER_JOIN_TIMEOUT_MS = 30_000;
 
 export interface PlaytestRunResult {
   success: boolean;
-  /** Absent when the script ran through the planted runner. */
-  playtestId?: string;
+  playtestId: string;
   output: string[];
   error?: string;
   returnValues?: SerializedReturnValue[];
@@ -66,8 +64,9 @@ interface PlaytestRunArgs {
   code?: string;
   file?: string;
   mode?: PlaytestMode;
-  timeout?: number;
+  scriptTimeout?: number;
   scriptArgs?: string[];
+  input?: string[];
 }
 
 export async function playtestRunHandlerAsync(
@@ -85,14 +84,15 @@ export async function playtestRunHandlerAsync(
     'edit'
   );
 
-  if (options.context === 'server') {
-    return runWithPlantedRunnerAsync(editSession, options);
-  }
-
   const playtest = await startPlaytestAsync(
     connection,
     editSession,
-    options.mode
+    options.mode,
+    undefined,
+    {
+      scripts: [options.scriptContent],
+      serverOnly: options.context === 'server',
+    }
   );
 
   let result: PlaytestRunResult;
@@ -101,12 +101,17 @@ export async function playtestRunHandlerAsync(
     if (!session) {
       throw new Error(`Playtest has no ${options.context} session`);
     }
+    // In play mode the server's code expects the player, who joins a moment later
+    if (options.mode === 'play' && options.context === 'server') {
+      await waitForPlayerAsync(session);
+    }
 
     result = {
       ...(await execHandlerAsync(session, {
         scriptContent: options.scriptContent,
         timeout: options.timeout,
         args: options.args,
+        inputs: options.inputs,
       })),
       playtestId: playtest.playtestId,
     };
@@ -123,44 +128,19 @@ export async function playtestRunHandlerAsync(
   return stopError ? { ...result, stopError } : result;
 }
 
-async function runWithPlantedRunnerAsync(
-  editSession: BridgeSession,
-  options: PlaytestRunOptions
-): Promise<PlaytestRunResult> {
-  const runnerSource = await fs.readFile(
-    resolvePackagePath(
-      import.meta.url,
-      'src',
-      'commands',
-      'playtest',
-      'run',
-      'playtest-runner.luau'
-    ),
-    'utf-8'
+async function waitForPlayerAsync(serverSession: BridgeSession): Promise<void> {
+  const deadline = Date.now() + PLAYER_JOIN_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const { players } = await serverSession.playtestPlayersAsync(
+      { op: 'list' },
+      PLAYER_JOIN_TIMEOUT_MS
+    );
+    if (players.length > 0) return;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(
+    `No player joined the playtest within ${PLAYER_JOIN_TIMEOUT_MS / 1000}s`
   );
-
-  const result = await editSession.runPlaytestScriptAsync({
-    mode: options.mode,
-    script: options.scriptContent,
-    runnerSource,
-    timeoutSec: (options.timeout ?? DEFAULT_TIMEOUT_MS) / 1000,
-    args: options.args,
-  });
-
-  return toCommandResult(result);
-}
-
-/** Shapes a bridge ExecResult the way `console exec` reports it. */
-function toCommandResult(result: ExecResult): CommandExecResult {
-  return {
-    success: result.success,
-    output: result.output.map((entry) => entry.body),
-    error: result.error,
-    returnValues: result.returnValues,
-    summary: result.success
-      ? 'Script executed successfully'
-      : `Script failed: ${result.error}`,
-  };
 }
 
 /** Ends the playtest, returning why it could not instead of throwing. */
@@ -207,10 +187,14 @@ export const playtestRunCommand = defineCommand<
       choices: ['play', 'run'],
       default: 'play',
     }),
-    timeout: arg.option({
-      description: 'Execution timeout in milliseconds',
+    scriptTimeout: arg.option({
+      description: 'Cancel the script after this many milliseconds',
       type: 'number',
     }),
+    input: arg.option({
+      description: INPUT_ARG_DESCRIPTION,
+      array: true,
+    }),
     scriptArgs: arg.passthrough({
       description:
         'Arguments after --, passed to the script as ... (all strings)',
@@ -226,14 +210,16 @@ export const playtestRunCommand = defineCommand<
   },
   handler: async (connection, args, targeting) => {
     const { scriptContent } = await resolveScriptContentAsync(args);
+    const inputs = await readInputFilesAsync(args.input);
 
     return playtestRunHandlerAsync(connection, {
       scriptContent,
       mode: args.mode ?? 'play',
       context: targeting.context ?? 'server',
       target: targeting.target,
-      timeout: args.timeout,
+      timeout: args.scriptTimeout,
       args: args.scriptArgs,
+      inputs,
     });
   },
 });

package/src/commands/playtest/start/start-playtest.lua

@@ -12,11 +12,18 @@
 	  client per player, each in its own Studio process.
 	- The playtest id, bridge port and edit instance id ride along as the test
 	  args. The playtest's DataModels cannot make the HTTP requests port
-	  discovery needs, so the plugin in each connects straight to that port,
-	  registers under the edit session's instance, and answers with the
-	  playtest id when asked which playtest it belongs to.
+	  discovery needs, so the plugin in each connects straight to that port and
+	  registers under the edit session's instance and the playtest id.
+	- With `bridge`, it first plants the studio-bridge client as a Script in
+	  ServerScriptService, for when Studio does not load user plugins into
+	  playtests. The playtest copies the edit DataModel, so the client starts in
+	  its server and connects as its server session. With
+	  `bridge.clientEntrySource` it also plants a LocalScript in
+	  StarterPlayerScripts, which every player's client runs and connects as its
+	  client session. The plants are removed once the playtest ends.
 
-	Request: `{ type: "startPlaytest", payload: { mode: "play" | "run", playtestId, bridgePort, instanceId, players? } }`
+	Request: `{ type: "startPlaytest", payload: { mode: "play" | "run", playtestId, bridgePort, instanceId, players?, bridge? } }`
+	`bridge`: `{ entrySource, clientEntrySource?, modules: { [name]: source }, precompiled: { source } }`
 	Response: `{ type: "playtestEnded", payload: { playtestId, success, error? } }`
 
 	@class StartPlaytestAction
@@ -62,7 +69,10 @@ function StartPlaytestAction.register(router: any, sendMessage: SendMessage?)
 				studioBridgeInstanceId = instanceId,
 				studioBridgePlayers = players,
 			}
-			task.spawn(StartPlaytestAction._runAsync, sendMessage, mode, testArgs, requestId, sessionId)
+			local planted = if payload.bridge ~= nil
+				then StartPlaytestAction._plant(router, payload.bridge, playtestId)
+				else {}
+			task.spawn(StartPlaytestAction._runAsync, sendMessage, mode, testArgs, requestId, sessionId, planted)
 
 			-- Replied through sendMessage, so the router must not reply as well
 			return nil
@@ -80,7 +90,8 @@ function StartPlaytestAction._runAsync(
 		studioBridgePlayers: number?,
 	},
 	requestId: string,
-	sessionId: string
+	sessionId: string,
+	planted: { Instance }
 )
 	local ok, err = pcall(function()
 		local studioTestService = game:GetService("StudioTestService") :: any
@@ -93,6 +104,10 @@ function StartPlaytestAction._runAsync(
 		end
 	end)
 
+	for _, instance in planted do
+		instance:Destroy()
+	end
+
 	sendMessage({
 		type = "playtestEnded",
 		sessionId = sessionId,
@@ -105,4 +120,88 @@ function StartPlaytestAction._runAsync(
 	})
 end
 
+--[[
+	Plants the studio-bridge client for the playtest `playtestId` and returns it.
+	Errors on a malformed `bridge`, or a precompiled source that does not
+	compile, before anything is planted: the planted client skips a source that
+	fails to load, which would hide the compile error.
+]]
+function StartPlaytestAction._plant(router: any, bridge: any, playtestId: string): { Instance }
+	if
+		type(bridge) ~= "table"
+		or type(bridge.entrySource) ~= "string"
+		or type(bridge.modules) ~= "table"
+		or type(bridge.precompiled) ~= "table"
+	then
+		error("Invalid bridge in startPlaytest request")
+	end
+
+	for _, source in bridge.precompiled do
+		local fn, compileErr
+		if type(router.Compile) == "function" then
+			fn, compileErr = router:Compile(source, "=exec")
+		else
+			fn, compileErr = (loadstring :: any)(source, "=exec")
+		end
+		if not fn then
+			error(`Script does not compile: {compileErr or "unknown error"}`, 0)
+		end
+	end
+
+	local entry = Instance.new("Script")
+	entry.Name = "StudioBridgePlaytest"
+	entry.Source = bridge.entrySource
+	entry:SetAttribute("PlaytestId", playtestId)
+
+	local shared = Instance.new("Folder")
+	shared.Name = "Shared"
+	shared.Parent = entry
+	for name, source in bridge.modules do
+		local moduleScript = Instance.new("ModuleScript")
+		moduleScript.Name = name
+		moduleScript.Source = source
+		moduleScript.Parent = shared
+	end
+
+	local precompiled = Instance.new("Folder")
+	precompiled.Name = "Precompiled"
+	precompiled.Parent = entry
+	for index, source in bridge.precompiled do
+		local moduleScript = Instance.new("ModuleScript")
+		moduleScript.Name = tostring(index)
+		moduleScript.Source = source
+		moduleScript.Parent = precompiled
+	end
+
+	local planted = { entry }
+	local clientEntry: LocalScript? = nil
+	if type(bridge.clientEntrySource) == "string" then
+		clientEntry = Instance.new("LocalScript")
+		local client = clientEntry :: LocalScript
+		client.Name = "StudioBridgePlaytestClient"
+		client.Source = bridge.clientEntrySource
+		client:SetAttribute("PlaytestId", playtestId)
+		shared:Clone().Parent = client
+		precompiled:Clone().Parent = client
+		table.insert(planted, client)
+	end
+
+	-- A bridge left from an earlier playtest would stand in for this one's
+	local serverScriptService = game:GetService("ServerScriptService")
+	local starterPlayerScripts = game:GetService("StarterPlayer"):WaitForChild("StarterPlayerScripts")
+	for _, container in { serverScriptService, starterPlayerScripts } do
+		for _, child in container:GetChildren() do
+			if child.Name == entry.Name or child.Name == "StudioBridgePlaytestClient" then
+				child:Destroy()
+			end
+		end
+	end
+
+	entry.Parent = serverScriptService
+	if clientEntry then
+		clientEntry.Parent = starterPlayerScripts
+	end
+	return planted
+end
+
 return StartPlaytestAction