@s2script/sdk 0.0.1 → 0.3.0

package/admin.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @s2script/admin — engine-generic admin flag model + cache API.
+ *
+ * Resolved at runtime via `globalThis.__s2pkg_admin`; no game-specific symbols.
+ * Import: `import { ADMFLAG, Admin } from "./admin";`
+ */
+
+/** SourceMod-parity admin flag bitmask constants (SM bit values). */
+export declare const ADMFLAG: {
+  readonly RESERVATION: number;
+  readonly GENERIC:     number;
+  readonly KICK:        number;
+  readonly BAN:         number;
+  readonly UNBAN:       number;
+  readonly SLAY:        number;
+  readonly CHANGEMAP:   number;
+  readonly CONVARS:     number;
+  readonly CONFIG:      number;
+  readonly CHAT:        number;
+  readonly VOTE:        number;
+  readonly PASSWORD:    number;
+  readonly RCON:        number;
+  readonly CHEATS:      number;
+  readonly ROOT:        number;
+};
+
+/** An admin entry: their SteamID64, their combined flag mask, and a helper to check flags. */
+export interface AdminInfo {
+  readonly steamId: string;
+  readonly flags:   number;
+  /** Immunity level (0 = none). A lower-immunity admin cannot target a higher one. */
+  readonly immunity: number;
+  /** Names of the groups this admin belongs to. */
+  readonly groups:  readonly string[];
+  /** True if `required` flags are all set, OR if this admin has ROOT (root ⇒ all). */
+  hasFlags(required: number): boolean;
+}
+
+/** A resolved admin group (from admin_groups.json): its flags, immunity, and per-command overrides. */
+export interface AdminGroup {
+  readonly name: string;
+  readonly flags: number;
+  readonly immunity: number;
+  readonly overrides: Readonly<Record<string, { public: boolean; mask: number }>>;
+}
+
+/** The admin API: add/remove runtime admins, look up by SteamID or slot, reload from file. */
+export declare const Admin: {
+  /** Add (or overwrite) a runtime admin. Not persisted to admins.json. */
+  add(steamId: string, flags: number, immunity?: number): void;
+  /** Remove a runtime admin. */
+  remove(steamId: string): void;
+  /** Get an admin by SteamID64 (union of file + runtime tiers), or null if not an admin. */
+  get(steamId: string): AdminInfo | null;
+  /** Get an admin by player slot (resolves SteamID via engine), or null. */
+  forSlot(slot: number): AdminInfo | null;
+  /** True if `callerSlot` may act on `targetSlot` (console = infinite; blocked iff target immunity > caller). */
+  canTarget(callerSlot: number, targetSlot: number): boolean;
+  /** A resolved group by name (from admin_groups.json), or null. */
+  getGroup(name: string): AdminGroup | null;
+  /** Re-read admins.json into the file tier (clears old file-tier entries first). */
+  reload(): void;
+};

package/bans.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @s2script/bans — engine-generic SteamID64 ban store + bans.json persistence.
+ *
+ * Resolved at runtime via `globalThis.__s2pkg_bans`; no game-specific symbols.
+ * Import: `import { Bans } from "./bans";`
+ *
+ * The store is host-global in core, populated from `addons/s2script/configs/bans.json` via the config
+ * bridge. Enforcement is JS-driven: a ban plugin (e.g. @s2script/basebans) registers a
+ * `Clients.onConnect` handler that looks a connecting SteamID64 up here and, if banned, shows the
+ * reason then kicks (`Client.kickWithReason`) — a banned player is admitted, shown their reason, and
+ * kicked, not instant-rejected. A 3rd-party ban system registers its own onConnect against its own store.
+ */
+
+/** A ban entry's value: expiry + reason. `until === 0` = permanent, else unix-second expiry. */
+export interface BanInfo {
+  /** Unix-second expiry, or 0 for a permanent ban. */
+  until: number;
+  /** The ban reason (may be empty). */
+  reason: string;
+}
+
+/** A ban entry as listed by `Bans.list()`: the SteamID64 plus its value. */
+export interface BanEntry {
+  /** The banned SteamID64 (decimal string). */
+  steamid: string;
+  /** Unix-second expiry, or 0 for a permanent ban. */
+  until: number;
+  /** The ban reason (may be empty). */
+  reason: string;
+}
+
+/** The ban API: add/remove bans, look up by SteamID64, list, and reload from bans.json. */
+export declare const Bans: {
+  /** Add (or overwrite) a ban and persist it to bans.json. `minutes <= 0` = permanent. */
+  add(steamId: string, minutes: number, reason?: string): void;
+  /** Remove a ban and persist. Returns whether the SteamID64 was banned. */
+  remove(steamId: string): boolean;
+  /** Get a ban by SteamID64, or null if not banned. */
+  get(steamId: string): BanInfo | null;
+  /** List every ban currently in the cache. */
+  list(): BanEntry[];
+  /** Re-read bans.json into the cache (clears the old cache first). */
+  reload(): void;
+};

