@s2script/sdk 0.30.2 → 0.31.0

package/entity.d.ts

@@ -3,7 +3,7 @@
  * NO runtime code: the engine injects the implementation at load time.
  */
 
-import type { Vector } from "./math";
+import type { Vector, QAngle } from "./math";
 
 /**
  * A host-liveness-gated handle to a live entity. `id` is a HOST-MINTED monotonic liveness
@@ -88,6 +88,14 @@ 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;
+  /** 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. */
+  readQAngle(offset: number): QAngle | null;
+  /** The `Vector` at the end of a pointer chain, or null on a stale ref or a null hop. */
+  readVectorChain(ptrOffs: number[], finalOff: number): Vector | null;
+  /** The `QAngle` at the end of a pointer chain, or null on a stale ref or a null hop. */
+  readQAngleChain(ptrOffs: number[], finalOff: number): QAngle | null;
   /** Follow a pointer chain (each an offset), then read a scalar at `finalOff`. null if the root is stale or any
    *  hop is null. `readHandleVia` decodes a handle field → a liveness-gated EntityRef; vectors use readFloatsChain. */
   readInt32Via(pathOffs: number[], finalOff: number): number | null;

package/ext/s2ext.h

@@ -0,0 +1,155 @@
+/* s2script native extension ABI, version 1.
+ *
+ * A native extension is a shared library in addons/s2script/extensions/ that adds natives to
+ * s2script without a core change, the way SourceMod extensions do. It never sees V8 or Rust:
+ * it registers plain C functions with a declared signature, and the host binds each one as a
+ * JavaScript function. A plugin that declares the extension in package.json imports it by name:
+ *
+ *     "s2script": { "extensions": { "@community/fastmath": "^0.1.0" } }
+ *     import { clamp } from "@community/fastmath";
+ *
+ * The rules:
+ *
+ * - Export two functions, s2ext_info and s2ext_init. The host calls s2ext_info first and refuses
+ *   the extension (with a named reason, while the server keeps running) if its ABI version is
+ *   not one the host speaks. Then it calls s2ext_init once, on the game thread, where the
+ *   extension registers its natives.
+ * - Every native's C function takes an opaque receiver first, then its declared arguments:
+ *       int32_t clamp(void* recv, int32_t v, int32_t lo, int32_t hi);
+ *   The receiver is meaningless to the extension; it is there because it is the shape V8's fast
+ *   API calls, which lets the host point optimised JavaScript straight at your function.
+ * - Natives run on the game thread. A native whose types are all numbers or booleans, and that
+ *   does not set S2N_CAN_FAIL, is a fast native: optimised code calls it directly, so it must not
+ *   block, must not call back into the host except log and schema_offset, and must not keep the
+ *   receiver.
+ * - Extensions load at server start and are never unloaded.
+ * - Structs only grow by appending fields, and each carries its size, so an older or newer peer
+ *   is detected without a version bump. A real break bumps S2EXT_ABI_VERSION.
+ * - Native code runs with full access, the same trust as a Metamod plugin. Engine access goes
+ *   through the host services below, never through engine tables directly.
+ *
+ * Supported platform for ABI 1: x86-64 Linux (the System V calling convention).
+ */
+#ifndef S2EXT_H
+#define S2EXT_H
+
+#include <stdint.h>
+#ifndef __cplusplus
+#include <stdbool.h>
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define S2EXT_ABI_VERSION 1u
+
+/* Argument and result types, and how each crosses.
+ *
+ *   type          C type            JavaScript         notes
+ *   S2T_VOID      void              undefined          result only
+ *   S2T_BOOL      bool              boolean            arguments convert as JS truthiness
+ *   S2T_I32       int32_t           number             arguments convert as ToInt32
+ *   S2T_U32       uint32_t          number             arguments convert as ToUint32
+ *   S2T_F32       float             number
+ *   S2T_F64       double            number
+ *   S2T_STRING    const char*       string             UTF-8, NUL-terminated. An argument is
+ *                                                      valid only during the call, and a string
+ *                                                      with an embedded NUL is refused. A result
+ *                                                      is copied at once and must stay valid until
+ *                                                      your next native returns; NULL gives null.
+ *   S2T_ENTITY    void*             EntityRef          argument only: the live entity's address,
+ *                                                      valid only during the call. A stale ref
+ *                                                      throws S2Error code "stale_entity" and
+ *                                                      your function is not called.
+ *
+ * Limits per native: at most 5 arguments of the integer class (bool, i32, u32, string, entity)
+ * and at most 8 of the float class (f32, f64), so every argument travels in a register.
+ * A native with a string or entity anywhere, or with S2N_CAN_FAIL, is called through the host's
+ * generic path rather than directly. That path costs roughly 100-150 ns per call, against
+ * under 10 ns for a fast native.
+ */
+typedef enum S2Type {
+  S2T_VOID = 0,
+  S2T_BOOL = 1,
+  S2T_I32 = 2,
+  S2T_U32 = 3,
+  S2T_F32 = 4,
+  S2T_F64 = 5,
+  S2T_STRING = 6,
+  S2T_ENTITY = 7
+} S2Type;
+
+/* Native flags. */
+enum {
+  /* The native may call host->fail. If it does, its result is discarded and the call throws an
+   * S2Error with the given code. */
+  S2N_CAN_FAIL = 1u
+};
+
+/* Log levels for S2HostApi.log. */
+enum { S2LOG_INFO = 0, S2LOG_WARN = 1, S2LOG_ERROR = 2 };
+
+/* What the host hands an extension. Grows only by appending fields: check `size` before using a
+ * field added after version 1. Every service takes the host pointer it was reached through. */
+typedef struct S2HostApi {
+  uint32_t size;
+  uint32_t abi;
+  /* The runtime's version, e.g. "0.4.0". */
+  const char* host_version;
+  /* One line in the server console, prefixed with the extension's name. */
+  void (*log)(const struct S2HostApi* host, int32_t level, const char* message);
+  /* A networked field's byte offset in its class (Source 2 schema), or -1 if either name is
+   * unknown. Cached by the host; safe from a fast native. Game thread only. */
+  int32_t (*schema_offset)(const struct S2HostApi* host, const char* class_name, const char* field);
+  /* Inside a native registered with S2N_CAN_FAIL: make this call throw S2Error. `code` is a short
+   * lowercase identifier ([a-z0-9_], up to 32 bytes), `message` is free text. Ignored, with a
+   * warning, anywhere else. */
+  void (*fail)(const struct S2HostApi* host, const char* code, const char* message);
+} S2HostApi;
+
+/* One native, as s2ext_init registers it. */
+typedef struct S2NativeDesc {
+  uint32_t size;               /* sizeof(S2NativeDesc) */
+  const char* name;            /* a JavaScript identifier, unique in this extension */
+  void* fn;                    /* ret fn(void* recv, args...) */
+  S2Type ret;
+  const S2Type* args;
+  uint32_t nargs;
+  uint32_t flags;              /* S2N_* */
+  const char* doc;             /* optional: a one-paragraph description, for the generated typings */
+  const char* const* arg_names;/* optional: nargs parameter names, for the generated typings */
+} S2NativeDesc;
+
+typedef struct S2Registrar S2Registrar;
+typedef struct S2RegistrarApi {
+  uint32_t size;
+  /* Register one native. Returns 0, or nonzero if the descriptor is refused; the host has then
+   * recorded why, and the extension is refused as a whole once s2ext_init returns. Valid only
+   * during s2ext_init. */
+  int32_t (*native)(S2Registrar* reg, const S2NativeDesc* desc);
+} S2RegistrarApi;
+
+typedef struct S2ExtInfo {
+  uint32_t size;               /* sizeof(S2ExtInfo) */
+  uint32_t abi;                /* S2EXT_ABI_VERSION */
+  const char* name;            /* the npm-style name plugins import, e.g. "@community/fastmath" */
+  const char* version;         /* semver, e.g. "0.1.0" */
+} S2ExtInfo;
+
+#if defined(_WIN32)
+#define S2EXT_EXPORT __declspec(dllexport)
+#else
+#define S2EXT_EXPORT __attribute__((visibility("default")))
+#endif
+
+/* Exported by the extension. s2ext_info must return a pointer that stays valid for the process.
+ * s2ext_init returns 0 on success; anything else refuses the extension. The host pointer stays
+ * valid for the process, so keep it for later service calls. */
+S2EXT_EXPORT const S2ExtInfo* s2ext_info(void);
+S2EXT_EXPORT int32_t s2ext_init(const S2HostApi* host, S2Registrar* reg, const S2RegistrarApi* api);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.30.2",
+  "version": "0.31.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",
@@ -34,7 +34,8 @@
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE",
-    "contracts"
+    "contracts",
+    "ext"
   ],
   "exports": {
     ".": {

package/unsafe.d.ts

@@ -10,6 +10,92 @@
  * (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md and ARCHITECTURE.md §2.0.7).
  */
 
+import type { EntityRef } from "./entity";
+import type { Vector, QAngle } from "./math";
+
+declare const ptrBrand: unique symbol;
+
+/**
+ * A raw address in the server process: what an engine call with a `ptr` return gives you, what
+ * {@link Ptr.from} makes from an entity, and what a `ptr` argument takes.
+ *
+ * UNSAFE. Nothing tracks what a `Ptr` points at. It answers typed reads and writes at a byte
+ * offset, follows pointer fields with {@link Ptr.deref}, and can be handed to any generated
+ * struct view, but a stale or wrong address reads garbage or crashes the server exactly as it
+ * would in a Metamod plugin. Only addresses that can never be valid (the null page, anything
+ * outside the user half of the address space) are refused, with an `S2Error` whose `code` is
+ * `"bad_address"`. Prefer entity handles and their schema fields, which are checked on every
+ * access; reach for `Ptr` when an engine structure has no other door.
+ *
+ * Do not keep a `Ptr` past the call or event that produced it unless you know the lifetime of the
+ * memory behind it.
+ *
+ * @example
+ * import { Ptr } from "@s2script/sdk/unsafe";
+ * const p = Ptr.from(pawn);              // the entity's address, or null when it is stale
+ * if (p) console.log(p.readInt32(healthOffset));
+ */
+export declare class Ptr {
+  private constructor();
+  private readonly [ptrBrand]: true;
+  /** The null pointer. Reads through it throw. */
+  static readonly NULL: Ptr;
+  /** A `Ptr` for an address, or an entity's current address (null once the entity is gone). */
+  static from(address: number | Ptr): Ptr;
+  static from(entity: EntityRef): Ptr | null;
+  /** The address as a number. Exact: every user-space address is below 2^47. */
+  readonly address: number;
+  isNull(): boolean;
+  /** This address plus `bytes`. */
+  add(bytes: number): Ptr;
+  equals(other: Ptr): boolean;
+  /** `0x…` */
+  toString(): string;
+  /** Hand this address to a view factory, such as a game package's struct view. */
+  as<T>(view: (ptr: Ptr) => T): T;
+  /** The pointer stored at `offset` (a pointer field), as a `Ptr`. `Ptr.NULL` when it holds null. */
+  deref(offset?: number): Ptr;
+  readPtr(offset: number): Ptr;
+  writePtr(offset: number, value: Ptr): true;
+  readInt8(offset: number): number;
+  readUInt8(offset: number): number;
+  readInt16(offset: number): number;
+  readUInt16(offset: number): number;
+  readInt32(offset: number): number;
+  readUInt32(offset: number): number;
+  readFloat32(offset: number): number;
+  readFloat64(offset: number): number;
+  readBool(offset: number): boolean;
+  /** A 64-bit integer, as a decimal string (a JS number cannot hold every value). */
+  readInt64(offset: number): string;
+  readUInt64(offset: number): string;
+  writeInt8(offset: number, value: number): true;
+  writeUInt8(offset: number, value: number): true;
+  writeInt16(offset: number, value: number): true;
+  writeUInt16(offset: number, value: number): true;
+  writeInt32(offset: number, value: number): true;
+  writeUInt32(offset: number, value: number): true;
+  writeFloat32(offset: number, value: number): true;
+  writeFloat64(offset: number, value: number): true;
+  writeBool(offset: number, value: boolean): true;
+  /** The NUL-terminated string at `offset`, reading at most `maxLen` bytes. */
+  readString(offset: number, maxLen: number): string;
+  /** Write `value` into a `maxLen`-byte buffer, truncated so it always ends in a NUL. */
+  writeString(offset: number, maxLen: number, value: string): boolean;
+  /** `count` consecutive 32-bit floats (a vector, an angle). */
+  readFloats(offset: number, count: number): number[];
+  /** The `Vector` at `offset`. */
+  readVector(offset: number): Vector;
+  /** The `QAngle` at `offset`. */
+  readQAngle(offset: number): QAngle;
+  /** The `Vector` at the end of a pointer chain, or null on a null hop. */
+  readVectorChain(ptrOffs: number[], finalOff: number): Vector | null;
+  /** The `QAngle` at the end of a pointer chain, or null on a null hop. */
+  readQAngleChain(ptrOffs: number[], finalOff: number): QAngle | null;
+  /** A `CEntityHandle` field, resolved through the entity books: null when it names no live entity. */
+  readHandle(offset: number): EntityRef | null;
+}
+
 /**
  * The calls this plugin declares. The base interface is EMPTY — `s2s build` generates
  * `.s2script/gamedata.d.ts`, which augments this from your gamedata's `calls` section.
@@ -59,8 +145,64 @@ export interface FunctionSubscription extends Disposable {
  * const onFoo = Engine.hook("onFoo");
  * if (onFoo) onFoo((view) => { view.reason = 0; });
  */
+/** A target validator, as in `gamedata/functions.jsonc`. */
+export interface FunctionValidator {
+  prologue?: string;
+  'string-xref'?: { at: number; dispOff: number; instrLen: number; expect: string };
+  'vtable-member'?: string;
+}
+/** A function located by byte signature. */
+export interface SignatureTarget {
+  kind?: 'signature';
+  module: string;
+  pattern: string;
+  validate: FunctionValidator;
+  targetValidate?: FunctionValidator;
+}
+/** A function located by vtable slot. */
+export interface VirtualTarget {
+  kind?: 'virtual';
+  module: string;
+  class: string;
+  index: number;
+  validate: FunctionValidator;
+}
+/** A parameter or return type. `ptr` is a raw address, a {@link Ptr} (or null) in JavaScript. */
+export type FunctionValueType = 'bool' | 'i32' | 'u32' | 'i64' | 'u64' | 'f32' | 'f64' | 'entity' | 'entity?' | 'string' | 'vector' | 'ptr';
+/** One engine function, written exactly as an entry of `gamedata/functions.jsonc`. */
+export interface FunctionDeclaration<T> {
+  target: T | { ref: string };
+  receiver?: { type: 'none' | 'entity' };
+  parameters?: readonly { name: string; type: FunctionValueType; ownership?: 'callee-borrowed' | 'callee-retained' | 'native-observed'; mutable?: 'pre' }[];
+  returns?: FunctionValueType | 'void' | { type: 'string' | 'vector'; ownership: 'caller-borrowed' | 'native-observed' };
+  surfaces?: readonly ('call' | 'pre' | 'post')[];
+  suppression?: 'generic' | 'none';
+  requirement?: 'optional' | 'required';
+  resolve?: 'direct' | 'ctor-body-xref' | 'lea-disp' | 'validated-call';
+}
+
 export declare const Engine: {
   function<K extends keyof EngineFunctions>(name: K): EngineFunctions[K];
+  /**
+   * Declare an engine function inline, by byte signature, and get its binding: the same as
+   * writing the declaration in `gamedata/functions.jsonc` and calling {@link Engine.function}.
+   *
+   * `s2s build` copies the declaration into the plugin's manifest, so it is validated, listed and
+   * checked after game updates like any other. That is why both arguments must be literals; a
+   * computed declaration fails the build. The binding's types come from the build, so run it once
+   * after adding a declaration.
+   *
+   * @example
+   * const ignite = Engine.fromSignature("ignite", {
+   *   target: { module: "libserver.so", pattern: "55 48 89 E5 ...", validate: { prologue: "55 48 89 E5" } },
+   *   receiver: { type: "entity" },
+   *   parameters: [{ name: "seconds", type: "f32" }],
+   *   surfaces: ["call"],
+   * });
+   */
+  fromSignature<K extends keyof EngineFunctions>(name: K, declaration: FunctionDeclaration<SignatureTarget>): EngineFunctions[K];
+  /** {@link Engine.fromSignature} for a function located by vtable slot. */
+  fromVirtual<K extends keyof EngineFunctions>(name: K, declaration: FunctionDeclaration<VirtualTarget>): EngineFunctions[K];
   /**
    * The declared call, or `null` when its descriptor failed a load-time gate (signature miss,
    * validator rejection, slot outside `.text`, missing platform entry, or the plugin is not