@s2script/sdk 0.17.0 → 0.19.0

package/entity.d.ts

@@ -3,6 +3,8 @@
  * NO runtime code: the engine injects the implementation at load time.
  */
 
+import type { Vector } from "./math";
+
 /**
  * A host-liveness-gated handle to a live entity. `id` is a HOST-MINTED monotonic liveness
  * id — liveness is decided by the host's books (fed by engine create/delete notifications,
@@ -26,6 +28,13 @@ export declare class EntityRef {
   /** This entity's target (`CBaseEntity::m_target`) — the targetname of the entity it acts on, e.g. a
    *  `func_button`'s target entity. `""` if the entity has no target; `null` if the ref is stale/invalid. */
   readonly target: string | null;
+  /** This entity's world-space position (`CGameSceneNode::m_vecAbsOrigin`, reached via
+   *  `CBaseEntity::m_CBodyComponent` -> `CBodyComponent::m_pSceneNode`) — the same field CS2's
+   *  `Pawn.origin` exposes for player pawns, readable here on any entity (e.g. ranking candidate
+   *  `func_button`s by distance to a reference point). There is no meaningful "empty" position, so
+   *  unlike {@link EntityRef.name}/{@link EntityRef.target}, `null` means exactly one thing: could not
+   *  read (the ref is stale/invalid, or the field/chain didn't resolve) — never "no position". */
+  readonly origin: Vector | null;
   /** @internal The host mints refs; this is not part of the public API surface. */
   private constructor();
   /** True iff the host's books say live AND the identity slot still matches. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.17.0",
+  "version": "0.19.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",

package/ws.d.ts

@@ -13,17 +13,36 @@ export interface WebSocket {
   /** Close the connection. */
   close(): void;
 }
+/** Options for {@link WebSocket.connect}. */
+export interface WebSocketInit {
+  /**
+   * Extra headers to send on the opening handshake — the usual reason being a
+   * credential the server requires, e.g. `Authorization: Bearer <token>`.
+   *
+   * Headers the handshake owns are refused, and the connect rejects rather than
+   * silently dropping them: `Host`, `Connection`, `Upgrade`, any
+   * `Sec-WebSocket-*`, `Content-Length`, `Transfer-Encoding`. Values containing
+   * control characters are refused for the same reason.
+   */
+  headers?: Record<string, string>;
+}
+
 /** Entry point for opening WebSocket connections. */
 export declare const WebSocket: {
   /**
    * Connect to a WebSocket server (`wss://` for TLS) off the game thread.
    * @returns Resolves on the open handshake with the live {@link WebSocket} handle.
-   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error).
+   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error, or a refused header).
    * @example
    * import { WebSocket } from "@s2script/sdk/ws";
    * const ws = await WebSocket.connect("wss://ws.postman-echo.com/raw");
    * ws.onMessage((data) => { console.log("echo:", data); ws.close(); });
    * ws.send("hello-from-s2script");
+   * @example
+   * // A server that authenticates the handshake rather than the first frame.
+   * const ws = await WebSocket.connect("wss://maul.example/v2/ws", {
+   *   headers: { Authorization: `Bearer ${jwt}` },
+   * });
    */
-  connect(url: string): Promise<WebSocket>;
+  connect(url: string, init?: WebSocketInit): Promise<WebSocket>;
 };