@zaisma/game-server 1.4.0 → 1.6.0

package/src/room.d.ts

@@ -7,7 +7,7 @@
  * running one copy of the game server. Names follow docs/NAMING.md.
  */
 import { type GameDatabase } from "./database.ts";
-import type { PlayerKind, ReceiptClaims } from "./pass.ts";
+import type { PassClaims, PlayerKind, ReceiptClaims } from "./pass.ts";
 import type { Server } from "./requests.ts";
 import { type Schedule, type ScheduledRun } from "./schedules.ts";
 import { type StateChange } from "./state-sync.ts";
@@ -409,6 +409,13 @@ export interface GameServer<S = any> {
      * Off by default. The state goes as JSON, so keep it plain; cut what each player sees with stateView.
      */
     stateSyncEnabled?: boolean;
+    /**
+     * Check chat between adults (room.chat) with Zaisma's filter too: contact details, moving apps or
+     * meeting up, personal details and sexual content are stopped, as they always are for under-18s. Off by
+     * default, when chat between adults is only flagged (hasSwearing, hasSlur) and your game decides. Each
+     * message the filter's AI looks at counts on your hosting meter (adult_chat_checks).
+     */
+    adultChatFilterEnabled?: boolean;
     /**
      * How often a real-time room saves its state, in seconds: 1 to 60, default 5. A restarted room comes
      * back with the last saved state (onRestored). Turn-based rooms save after every change and ignore it.
@@ -473,6 +480,16 @@ export interface GameServer<S = any> {
      * joinInfo.fromRoomCode, and not again when they arrive.
      */
     canJoin?(state: S, player: Player, room: Room, joinData: unknown, joinInfo: JoinInfo): JoinAnswer | Promise<JoinAnswer>;
+    /**
+     * A player sent a chat message (room.chat in their game), before Zaisma's filter checks it: answer true
+     * to send it, false to stop it (the sender's room.chat fails with chat_stopped, reason stopped_by_game),
+     * or { toPlayerIds } to send it to only some of chatInfo.toPlayerIds, like a team chat or a player your
+     * moderators muted. chatInfo.toPlayerIds are the players the sender's game sent it to; whatever you
+     * answer, it reaches only those of them who may chat with the sender, never anyone else. Only decide
+     * here, as in canJoin: room can be read, not changed. Without onChat every message goes on to the
+     * filter. If it throws or answers anything else, the message is stopped and the mistake is logged.
+     */
+    onChat?(state: S, player: Player, room: Room, chatInfo: ChatInfo): ChatAnswer | Promise<ChatAnswer>;
     /** After room.moveTo: who the other room took, and who it turned away and why. */
     onMoved?(state: S, moveResult: MoveResult, room: Room): HandlerResult<S>;
     /**
@@ -581,6 +598,29 @@ export declare function restoreInfoOf(savedAtMs: number, nowMs?: number, savedVe
 export type JoinAnswer = boolean | {
     refusalMessage: string;
 };
+/** A chat message as onChat sees it: what the player typed, and the players their game sent it to. */
+export interface ChatInfo {
+    text: string;
+    toPlayerIds: string[];
+}
+/**
+ * What onChat answers: true sends the message on to Zaisma's filter; false stops it; { toPlayerIds }
+ * sends it to only those of chatInfo.toPlayerIds (it can narrow who reads it, never widen it).
+ */
+export type ChatAnswer = boolean | {
+    toPlayerIds: string[];
+};
+/** What the sender hears when the game server's onChat stopped their message. */
+export declare const STOPPED_BY_GAME_MESSAGE = "Your message wasn't sent.";
+/** onChat's answer as the room acts on it: send (to toPlayerIds, or all it was sent to when null), or stop. Anything else is a mistake, and stops it. */
+export declare function readChatAnswer(answer: unknown): {
+    isAllowed: true;
+    toPlayerIds: string[] | null;
+} | {
+    isAllowed: false;
+} | {
+    mistake: GameServerError;
+};
 /**
  * canJoin's answer as the room acts on it: let in, or turn away with a refusalMessage (null for the
  * usual one). Answering nothing or anything else is a mistake (bad_handler_answer), described for the game server's errors.
@@ -594,7 +634,7 @@ export declare function readJoinAnswer(answer: unknown): {
     mistake: GameServerError;
 };
 /** Everything a game server object may have, in the order the docs give them. Anything else is refused. */
-export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "reconnectTimeoutSec", "maximumRoomCountPerPlayer", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onPurchase", "onRefund", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
+export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "adultChatFilterEnabled", "reconnectTimeoutSec", "maximumRoomCountPerPlayer", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onChat", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onPurchase", "onRefund", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
 export declare const ROOM_LIMITS: {
     /** Players in one room: what one room carries at 60 ticks a second (test/load/room-load.test.ts). */
     readonly maximumPlayerCount: 100;
@@ -774,6 +814,13 @@ export interface RoomSettings {
  * isSpectator: true, and they get the players, the state and every message sent to everyone, but they send
  * nothing: only probe answers, and anything else gets spectator_cannot_send. welcome and every "room"
  * message carry spectatorCount, and a "room" message goes out whenever it changes.
+ *
+ * Chat (room.chat): a client sends {type: "chat", chatNumber, text, toPlayerIds?}, which the room's host
+ * handles before the game's messages (readChatMessage, then startChat, Zaisma's filter, and deliverChat
+ * or stopChat). Each player it reaches gets {type: "chat", fromPlayerId, text, hasSwearing, hasSlur,
+ * sentAt}; the sender gets {type: "chat_sent", chatNumber, sentAt}, {type: "chat_stopped", chatNumber,
+ * reason, message}, or an error with its chatNumber (chat_not_allowed, chat_empty, chat_too_long,
+ * chat_too_fast). chat_sent never says who read it. welcome says canChat: whether this player can chat at all.
  */
 export type ServerMessage = {
     type: "welcome";
@@ -787,6 +834,7 @@ export type ServerMessage = {
     endsAt: string | null;
     probeIntervalSec: number | null;
     protocolVersionNumber: number;
+    canChat: boolean;
 } | {
     type: "probe";
     probeNumber: number;
@@ -835,11 +883,28 @@ export type ServerMessage = {
 } | {
     type: "blocks";
     playerIds: string[];
+} | {
+    type: "chat";
+    fromPlayerId: string;
+    text: string;
+    hasSwearing: boolean;
+    hasSlur: boolean;
+    sentAt: string;
+} | {
+    type: "chat_sent";
+    chatNumber: number;
+    sentAt: string;
+} | {
+    type: "chat_stopped";
+    chatNumber: number;
+    reason: string;
+    message: string;
 } | {
     type: "error";
     code: RoomErrorCode;
     message: string;
     versionId?: string;
+    chatNumber?: number;
 } | {
     type: "ended";
     message: string;
@@ -863,6 +928,11 @@ export type ClientMessage = {
 } | {
     type: "message";
     data: unknown;
+} | {
+    type: "chat";
+    chatNumber: number;
+    text: string;
+    toPlayerIds?: string[];
 } | {
     type: "zaisma:purchase";
     purchaseId: string;
@@ -902,7 +972,7 @@ export type ClientMessage = {
  * the game became unavailable, its kept room was deleted, or no players were left for its spectators.
  */
 export type EndReason = "game" | "hosting_paused" | "game_server_stopped" | "game_unavailable" | "kept_room_deleted" | "no_players";
-export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full";
+export type RoomErrorCode = "room_full" | "room_closed" | "ended" | "too_big" | "too_fast" | "bad_message" | "bad_pass" | "no_hello" | "not_allowed" | "game_unavailable" | "busy" | "kept_out" | "refused" | "room_not_running" | "hosting_paused" | "account_needed" | "game_not_open_to_player" | "blocked_player_here" | "other_version" | "spectators_full" | "spectator_cannot_send" | "already_playing" | "bad_origin" | "send_queue_full" | "chat_not_here" | "chat_not_allowed" | "chat_empty" | "chat_too_long" | "chat_too_fast";
 export declare const ERROR_TEXT: Record<RoomErrorCode, string>;
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export declare const HOSTING_PAUSED_END_MESSAGE = "This game's hosting is paused, so this match has ended. New rooms open again when the month resets or its developer adds credit.";
@@ -928,6 +998,8 @@ export interface SavedRoom extends RoomSettings {
     sessionBlocks?: [string, string][];
     /** Friendships between the room's players, as pairs of player IDs. */
     friendships?: [string, string][];
+    /** Who each account player the room remembers may chat with, by player ID. */
+    chatSettings?: Record<string, PlayerChatSettings>;
     /** When Zaisma will end the match (room.endsAt), once it's set. */
     endsAt?: string;
     /** Kept (room.setKept): it sleeps with its state when everyone leaves, instead of going a day later. */
@@ -1011,7 +1083,33 @@ export declare function checkRoomData(given: unknown, maximumSizeBytes: number):
  */
 export declare function errorMessage(code: RoomErrorCode, message?: string, details?: {
     versionId: string;
+} | {
+    chatNumber: number;
 }): string;
+/**
+ * Who an account player may chat with, from their pass (who_can_chat and chat_group_id): kept by the
+ * room's host, never shown to the game. A guest has none and chats with nobody.
+ */
+export interface PlayerChatSettings {
+    whoCanChat: "nobody" | "friends" | "anyone";
+    chatGroupId: string | null;
+}
+/** A checked pass's chat settings, for RoomCore.setChatSettings: null for a guest. A setting this version doesn't know chats with nobody. */
+export declare function chatSettingsOf(claims: PassClaims): PlayerChatSettings | null;
+/** A chat message from a client as readChatMessage found it, for startChat to check. */
+export interface ChatClientMessage {
+    chatNumber: number;
+    text: unknown;
+    toPlayerIds: unknown;
+    sizeBytes: number;
+}
+/** Room traffic of chat, in the room's message types. */
+export declare const CHAT_MESSAGE_TYPE = "(chat)";
+/**
+ * A client's chat message ({type: "chat"}), or null for any other text, which goes to receive. The
+ * room's host handles chat before receive, since Zaisma's filter runs between the room and the players.
+ */
+export declare function readChatMessage(text: string): ChatClientMessage | null;
 /** Whether a player may come in, and if not, why. */
 export type Admission = {
     isAllowed: true;
@@ -1163,6 +1261,12 @@ export declare class RoomCore<S = any> {
     private readonly sessionBlocks;
     /** Friendships between players from their accounts (Zaisma's own record, or passes on your own server): pairKey(first, second). */
     private readonly friendships;
+    /** Who each account player may chat with, from their pass: never in Player, so games never see it. */
+    private readonly chatSettings;
+    /** When each player sent their chat messages in the last CHAT_ROOM_LIMITS.chatWindowDurationMs. */
+    private readonly chatSentAtMs;
+    /** Each player's last chat messages, for Zaisma's filter to read pieces together: in memory only. */
+    private readonly recentChats;
     /** The blocks each player was last told of, so they're told again only when theirs change. */
     private readonly toldBlocks;
     /** When each player in the match was last heard from, when their game was hidden, and the idle check their game asked for. */
@@ -1190,6 +1294,8 @@ export declare class RoomCore<S = any> {
     private readonly api;
     /** The room as canJoin and stateView see it: reading works, and any call that changes or sends throws room_call_unavailable. */
     private readonly canJoinRoom;
+    /** The room as onChat sees it: reading only, like canJoin. */
+    private readonly chatRoom;
     private readonly stateViewRoom;
     readonly server: GameServer<S>;
     private readonly transport;
@@ -1259,6 +1365,45 @@ export declare class RoomCore<S = any> {
      * room knew of that player's, so a friend removed since is gone. Call before join.
      */
     setFriends(playerId: string, friendPlayerIds: readonly string[]): void;
+    /** A player's chat settings from their pass, before join: null for a guest, who chats with nobody. */
+    setChatSettings(playerId: string, settings: PlayerChatSettings | null): void;
+    /** Whether a player can chat at all: an account whose setting isn't nobody, with a chat group. */
+    canChat(playerId: string): boolean;
+    /**
+     * Whether one player's chat may reach another, canChat's rule on passes (pass.ts): two accounts in the
+     * same chat group with no block either way, friends unless both chat with anyone.
+     */
+    private mayChat;
+    /** Who a player's chat may reach: the players in the match (or those of toPlayerIds in it), never spectators, kept only where they may chat. */
+    chatReceivers(senderPlayerId: string, toPlayerIds?: readonly string[]): string[];
+    /**
+     * A chat message from a player (readChatMessage), checked by the room: the sender, the text, their pace,
+     * then the game server's onChat with the players their game sent it to. When it goes no further the room
+     * answers the sender itself (an error, or chat_stopped with stopped_by_game) and this is null. Otherwise
+     * it's the text, who may read it (chatReceivers, which may be nobody) and the sender's last messages, for
+     * the host to run Zaisma's filter and then deliverChat or stopChat.
+     */
+    startChat(playerId: string, chat: ChatClientMessage): Promise<{
+        text: string;
+        receiverPlayerIds: string[];
+        recentTexts: string[];
+    } | null>;
+    /**
+     * Send a chat message Zaisma's filter let through to its receivers, and tell the sender it went
+     * (chat_sent), even when it reached nobody: the sender never learns who can't read them.
+     */
+    deliverChat(senderPlayerId: string, chatNumber: number, receiverPlayerIds: readonly string[], chat: {
+        text: string;
+        hasSwearing: boolean;
+        hasSlur: boolean;
+    }): void;
+    /** Tell the sender their chat message was stopped: reason is the filter's, or stopped_by_game; message is what they see. */
+    stopChat(senderPlayerId: string, chatNumber: number, reason: string, message: string): void;
+    /** A player's chat messages from the last CHAT_CHECK_LIMITS.recentTextDurationMs, oldest first, up to recentTextCount. */
+    recentChatTexts(playerId: string): string[];
+    private rememberChat;
+    /** Whether a player may send another chat message: CHAT_ROOM_LIMITS.maximumChatMessageCount in any chatWindowDurationMs. */
+    private takeChat;
     /** Whether two players have a block between them, either way: from their accounts, or one a player's game said it made. */
     hasBlockBetween(firstPlayerId: string, secondPlayerId: string): boolean;
     /**

package/src/room.js

@@ -6,6 +6,7 @@
  * developer's code that holds the official game state. A *room* is one live match,
  * running one copy of the game server. Names follow docs/NAMING.md.
  */
+import { CHAT_CHECK_LIMITS, CHAT_ROOM_LIMITS } from "./chat.js";
 import { DatabaseError } from "./database.js";
 import { isRoomCode, roomCode } from "./names.js";
 import { readSchedules } from "./schedules.js";
@@ -22,6 +23,20 @@ function shownPlayer(player) {
 export function restoreInfoOf(savedAtMs, nowMs = Date.now(), savedVersionId = null, isSavedEmpty = false) {
     return { savedAt: new Date(savedAtMs).toISOString(), lostDurationSec: isSavedEmpty ? 0 : Math.max(0, Math.round((nowMs - savedAtMs) / 1000)), savedVersionId };
 }
+/** What the sender hears when the game server's onChat stopped their message. */
+export const STOPPED_BY_GAME_MESSAGE = "Your message wasn't sent.";
+/** onChat's answer as the room acts on it: send (to toPlayerIds, or all it was sent to when null), or stop. Anything else is a mistake, and stops it. */
+export function readChatAnswer(answer) {
+    if (answer === true)
+        return { isAllowed: true, toPlayerIds: null };
+    if (answer === false)
+        return { isAllowed: false };
+    const toPlayerIds = typeof answer === "object" && answer !== null && !Array.isArray(answer) ? answer.toPlayerIds : undefined;
+    if (Array.isArray(toPlayerIds) && toPlayerIds.every((id) => typeof id === "string") && Object.keys(answer).length === 1)
+        return { isAllowed: true, toPlayerIds };
+    const given = answer === undefined || answer === null ? "nothing" : typeof answer === "string" ? `the text ${JSON.stringify(answer.slice(0, 60))}` : typeof answer === "object" ? describeObject(answer) : String(answer);
+    return { mistake: new GameServerError("bad_handler_answer", "onChat", `onChat answered ${given}, so the message was stopped.`, 'Answer true to send it, false to stop it, or { toPlayerIds: ["player_..."] } to send it to only those players.') };
+}
 function describeObject(given) {
     try {
         return (JSON.stringify(given) ?? "an object").slice(0, 80);
@@ -59,12 +74,14 @@ export const GAME_SERVER_OPTIONS = [
     "awayMode",
     "seatHoldDurationSec",
     "stateSyncEnabled",
+    "adultChatFilterEnabled",
     "reconnectTimeoutSec",
     "maximumRoomCountPerPlayer",
     "stateSaveIntervalSec",
     "setup",
     "onJoin",
     "canJoin",
+    "onChat",
     "onMoved",
     "onLeave",
     "onSpectatorJoin",
@@ -240,6 +257,8 @@ export function defineGameServer(server) {
         throw bad("hostControlsEnabled", "hostControlsEnabled isn't true or false.", "Give true or false.");
     if (server.stateSyncEnabled !== undefined && typeof server.stateSyncEnabled !== "boolean")
         throw bad("stateSyncEnabled", "stateSyncEnabled isn't true or false.", "Give true to send each player the state and then only what changes, or leave it out.");
+    if (server.adultChatFilterEnabled !== undefined && typeof server.adultChatFilterEnabled !== "boolean")
+        throw bad("adultChatFilterEnabled", "adultChatFilterEnabled isn't true or false.", "Give true to check chat between adults with Zaisma's filter too, or leave it out.");
     if (server.stateView !== undefined && !server.stateSyncEnabled)
         throw bad("stateView", "stateView only works with stateSyncEnabled.", "Add stateSyncEnabled: true, or leave stateView out.");
     if (idleCheck !== undefined && idleCheck !== "server" && idleCheck !== "client" && idleCheck !== "off") {
@@ -290,6 +309,11 @@ export const ERROR_TEXT = {
     bad_origin: "Rooms take players from the game's own page.",
     // The SDK's own: sends waiting while it reconnects ran past its queue.
     send_queue_full: "Up to 60 sends wait while reconnecting; older ones were dropped.",
+    chat_not_here: "This room's server doesn't take chat.",
+    chat_not_allowed: "You can't chat here.",
+    chat_empty: "Type a message first.",
+    chat_too_long: "That message is too long to send.",
+    chat_too_fast: "Too many messages at once. Wait a moment.",
 };
 /** What players are told when Zaisma ends a match at room.endsAt. */
 export const HOSTING_PAUSED_END_MESSAGE = "This game's hosting is paused, so this match has ended. New rooms open again when the month resets or its developer adds credit.";
@@ -323,6 +347,35 @@ export function checkRoomData(given, maximumSizeBytes) {
 export function errorMessage(code, message, details) {
     return JSON.stringify({ type: "error", code, message: message || ERROR_TEXT[code], ...details });
 }
+/** A checked pass's chat settings, for RoomCore.setChatSettings: null for a guest. A setting this version doesn't know chats with nobody. */
+export function chatSettingsOf(claims) {
+    if (claims.kind !== "account")
+        return null;
+    const whoCanChat = claims.who_can_chat === "friends" ? "friends" : claims.who_can_chat === "anyone" ? "anyone" : "nobody";
+    return { whoCanChat, chatGroupId: typeof claims.chat_group_id === "string" ? claims.chat_group_id : null };
+}
+/** Room traffic of chat, in the room's message types. */
+export const CHAT_MESSAGE_TYPE = "(chat)";
+/**
+ * A client's chat message ({type: "chat"}), or null for any other text, which goes to receive. The
+ * room's host handles chat before receive, since Zaisma's filter runs between the room and the players.
+ */
+export function readChatMessage(text) {
+    // Most messages aren't chat: only text that could be is parsed here, and one too big is receive's to refuse.
+    if (!text.includes('"chat"') || text.length > ROOM_LIMITS.maximumGameMessageSizeBytes)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || parsed.type !== "chat")
+        return null;
+    const chat = parsed;
+    return { chatNumber: Number.isSafeInteger(chat.chatNumber) ? chat.chatNumber : 0, text: chat.text, toPlayerIds: chat.toPlayerIds, sizeBytes: utf8ByteCount(text) };
+}
 /** WebSocket close code for a match that ended normally. */
 export const ENDED_CLOSE_CODE = 4000;
 /** Close code for a player refused or removed by the room: the SDK doesn't reconnect. */
@@ -482,6 +535,12 @@ export class RoomCore {
     sessionBlocks = new Set();
     /** Friendships between players from their accounts (Zaisma's own record, or passes on your own server): pairKey(first, second). */
     friendships = new Set();
+    /** Who each account player may chat with, from their pass: never in Player, so games never see it. */
+    chatSettings = new Map();
+    /** When each player sent their chat messages in the last CHAT_ROOM_LIMITS.chatWindowDurationMs. */
+    chatSentAtMs = new Map();
+    /** Each player's last chat messages, for Zaisma's filter to read pieces together: in memory only. */
+    recentChats = new Map();
     /** The blocks each player was last told of, so they're told again only when theirs change. */
     toldBlocks = new Map();
     /** When each player in the match was last heard from, when their game was hidden, and the idle check their game asked for. */
@@ -509,6 +568,8 @@ export class RoomCore {
     api;
     /** The room as canJoin and stateView see it: reading works, and any call that changes or sends throws room_call_unavailable. */
     canJoinRoom;
+    /** The room as onChat sees it: reading only, like canJoin. */
+    chatRoom;
     stateViewRoom;
     server;
     transport;
@@ -604,6 +665,8 @@ export class RoomCore {
                 this.sessionBlocks.add(blockKey(blocker, blocked));
             for (const [first, second] of saved.friendships ?? [])
                 this.friendships.add(pairKey(first, second));
+            for (const [id, settings] of Object.entries(saved.chatSettings ?? {}))
+                this.chatSettings.set(id, settings);
         }
         else if (startOptions.start) {
             const start = startOptions.start;
@@ -727,6 +790,7 @@ export class RoomCore {
         Object.defineProperty(this.api, PAIR_CHANGE_COUNT, { get: () => this.pairChangeCount });
         Object.defineProperty(this.api, STATE_SYNC, { value: { viewers: () => this.stateViewers(), send: (playerIds, frame) => this.sendStateFrom(playerIds, frame) } });
         this.canJoinRoom = readOnlyRoom(this.api, "canJoin");
+        this.chatRoom = readOnlyRoom(this.api, "onChat");
         this.stateViewRoom = readOnlyRoom(this.api, "stateView");
         if (restoreInfo)
             this.restored(restoreInfo, lostPlayers);
@@ -772,6 +836,7 @@ export class RoomCore {
             ...(this.endsAt ? { endsAt: this.endsAt } : {}),
             ...(this.isKept ? { isKept: true } : {}),
             ...this.savedBlocks(),
+            ...(this.chatSettings.size ? { chatSettings: Object.fromEntries([...this.chatSettings].filter(([id]) => this.known.has(id))) } : {}),
         };
     }
     /** The blocks worth keeping while the room sleeps: those between players it still remembers. */
@@ -810,6 +875,137 @@ export class RoomCore {
         this.dirty = true;
         this.pairChangeCount++;
     }
+    /** A player's chat settings from their pass, before join: null for a guest, who chats with nobody. */
+    setChatSettings(playerId, settings) {
+        if (settings)
+            this.chatSettings.set(playerId, { whoCanChat: settings.whoCanChat, chatGroupId: settings.chatGroupId });
+        else if (!this.chatSettings.delete(playerId))
+            return;
+        this.dirty = true;
+    }
+    /** Whether a player can chat at all: an account whose setting isn't nobody, with a chat group. */
+    canChat(playerId) {
+        const settings = this.chatSettings.get(playerId);
+        return settings !== undefined && settings.whoCanChat !== "nobody" && settings.chatGroupId !== null;
+    }
+    /**
+     * Whether one player's chat may reach another, canChat's rule on passes (pass.ts): two accounts in the
+     * same chat group with no block either way, friends unless both chat with anyone.
+     */
+    mayChat(senderPlayerId, receiverPlayerId) {
+        if (senderPlayerId === receiverPlayerId || !this.canChat(senderPlayerId) || !this.canChat(receiverPlayerId) || this.hasBlockBetween(senderPlayerId, receiverPlayerId))
+            return false;
+        const sender = this.chatSettings.get(senderPlayerId);
+        const receiver = this.chatSettings.get(receiverPlayerId);
+        if (sender.chatGroupId !== receiver.chatGroupId)
+            return false;
+        return (sender.whoCanChat === "anyone" && receiver.whoCanChat === "anyone") || this.areFriends(senderPlayerId, receiverPlayerId);
+    }
+    /** Who a player's chat may reach: the players in the match (or those of toPlayerIds in it), never spectators, kept only where they may chat. */
+    chatReceivers(senderPlayerId, toPlayerIds) {
+        const asked = toPlayerIds ? [...new Set(toPlayerIds)].filter((id) => this.players.has(id)) : [...this.players.keys()];
+        return asked.filter((id) => this.mayChat(senderPlayerId, id));
+    }
+    /**
+     * A chat message from a player (readChatMessage), checked by the room: the sender, the text, their pace,
+     * then the game server's onChat with the players their game sent it to. When it goes no further the room
+     * answers the sender itself (an error, or chat_stopped with stopped_by_game) and this is null. Otherwise
+     * it's the text, who may read it (chatReceivers, which may be nobody) and the sender's last messages, for
+     * the host to run Zaisma's filter and then deliverChat or stopChat.
+     */
+    async startChat(playerId, chat) {
+        const refuse = (code) => {
+            this.sendText(playerId, errorMessage(code, undefined, { chatNumber: chat.chatNumber }));
+            return null;
+        };
+        // Spectators send nothing, chat included; limited like anyone's messages, so refusing them costs little.
+        if (this.spectators.has(playerId))
+            return refuse(this.ended ? "ended" : this.take(playerId) ? "spectator_cannot_send" : "too_fast");
+        const player = this.players.get(playerId);
+        if (!player || this.ended)
+            return refuse("ended");
+        this.messageCount++;
+        this.countTraffic("inbound", CHAT_MESSAGE_TYPE, 1, chat.sizeBytes);
+        // Counted against the room's 30 a second like any message, then chat's own pace below.
+        if (!this.take(playerId))
+            return refuse("too_fast");
+        const isPlayerIdList = chat.toPlayerIds === undefined || (Array.isArray(chat.toPlayerIds) && chat.toPlayerIds.length <= this.maximumPlayerCount && chat.toPlayerIds.every((id) => typeof id === "string"));
+        if (typeof chat.text !== "string" || !isPlayerIdList)
+            return refuse("bad_message");
+        if (!this.canChat(playerId))
+            return refuse("chat_not_allowed");
+        if (!chat.text.trim())
+            return refuse("chat_empty");
+        if (chat.text.length > CHAT_CHECK_LIMITS.maximumMessageCharacterCount)
+            return refuse("chat_too_long");
+        if (!this.takeChat(playerId))
+            return refuse("chat_too_fast");
+        const presence = this.presence.get(playerId);
+        if (presence)
+            presence.seenAtMs = this.now();
+        const toPlayerIds = (chat.toPlayerIds === undefined ? [...this.players.keys()] : [...new Set(chat.toPlayerIds)]).filter((id) => id !== playerId && this.players.has(id));
+        let askedPlayerIds = toPlayerIds;
+        if (this.server.onChat) {
+            await this.settled();
+            let answer;
+            try {
+                answer = await this.server.onChat(this.state, player, this.chatRoom, { text: chat.text, toPlayerIds: [...toPlayerIds] });
+            }
+            catch (error) {
+                console.error("Game server error:", error);
+                answer = false;
+            }
+            const read = readChatAnswer(answer);
+            if ("mistake" in read)
+                console.error("Game server error:", read.mistake);
+            if ("mistake" in read || !read.isAllowed) {
+                this.stopChat(playerId, chat.chatNumber, "stopped_by_game", STOPPED_BY_GAME_MESSAGE);
+                return null;
+            }
+            if (read.toPlayerIds)
+                askedPlayerIds = toPlayerIds.filter((id) => read.toPlayerIds.includes(id));
+        }
+        const recentTexts = this.recentChatTexts(playerId);
+        this.rememberChat(playerId, chat.text);
+        return { text: chat.text, receiverPlayerIds: this.chatReceivers(playerId, askedPlayerIds), recentTexts };
+    }
+    /**
+     * Send a chat message Zaisma's filter let through to its receivers, and tell the sender it went
+     * (chat_sent), even when it reached nobody: the sender never learns who can't read them.
+     */
+    deliverChat(senderPlayerId, chatNumber, receiverPlayerIds, chat) {
+        const sentAt = new Date(this.now()).toISOString();
+        // Players who left, or blocked the sender, while the filter looked get nothing.
+        const receivers = receiverPlayerIds.filter((id) => this.players.has(id) && this.mayChat(senderPlayerId, id));
+        if (receivers.length)
+            this.sendEach(receivers, JSON.stringify({ type: "chat", fromPlayerId: senderPlayerId, text: chat.text, hasSwearing: chat.hasSwearing, hasSlur: chat.hasSlur, sentAt }), CHAT_MESSAGE_TYPE);
+        this.sendText(senderPlayerId, JSON.stringify({ type: "chat_sent", chatNumber, sentAt }));
+    }
+    /** Tell the sender their chat message was stopped: reason is the filter's, or stopped_by_game; message is what they see. */
+    stopChat(senderPlayerId, chatNumber, reason, message) {
+        this.sendText(senderPlayerId, JSON.stringify({ type: "chat_stopped", chatNumber, reason, message }));
+    }
+    /** A player's chat messages from the last CHAT_CHECK_LIMITS.recentTextDurationMs, oldest first, up to recentTextCount. */
+    recentChatTexts(playerId) {
+        const nowMs = this.now();
+        return (this.recentChats.get(playerId) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs).map((sent) => sent.text);
+    }
+    rememberChat(playerId, text) {
+        const nowMs = this.now();
+        const recent = (this.recentChats.get(playerId) ?? []).filter((sent) => nowMs - sent.sentAtMs < CHAT_CHECK_LIMITS.recentTextDurationMs);
+        recent.push({ text, sentAtMs: nowMs });
+        this.recentChats.set(playerId, recent.slice(-CHAT_CHECK_LIMITS.recentTextCount));
+    }
+    /** Whether a player may send another chat message: CHAT_ROOM_LIMITS.maximumChatMessageCount in any chatWindowDurationMs. */
+    takeChat(playerId) {
+        const nowMs = this.now();
+        const sentAtMs = (this.chatSentAtMs.get(playerId) ?? []).filter((atMs) => nowMs - atMs < CHAT_ROOM_LIMITS.chatWindowDurationMs);
+        const isTaken = sentAtMs.length < CHAT_ROOM_LIMITS.maximumChatMessageCount;
+        if (isTaken)
+            sentAtMs.push(nowMs);
+        this.chatSentAtMs.set(playerId, sentAtMs);
+        return isTaken;
+    }
     /** Whether two players have a block between them, either way: from their accounts, or one a player's game said it made. */
     hasBlockBetween(firstPlayerId, secondPlayerId) {
         if (firstPlayerId === secondPlayerId)
@@ -1133,7 +1329,7 @@ export class RoomCore {
         this.remember(player.id);
         this.presence.set(player.id, newPresence(this.now(), joinOptions.clientIdle === undefined ? (this.presence.get(player.id)?.clientIdle ?? {}) : clientIdle(joinOptions.clientIdle)));
         const probeIntervalSec = this.ticking ? ROOM_TUNING.probeIntervalSec : null;
-        this.sendText(player.id, JSON.stringify({ type: "welcome", me: shownPlayer(player), isSpectator: false, players: this.list(), room: this.settings(), spectatorCount: this.spectators.size, hostPlayerId: this.hostPlayerId, awayChecks: this.checks(player.id), endsAt: this.endsAt, probeIntervalSec, protocolVersionNumber: PROTOCOL_VERSION_NUMBER }));
+        this.sendText(player.id, JSON.stringify({ type: "welcome", me: shownPlayer(player), isSpectator: false, players: this.list(), room: this.settings(), spectatorCount: this.spectators.size, hostPlayerId: this.hostPlayerId, awayChecks: this.checks(player.id), endsAt: this.endsAt, probeIntervalSec, protocolVersionNumber: PROTOCOL_VERSION_NUMBER, canChat: this.canChat(player.id) }));
         // Every room gets a first ping and clock sample right away, ticking or not.
         this.probe(player.id);
         // A new connection starts with nothing of the state: a full copy comes with the next round.
@@ -1172,7 +1368,7 @@ export class RoomCore {
         this.spectators.set(spectator.id, spectator);
         this.presence.set(spectator.id, newPresence(this.now(), {}));
         const probeIntervalSec = this.ticking ? ROOM_TUNING.probeIntervalSec : null;
-        this.sendText(spectator.id, JSON.stringify({ type: "welcome", me: shownPlayer(spectator), isSpectator: true, players: this.list(), room: this.settings(), spectatorCount: this.spectators.size, hostPlayerId: this.hostPlayerId, awayChecks: { idleTimeoutSec: null, hiddenTimeoutSec: null }, endsAt: this.endsAt, probeIntervalSec, protocolVersionNumber: PROTOCOL_VERSION_NUMBER }));
+        this.sendText(spectator.id, JSON.stringify({ type: "welcome", me: shownPlayer(spectator), isSpectator: true, players: this.list(), room: this.settings(), spectatorCount: this.spectators.size, hostPlayerId: this.hostPlayerId, awayChecks: { idleTimeoutSec: null, hiddenTimeoutSec: null }, endsAt: this.endsAt, probeIntervalSec, protocolVersionNumber: PROTOCOL_VERSION_NUMBER, canChat: false }));
         this.probe(spectator.id);
         // A new connection starts with nothing of the state: a full copy comes with the next round.
         if (this.server.stateSyncEnabled) {
@@ -1254,6 +1450,8 @@ export class RoomCore {
     /** Take a player out of the match, forgetting what the room knew about them while they were in. */
     out(playerId) {
         this.players.delete(playerId);
+        this.chatSentAtMs.delete(playerId);
+        this.recentChats.delete(playerId);
         this.latestSlots.delete(playerId);
         this.stateSkippedPlayerIds.delete(playerId);
         this.fullCopyPlayerIds.delete(playerId);
@@ -1482,6 +1680,9 @@ export class RoomCore {
             case "message":
                 this.input(() => this.server.onMessage?.(this.state, player, this.api, message.data), "onMessage");
                 return null;
+            case "chat":
+                // The room's host takes chat before it gets here (readChatMessage); a host that doesn't, doesn't take chat.
+                return "chat_not_here";
             case "zaisma:purchase":
                 this.purchaseTold(playerId, message);
                 return null;
@@ -1898,7 +2099,7 @@ export class RoomCore {
         const viewerIds = this.stateViewerIds();
         const stateView = this.server.stateView;
         const state = this.state;
-        const round = tracker.round(state, viewerIds, stateView ? (viewerId) => stateView(state, (this.players.get(viewerId) ?? this.spectators.get(viewerId)), this.stateViewRoom) : null, this.backedUpViewers(viewerIds));
+        const round = tracker.round(state, viewerIds, stateView ? (viewerId) => stateView(state, { ...(this.players.get(viewerId) ?? this.spectators.get(viewerId)) }, this.stateViewRoom) : null, this.backedUpViewers(viewerIds));
         for (const problem of round.problems)
             console.error(`Game server error: ${problem}`);
         for (const { playerIds, frame } of round.frames)