@s2script/sdk 0.2.0 → 0.4.0

package/clients.d.ts

@@ -27,6 +27,13 @@ export declare class Client {
   readonly ip: string;
   /** Show `reason` (chat + console) once the client is in-game, then kick after `delaySeconds` (default 5). Intended to be called from a Clients.onConnect handler. */
   kickWithReason(reason: string, delaySeconds?: number): void;
+  /**
+   * Server-side voice mute: while true, this client's OUTGOING voice is silenced for every receiver.
+   * Framework state (not an engine field): cleared automatically on disconnect, persists across map
+   * changes while connected. If the voice descriptor is degraded (hook/validation failure — named
+   * reason in the server log), setting is an inert no-op and reads stay false.
+   */
+  voiceMuted: boolean;
 }
 export declare const Clients: {
   /** Fires when a client connects (all clients incl. bots; carries name/xuid). May be async. */
@@ -41,6 +48,12 @@ export declare const Clients: {
   onDisconnect(handler: (client: Client) => void): void;
   /** Fires when a client's settings (name/cvars) change. */
   onSettingsChanged(handler: (client: Client) => void): void;
+  /**
+   * Fires while a client transmits voice. Throttled to at most one dispatch per client per second;
+   * the FIRST packet of a transmission always fires (a lazy mute-on-talk lands immediately).
+   * Handlers should be idempotent. Never fires for bots.
+   */
+  onVoice(handler: (client: Client) => void): void;
   /** The client in `slot`, or null if the slot is empty. */
   fromSlot(slot: number): Client | null;
   /** Every currently-connected client. */

package/config.d.ts

@@ -1,5 +1,7 @@
 /** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
-export type Config = Record<string, string | number | boolean>;
+/** A materialized config value: a scalar, or a nested section object of further values. */
+export type ConfigValue = string | number | boolean | { [k: string]: ConfigValue };
+export type Config = Record<string, ConfigValue>;
 export declare const config: {
   getString(key: string): string;
   getInt(key: string): number;

package/dist/cli.js

@@ -89,6 +89,9 @@ function typecheckPlugin(pluginDir, opts) {
   const options = {
     strict: true,
     noEmit: true,
+    // Accept explicit `.ts` import extensions (node type-stripping requires them for source-to-source
+    // imports; esbuild strips them at bundle time). Backward-compatible — extensionless imports still resolve.
+    allowImportingTsExtensions: true,
     moduleResolution: ts.ModuleResolutionKind.Bundler,
     module: ts.ModuleKind.ESNext,
     target: ts.ScriptTarget.ES2020,
@@ -139,25 +142,100 @@ function formatDiagnostics(diags) {
 }
 
 // src/config-validate.ts
+function isDeclType(t) {
+  return t === "string" || t === "int" || t === "float" || t === "bool";
+}
+function matchesType(v, t) {
+  switch (t) {
+    case "string":
+      return typeof v === "string";
+    case "int":
+      return typeof v === "number" && Number.isInteger(v);
+    case "float":
+      return typeof v === "number";
+    case "bool":
+      return typeof v === "boolean";
+  }
+}
 function validateConfigBlock(config) {
   const errs = [];
   if (config == null) return errs;
-  if (typeof config !== "object" || Array.isArray(config)) return ["s2script.config must be an object"];
-  for (const [key, raw] of Object.entries(config)) {
-    if (typeof raw !== "object" || raw === null) {
-      errs.push(`config '${key}': must be { type, default }`);
+  validateEntries(config, "", errs);
+  return errs;
+}
+function validateEntries(node, prefix, errs) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    errs.push(`${prefix ? `config '${prefix}'` : "s2script.config"} must be an object`);
+    return;
+  }
+  for (const [key, raw] of Object.entries(node)) {
+    const full = prefix ? `${prefix}.${key}` : key;
+    if (key.includes(".")) {
+      errs.push(`config '${full}': key must not contain '.' (dotted names are reserved for section access)`);
       continue;
     }
-    const decl = raw;
-    const t = decl.type, d = decl.default;
-    if (t !== "string" && t !== "int" && t !== "float" && t !== "bool") {
-      errs.push(`config '${key}': unknown type ${JSON.stringify(t)} (want string|int|float|bool)`);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      errs.push(`config '${full}': must be a declaration { type, default } or a section object`);
       continue;
     }
-    const ok = t === "string" && typeof d === "string" || t === "int" && typeof d === "number" && Number.isInteger(d) || t === "float" && typeof d === "number" || t === "bool" && typeof d === "boolean";
-    if (!ok) errs.push(`config '${key}': default ${JSON.stringify(d)} does not match type '${t}'`);
+    const obj = raw;
+    if (typeof obj.type === "string") {
+      validateDecl(full, obj, obj.type, errs);
+    } else {
+      validateEntries(obj, full, errs);
+    }
   }
-  return errs;
+}
+function validateDecl(full, decl, typeStr, errs) {
+  if (!isDeclType(typeStr)) {
+    errs.push(`config '${full}': unknown type ${JSON.stringify(typeStr)} (want string|int|float|bool)`);
+    return;
+  }
+  const t = typeStr;
+  if (!("default" in decl)) {
+    errs.push(`config '${full}': missing 'default'`);
+  } else if (!matchesType(decl.default, t)) {
+    errs.push(`config '${full}': default ${JSON.stringify(decl.default)} does not match type '${t}'`);
+  }
+  const hasMin = decl.min !== void 0;
+  const hasMax = decl.max !== void 0;
+  const hasEnum = decl.enum !== void 0;
+  if (hasEnum && (hasMin || hasMax)) {
+    errs.push(`config '${full}': 'enum' is mutually exclusive with 'min'/'max'`);
+  }
+  if (hasMin || hasMax) {
+    if (t !== "int" && t !== "float") {
+      errs.push(`config '${full}': 'min'/'max' apply to int|float only (type '${t}')`);
+    }
+    if (hasMin && typeof decl.min !== "number") errs.push(`config '${full}': 'min' must be a number`);
+    if (hasMax && typeof decl.max !== "number") errs.push(`config '${full}': 'max' must be a number`);
+    if (typeof decl.min === "number" && typeof decl.max === "number" && decl.min > decl.max) {
+      errs.push(`config '${full}': 'min' (${decl.min}) exceeds 'max' (${decl.max})`);
+    }
+    if (typeof decl.default === "number") {
+      if (typeof decl.min === "number" && decl.default < decl.min) errs.push(`config '${full}': default ${decl.default} is below min ${decl.min}`);
+      if (typeof decl.max === "number" && decl.default > decl.max) errs.push(`config '${full}': default ${decl.default} is above max ${decl.max}`);
+    }
+  }
+  if (hasEnum) {
+    if (t !== "string" && t !== "int") {
+      errs.push(`config '${full}': 'enum' applies to string|int only (type '${t}')`);
+    }
+    if (!Array.isArray(decl.enum) || decl.enum.length === 0) {
+      errs.push(`config '${full}': 'enum' must be a non-empty array`);
+    } else {
+      for (const e of decl.enum) {
+        if (!matchesType(e, t)) errs.push(`config '${full}': enum value ${JSON.stringify(e)} does not match type '${t}'`);
+      }
+      if ("default" in decl && matchesType(decl.default, t) && !decl.enum.some((e) => e === decl.default)) {
+        errs.push(`config '${full}': default ${JSON.stringify(decl.default)} is not one of enum`);
+      }
+    }
+  }
+  if (decl.sensitive !== void 0 && typeof decl.sensitive !== "boolean") errs.push(`config '${full}': 'sensitive' must be a boolean`);
+  if (decl.group !== void 0 && typeof decl.group !== "string") errs.push(`config '${full}': 'group' must be a string`);
+  if (decl.label !== void 0 && typeof decl.label !== "string") errs.push(`config '${full}': 'label' must be a string`);
+  if (decl.description !== void 0 && typeof decl.description !== "string") errs.push(`config '${full}': 'description' must be a string`);
 }
 
 // src/publish-gate.ts
@@ -1176,13 +1254,85 @@ async function createPlugin(opts = {}) {
   };
 }
 
+// src/config/gen.ts
+import AdmZip2 from "adm-zip";
+import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join9 } from "node:path";
+
+// src/config/config-path.ts
+function configFileName(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_") + ".json";
+}
+
+// src/config/gen.ts
+function isDecl(v) {
+  return typeof v.type === "string";
+}
+function generateDefaultJsonc(config) {
+  return "{\n" + genEntries(config, 1) + "}\n";
+}
+function genEntries(entries, indent) {
+  const pad = "  ".repeat(indent);
+  const keys = Object.keys(entries).filter((k) => !k.includes(".")).sort();
+  let out = "";
+  keys.forEach((key, i) => {
+    const comma = i + 1 < keys.length ? "," : "";
+    const raw = entries[key];
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
+    const obj = raw;
+    if (isDecl(obj)) {
+      const desc = typeof obj.description === "string" ? obj.description : "";
+      out += `${pad}// ${String(obj.type)}${desc ? ` \u2014 ${desc}` : ""}
+`;
+      out += `${pad}${JSON.stringify(key)}: ${JSON.stringify(obj.default)}${comma}
+`;
+    } else {
+      out += `${pad}${JSON.stringify(key)}: {
+`;
+      out += genEntries(obj, indent + 1);
+      out += `${pad}}${comma}
+`;
+    }
+  });
+  return out;
+}
+function genConfigFromManifest(manifest, outDir) {
+  const config = manifest.config;
+  if (config == null || typeof config !== "object" || Array.isArray(config) || Object.keys(config).length === 0) {
+    return null;
+  }
+  const id = typeof manifest.id === "string" ? manifest.id : "";
+  if (!id) throw new Error("config gen: manifest declares config but has no id");
+  mkdirSync3(outDir, { recursive: true });
+  const path = join9(outDir, configFileName(id));
+  writeFileSync6(path, generateDefaultJsonc(config));
+  return path;
+}
+function genConfigForS2sp(s2spPath, outDir) {
+  const zip = new AdmZip2(s2spPath);
+  const entry = zip.getEntry("manifest.json");
+  if (!entry) throw new Error(`config gen: ${s2spPath} has no manifest.json`);
+  const manifest = JSON.parse(entry.getData().toString("utf8"));
+  return genConfigFromManifest(manifest, outDir);
+}
+function runConfigGen(s2sps, outDir) {
+  const written = [];
+  const skipped = [];
+  for (const p of s2sps) {
+    const r = genConfigForS2sp(p, outDir);
+    if (r) written.push(r);
+    else skipped.push(p);
+  }
+  return { written, skipped };
+}
+
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname3, join as join9, resolve as resolve6 } from "node:path";
+import { dirname as dirname3, join as join10, resolve as resolve6 } from "node:path";
 var argv = process.argv.slice(2);
 var command = argv[0];
 function repoRootFromCli() {
-  return join9(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join10(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 function parseFlag(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`));
@@ -1194,6 +1344,20 @@ function parseFlag(args, name) {
 function hasFlag(args, name) {
   return args.includes(name);
 }
+function positionals(args, flagsWithValue) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const name = a.split("=")[0];
+      if (flagsWithValue.includes(name) && !a.includes("=")) i++;
+      continue;
+    }
+    if (a.startsWith("-")) continue;
+    out.push(a);
+  }
+  return out;
+}
 if (command === "gen-schema") {
   const repoRoot = repoRootFromCli();
   const check = argv[1] === "--check";
@@ -1257,6 +1421,22 @@ if (command === "gen-schema") {
     console.error(String(e instanceof Error ? e.message : e));
     process.exit(1);
   }
+} else if (command === "config" && argv[1] === "gen") {
+  const args = argv.slice(2);
+  const outDir = parseFlag(args, "--out") ?? process.cwd();
+  const s2sps = positionals(args, ["--out"]);
+  if (s2sps.length === 0) {
+    console.error("Usage: s2s config gen <plugin.s2sp...> --out <dir>");
+    process.exit(1);
+  }
+  try {
+    const { written, skipped } = runConfigGen(s2sps, outDir);
+    for (const w of written) console.log(`config gen: wrote ${w}`);
+    for (const s of skipped) console.log(`config gen: ${s} declares no config \u2014 skipped`);
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
 } else if (command === "build" && argv[1]) {
   const args = argv.slice(1);
   const dir = args.find((a) => !a.startsWith("-"));
@@ -1274,7 +1454,7 @@ if (command === "gen-schema") {
   }
 } else {
   console.error(
-    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]"
+    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]"
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",
   "bin": {
@@ -103,6 +103,9 @@
     "./translations": {
       "types": "./translations.d.ts"
     },
+    "./transmit": {
+      "types": "./transmit.d.ts"
+    },
     "./usercmd": {
       "types": "./usercmd.d.ts"
     },

package/transmit.d.ts

@@ -0,0 +1,32 @@
+/** @s2script/transmit — per-client entity visibility filtering (Source2 CheckTransmit).
+ *  Declarative rules: a plugin says "this entity is visible only to these viewer slots" and the
+ *  engine-side hook enforces it every snapshot — zero JS runs in the per-client hot path. */
+import type { EntityRef } from "./entity";
+
+export interface TransmitStats {
+  /** CheckTransmit invocations observed since load/reset. */
+  snapshots: number;
+  /** Live rule entries in the native table. */
+  entries: number;
+  /** Total transmit bits cleared since load/reset. */
+  bitsCleared: number;
+  /** Nanoseconds spent in the post-hook, last invocation. */
+  nsLast: number;
+  /** Worst single invocation (ns) since load/reset. */
+  nsMax: number;
+}
+
+export declare const Transmit: {
+  /** Replace this plugin's visibility rule for `entity`: it is transmitted ONLY to the given viewer
+   *  slots (an empty array = hidden from everyone). Multiple plugins AND-merge — an entity reaches a
+   *  viewer only if every plugin holding a rule on it allows that viewer. Returns false if the ref is
+   *  stale or the capability is unavailable/disabled. Throws RangeError on a slot outside [0, 64). */
+  setVisibleTo(entity: EntityRef, viewers: readonly number[]): boolean;
+  /** Remove this plugin's rule for `entity` (visible to all again, as far as this plugin is
+   *  concerned). Returns false if the ref is stale or the capability is unavailable. */
+  reset(entity: EntityRef): boolean;
+  /** Remove all of this plugin's rules. */
+  resetAll(): void;
+  /** Hot-path counters for measurement/debugging. */
+  stats(): TransmitStats;
+};

package/usermessages.d.ts

@@ -1,3 +1,5 @@
+import type { HookResultValue } from "./events";
+
 /** A general protobuf user-message builder. Build then send in one synchronous burst. */
 export class UserMessage {
   constructor(name: string);
@@ -12,3 +14,36 @@ export class UserMessage {
   /** Broadcast to all connected non-bot clients. */
   sendAll(): boolean;
 }
+
+// --- UserMessage interception (usermsg-hook slice) ---
+
+/** A BLOCK-SCOPED view of an intercepted outbound user message — valid only during a
+ *  UserMessages.onPre handler; across an await (or stashed) all reads return null/[]/"". */
+export interface UserMessageView {
+  /** Canonical unscoped message name (e.g. "CMsgTEFireBullets"). */
+  readonly name: string;
+  /** Numeric network-message id (e.g. 452). */
+  readonly id: number;
+  /** Recipient slots (0-based) this post targets; a broadcast decodes to all live slots. Read-only in v1. */
+  readonly recipients: number[];
+  /** protobuf TextFormat dump — the documented FALLBACK for unmapped messages only; prefer typed reads. */
+  readonly debugString: string;
+  hasField(path: string): boolean;
+  /** Scalar int read (int32/uint32/fixed32/enum; bool as 0/1). Dotted nested paths supported
+   *  ("origin.x" walks sub-messages). null = no such field / repeated / no current message. */
+  readInt(path: string): number | null;
+  readFloat(path: string): number | null;
+  readBool(path: string): boolean | null;
+  readString(path: string): string | null;
+}
+
+export declare const UserMessages: {
+  /** Pre-hook an outbound user message by unscoped name (partial match, SayText2-style; the view
+   *  carries the canonical name). Runs SYNCHRONOUSLY before delivery. Return >= HookResult.Handled
+   *  to SUPPRESS the send for every recipient; Continue/undefined passes it through. THROWS at
+   *  subscribe time on an unresolvable name or a degraded intercept descriptor. */
+  onPre(name: string, handler: (msg: UserMessageView) => HookResultValue | void): void;
+  /** Removes ALL of the calling plugin's handlers for this name (mux off semantics — handler
+   *  identity not compared, matching Events.off). */
+  off(name: string, handler?: (msg: UserMessageView) => HookResultValue | void): void;
+};