trucoshi 12.1.0 → 12.1.1

package/dist/events.d.ts

@@ -56,6 +56,7 @@ export declare enum EClientEvent {
     LOGOUT = "LOGOUT",
     LEAVE_MATCH = "LEAVE_MATCH",
     CREATE_MATCH = "CREATE_MATCH",
+    CREATE_TUTORIAL_MATCH = "CREATE_TUTORIAL_MATCH",
     FETCH_ACCOUNT_DETAILS = "FETCH_ACCOUNT_DETAILS",
     FETCH_MATCH_DETAILS = "FETCH_MATCH_DETAILS",
     SET_MATCH_OPTIONS = "SET_MATCH_OPTIONS",
@@ -103,6 +104,10 @@ export interface ClientToServerEvents {
         match?: IPublicMatch;
         activeMatches?: IPublicMatchInfo[];
     }>) => void;
+    [EClientEvent.CREATE_TUTORIAL_MATCH]: (tutorialId: string | null | undefined, callback: IEventCallback<{
+        match?: IPublicMatch;
+        activeMatches?: IPublicMatchInfo[];
+    }>) => void;
     [EClientEvent.SET_MATCH_OPTIONS]: (matchSessionId: string, options: Partial<ILobbyOptions>, callback: IEventCallback<{
         match?: IPublicMatch;
         activeMatches?: IPublicMatchInfo[];

package/dist/events.js

@@ -28,6 +28,7 @@ export var EClientEvent;
     EClientEvent["LOGOUT"] = "LOGOUT";
     EClientEvent["LEAVE_MATCH"] = "LEAVE_MATCH";
     EClientEvent["CREATE_MATCH"] = "CREATE_MATCH";
+    EClientEvent["CREATE_TUTORIAL_MATCH"] = "CREATE_TUTORIAL_MATCH";
     EClientEvent["FETCH_ACCOUNT_DETAILS"] = "FETCH_ACCOUNT_DETAILS";
     EClientEvent["FETCH_MATCH_DETAILS"] = "FETCH_MATCH_DETAILS";
     EClientEvent["SET_MATCH_OPTIONS"] = "SET_MATCH_OPTIONS";

package/dist/lib/classes/Deck.d.ts

@@ -6,6 +6,6 @@ export declare function dealCards<TPlayer extends {
     key: string;
     idx: number;
     setHand(h: Array<ICard>): void;
-} = IPlayer>(table: ITable<TPlayer>, deck: IDeck): void;
+} = IPlayer>(table: ITable<TPlayer>, deck: IDeck, fixedHandsByPlayerIdx?: Record<string, ICard[]>): void;
 export declare function shuffleArray<T = unknown>(array: Array<T>, getRandom?: (max: number) => number): Array<T>;
 export declare function PlayedCard(player: IPlayer | IPublicPlayer, card: ICard, burn?: boolean): IPlayedCard;

package/dist/lib/classes/Deck.js

@@ -38,11 +38,54 @@ export function Deck() {
     return deck;
 }
 export const getAllCards = () => Object.keys(CARDS);
-export function dealCards(table, deck) {
+const normalizeFixedHands = (table, fixedHandsByPlayerIdx) => {
+    if (!fixedHandsByPlayerIdx) {
+        return null;
+    }
+    const fixedHands = new Map();
+    const usedCards = new Set();
+    const playersByIdx = new Set(table.players.map((player) => player.idx));
+    for (const [playerIdxText, cards] of Object.entries(fixedHandsByPlayerIdx)) {
+        const playerIdx = Number(playerIdxText);
+        if (!Number.isInteger(playerIdx) || !playersByIdx.has(playerIdx)) {
+            throw new Error(`Invalid fixed hand player index: ${playerIdxText}`);
+        }
+        if (!Array.isArray(cards) || cards.length !== 3) {
+            throw new Error(`Fixed hand for player ${playerIdx} must contain exactly 3 cards`);
+        }
+        for (const card of cards) {
+            if (!(card in CARDS)) {
+                throw new Error(`Invalid fixed hand card: ${card}`);
+            }
+            if (usedCards.has(card)) {
+                throw new Error(`Duplicate fixed hand card: ${card}`);
+            }
+            usedCards.add(card);
+        }
+        fixedHands.set(playerIdx, cards);
+    }
+    return fixedHands;
+};
+export function dealCards(table, deck, fixedHandsByPlayerIdx) {
     const cheat_lots_of_flowers = process.env.APP_CHEAT_LOTS_OF_FLOWERS_FOR_TESTING === "1";
     const cheat_cards = process.env.APP_CHEAT_CARDS || "";
     const playerHands = [];
     const players = table.getPlayersForehandFirst();
+    const fixedHands = normalizeFixedHands(table, fixedHandsByPlayerIdx);
+    if (fixedHands) {
+        for (const player of table.players) {
+            const fixedHand = fixedHands.get(player.idx);
+            playerHands[player.idx] = fixedHand
+                ? fixedHand.map((card) => deck.pick(card) || (() => {
+                    throw new Error(`Fixed hand card is not available in deck: ${card}`);
+                })())
+                : deck.takeThree();
+        }
+        for (const player of table.players) {
+            player.setHand(playerHands[player.idx]);
+        }
+        return;
+    }
     for (let i = 0; i < 3; i++) {
         for (const player of players) {
             playerHands[player.idx] = [...(playerHands[player.idx] || []), deck.takeCard()];
@@ -70,8 +113,8 @@ export function dealCards(table, deck) {
             playerHands[player.idx] = deck.takeThree();
         }
     }
-    for (const [key, player] of table.players.entries()) {
-        player.setHand(playerHands[key]);
+    for (const player of table.players) {
+        player.setHand(playerHands[player.idx]);
     }
 }
 const defaultGetRandom = (max) => Math.floor(Math.random() * max);

package/dist/tutorials/basic-truco-v1.json

@@ -0,0 +1,408 @@
+{
+    "id": "basic-truco-v1",
+    "title": "Aprende a jugar",
+    "botProfile": "ProfeTruco",
+    "botName": "Profe Truco",
+    "options": {
+        "maxPlayers": 2,
+        "matchPoint": 9,
+        "flor": true,
+        "satsPerPlayer": 0
+    },
+    "hands": [
+        {
+            "goal": "Entender el objetivo y la fuerza de las cartas.",
+            "cardsByPlayerIdx": {
+                "0": ["4c", "7e", "1e"],
+                "1": ["6b", "5o", "3c"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "Bienvenido. Ganas el partido llegando a 9 puntos antes que el Profe."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "text": "La ronda se gana con la carta mas fuerte. El ancho de espada es la mejor."
+                },
+                {
+                    "trigger": "after_human_action",
+                    "actionValue": "1e",
+                    "text": "Esa manda. Despues vienen ancho de basto, 7 de espada y 7 de oro."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 2,
+                    "text": "Ahora cerra la mano usando otra carta fuerte cuando haga falta."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 3,
+                    "state": "WAITING_PLAY",
+                    "text": "Si hace falta otra ronda, elegi la carta que mejor cierre la mano."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "Perfecto. En truco se gana al mejor de tres rondas."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "3c" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "6b" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "5o" }
+                }
+            ]
+        },
+        {
+            "goal": "Aprender a jugar bajo antes de gastar cartas fuertes.",
+            "cardsByPlayerIdx": {
+                "0": ["4b", "7o", "1b"],
+                "1": ["5c", "3o", "2e"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "No siempre conviene tirar lo mejor de entrada. Guardar poder tambien gana manos."
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "text": "Ahora arranca el Profe. Mira que carta tira antes de gastar una fuerte."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "text": "Podes probar con el 4 de basto y guardar dos cartas bravas."
+                },
+                {
+                    "trigger": "after_bot_action",
+                    "roundIdx": 2,
+                    "actionValue": "3o",
+                    "text": "Si perdes una ronda, tranqui. Usa una fuerte para recuperar control."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 2,
+                    "text": "El ancho de basto es enorme. Usalo si necesitas ganar esta ronda."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 3,
+                    "text": "Te queda el 7 de oro. Muy buena carta para definir."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "Linda remontada. A veces perder barato la primera te deja mejor parado."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "5c" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "3o" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "2e" }
+                }
+            ]
+        },
+        {
+            "goal": "Cantar Envido antes de jugar y comparar tantos.",
+            "cardsByPlayerIdx": {
+                "0": ["7c", "6c", "1o"],
+                "1": ["5b", "4b", "re"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "Tenes 33 de envido: 7 y 6 de copa suman 20 + 13. Cantalo antes de jugar."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "text": "Toca ENVIDO ahora. El envido se resuelve antes de seguir con las cartas."
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "state": "WAITING_ENVIDO_ANSWER",
+                    "text": "El Profe puede aceptar con QUIERO o achicarse con NO QUIERO."
+                },
+                {
+                    "trigger": "after_bot_action",
+                    "actionValue": "QUIERO",
+                    "text": "El Profe quiso. Ahora declara tus 33 para comparar tantos."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "state": "WAITING_ENVIDO_POINTS_ANSWER",
+                    "text": "Deci 33. Ese tanto obliga al Profe a superar tu envido."
+                },
+                {
+                    "trigger": "after_bot_action",
+                    "actionValue": 29,
+                    "text": "El Profe dijo 29. Tus 33 ganan el envido."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "state": "WAITING_PLAY",
+                    "text": "Ahora segui la mano. El envido suma aparte del juego de cartas."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 2,
+                    "state": "WAITING_PLAY",
+                    "text": "Ahora segui jugando tus cartas. Busca ganar la ronda sin regalar de mas."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 3,
+                    "state": "WAITING_PLAY",
+                    "text": "Ya conoces la idea: elegi la mejor carta para esta ronda."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "Clave: si tenes buen tanto, canta antes de mostrar cartas."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "state": "WAITING_ENVIDO_ANSWER",
+                    "action": { "type": "command", "value": "QUIERO" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "state": "WAITING_ENVIDO_POINTS_ANSWER",
+                    "action": { "type": "command", "value": 29 }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "re" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "5b" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "4b" }
+                }
+            ]
+        },
+        {
+            "goal": "Responder Truco y entender cuando aceptar o rechazar.",
+            "cardsByPlayerIdx": {
+                "0": ["7b", "3e", "1c"],
+                "1": ["4o", "2b", "1e"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "El Truco sube la apuesta de la mano. Aceptar puede pagar, pero duele perder."
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "text": "Ahora empieza el Profe. No aceptes presion sin mirar tu mano."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "text": "Responde con el 7 de basto. No es fuerte, pero guardas dos cartas decentes."
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "text": "Ojo, el Profe te va a apretar con TRUCO."
+                },
+                {
+                    "trigger": "after_bot_action",
+                    "actionValue": "TRUCO",
+                    "text": "Con QUIERO jugas por 2 puntos. Con NO QUIERO entregas solo 1."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "state": "WAITING_FOR_TRUCO_ANSWER",
+                    "text": "Aca acepta con QUIERO: tenes cartas para pelear y aprender el riesgo."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 2,
+                    "state": "WAITING_PLAY",
+                    "text": "Ahora juga tu mejor carta disponible para pelear el Truco."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 3,
+                    "state": "WAITING_PLAY",
+                    "text": "Si queda una ronda, mira que carta te queda y busca cerrarla."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "A veces se pierde un Truco querido. La clave es medir riesgo y mano."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "4o" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "command", "value": "TRUCO" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "1e" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "2b" }
+                }
+            ]
+        },
+        {
+            "goal": "Reconocer Flor y declararla con tres cartas del mismo palo.",
+            "cardsByPlayerIdx": {
+                "0": ["7o", "6o", "1o"],
+                "1": ["4e", "5b", "rc"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "Tres cartas del mismo palo son Flor. Tenes flor de oro: cantala antes de jugar."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "text": "Toca FLOR. Con flor activa, vale mas que pensar en envido."
+                },
+                {
+                    "trigger": "after_human_action",
+                    "actionValue": "FLOR",
+                    "text": "Flor cantada. Ahora segui jugando la mano de cartas."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 1,
+                    "state": "WAITING_PLAY",
+                    "text": "Tu 7 de oro es muy fuerte. Usalo para marcar la cancha."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 2,
+                    "state": "WAITING_PLAY",
+                    "text": "Ahora segui jugando tus cartas. La Flor ya sumo, falta la mano."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "roundIdx": 3,
+                    "state": "WAITING_PLAY",
+                    "text": "Ya conoces la idea: elegi la mejor carta para esta ronda."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "Bien ahi. Si ves tres del mismo palo, primero mira la Flor."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "4e" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "5b" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "rc" }
+                }
+            ]
+        },
+        {
+            "goal": "Aprender cuando irse al mazo para perder menos.",
+            "cardsByPlayerIdx": {
+                "0": ["4c", "5o", "6b"],
+                "1": ["1e", "7e", "3b"]
+            },
+            "messages": [
+                {
+                    "trigger": "hand_start",
+                    "text": "Mano flojita: sin envido fuerte y sin cartas altas. No todo se pelea."
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "text": "El Profe huele debilidad y va a cantar TRUCO."
+                },
+                {
+                    "trigger": "after_bot_action",
+                    "actionValue": "TRUCO",
+                    "text": "Con esta mano, irte al MAZO es correcto: perdes poco y pasas a la proxima."
+                },
+                {
+                    "trigger": "before_human_turn",
+                    "state": "WAITING_FOR_TRUCO_ANSWER",
+                    "text": "Toca NO QUIERO. En truco, abandonar a tiempo tambien es jugar bien."
+                },
+                {
+                    "trigger": "hand_end",
+                    "text": "Excelente. Ahora intenta ganarme el resto del partido sin ayuda."
+                }
+            ],
+            "botActions": [
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "command", "value": "TRUCO" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 1,
+                    "action": { "type": "card", "value": "1e" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 2,
+                    "action": { "type": "card", "value": "7e" }
+                },
+                {
+                    "trigger": "before_bot_action",
+                    "roundIdx": 3,
+                    "action": { "type": "card", "value": "3b" }
+                }
+            ]
+        }
+    ]
+}

