@s2script/sdk 0.32.0 → 0.34.0

package/README.md

@@ -148,6 +148,43 @@ and records which member versions each release pinned. Make the workspace root t
 - A plugin already published **before** it joined a bundle must be republished at a new version
   from the bundle's workspace, so that its registry entry carries the claim.
 
+#### Several bundles in one workspace
+
+To combine several bundled monorepos (say a TTT and a Jailbreak, each its own bundle) into one
+parent repo with one `.changeset/` and one release, make the parent the only workspace and list
+each bundle's directory under `s2script.workspace.bundles`:
+
+```json
+{
+  "name": "@edge/servers",
+  "private": true,
+  "workspaces": ["ttt/plugins/*", "ttt/packages/*", "jb/plugins/*", "jb/packages/*"],
+  "s2script": {
+    "workspace": { "plugins": ["ttt/plugins/*", "jb/plugins/*"], "bundles": ["ttt", "jb"] }
+  }
+}
+```
+
+Each listed directory keeps a package.json that describes its bundle and nothing else:
+
+```json
+{
+  "name": "@edge/jailbreak",
+  "version": "1.0.0",
+  "s2script": { "kind": "bundle", "bundle": { "optional": ["@edge/jailbreak-gangperks"] } }
+}
+```
+
+- A bundle's **members** are the non-private plugins under its directory. A plugin under no listed
+  directory is published on its own, in no bundle.
+- The descriptor must **not** keep `s2script.workspace` (s2s would stop there and treat it as a
+  separate workspace) and must not itself be a workspace package. Drop the child's own
+  `workspaces`, lockfile and `.changeset/` too: npm and changesets only read the parent's.
+- **`s2s version`** at the parent bumps each bundle by the largest bump among its own members, and
+  `s2s deploy` publishes every bundle after its members. A member that fails to publish holds back
+  only its own bundle.
+- The root and a listed directory cannot both be bundles, and bundle directories cannot nest.
+
 The membership claim travels in the registry upload only — the `.s2sp` manifest the runtime loads
 is unchanged, and the runtime has no notion of bundles.
 

package/clients.d.ts

@@ -73,6 +73,94 @@ export declare class Client {
    * client.fakeCommand("say hello");   // as though the player typed it
    */
   fakeCommand(cmd: string): boolean;
+  /**
+   * Ask this client for its own value of a cvar (SourceMod `QueryClientConVar`). The client
+   * answers over the network, so this resolves on a later frame.
+   *
+   * Resolves `null` when no query was sent (a bot, a disconnected client, a name that is empty or
+   * contains whitespace, or a build where the reply hook is unavailable) or when the client
+   * disconnects or has not answered within 15 seconds. `value` is `""` unless `status` is `"ok"`.
+   *
+   * The value is what the client reports. A modified client can report anything, so treat it as a
+   * hint, not proof.
+   *
+   * @example
+   * const reply = await client.queryConVar("cl_interp_ratio");
+   * if (reply?.status === "ok") console.log(`${client.name}: ${reply.value}`);
+   */
+  queryConVar(name: string): Promise<ConVarQueryResult | null>;
+  /**
+   * Set this client's own copy of a replicated cvar without touching the server's value
+   * (SourceMod `SendConVarValue`). The client applies it only to cvars the server is allowed to
+   * replicate; the next server-side change to that cvar overwrites it. Booleans send `"1"`/`"0"`.
+   *
+   * Returns `false` for a bot, a disconnected client or an empty name.
+   *
+   * @example
+   * client.replicateConVar("sv_cheats", true);   // client-side only, e.g. for a practice HUD
+   */
+  replicateConVar(name: string, value: string | number | boolean): boolean;
+  /**
+   * One snapshot of this client's network counters, read from the engine's net channel
+   * (SourceMod `GetClientLatency`, `GetClientAvgLoss`, `GetClientAvgChoke`, `GetClientAvgData`,
+   * `GetClientAvgPackets`, `GetClientTime`, `IsClientTimingOut` and `GetClientDataRate` in one
+   * call). Read it again for fresh values; nothing in it updates on its own.
+   *
+   * Returns `null` for a bot (bots have no net channel), a disconnected client, or a server build
+   * whose net-channel layout this build has not been verified against.
+   *
+   * @example
+   * const stats = client.netStats();
+   * if (stats) console.log(`${client.name}: ${Math.round(stats.avgLatency * 1000)} ms, ` +
+   *   `${(stats.avgLoss.incoming * 100).toFixed(1)}% loss`);
+   */
+  netStats(): ClientNetStats | null;
+}
+/** A value measured separately for each direction, as seen from the server. */
+export interface NetFlowPair {
+  /** Server to client. */
+  outgoing: number;
+  /** Client to server. */
+  incoming: number;
+}
+/** What {@link Client.netStats} returns. Times are in seconds. */
+export interface ClientNetStats {
+  /** Average packet latency. */
+  avgLatency: number;
+  /** The engine's current round-trip estimate: more accurate than `avgLatency`, but jittery. */
+  engineLatency: number;
+  /** Average packet loss, from 0 to 1. */
+  avgLoss: NetFlowPair;
+  /** Average choke, from 0 to 1. */
+  avgChoke: NetFlowPair;
+  /** Average data rate in bytes per second. */
+  avgData: NetFlowPair;
+  /** Average packets per second. */
+  avgPackets: NetFlowPair;
+  /** Bytes sent or received since the client connected. */
+  totalData: NetFlowPair;
+  /** Packets sent or received since the client connected. */
+  totalPackets: NetFlowPair;
+  /** How long the client has been connected. */
+  timeConnected: number;
+  /** Time since the last packet from the client arrived. */
+  timeSinceLastReceived: number;
+  /** Whether the channel is about to time out. */
+  isTimingOut: boolean;
+  /** The send data rate the channel is allowed, in bytes per second. */
+  dataRate: number;
+}
+/**
+ * How a client answered {@link Client.queryConVar}: `"ok"` (value is set), `"notFound"` (no such
+ * cvar), `"notValid"` (the name is a command, not a cvar), `"protected"` (the client refused to
+ * reveal it), or `"unknown"` for a status this build does not recognise.
+ */
+export type ConVarQueryStatus = "ok" | "notFound" | "notValid" | "protected" | "unknown";
+/** The client's answer to {@link Client.queryConVar}. */
+export interface ConVarQueryResult {
+  status: ConVarQueryStatus;
+  /** The client's value, or `""` when `status` is not `"ok"`. */
+  value: string;
 }
 /**
  * Look up connected clients by slot or enumerate them all.