package/chat.d.ts

@@ -0,0 +1,22 @@
+/** @s2script/chat — print messages to player chat. NO runtime code (injected at load). */
+import type { HookResultValue } from "./events";
+
+export declare const Chat: {
+  /**
+   * An opaque prefix prepended to every chat message (NOT rcon/console replies). Color is content the
+   * caller owns (SourceMod-parity), so the engine-generic layer never picks one. A game/plugin sets this
+   * to a color control byte — e.g. `Chat.color = ChatColors.Green` from `@s2script/cs2`. `""` = send raw
+   * (CS2 needs a leading control byte for chat to render). A message may also embed its own colors.
+   */
+  color: string;
+  /** Print to the chat of the client in `slot` (0-based). */
+  toSlot(slot: number, message: string): void;
+  /** Print to every live player's chat. */
+  toAll(message: string): void;
+  /**
+   * Subscribe to raw player chat. The handler receives the speaker's `slot`, the raw `text`, and
+   * `teamonly`. Returning `>= HookResult.Handled` (2) suppresses the broadcast (SM-parity). Non-command
+   * chat lines are delivered here; the `@`-trigger layer subscribes through this.
+   */
+  onMessage(handler: (slot: number, text: string, teamonly: boolean) => HookResultValue | void): void;
+};

package/clients.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @s2script/clients — engine-generic client handle + lifecycle events.
+ * Resolved at runtime via globalThis.__s2pkg_clients. Import: import { Client, Clients } from "./clients";
+ */
+/** A connected client, identified by its 0-based slot (CPlayerSlot). Slot-backed; getters read live. */
+export declare class Client {
+  readonly slot: number;
+  /** True while a client occupies this slot. */
+  isValid(): boolean;
+  /** Decimal SteamID64; "0" for a bot or an unauthenticated client. */
+  readonly steamId: string;
+  /** Display name; "" if unavailable. */
+  readonly name: string;
+  /** Engine user-id; -1 if none. */
+  readonly userId: number;
+  /** Tracked signon state: 0 = none/disconnected, 2 = connected, 5 = spawned, 6 = full (in-game); -1 if the slot is out of range. */
+  readonly signonState: number;
+  /** True for a fake client (bot) — derived from steamId === "0". */
+  readonly isBot: boolean;
+  /** Disconnect this client. */
+  kick(reason?: string): void;
+  /** Send a chat (SayText2) line to this client. */
+  chat(message: string): void;
+  /** Print one line to this client's developer console (skipped for bots). */
+  print(message: string): void;
+  /** This client's IP address (":port" stripped); "" for a bot. */
+  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. */
+  onConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** Fires when a client is put in the server (controller/pawn context now exists). May be async. */
+  onPutInServer(handler: (client: Client) => void | Promise<void>): void;
+  /** Fires when a client goes active (spawned / in-game). May be async. */
+  onActive(handler: (client: Client) => void | Promise<void>): void;
+  /** Fires when a client is fully connected. May be async. */
+  onFullyConnect(handler: (client: Client) => void | Promise<void>): void;
+  /** Fires when a client disconnects. Only `.slot` is guaranteed live here — capture identity earlier if needed. */
+  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. */
+  all(): Client[];
+};

package/commands.d.ts