package/dist/tutorials/index.d.ts

@@ -0,0 +1,5 @@
+import { ITutorialScenario, TutorialScenarioId } from "../types";
+export declare const DEFAULT_TUTORIAL_SCENARIO_ID: TutorialScenarioId;
+export declare const validateTutorialScenario: (scenario: ITutorialScenario) => ITutorialScenario;
+export declare const TUTORIAL_SCENARIOS: Record<TutorialScenarioId, ITutorialScenario>;
+export declare const getTutorialScenario: (id?: TutorialScenarioId | null | undefined) => ITutorialScenario;

package/dist/tutorials/index.js

@@ -0,0 +1,115 @@
+import { CARDS, EAnswerCommand, EEnvidoAnswerCommand, EEnvidoCommand, EFlorCommand, EHandState, ESayCommand, ETrucoCommand, } from "../types";
+import basicTrucoV1 from "./basic-truco-v1.json";
+export const DEFAULT_TUTORIAL_SCENARIO_ID = "basic-truco-v1";
+const MESSAGE_TRIGGERS = [
+    "hand_start",
+    "before_human_turn",
+    "after_human_action",
+    "before_bot_action",
+    "after_bot_action",
+    "hand_end",
+];
+const COMMANDS = new Set([
+    ...Object.values(ESayCommand),
+    ...Object.values(ETrucoCommand),
+    ...Object.values(EAnswerCommand),
+    ...Object.values(EEnvidoCommand),
+    ...Object.values(EEnvidoAnswerCommand),
+    ...Object.values(EFlorCommand),
+]);
+const HAND_STATES = new Set(Object.values(EHandState));
+const isCard = (value) => typeof value === "string" && value in CARDS;
+const isCommand = (value) => typeof value === "string" && COMMANDS.has(value);
+const assertValidActionValue = (value, context) => {
+    if (typeof value === "number") {
+        return;
+    }
+    if (isCard(value) || isCommand(value)) {
+        return;
+    }
+    throw new Error(`${context} has invalid action value: ${String(value)}`);
+};
+const validateMessage = (message, context) => {
+    if (!MESSAGE_TRIGGERS.includes(message.trigger)) {
+        throw new Error(`${context} has invalid trigger: ${message.trigger}`);
+    }
+    if (typeof message.text !== "string" || !message.text.trim()) {
+        throw new Error(`${context} must contain text`);
+    }
+    if (message.text.length > 120) {
+        throw new Error(`${context} text is longer than 120 characters`);
+    }
+    if (message.state && !HAND_STATES.has(message.state)) {
+        throw new Error(`${context} has invalid state: ${message.state}`);
+    }
+    if (message.actionValue !== undefined) {
+        assertValidActionValue(message.actionValue, context);
+    }
+};
+const validateBotAction = (botAction, context) => {
+    var _a;
+    if (botAction.trigger !== "before_bot_action") {
+        throw new Error(`${context} has invalid trigger: ${botAction.trigger}`);
+    }
+    if (botAction.state && !HAND_STATES.has(botAction.state)) {
+        throw new Error(`${context} has invalid state: ${botAction.state}`);
+    }
+    if (!["card", "command"].includes((_a = botAction.action) === null || _a === void 0 ? void 0 : _a.type)) {
+        throw new Error(`${context} has invalid action type`);
+    }
+    if (botAction.action.type === "card" && !isCard(botAction.action.value)) {
+        throw new Error(`${context} card action must use a valid card id`);
+    }
+    if (botAction.action.type === "command" && !isCommand(botAction.action.value) && typeof botAction.action.value !== "number") {
+        throw new Error(`${context} command action must use a valid command`);
+    }
+};
+const validateHand = (hand, handIdx) => {
+    if (typeof hand.goal !== "string" || !hand.goal.trim()) {
+        throw new Error(`Tutorial hand ${handIdx} must have a goal`);
+    }
+    const usedCards = new Set();
+    for (const [playerIdx, cards] of Object.entries(hand.cardsByPlayerIdx || {})) {
+        if (!Number.isInteger(Number(playerIdx))) {
+            throw new Error(`Tutorial hand ${handIdx} has invalid player index: ${playerIdx}`);
+        }
+        if (!Array.isArray(cards) || cards.length !== 3) {
+            throw new Error(`Tutorial hand ${handIdx} player ${playerIdx} must have exactly 3 cards`);
+        }
+        for (const card of cards) {
+            if (!isCard(card)) {
+                throw new Error(`Tutorial hand ${handIdx} has invalid card: ${String(card)}`);
+            }
+            if (usedCards.has(card)) {
+                throw new Error(`Tutorial hand ${handIdx} has duplicate card: ${card}`);
+            }
+            usedCards.add(card);
+        }
+    }
+    hand.messages.forEach((message, index) => validateMessage(message, `Tutorial hand ${handIdx} message ${index}`));
+    hand.botActions.forEach((botAction, index) => validateBotAction(botAction, `Tutorial hand ${handIdx} bot action ${index}`));
+};
+export const validateTutorialScenario = (scenario) => {
+    if (!scenario.id || !scenario.title || !scenario.botProfile || !scenario.botName) {
+        throw new Error("Tutorial scenario must define id, title, botProfile, and botName");
+    }
+    if (scenario.options.maxPlayers !== 2) {
+        throw new Error("Tutorial v1 scenarios must be 1v1");
+    }
+    if (!Array.isArray(scenario.hands) || !scenario.hands.length) {
+        throw new Error(`Tutorial scenario ${scenario.id} must include hands`);
+    }
+    scenario.hands.forEach((hand, index) => validateHand(hand, index + 1));
+    return scenario;
+};
+export const TUTORIAL_SCENARIOS = {
+    [basicTrucoV1.id]: validateTutorialScenario(basicTrucoV1),
+};
+export const getTutorialScenario = (id = DEFAULT_TUTORIAL_SCENARIO_ID) => {
+    const scenarioId = id !== null && id !== void 0 ? id : DEFAULT_TUTORIAL_SCENARIO_ID;
+    const scenario = TUTORIAL_SCENARIOS[scenarioId];
+    if (!scenario) {
+        throw new Error(`Tutorial scenario not found: ${scenarioId}`);
+    }
+    return scenario;
+};

