@s2script/sdk 0.31.0 → 0.32.0

package/entity.d.ts

@@ -88,6 +88,25 @@ export declare class EntityRef {
    *  at `finalOff` into a number[]. All in-core (raw pointers never cross); null if the root is stale or any hop
    *  is null. */
   readFloatsChain(ptrOffs: number[], finalOff: number, count: number): number[] | null;
+  /**
+   * Zero-allocation bulk read for per-tick hot paths: one liveness check, then every field `plan`
+   * names, written as numbers into your preallocated `out` starting at `outIndex` (default 0).
+   *
+   * `plan` is a flat run of entries `[hops, hop0..hopN-1, finalOff, kind, count]`: follow `hops`
+   * (0..8) pointer offsets, then read `count` (1..16) contiguous {@link GatherKind} elements at
+   * `finalOff`. An entry whose chain hits a null pointer writes `NaN` into its slots; the rest of
+   * the plan still runs. Build the plan once and reuse both arrays every tick.
+   *
+   * Returns the slot count written, `-1` when the ref is stale, or `-2` for a malformed plan or an
+   * `out` too short for the whole plan (nothing is written in either failure case).
+   * @example
+   * import { GatherKind } from "@s2script/sdk/entity";
+   * // two floats at +0x10, then one u8 behind the pointer at +0x30
+   * const plan = new Int32Array([0, 0x10, GatherKind.Float32, 2, 1, 0x30, 0x8, GatherKind.UInt8, 1]);
+   * const out = new Float64Array(3);
+   * if (ref.gather(plan, out) === 3) console.log(out[0], out[1], out[2]);
+   */
+  gather(plan: Int32Array, out: Float64Array, outIndex?: number): number;
   /** The `Vector` at `offset`, or null if the ref is stale. */
   readVector(offset: number): Vector | null;
   /** The `QAngle` at `offset`, or null if the ref is stale. */
@@ -212,6 +231,19 @@ export declare class EntityRef {
   acceptInput(input: string, value?: string, activator?: EntityRef, caller?: EntityRef, delay?: number): boolean;
 }
 
+/** Element kinds for {@link EntityRef.gather} plans — the scalar kinds a `Float64Array` holds exactly. */
+export declare const GatherKind: {
+  readonly Int32: number;
+  readonly Float32: number;
+  readonly Bool: number;
+  readonly Int8: number;
+  readonly Int16: number;
+  readonly UInt8: number;
+  readonly UInt16: number;
+  readonly UInt32: number;
+  readonly Float64: number;
+};
+
 /** Keyvalues for a CEntityKeyValues-configured spawn. Inference: string -> SetString,
  *  boolean -> SetBool, integer (int32) -> SetInt, other finite number -> SetFloat.
  *  Keys are case-insensitive (hashed via MurmurHash2LowerCase, the engine's own keying). */

package/files.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @s2script/files — sandboxed, off-thread file IO. Reads, writes (optionally gzip-compressed),
+ * lists and removes run on the shared async runtime's worker threads; the game thread only copies
+ * the payload and later receives the result on a frame drain. NO runtime code (injected at load).
+ *
+ * Every path is relative to this plugin's own root (`<data dir>/files/<plugin id>/`), `/`-separated,
+ * with segments of `[A-Za-z0-9._-]` (no `.`/`..`, at most 8 deep, 256 bytes). Anything else rejects
+ * with an `InvalidPath` error before any IO. One payload is capped by the async policy's
+ * `input_item_bytes` (8 MiB by default, measured after decompression) — see docs/ASYNC_LIMITS.md.
+ */
+
+/** Options for {@link Files.read} / {@link Files.readText}. */
+export interface FileReadOptions {
+  /** Decompress a gzip file (written with `{ gzip: true }`) off-thread. Default false. */
+  gzip?: boolean;
+}
+
+/** Options for {@link Files.write}. */
+export interface FileWriteOptions {
+  /** Compress with gzip off-thread before writing. Default false. Cannot combine with `append`. */
+  gzip?: boolean;
+  /**
+   * Append instead of replace. Default false: a replacing write is atomic (temp file + rename), so
+   * a crash or a concurrent read never observes a torn file. Appends are not atomic.
+   */
+  append?: boolean;
+}
+
+/**
+ * Off-thread file IO in this plugin's sandbox. Promises reject with `AsyncQueueFull`,
+ * `AsyncPayloadTooLarge`, `AsyncCancelled` (the plugin unloaded first) or a descriptive IO error.
+ * @example
+ * import { Files } from "@s2script/sdk/files";
+ * // persist a binary blob compressed, then read it back — neither step blocks the game thread
+ * await Files.write("replays/surf_utopia/wr.bin", frames, { gzip: true });
+ * const back = await Files.read("replays/surf_utopia/wr.bin", { gzip: true });
+ * if (back) console.log(`replay is ${back.length} bytes`);
+ */
+export declare const Files: {
+  /** Read a file as bytes (a fresh `Uint8Array`). Resolves `null` when the file does not exist. */
+  read(path: string, opts?: FileReadOptions): Promise<Uint8Array | null>;
+  /** Read a file as UTF-8 text (invalid sequences become U+FFFD). Resolves `null` when absent. */
+  readText(path: string, opts?: FileReadOptions): Promise<string | null>;
+  /**
+   * Write `data` (bytes, or a string as UTF-8), creating parent directories. The payload is copied
+   * synchronously, so the caller may reuse its buffer as soon as this returns.
+   */
+  write(path: string, data: Uint8Array | string, opts?: FileWriteOptions): Promise<void>;
+  /** Delete a file. Resolves `true` if it existed. */
+  remove(path: string): Promise<boolean>;
+  /**
+   * The sorted entry names in a directory (default: the plugin root). Subdirectories end in `/`.
+   * A missing directory resolves `[]`.
+   */
+  list(dir?: string): Promise<string[]>;
+};

package/index.d.ts

@@ -24,6 +24,7 @@ export * from "./damage";
 export * from "./db";
 export * from "./entity";
 export * from "./events";
+export * from "./files";
 export * from "./http";
 export * from "./interfaces";
 export * from "./math";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "license": "MIT OR Apache-2.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",
@@ -80,6 +80,9 @@
     "./http": {
       "types": "./http.d.ts"
     },
+    "./files": {
+      "types": "./files.d.ts"
+    },
     "./interfaces": {
       "types": "./interfaces.d.ts"
     },

package/server.d.ts

@@ -63,4 +63,15 @@ export declare const Server: {
   readonly mapName: string;
   /** The current map time in seconds (`GetGlobals()->curtime`). `0` if unavailable. */
   readonly gameTime: number;
+  /**
+   * The integer simulation tick (`GetGlobals()->tickcount`). Monotonic within a map and frozen
+   * while the game is paused — count ticks for anything timer-grade instead of differencing the
+   * float {@link Server.gameTime}. `0` if unavailable.
+   */
+  readonly tickCount: number;
+  /**
+   * Seconds per simulation tick, from the game's own server config (`0.015625` on a 64-tick
+   * server). Fixed for the server's lifetime. `0` only when the engine cannot report it.
+   */
+  readonly tickInterval: number;
 };