@@ -0,0 +1,51 @@
+/** @s2script/commands — register server commands. NO runtime code (injected at load). */
+export interface CommandContext {
+  /** 0-based caller slot, or -1 for the server console. */
+  readonly callerSlot: number;
+  /** argString split on whitespace (0-based; the command name is NOT included). Kept for compat. */
+  readonly args: string[];
+  /** everything after the command name (raw) — SM `GetCmdArgString`. */
+  readonly argString: string;
+  /** number of whitespace-split arguments — SM `GetCmdArgs`. */
+  readonly argCount: number;
+  /** the nth argument (0-based), or `""` if absent — SM `GetCmdArg`. */
+  arg(n: number): string;
+  /** the nth argument parsed as an integer, or `fallback` (default 0) if absent/non-numeric. */
+  argInt(n: number, fallback?: number): number;
+  /** the nth argument parsed as a float, or `fallback` (default 0) if absent/non-numeric. */
+  argFloat(n: number, fallback?: number): number;
+  /** every argument from index `n` onward, re-joined with a single space (a reason/message/value that spans spaces). */
+  argsFrom(n: number): string;
+  /** reply to the caller: server console → server print; a player → their chat. */
+  reply(message: string): void;
+  /** reply to the caller, translated for THEIR language (SM's `%t` on the reply path). Soft-deps
+   * `@s2script/translations` — degrades to the raw `key` if it isn't loaded. */
+  replyT(key: string, ...args: (string | number)[]): void;
+}
+/** A parsed chat trigger: which command + args, and whether it was the silent (`/`) trigger. */
+export interface ChatTrigger {
+  /** `true` = the silent trigger (`/`, hidden); `false` = the public trigger (`!`). */
+  readonly silent: boolean;
+  /** the command name (the first token after the trigger char; NOT `sm_`-prefixed). */
+  readonly name: string;
+  /** everything after the command name. */
+  readonly argString: string;
+}
+
+export declare const Commands: {
+  register(name: string, handler: (ctx: CommandContext) => void): void;
+  registerServer(name: string, handler: (ctx: CommandContext) => void): void;
+  registerAdmin(name: string, flags: number, handler: (ctx: CommandContext) => void): void;
+  /** Invoke a registered command by name in THIS plugin (applying its gating). Returns true if it exists. */
+  dispatch(name: string, slot: number, argString: string): boolean;
+  /** Parse a chat message for a trigger (`!`/`/`). Returns the parsed trigger, or null if it's ordinary chat. */
+  parseChatTrigger(message: string): ChatTrigger | null;
+  /** If `message` is a trigger, dispatch the command (tries `name` then `sm_<name>`) as `slot`; returns
+   * `{ silent, ran }` (the caller should suppress the chat message), or null if it was ordinary chat. */
+  handleChatTrigger(slot: number, message: string): { silent: boolean; ran: boolean } | null;
+  /** The trigger characters — SM PublicChatTrigger (`"!"`) / SilentChatTrigger (`"/"`). Mutate to reconfigure. */
+  readonly triggers: { public: string; silent: string };
+  /** Every globally-registered command with its required admin `flags`: `0` = anyone, `-1` = console/server-only,
+   * else the `ADMFLAG` bit mask (map bits→names in your plugin). The `sm_help` backend. */
+  list(): { name: string; flags: number }[];
+};

package/config.d.ts

@@ -0,0 +1,14 @@
+/** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
+export type Config = Record<string, string | number | boolean>;
+export declare const config: {
+  getString(key: string): string;
+  getInt(key: string): number;
+  getFloat(key: string): number;
+  getBool(key: string): boolean;
+  /** Opt into live-reload: the handler fires with the re-materialized config when the file changes. */
+  onChange(handler: (cfg: Config) => void): void;
+  /** Read a raw file from the configs dir (name includes its extension, e.g. "maplist.txt"). null if absent. */
+  readFile(name: string): string | null;
+  /** Write a raw file to the configs dir (creates/overwrites). */
+  writeFile(name: string, content: string): void;
+};

package/console.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @s2script/console — author-time type stubs for the engine console.
+ * NO runtime code: the engine injects the implementation at load time.
+ */
+
+/** Engine-provided console (log/error/warn/info). Also available as the global `console`. */
+export declare const console: {
+  log(...data: any[]): void;
+  error(...data: any[]): void;
+  warn(...data: any[]): void;
+  info(...data: any[]): void;
+};

