# API overview

Author-time types ship in two npm packages; the engine injects the runtime at load:

- **`@s2script/sdk`** — every engine-generic capability. Prefer the root barrel (`import { command, hook } from "@s2script/sdk"`); subpaths (`@s2script/sdk/entity`, `/events`, `/chat`, …) stay valid. Also carries the `s2s` build CLI. `@s2script/sdk/unsafe` stays a deliberate subpath.
- **`@s2script/cs2`** — CS2 game types (`Player`, `Pawn`, schema accessors, the typed event overlay, `ChatColors`). `Player` is not on the SDK barrel.

## How imports work

```ts
import { command, hook, HookResult } from '@s2script/sdk';
import { Player } from '@s2script/cs2';
```

Add `@s2script/sdk` (and `@s2script/cs2`) to your package's `dependencies`. The CLI externalizes both by wildcard; the host maps `@s2script/sdk/<name>` → the injected runtime module. Subpath imports stay valid.

## Two flavors of API

- **Load-window APIs** — call from `OnPluginStart`; they throw after settle. `command`, `hook.on` / `hook.onPre`, `translations`, `publish` / `use` / `tryUse` / `watchOptional` / `bindForwards`, `previous()`, `pluginId()`, `createScope()`, `onOutput`, `topmenu`. On CS2, `CustomHudLayout` (`ui` is a deprecated alias), `gameRules`, `players`, `items` (`ItemsApi` — `import { items } from "@s2script/cs2"`). These are ledgered and torn down on unload. `hudkit` is used from `OnPluginStart` or a later callback — methods and `layout`/`hud` throw before plugin context exists; claimed handles stay usable after settle. CJS module evaluation is **before** this window — do not register at module top level.
- **Named publics** — `OnPluginStart` / `OnPluginEnd` / `OnPluginState`, `OnMapStart` / `OnGameFrame` / `OnClientConnected` / `OnEntityCreated` / `OnTakeDamage` / … Missing export = not subscribed. Game events are `hook.on` / `hook.onPre`, not `hook` subjects.
- **Stateless helpers** are plain named imports — `Chat`, `Player`, `Admin`, `config`, `Translations`, `Events.fire`, `delay`, `fetch`. `config.onChange` is typed on the free `config` import and is not load-window-gated.

`SDKHook` is the exception to load-window registration: per-entity, books-gated, callable whenever you hold a live `EntityRef`. See [SDKHooks](https://s2script.com/docs/concepts/sdkhooks) (`OnTakeDamage` / `OnTakeDamagePost`, `SetTransmit`, lifecycle virtuals, `Weapon*` / `Reload`).

```ts
import { hook, Chat } from '@s2script/sdk';

export function OnPluginStart(): void {
	hook.on('round_start', () => Chat.toAll('go!')); // game-event catalog → hook
}

export function OnGameFrame(): void {
	// before simulation — SourceMod's public. There is no OnGameFramePre / OnGameFramePost.
}
```

Post-simulation work is `createScope().server.onGameFrame(fn, { phase: 'post' })`, not a named public. See [lifecycle](https://s2script.com/docs/concepts/lifecycle).

## Engine-generic highlights

| Subpath                                      | Role                                                                                                                              |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `@s2script/sdk`                              | Authoring barrel: `command`, `hook`, `previous`, named-public types                                                               |
| `@s2script/sdk/plugin`                       | `hook` (game-event catalog), `onOutput`, `createScope`, `previous`, `publish` / `use` / `watchOptional` / `bindForwards`, `Scope` |
| `@s2script/sdk/entity`                       | `EntityRef`, create/spawn, I/O                                                                                                    |
| `@s2script/sdk/events`                       | Fire events + `HookResult`                                                                                                        |
| `@s2script/sdk/sdkhooks`                     | `SDKHook` / `SDKUnhook` (`OnTakeDamage` / `OnTakeDamagePost`, `SetTransmit`, lifecycle virtuals, `Weapon*` / `Reload`)            |
| `@s2script/sdk/timers`                       | delay / nextTick / nextFrame / threadSleep                                                                                        |
| `@s2script/sdk/clients`                      | Connection-lifetime `Client` handle                                                                                               |
| `@s2script/sdk/commands`                     | `command` / `command.admin` / `command.server`                                                                                    |
| `@s2script/sdk/chat`                         | Chat send                                                                                                                         |
| `@s2script/sdk/admin`                        | Admin flags + cache                                                                                                               |
| `@s2script/sdk/server`                       | Server.command, cvars                                                                                                             |
| `@s2script/sdk/db`                           | SQLite / SQL database (named result-size errors)                                                                                  |
| `@s2script/sdk/cookies`                      | Client preference cookies (`set` / `setAuthId` admission boolean)                                                                 |
| `@s2script/sdk/http` · `/ws` · `/net`        | Async network (boolean socket sends; named capacity errors)                                                                       |
| `@s2script/sdk/menu` · `/topmenu` · `/votes` | Menus, TopMenu dashboard, votes                                                                                                   |
| `@s2script/sdk/translations`                 | Phrase files + `cmd.replyT`                                                                                                       |
| `@s2script/sdk/unsafe`                       | `Engine.function` — plugin-declared engine calls and PRE/POST hooks                                                               |

## CS2

`@s2script/cs2` — `Player`, `Pawn`, schema accessors, the typed event overlay, `ChatColors`, `pickPlayer`, Fade/Shake/HintText, `CustomPlayerCamera`, and `CustomHudLayout` / `hudkit` (custom Panorama HUD — prefer `hudkit`). Load-window CS2 exports: `CustomHudLayout`, `gameRules`, `players`, `items` (`ItemsApi` pickup gates). Use `hudkit` from `OnPluginStart` or later (throws before plugin context; usable after settle).

## Next

- [Full package reference](https://s2script.com/docs/api/packages)
- [Modules catalog](https://s2script.com/docs/api/modules) — generated from the shipped type definitions
- Concepts: [lifecycle](https://s2script.com/docs/concepts/lifecycle), [entities](https://s2script.com/docs/concepts/entities), [events](https://s2script.com/docs/concepts/events), [SDKHooks](https://s2script.com/docs/concepts/sdkhooks), [commands](https://s2script.com/docs/concepts/commands), [translations](https://s2script.com/docs/concepts/translations), [async](https://s2script.com/docs/concepts/async), [cookies](https://s2script.com/docs/concepts/cookies), [interfaces](https://s2script.com/docs/concepts/interfaces), [HUD](https://s2script.com/docs/concepts/hud), [custom camera](https://s2script.com/docs/concepts/camera)