trucoshi 12.1.0 → 12.2.0

package/dist/tutorials/index.d.ts

@@ -0,0 +1,11 @@
+import { IPlayedCard, ITutorialScenario, TutorialScenarioId } from "../types";
+import type { IRound } from "../truco/Round";
+export declare const DEFAULT_TUTORIAL_SCENARIO_ID: TutorialScenarioId;
+export declare const TUTORIAL_ROUND_RESULT_TOKEN = "{{roundResult}}";
+export declare const TUTORIAL_PREVIOUS_ROUND_SCORE_TOKEN = "{{previousRoundScore}}";
+export declare const renderTutorialRoundResult: (playedCards: IPlayedCard[]) => string | null;
+export declare const renderTutorialPreviousRoundScore: (rounds: IRound[] | undefined) => string | null;
+export declare const renderTutorialMessageText: (text: string, roundCards: IPlayedCard[] | undefined, previousRounds?: IRound[]) => string | null;
+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,238 @@
+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";
+export const TUTORIAL_ROUND_RESULT_TOKEN = "{{roundResult}}";
+export const TUTORIAL_PREVIOUS_ROUND_SCORE_TOKEN = "{{previousRoundScore}}";
+const SUIT_NAMES = {
+    e: "espada",
+    b: "basto",
+    o: "oro",
+    c: "copa",
+};
+const CARD_NUMBER_NAMES = {
+    r: "12",
+    c: "11",
+    p: "10",
+};
+const getTutorialCardName = (card) => {
+    var _a, _b;
+    if (card === "1e") {
+        return "ancho de espada";
+    }
+    if (card === "1b") {
+        return "ancho de basto";
+    }
+    const suit = card.slice(-1);
+    const number = card.slice(0, -1);
+    const cardNumber = (_a = CARD_NUMBER_NAMES[number]) !== null && _a !== void 0 ? _a : number;
+    const suitName = (_b = SUIT_NAMES[suit]) !== null && _b !== void 0 ? _b : suit;
+    return `${cardNumber} de ${suitName}`;
+};
+export const renderTutorialRoundResult = (playedCards) => {
+    if (playedCards.length !== 2) {
+        return null;
+    }
+    const humanCard = playedCards.find((playedCard) => !playedCard.player.bot);
+    const botCard = playedCards.find((playedCard) => playedCard.player.bot);
+    if (!humanCard || !botCard) {
+        return null;
+    }
+    const humanValue = CARDS[humanCard.card];
+    const botValue = CARDS[botCard.card];
+    if (humanValue === undefined || botValue === undefined) {
+        return null;
+    }
+    const humanName = getTutorialCardName(humanCard.card);
+    const botName = getTutorialCardName(botCard.card);
+    if (humanValue > botValue) {
+        return `Ganaste la ronda: tu ${humanName} le gana al ${botName} del Profe.`;
+    }
+    if (botValue > humanValue) {
+        return `Gano el Profe: su ${botName} le gana a tu ${humanName}.`;
+    }
+    return `Parda: tu ${humanName} y el ${botName} tienen la misma fuerza.`;
+};
+export const renderTutorialPreviousRoundScore = (rounds) => {
+    const completedRounds = (rounds !== null && rounds !== void 0 ? rounds : []).filter((round) => round.cards.length >= 2);
+    if (!completedRounds.length) {
+        return null;
+    }
+    const score = completedRounds.reduce((current, round) => {
+        var _a;
+        if (round.tie) {
+            current.ties += 1;
+            return current;
+        }
+        if ((_a = round.winner) === null || _a === void 0 ? void 0 : _a.bot) {
+            current.bot += 1;
+            return current;
+        }
+        if (round.winner) {
+            current.human += 1;
+        }
+        return current;
+    }, { human: 0, bot: 0, ties: 0 });
+    if (score.human === 1 && score.bot === 1 && score.ties === 0) {
+        return "Van una ronda ganada cada uno.";
+    }
+    if (score.human === 1 && score.bot === 0 && score.ties === 0) {
+        return "Venis con una ronda ganada.";
+    }
+    if (score.bot === 1 && score.human === 0 && score.ties === 0) {
+        return "El Profe viene con una ronda ganada.";
+    }
+    if (score.ties === 1 && score.human === 0 && score.bot === 0) {
+        return "La primera fue parda.";
+    }
+    return "Las rondas anteriores dejaron la mano abierta.";
+};
+export const renderTutorialMessageText = (text, roundCards, previousRounds) => {
+    let renderedText = text;
+    if (renderedText.includes(TUTORIAL_ROUND_RESULT_TOKEN)) {
+        const roundResult = roundCards ? renderTutorialRoundResult(roundCards) : null;
+        if (!roundResult) {
+            return null;
+        }
+        renderedText = renderedText.split(TUTORIAL_ROUND_RESULT_TOKEN).join(roundResult);
+    }
+    if (renderedText.includes(TUTORIAL_PREVIOUS_ROUND_SCORE_TOKEN)) {
+        const previousRoundScore = renderTutorialPreviousRoundScore(previousRounds);
+        if (!previousRoundScore) {
+            return null;
+        }
+        renderedText = renderedText
+            .split(TUTORIAL_PREVIOUS_ROUND_SCORE_TOKEN)
+            .join(previousRoundScore);
+    }
+    return renderedText;
+};
+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 validateCardList = (value, context) => {
+    if (!Array.isArray(value) || value.some((card) => !isCard(card))) {
+        throw new Error(`${context} must be a list of valid card ids`);
+    }
+};
+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 > 155) {
+        throw new Error(`${context} text is longer than 155 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);
+    }
+    if (message.roundComplete !== undefined && typeof message.roundComplete !== "boolean") {
+        throw new Error(`${context} has invalid roundComplete`);
+    }
+    if (message.roundCardCount !== undefined &&
+        (!Number.isInteger(message.roundCardCount) || message.roundCardCount < 0)) {
+        throw new Error(`${context} has invalid roundCardCount`);
+    }
+    if (message.requiresHandCards !== undefined) {
+        validateCardList(message.requiresHandCards, `${context} requiresHandCards`);
+    }
+    if (message.requiresRoundCards !== undefined) {
+        validateCardList(message.requiresRoundCards, `${context} requiresRoundCards`);
+    }
+};
+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,53 @@ 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;
+    roundComplete?: boolean;
+    roundCardCount?: number;
+    requiresHandCards?: ICard[];
+    requiresRoundCards?: ICard[];
+}
+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;
@@ -53,6 +100,7 @@ export interface IJoinQueueOptions {
 export interface IQueueStatus {
     requestId: string;
     maxPlayers: 0 | 2 | 4 | 6;
+    allowBots: boolean;
     queuedPlayers: number;
     requiredPlayers: number;
     position: number;
@@ -151,6 +199,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 +218,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 +233,8 @@ export interface IChatMessage {
     hidden?: boolean;
     command?: boolean;
     card?: boolean;
+    tutorial?: boolean;
+    tutorialContext?: string;
     content: string;
     sound: string | boolean;
 }
@@ -190,6 +247,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.2.0",
   "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",

package/prisma/client/edge.js

@@ -36,11 +36,11 @@ exports.Prisma = Prisma
 exports.$Enums = {}
 
 /**
- * Prisma Client JS version: 6.19.2
+ * Prisma Client JS version: 6.19.3
  * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 Prisma.prismaVersion = {
-  client: "6.19.2",
+  client: "6.19.3",
   engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 }
 
@@ -330,7 +330,7 @@ const config = {
     "schemaEnvPath": "../../.env"
   },
   "relativePath": "..",
-  "clientVersion": "6.19.2",
+  "clientVersion": "6.19.3",
   "engineVersion": "c2990dca591cba766e3b7ef5d9e8a84796e47ab7",
   "datasourceNames": [
     "db"

package/prisma/client/index-browser.js

@@ -21,11 +21,11 @@ exports.Prisma = Prisma
 exports.$Enums = {}
 
 /**
- * Prisma Client JS version: 6.19.2
+ * Prisma Client JS version: 6.19.3
  * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 Prisma.prismaVersion = {
-  client: "6.19.2",
+  client: "6.19.3",
   engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 }
 

package/prisma/client/index.d.ts

@@ -418,7 +418,7 @@ export namespace Prisma {
   export import Exact = $Public.Exact
 
   /**
-   * Prisma Client JS version: 6.19.2
+   * Prisma Client JS version: 6.19.3
    * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
    */
   export type PrismaVersion = {

package/prisma/client/index.js

@@ -36,11 +36,11 @@ exports.Prisma = Prisma
 exports.$Enums = {}
 
 /**
- * Prisma Client JS version: 6.19.2
+ * Prisma Client JS version: 6.19.3
  * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 Prisma.prismaVersion = {
-  client: "6.19.2",
+  client: "6.19.3",
   engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 }
 
@@ -331,7 +331,7 @@ const config = {
     "schemaEnvPath": "../../.env"
   },
   "relativePath": "..",
-  "clientVersion": "6.19.2",
+  "clientVersion": "6.19.3",
   "engineVersion": "c2990dca591cba766e3b7ef5d9e8a84796e47ab7",
   "datasourceNames": [
     "db"

package/prisma/client/package.json

@@ -151,7 +151,7 @@
     },
     "./*": "./*"
   },
-  "version": "6.19.2",
+  "version": "6.19.3",
   "sideEffects": false,
   "imports": {
     "#wasm-engine-loader": {

package/prisma/client/wasm.js

@@ -36,11 +36,11 @@ exports.Prisma = Prisma
 exports.$Enums = {}
 
 /**
- * Prisma Client JS version: 6.19.2
+ * Prisma Client JS version: 6.19.3
  * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 Prisma.prismaVersion = {
-  client: "6.19.2",
+  client: "6.19.3",
   engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 }
 
@@ -330,7 +330,7 @@ const config = {
     "schemaEnvPath": "../../.env"
   },
   "relativePath": "..",
-  "clientVersion": "6.19.2",
+  "clientVersion": "6.19.3",
   "engineVersion": "c2990dca591cba766e3b7ef5d9e8a84796e47ab7",
   "datasourceNames": [
     "db"