package/cookies.d.ts

@@ -0,0 +1,25 @@
+/** @s2script/cookies — SM-parity client preference cookies. NO runtime code (injected as __s2pkg_cookies). */
+import type { Client } from "./clients";
+export enum CookieAccess { Public, Protected, Private }
+export interface Cookie { readonly name: string; readonly access: CookieAccess; readonly default: string; }
+export interface CookieOptions { description?: string; access?: CookieAccess; default?: string; }
+export declare const Cookies: {
+  /** Register (or return an existing) cookie definition. */
+  register(name: string, opts?: CookieOptions): Cookie;
+  /** Cache value for this client (a stored "" is a real value), else the cookie's default. Default for bots. */
+  get(client: Client, cookie: Cookie): string;
+  /** Write the cache + mark dirty (flushed to the DB on disconnect). No-op for bots. */
+  set(client: Client, cookie: Cookie, value: string): void;
+  /** Has this client's cookies finished loading from the DB? */
+  areCached(client: Client): boolean;
+  /** Unix timestamp of the cookie's last write (set or DB load), or 0 if never set. 0 for bots. */
+  getTime(client: Client, cookie: Cookie): number;
+  /** Write a cookie for a SteamID64 that may not be connected right now (`SetAuthIdCookie` parity):
+   * updates the cache immediately (an online client sees it right away) and queues the write for the
+   * clientprefs plugin to persist directly next frame — an offline SteamID never fires the disconnect
+   * flush. No-op for "0" (bot/unset). */
+  setAuthId(steamId: string, cookie: Cookie, value: string): void;
+  /** Fires once per client, after that client's cookies finish loading (`OnClientCookiesCached`
+   * parity) — post-frame, after the load's async DB read completes. */
+  onCached(handler: (client: Client) => void): void;
+};

package/damage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @s2script/damage — damage pre-hooks (SDKHooks-equivalent). NO runtime code (injected at load).
+ * CTakeDamageInfo is a Source 2 engine type, so this module is engine-generic (lives in core).
+ */
+import type { EntityRef } from "./entity";
+
+/** A block-scoped view of the current damage event (valid only inside a Damage.onPre handler). */
+export interface DamageInfo {
+  /** The damage amount (m_flDamage). Assigning MODIFIES the live damage; set to 0 to block. */
+  damage: number;
+  /** The damage-type bit flags (m_bitsDamageType). */
+  readonly damageType: number;
+  /** The attacking entity (m_hAttacker), or null if none/stale. */
+  readonly attacker: EntityRef | null;
+  /** The inflicting entity (m_hInflictor), or null if none/stale. */
+  readonly inflictor: EntityRef | null;
+  /** The victim — the entity taking damage (the hooked `this`), or null if stale. */
+  readonly victim: EntityRef | null;
+}
+
+export declare const Damage: {
+  /** Register a pre-damage hook. The handler reads/modifies the DamageInfo in place (damage=0 blocks). */
+  onPre(handler: (info: DamageInfo) => void): void;
+};

package/db.d.ts

@@ -0,0 +1,27 @@
+/** @s2script/db — engine-generic async SQLite database. NO runtime code (injected as __s2pkg_db). */
+export type SqlValue = string | number | boolean | null;
+export type Row = Record<string, SqlValue>;
+export interface ExecuteResult { changes: number; lastInsertId: number; }
+
+export interface DriverConnection {
+  query(sql: string, params?: SqlValue[]): Promise<Row[]>;
+  execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+  close(): Promise<void>;
+}
+export interface ConnectionConfig { driver: string; name: string; [k: string]: unknown; }
+export interface Driver {
+  readonly name: string;
+  connect(config: ConnectionConfig): Promise<DriverConnection>;
+}
+/** A live database connection (delegates to its driver). */
+export interface Database {
+  query(sql: string, params?: SqlValue[]): Promise<Row[]>;
+  execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+  close(): Promise<void>;
+}
+export declare const Database: {
+  /** Open a connection by name (default "default"). Resolves the driver + config, then connects. */
+  open(name?: string): Promise<Database>;
+  /** Register a custom driver (per-plugin context). SQLite is built in. */
+  registerDriver(driver: Driver): void;
+};