Cookies

Register a cookie, then read and write through Cookies. Cookies.set and Cookies.setAuthId return an admission boolean — not a durability acknowledgement.

import { Cookies, Clients, command, HookResult } from '@s2script/sdk';

const boots = Cookies.register('demo_boots', { default: '0' });

export function OnPluginStart(): void {
	command('sm_toggle_boots', (cmd) => {
		const client = Clients.fromSlot(cmd.callerSlot);
		if (!client || client.steamId === '0') return HookResult.Handled;

		const next = Cookies.get(client, boots) === '1' ? '0' : '1';
		if (!Cookies.set(client, boots, next)) {
			cmd.reply('preference rejected; retry when persistence capacity recovers');
			return HookResult.Handled;
		}
		cmd.reply(`boots=${Cookies.get(client, boots)} (DB commit is asynchronous)`);
		return HookResult.Handled;
	});
}

false means admission was rejected: the identity is invalid, stale, or a bot ("0"), or the bounded host persistence outbox cannot reserve capacity. Rejection leaves the cache unchanged. Check false and report, shed, or retry. Structural mocks must return boolean, not void.

true means the host accepted the write into the outbox before mutating the cache. The host keeps ownership until the database acknowledges it, including across clientprefs reload and same-process core reinit. Process exit or library destruction can still lose unacknowledged writes.

Cookies.setAuthId(steamId, cookie, value) uses the same contract for an online or offline SteamID64 (SetAuthIdCookie parity). false leaves both cache and outbox unchanged (including empty / "0" identity).

Read stored values after OnClientCookiesCached or Cookies.areCached(client).

Persistence#

clientprefs is the sole cookie-table writer. Plugins must not issue unconditional cookie upserts (INSERT OR REPLACE). Versioned SQLite rows use writer_epoch plus an int64 revision; a conditional UPSERT rejects older late writes.

First adoption of the versioned cookie schema needs matched core and clientprefs artifacts installed with the server stopped, then a fresh process. Do not hot-load a newer clientprefs over an older generation with unversioned cookie writes still in flight.

See the cookies module.