package/dist/types.d.ts

@@ -46,6 +46,49 @@ export interface ILobbyOptions {
     abandonTime: number;
     satsPerPlayer: number;
 }
+export type TutorialScenarioId = "basic-truco-v1" | string;
+export type ITutorialMessageTrigger = "hand_start" | "before_human_turn" | "after_human_action" | "before_bot_action" | "after_bot_action" | "hand_end";
+export interface ITutorialMessage {
+    trigger: ITutorialMessageTrigger;
+    text: string;
+    roundIdx?: number;
+    state?: EHandState;
+    playerIdx?: number;
+    actionValue?: ECommand | ICard | number;
+}
+export interface ITutorialBotAction {
+    trigger: Extract<ITutorialMessageTrigger, "before_bot_action">;
+    roundIdx?: number;
+    state?: EHandState;
+    playerIdx?: number;
+    action: {
+        type: "card" | "command";
+        value: ICard | ECommand | number;
+    };
+}
+export interface ITutorialHand {
+    goal: string;
+    cardsByPlayerIdx: Record<string, [ICard, ICard, ICard]>;
+    messages: ITutorialMessage[];
+    botActions: ITutorialBotAction[];
+}
+export interface ITutorialScenario {
+    id: TutorialScenarioId;
+    title: string;
+    botProfile: BotProfile;
+    botName: string;
+    options: Pick<ILobbyOptions, "maxPlayers" | "matchPoint" | "flor" | "satsPerPlayer"> & Partial<Omit<ILobbyOptions, "maxPlayers" | "matchPoint" | "flor" | "satsPerPlayer">>;
+    hands: ITutorialHand[];
+}
+export interface ITutorialRuntime {
+    scenario: ITutorialScenario;
+    sentMessageKeys: Set<string>;
+    executedActionKeys: Set<string>;
+    messageQueue: Promise<void>;
+    hasQueuedMessage: boolean;
+    inputLocked: boolean;
+    messageGeneration: number;
+}
 export interface IJoinQueueOptions {
     maxPlayers: 0 | 2 | 4 | 6;
     allowBots: boolean;
@@ -151,6 +194,12 @@ export interface IPublicMatch {
     lastCard?: ICard | null;
     lastCommand?: ECommand | number | null;
     awardedSatsPerPlayer?: number;
+    tutorial?: {
+        id: TutorialScenarioId;
+        title: string;
+        botKey: string;
+        inputLocked?: boolean;
+    };
 }
 export interface IPublicMatchStats {
     spectators: number;
@@ -164,6 +213,7 @@ export interface IPublicMatchInfo {
     winnerTeamIdx: 0 | 1 | undefined;
     createdFromQueue: boolean;
     queueOptions?: IJoinQueueOptions;
+    isTutorial?: boolean;
 }
 export type IPublicChatRoom = Pick<IChatRoom, "id" | "messages">;
 export interface IChatMessage {
@@ -178,6 +228,8 @@ export interface IChatMessage {
     hidden?: boolean;
     command?: boolean;
     card?: boolean;
+    tutorial?: boolean;
+    tutorialContext?: string;
     content: string;
     sound: string | boolean;
 }
@@ -190,6 +242,7 @@ export interface IChatRoom {
     send(user: IChatMessage["user"], message: string, sound?: string | boolean): void;
     card(user: IChatMessage["user"], card: ICard, sound?: string | boolean): void;
     command(team: 0 | 1, command: ECommand | number, sound?: string | boolean): void;
+    tutorial(user: IChatMessage["user"], message: string, sound?: string | boolean, tutorialContext?: string): void;
     system(message: string, sound?: string | boolean): void;
     sound(sound: string, toTeamIdx?: "0" | "1", fromUser?: IChatMessage["user"]): void;
     emit(message?: IChatMessage, teamIdxs?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trucoshi",
-  "version": "12.1.0",
+  "version": "12.1.1",
   "description": "Truco Game Server",
   "main": "dist/types.js",
   "license": "GPL-3.0",
@@ -65,6 +65,7 @@
   "files": [
     "dist/lib/*",
     "dist/cosmetics/*",
+    "dist/tutorials/*",
     "dist/types.js",
     "dist/types.d.ts",
     "dist/events.js",