volleyballsimtypes 0.0.388 → 0.0.390

package/dist/cjs/src/service/team/team-generator.js

@@ -9,6 +9,7 @@ const player_1 = require("../player");
 const utils_1 = require("../utils");
 const team_1 = require("./team");
 const tactics_1 = require("./tactics");
+const energy_band_1 = require("./energy-band");
 const formation_1 = require("./formation");
 const match_1 = require("../match");
 const logger_1 = __importDefault(require("../../logger"));
@@ -66,7 +67,8 @@ class TeamGenerator {
             lineup,
             liberoReplacements: [lineup[3], lineup[6]],
             pinchServerSubs: new Map(),
-            substitutionTolerance: Math.round((0, utils_1.randomNumber)(1, 50))
+            substitutionTolerance: Math.round((0, utils_1.randomNumber)(1, 50)),
+            substitutionBand: TeamGenerator.BOT_SUB_BANDS[Math.floor(Math.random() * TeamGenerator.BOT_SUB_BANDS.length)]
         });
     }
     static createLineup(players, formation) {
@@ -92,9 +94,9 @@ class TeamGenerator {
                 throw new Error('NOT_ENOUGH_PLAYERS_FOR_TEAM_2');
             out[i] = courtPlayer;
         }
-        // Can only have 12 players in the team.
+        // FIVB: 6 starters + libero + up to 6 substitutes on the bench.
         out.bench = filtered.sort(player_1.Player.compareStats)
-            .slice(0, 5);
+            .slice(0, 6);
         out[match_1.CourtPosition.LIBERO_ZONE] = libero;
         return out;
     }
@@ -107,3 +109,5 @@ TeamGenerator.RARITIES = [
     ...buildBlock(player_1.RarityEnum.LEGENDARY, 2)
 ];
 TeamGenerator.ROLES = [player_1.RoleEnum.LIBERO, player_1.RoleEnum.MIDDLE_BLOCKER, player_1.RoleEnum.OPPOSITE_HITTER, player_1.RoleEnum.OUTSIDE_HITTER, player_1.RoleEnum.SETTER];
+// Bots auto-sub on fatigue via the team-default band; they don't configure designated subs.
+TeamGenerator.BOT_SUB_BANDS = [energy_band_1.EnergyBand.WORN, energy_band_1.EnergyBand.TIRED, energy_band_1.EnergyBand.EXHAUSTED];

package/dist/esm/src/api/index.d.ts

@@ -1,4 +1,4 @@
-import { BoxScore, DataProps, DeclineStatus, Division as _Division, League as _League, Match as _Match, MatchSet as _MatchSet, Player as _Player, PlayerPosition, Qualifier as _Qualifier, QualifierMatch as _QualifierMatch, Rally as _Rally, RallyEvent as _RallyEvent, Season as _Season, Standing as _Standing, Team as _Team, Tournament as _Tournament, TournamentMatch as _TournamentMatch, National as _National, NationalMatch as _NationalMatch, Country as _Country, CourtPosition } from '../service';
+import { BoxScore, DataProps, DeclineStatus, Division as _Division, League as _League, Match as _Match, MatchSet as _MatchSet, Player as _Player, PlayerPosition, Qualifier as _Qualifier, QualifierMatch as _QualifierMatch, Rally as _Rally, RallyEvent as _RallyEvent, Season as _Season, Standing as _Standing, Team as _Team, Tournament as _Tournament, TournamentMatch as _TournamentMatch, National as _National, NationalMatch as _NationalMatch, Country as _Country, CourtPosition, ConditionLogic, PinchCondition, SubBand } from '../service';
 export type Rally = DataProps<_Rally> & {
     homePlayerPosition: PlayerPosition[];
     awayPlayerPosition: PlayerPosition[];
@@ -56,12 +56,22 @@ export interface StartingLineup {
     [CourtPosition.LIBERO_ZONE]?: string;
     bench: string[];
 }
+export interface ApiDesignatedSub {
+    starterId: string;
+    benchId?: string;
+    isPinchServer: boolean;
+    fatigueBand?: SubBand;
+    conditions?: PinchCondition[];
+    conditionLogic?: ConditionLogic;
+}
 export interface Tactics {
     lineup: StartingLineup;
     substitutionTolerance: number;
     liberoReplacements: string[];
     pinchServerSubs: Record<string, string>;
     receiveRotationOffset: boolean;
+    designatedSubs: ApiDesignatedSub[];
+    substitutionBand: SubBand;
 }
 export type Team = Omit<DataProps<_Team>, 'roster' | '_rating' | 'rating' | 'tactics'> & {
     roster: Player[];

package/dist/esm/src/data/models/tactics.d.ts

@@ -1,7 +1,7 @@
 import * as Sequelize from 'sequelize';
 import { Model, Optional } from 'sequelize';
 import { PlayerId, TeamId, TeamModel } from '.';
-import { CourtPosition } from '../../service';
+import { ConditionLogic, CourtPosition, PinchCondition, SubBand } from '../../service';
 export interface TacticsLineupAttributes {
     [CourtPosition.LIBERO_ZONE]?: PlayerId;
     [CourtPosition.LEFT_BACK]: PlayerId;
@@ -13,6 +13,14 @@ export interface TacticsLineupAttributes {
     bench: PlayerId[];
 }
 export type PinchServerSubsAttributes = Record<PlayerId, PlayerId>;
+export interface DesignatedSubAttributes {
+    starterId: PlayerId;
+    benchId?: PlayerId;
+    isPinchServer: boolean;
+    fatigueBand?: SubBand;
+    conditions?: PinchCondition[];
+    conditionLogic?: ConditionLogic;
+}
 export interface TacticsAttributes {
     team_id: string;
     substitution_tolerance: number;
@@ -20,10 +28,12 @@ export interface TacticsAttributes {
     libero_replacements: PlayerId[];
     pinch_server_subs: PinchServerSubsAttributes;
     receive_rotation_offset: boolean;
+    designated_subs: DesignatedSubAttributes[];
+    substitution_band: SubBand;
 }
 export type TacticsPk = 'team_id';
 export type TacticsId = TacticsModel[TacticsPk];
-export type TacticsOptionalAttributes = 'substitution_tolerance' | 'lineup' | 'libero_replacements' | 'pinch_server_subs' | 'receive_rotation_offset';
+export type TacticsOptionalAttributes = 'substitution_tolerance' | 'lineup' | 'libero_replacements' | 'pinch_server_subs' | 'receive_rotation_offset' | 'designated_subs' | 'substitution_band';
 export type TacticsCreationAttributes = Optional<TacticsAttributes, TacticsOptionalAttributes>;
 export declare class TacticsModel extends Model<TacticsAttributes, TacticsCreationAttributes> implements TacticsAttributes {
     team_id: string;
@@ -32,6 +42,8 @@ export declare class TacticsModel extends Model<TacticsAttributes, TacticsCreati
     libero_replacements: PlayerId[];
     pinch_server_subs: PinchServerSubsAttributes;
     receive_rotation_offset: boolean;
+    designated_subs: DesignatedSubAttributes[];
+    substitution_band: SubBand;
     team: TeamModel;
     getTeam: Sequelize.BelongsToGetAssociationMixin<TeamModel>;
     setTeam: Sequelize.BelongsToSetAssociationMixin<TeamModel, TeamId>;

package/dist/esm/src/data/models/tactics.js

@@ -36,6 +36,16 @@ export class TacticsModel extends Model {
                 type: DataTypes.BOOLEAN,
                 allowNull: false,
                 defaultValue: false
+            },
+            designated_subs: {
+                type: DataTypes.JSONB,
+                allowNull: false,
+                defaultValue: []
+            },
+            substitution_band: {
+                type: DataTypes.STRING,
+                allowNull: false,
+                defaultValue: 'TIRED'
             }
         }, {
             sequelize,

package/dist/esm/src/data/transformers/tactics.js

@@ -36,7 +36,16 @@ function transformToAttributes(tactics, teamId) {
         receive_rotation_offset: tactics.receiveRotationOffset ?? false,
         lineup: transformFromLineup(tactics.lineup),
         libero_replacements: tactics.liberoReplacements.map((lr) => lr.id),
-        pinch_server_subs: Object.fromEntries([...tactics.pinchServerSubs].map(([k, v]) => [k.id, v.id]))
+        pinch_server_subs: Object.fromEntries([...tactics.pinchServerSubs].map(([k, v]) => [k.id, v.id])),
+        substitution_band: tactics.substitutionBand,
+        designated_subs: tactics.designatedSubs.map(ds => ({
+            starterId: ds.starter.id,
+            benchId: ds.bench?.id,
+            isPinchServer: ds.isPinchServer,
+            fatigueBand: ds.fatigueBand,
+            conditions: ds.conditions,
+            conditionLogic: ds.conditionLogic
+        }))
     };
 }
 function buildPinchServerSubs(pinchServerSubs, roster) {
@@ -52,7 +61,16 @@ function transformToObject(model, roster) {
         receiveRotationOffset: model.receive_rotation_offset,
         lineup: transformToLineup(model.lineup, roster),
         liberoReplacements: model.libero_replacements.map((lr) => findPlayer(lr, roster)),
-        pinchServerSubs: buildPinchServerSubs(model.pinch_server_subs, roster)
+        pinchServerSubs: buildPinchServerSubs(model.pinch_server_subs, roster),
+        substitutionBand: model.substitution_band,
+        designatedSubs: (model.designated_subs ?? []).map(d => ({
+            starter: findPlayer(d.starterId, roster),
+            bench: d.benchId != null ? findPlayer(d.benchId, roster) : undefined,
+            isPinchServer: d.isPinchServer,
+            fatigueBand: d.fatigueBand,
+            conditions: d.conditions,
+            conditionLogic: d.conditionLogic
+        }))
     });
 }
 export { transformToObject as transformToTactics, transformToAttributes as transformFromTactics };

package/dist/esm/src/service/competition/standing.js

@@ -33,20 +33,28 @@ export class Standing {
         this.totalMatches = this.matchesWon + this.matchesLost;
     }
     static sortFn(matches) {
+        // A zero denominator (no sets/points lost) is the BEST possible ratio, not the worst. The stored
+        // setsRatio/pointsRatio fall back to 0 in that case (and the table shows "MAX"), so we compare an
+        // effective ratio here that treats "won with nothing lost" as +Infinity, ranking it highest.
+        const effectiveRatio = (won, lost) => lost > 0 ? won / lost : (won > 0 ? Infinity : 0);
         return (standingA, standingB) => {
             if (standingB.points > standingA.points)
                 return 1;
-            else if (standingA.points > standingB.points)
+            if (standingA.points > standingB.points)
                 return -1;
-            else if (standingB.setsRatio > standingA.setsRatio)
+            const setRatioA = effectiveRatio(standingA.setsWon, standingA.setsLost);
+            const setRatioB = effectiveRatio(standingB.setsWon, standingB.setsLost);
+            if (setRatioB > setRatioA)
                 return 1;
-            else if (standingA.setsRatio > standingB.setsRatio)
+            if (setRatioA > setRatioB)
                 return -1;
-            else if (standingB.pointsRatio > standingA.pointsRatio)
+            const pointRatioA = effectiveRatio(standingA.pointsWon, standingA.pointsLost);
+            const pointRatioB = effectiveRatio(standingB.pointsWon, standingB.pointsLost);
+            if (pointRatioB > pointRatioA)
                 return 1;
-            else if (standingA.pointsRatio > standingB.pointsRatio)
+            if (pointRatioA > pointRatioB)
                 return -1;
-            else if (matches.length > 0) {
+            if (matches.length > 0) {
                 const ab = matches.find((match) => match.homeTeam.id === standingA.teamId && match.awayTeam.id === standingB.teamId);
                 const ba = matches.find((match) => match.awayTeam.id === standingA.teamId && match.homeTeam.id === standingB.teamId);
                 if (ba == null && ab == null)
@@ -63,8 +71,7 @@ export class Standing {
                 const b = (ba.homeScore ?? 0) + (ab.awayScore ?? 0);
                 return b - a;
             }
-            else
-                return 0;
+            return 0;
         };
     }
     calculateStanding(matches) {

package/dist/esm/src/service/competition/standing.test.js

@@ -134,6 +134,18 @@ describe('Standing', () => {
             const sorted = [b, a].sort(Standing.sortFn([]));
             expect(sorted[0].teamId).toBe(idA);
         });
+        it('ranks a team with no sets lost (MAX ratio) above a finite setsRatio when points tie', () => {
+            const idA = uuidv4();
+            const idB = uuidv4();
+            // Both 6 points. A swept its matches (won30=2 → setsWon=6, setsLost=0 → ratio is MAX/infinite);
+            // B also has 6 points but conceded sets (won31=2 → setsWon=6, setsLost=2 → setsRatio=3).
+            // The undefeated-in-sets team must rank FIRST, not last (the divide-by-zero bug ranked it last).
+            const a = makeStanding(idA, { won30: 2 });
+            const b = makeStanding(idB, { won31: 2 });
+            const sorted = [b, a].sort(Standing.sortFn([]));
+            expect(sorted[0].teamId).toBe(idA);
+            expect(sorted[1].teamId).toBe(idB);
+        });
         it('falls back to pointsRatio when points and setsRatio are equal', () => {
             const idA = uuidv4();
             const idB = uuidv4();

package/dist/esm/src/service/team/designated-sub.d.ts

@@ -0,0 +1,11 @@
+import { Player } from '../player';
+import { SubBand } from './energy-band';
+import { ConditionLogic, PinchCondition } from './pinch-condition';
+export interface DesignatedSub {
+    readonly starter: Player;
+    readonly bench?: Player;
+    readonly isPinchServer: boolean;
+    readonly fatigueBand?: SubBand;
+    readonly conditions?: PinchCondition[];
+    readonly conditionLogic?: ConditionLogic;
+}

package/dist/esm/src/service/team/designated-sub.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/service/team/energy-band.d.ts

@@ -0,0 +1,8 @@
+export declare enum EnergyBand {
+    ENERGETIC = "ENERGETIC",
+    WORN = "WORN",
+    TIRED = "TIRED",
+    EXHAUSTED = "EXHAUSTED"
+}
+export type SubBand = EnergyBand | 'NEVER';
+export declare const ENERGY_BAND_ORDER: readonly EnergyBand[];

package/dist/esm/src/service/team/energy-band.js

@@ -0,0 +1,17 @@
+// The named fatigue bands a player's energy falls into. The numeric cutoffs and per-band performance
+// multipliers live in the simulator (VolleyballSim court-player.ts ENERGY_BANDS); this enum is the shared
+// vocabulary used by tactics configuration (substitution thresholds) and, later, the UI.
+export var EnergyBand;
+(function (EnergyBand) {
+    EnergyBand["ENERGETIC"] = "ENERGETIC";
+    EnergyBand["WORN"] = "WORN";
+    EnergyBand["TIRED"] = "TIRED";
+    EnergyBand["EXHAUSTED"] = "EXHAUSTED";
+})(EnergyBand || (EnergyBand = {}));
+// Ordered best -> worst. Used to compare "is this player at-or-below the configured sub band".
+export const ENERGY_BAND_ORDER = [
+    EnergyBand.ENERGETIC,
+    EnergyBand.WORN,
+    EnergyBand.TIRED,
+    EnergyBand.EXHAUSTED
+];

package/dist/esm/src/service/team/index.d.ts

@@ -3,3 +3,6 @@ export * from './team-generator';
 export * from './formation';
 export * from './tactics';
 export * from './team-name';
+export * from './energy-band';
+export * from './pinch-condition';
+export * from './designated-sub';

package/dist/esm/src/service/team/index.js

@@ -3,3 +3,6 @@ export * from './team-generator';
 export * from './formation';
 export * from './tactics';
 export * from './team-name';
+export * from './energy-band';
+export * from './pinch-condition';
+export * from './designated-sub';

package/dist/esm/src/service/team/pinch-condition.d.ts

@@ -0,0 +1,56 @@
+export declare enum PinchConditionType {
+    ASAP = "ASAP",// every time the linked starter wins back the serve
+    TEAM_SET_POINT = "TEAM_SET_POINT",// team within `margin` of winning the set
+    OPPONENT_SET_POINT = "OPPONENT_SET_POINT",// opponent within `margin` of winning the set
+    SCORE_DIFF = "SCORE_DIFF",// team trailing/leading by at least `points`
+    AFTER_ROTATIONS = "AFTER_ROTATIONS",// from the team's Nth serve turn in the set onward
+    FROM_SET = "FROM_SET",// only set N or later
+    MIN_OWN_SCORE = "MIN_OWN_SCORE"
+}
+export declare enum OpponentRelation {
+    AHEAD = "AHEAD",
+    BEHIND = "BEHIND",
+    EITHER = "EITHER"
+}
+export declare enum ScoreDirection {
+    TRAILING = "TRAILING",
+    LEADING = "LEADING"
+}
+export interface AsapCondition {
+    readonly type: PinchConditionType.ASAP;
+}
+export interface TeamSetPointCondition {
+    readonly type: PinchConditionType.TEAM_SET_POINT;
+    readonly margin: number;
+    readonly opponent: OpponentRelation;
+}
+export interface OpponentSetPointCondition {
+    readonly type: PinchConditionType.OPPONENT_SET_POINT;
+    readonly margin: number;
+}
+export interface ScoreDiffCondition {
+    readonly type: PinchConditionType.SCORE_DIFF;
+    readonly direction: ScoreDirection;
+    readonly points: number;
+}
+export interface AfterRotationsCondition {
+    readonly type: PinchConditionType.AFTER_ROTATIONS;
+    readonly rotations: number;
+}
+export interface FromSetCondition {
+    readonly type: PinchConditionType.FROM_SET;
+    readonly set: number;
+}
+export interface MinOwnScoreCondition {
+    readonly type: PinchConditionType.MIN_OWN_SCORE;
+    readonly score: number;
+}
+export type PinchCondition = AsapCondition | TeamSetPointCondition | OpponentSetPointCondition | ScoreDiffCondition | AfterRotationsCondition | FromSetCondition | MinOwnScoreCondition;
+export type ConditionLogic = 'ALL' | 'ANY';
+export interface PinchSetState {
+    readonly ownScore: number;
+    readonly opponentScore: number;
+    readonly setTarget: number;
+    readonly setNumber: number;
+    readonly ownServeTurns: number;
+}

package/dist/esm/src/service/team/pinch-condition.js

@@ -0,0 +1,24 @@
+// Conditions that gate when a pinch server is forced in to serve (in for its linked starter when the team
+// wins back the serve, out the moment the serve is lost). Each condition is evaluated against the live set
+// state; a pinch entry combines them with ALL (every condition must hold) or ANY (one is enough).
+export var PinchConditionType;
+(function (PinchConditionType) {
+    PinchConditionType["ASAP"] = "ASAP";
+    PinchConditionType["TEAM_SET_POINT"] = "TEAM_SET_POINT";
+    PinchConditionType["OPPONENT_SET_POINT"] = "OPPONENT_SET_POINT";
+    PinchConditionType["SCORE_DIFF"] = "SCORE_DIFF";
+    PinchConditionType["AFTER_ROTATIONS"] = "AFTER_ROTATIONS";
+    PinchConditionType["FROM_SET"] = "FROM_SET";
+    PinchConditionType["MIN_OWN_SCORE"] = "MIN_OWN_SCORE"; // only once own score >= N
+})(PinchConditionType || (PinchConditionType = {}));
+export var OpponentRelation;
+(function (OpponentRelation) {
+    OpponentRelation["AHEAD"] = "AHEAD";
+    OpponentRelation["BEHIND"] = "BEHIND";
+    OpponentRelation["EITHER"] = "EITHER";
+})(OpponentRelation || (OpponentRelation = {}));
+export var ScoreDirection;
+(function (ScoreDirection) {
+    ScoreDirection["TRAILING"] = "TRAILING";
+    ScoreDirection["LEADING"] = "LEADING";
+})(ScoreDirection || (ScoreDirection = {}));

package/dist/esm/src/service/team/schemas/designated-sub.z.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { Player } from '../../player';
+import { EnergyBand } from '../energy-band';
+import { OpponentRelation, PinchConditionType, ScoreDirection } from '../pinch-condition';
+export declare const SubBandSchema: z.ZodUnion<readonly [z.ZodEnum<typeof EnergyBand>, z.ZodLiteral<"NEVER">]>;
+export declare const PinchConditionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.ASAP>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.TEAM_SET_POINT>;
+    margin: z.ZodNumber;
+    opponent: z.ZodEnum<typeof OpponentRelation>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.OPPONENT_SET_POINT>;
+    margin: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.SCORE_DIFF>;
+    direction: z.ZodEnum<typeof ScoreDirection>;
+    points: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.AFTER_ROTATIONS>;
+    rotations: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.FROM_SET>;
+    set: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<PinchConditionType.MIN_OWN_SCORE>;
+    score: z.ZodNumber;
+}, z.core.$strip>], "type">;
+export declare const ConditionLogicSchema: z.ZodUnion<readonly [z.ZodLiteral<"ALL">, z.ZodLiteral<"ANY">]>;
+export declare const DesignatedSubSchema: z.ZodObject<{
+    starter: z.ZodCustom<Player, Player>;
+    bench: z.ZodOptional<z.ZodCustom<Player, Player>>;
+    isPinchServer: z.ZodBoolean;
+    fatigueBand: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof EnergyBand>, z.ZodLiteral<"NEVER">]>>;
+    conditions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.ASAP>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.TEAM_SET_POINT>;
+        margin: z.ZodNumber;
+        opponent: z.ZodEnum<typeof OpponentRelation>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.OPPONENT_SET_POINT>;
+        margin: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.SCORE_DIFF>;
+        direction: z.ZodEnum<typeof ScoreDirection>;
+        points: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.AFTER_ROTATIONS>;
+        rotations: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.FROM_SET>;
+        set: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<PinchConditionType.MIN_OWN_SCORE>;
+        score: z.ZodNumber;
+    }, z.core.$strip>], "type">>>;
+    conditionLogic: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ALL">, z.ZodLiteral<"ANY">]>>;
+}, z.core.$strip>;

package/dist/esm/src/service/team/schemas/designated-sub.z.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { Player } from '../../player';
+import { EnergyBand } from '../energy-band';
+import { OpponentRelation, PinchConditionType, ScoreDirection } from '../pinch-condition';
+const playerInstanceSchema = z.custom((v) => v instanceof Player, {
+    message: 'INVALID_PLAYER_INSTANCE'
+});
+export const SubBandSchema = z.union([z.nativeEnum(EnergyBand), z.literal('NEVER')]);
+export const PinchConditionSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal(PinchConditionType.ASAP) }),
+    z.object({ type: z.literal(PinchConditionType.TEAM_SET_POINT), margin: z.number().int().min(1).max(25), opponent: z.nativeEnum(OpponentRelation) }),
+    z.object({ type: z.literal(PinchConditionType.OPPONENT_SET_POINT), margin: z.number().int().min(1).max(25) }),
+    z.object({ type: z.literal(PinchConditionType.SCORE_DIFF), direction: z.nativeEnum(ScoreDirection), points: z.number().int().min(1).max(25) }),
+    z.object({ type: z.literal(PinchConditionType.AFTER_ROTATIONS), rotations: z.number().int().min(1).max(6) }),
+    z.object({ type: z.literal(PinchConditionType.FROM_SET), set: z.number().int().min(1).max(5) }),
+    z.object({ type: z.literal(PinchConditionType.MIN_OWN_SCORE), score: z.number().int().min(0).max(40) })
+]);
+export const ConditionLogicSchema = z.union([z.literal('ALL'), z.literal('ANY')]);
+export const DesignatedSubSchema = z.object({
+    starter: playerInstanceSchema,
+    bench: playerInstanceSchema.optional(),
+    isPinchServer: z.boolean(),
+    fatigueBand: SubBandSchema.optional(),
+    conditions: z.array(PinchConditionSchema).optional(),
+    conditionLogic: ConditionLogicSchema.optional()
+}).superRefine((data, ctx) => {
+    if (data.isPinchServer) {
+        // Pinch mode needs a designated bench player (the server) and at least one condition.
+        if (data.bench == null) {
+            ctx.addIssue({ code: 'custom', message: 'PINCH_SERVER_REQUIRES_BENCH', path: ['bench'] });
+        }
+        if (data.conditions == null || data.conditions.length === 0) {
+            ctx.addIssue({ code: 'custom', message: 'PINCH_SERVER_REQUIRES_CONDITIONS', path: ['conditions'] });
+        }
+    }
+});

package/dist/esm/src/service/team/schemas/tactics.z.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Player } from '../../player';
+import { EnergyBand } from '../energy-band';
 export declare const TacticsInputSchema: z.ZodObject<{
     lineup: z.ZodObject<{
         4: z.ZodCustom<Player, Player>;
@@ -15,5 +16,36 @@ export declare const TacticsInputSchema: z.ZodObject<{
     liberoReplacements: z.ZodArray<z.ZodCustom<Player, Player>>;
     receiveRotationOffset: z.ZodDefault<z.ZodBoolean>;
     pinchServerSubs: z.ZodCustom<Map<Player, Player>, Map<Player, Player>>;
+    designatedSubs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        starter: z.ZodCustom<Player, Player>;
+        bench: z.ZodOptional<z.ZodCustom<Player, Player>>;
+        isPinchServer: z.ZodBoolean;
+        fatigueBand: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof EnergyBand>, z.ZodLiteral<"NEVER">]>>;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.ASAP>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.TEAM_SET_POINT>;
+            margin: z.ZodNumber;
+            opponent: z.ZodEnum<typeof import("..").OpponentRelation>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.OPPONENT_SET_POINT>;
+            margin: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.SCORE_DIFF>;
+            direction: z.ZodEnum<typeof import("..").ScoreDirection>;
+            points: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.AFTER_ROTATIONS>;
+            rotations: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.FROM_SET>;
+            set: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<import("..").PinchConditionType.MIN_OWN_SCORE>;
+            score: z.ZodNumber;
+        }, z.core.$strip>], "type">>>;
+        conditionLogic: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ALL">, z.ZodLiteral<"ANY">]>>;
+    }, z.core.$strip>>>;
+    substitutionBand: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<typeof EnergyBand>, z.ZodLiteral<"NEVER">]>>;
 }, z.core.$strip>;
 export type TacticsInput = z.infer<typeof TacticsInputSchema>;

package/dist/esm/src/service/team/schemas/tactics.z.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { Player } from '../../player';
+import { EnergyBand } from '../energy-band';
+import { DesignatedSubSchema, SubBandSchema } from './designated-sub.z';
 const playerInstanceSchema = z.custom((v) => v instanceof Player, {
     message: 'INVALID_PLAYER_INSTANCE'
 });
@@ -18,7 +20,8 @@ const lineupSchema = z.object({
     [MIDDLE_BACK]: playerInstanceSchema,
     [RIGHT_BACK]: playerInstanceSchema,
     [LIBERO_ZONE]: playerInstanceSchema.optional(),
-    bench: z.array(playerInstanceSchema)
+    // FIVB: up to 6 substitutes (the libero is tracked separately in LIBERO_ZONE).
+    bench: z.array(playerInstanceSchema).max(6)
 }).superRefine((data, ctx) => {
     const players = [
         data[LEFT_FRONT],
@@ -47,5 +50,8 @@ export const TacticsInputSchema = z.object({
     // Default false keeps every existing Tactics.create({...}) call (that omits this) valid.
     receiveRotationOffset: z.boolean().default(false),
     pinchServerSubs: z.custom((v) => v instanceof Map &&
-        Array.from(v.entries()).every(([k, val]) => k instanceof Player && val instanceof Player), { message: 'INVALID_PINCH_SERVER_SUBS' })
+        Array.from(v.entries()).every(([k, val]) => k instanceof Player && val instanceof Player), { message: 'INVALID_PINCH_SERVER_SUBS' }),
+    // New (designated-subs feature). Defaults keep every existing Tactics.create({...}) call valid.
+    designatedSubs: z.array(DesignatedSubSchema).default([]),
+    substitutionBand: SubBandSchema.default(EnergyBand.TIRED)
 });

package/dist/esm/src/service/team/schemas/team.z.d.ts

@@ -24,6 +24,37 @@ export declare const TeamInputSchema: z.ZodObject<{
         liberoReplacements: z.ZodArray<z.ZodCustom<Player, Player>>;
         receiveRotationOffset: z.ZodDefault<z.ZodBoolean>;
         pinchServerSubs: z.ZodCustom<Map<Player, Player>, Map<Player, Player>>;
+        designatedSubs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            starter: z.ZodCustom<Player, Player>;
+            bench: z.ZodOptional<z.ZodCustom<Player, Player>>;
+            isPinchServer: z.ZodBoolean;
+            fatigueBand: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<typeof import("..").EnergyBand>, z.ZodLiteral<"NEVER">]>>;
+            conditions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.ASAP>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.TEAM_SET_POINT>;
+                margin: z.ZodNumber;
+                opponent: z.ZodEnum<typeof import("..").OpponentRelation>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.OPPONENT_SET_POINT>;
+                margin: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.SCORE_DIFF>;
+                direction: z.ZodEnum<typeof import("..").ScoreDirection>;
+                points: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.AFTER_ROTATIONS>;
+                rotations: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.FROM_SET>;
+                set: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<import("..").PinchConditionType.MIN_OWN_SCORE>;
+                score: z.ZodNumber;
+            }, z.core.$strip>], "type">>>;
+            conditionLogic: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ALL">, z.ZodLiteral<"ANY">]>>;
+        }, z.core.$strip>>>;
+        substitutionBand: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<typeof import("..").EnergyBand>, z.ZodLiteral<"NEVER">]>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type TeamInput = z.infer<typeof TeamInputSchema>;

package/dist/esm/src/service/team/tactics.d.ts

@@ -1,5 +1,7 @@
 import { CourtPosition } from '../match';
 import { Player } from '../player';
+import { DesignatedSub } from './designated-sub';
+import { SubBand } from './energy-band';
 export interface StartingLineup {
     readonly [CourtPosition.LEFT_FRONT]: Player;
     readonly [CourtPosition.MIDDLE_FRONT]: Player;
@@ -16,6 +18,8 @@ export interface TacticsOpts {
     readonly liberoReplacements: Player[];
     readonly pinchServerSubs: Map<Player, Player>;
     readonly receiveRotationOffset: boolean;
+    readonly designatedSubs: DesignatedSub[];
+    readonly substitutionBand: SubBand;
 }
 export declare class Tactics {
     readonly lineup: StartingLineup;
@@ -23,6 +27,8 @@ export declare class Tactics {
     readonly liberoReplacements: Player[];
     readonly pinchServerSubs: Map<Player, Player>;
     readonly receiveRotationOffset: boolean;
+    readonly designatedSubs: DesignatedSub[];
+    readonly substitutionBand: SubBand;
     static create(input: unknown): Tactics;
     private constructor();
     findPlayerInLineup(id: string): CourtPosition | undefined;

package/dist/esm/src/service/team/tactics.js

@@ -1,4 +1,5 @@
 import { CourtPosition } from '../match';
+import { EnergyBand } from './energy-band';
 import { TacticsInputSchema } from './schemas/tactics.z';
 export class Tactics {
     static create(input) {
@@ -13,12 +14,14 @@ export class Tactics {
         }
         return new Tactics(result.data);
     }
-    constructor({ lineup, pinchServerSubs, liberoReplacements, substitutionTolerance = 1, receiveRotationOffset = false }) {
+    constructor({ lineup, pinchServerSubs, liberoReplacements, substitutionTolerance = 1, receiveRotationOffset = false, designatedSubs = [], substitutionBand = EnergyBand.TIRED }) {
         this.lineup = lineup;
         this.substitutionTolerance = substitutionTolerance;
         this.pinchServerSubs = pinchServerSubs;
         this.liberoReplacements = liberoReplacements;
         this.receiveRotationOffset = receiveRotationOffset;
+        this.designatedSubs = designatedSubs;
+        this.substitutionBand = substitutionBand;
     }
     findPlayerInLineup(id) {
         if (this.lineup.bench.some(p => p.id === id))

package/dist/esm/src/service/team/team-generator.d.ts

@@ -2,6 +2,7 @@ import { Player, RarityEnum, Role } from '../player';
 import { Team } from './team';
 import { Country } from '../country';
 import { Tactics } from './tactics';
+import { EnergyBand } from './energy-band';
 export declare class TeamGenerator {
     static readonly TEAM_PER_DIVISION = 16;
     static readonly RARITIES: RarityEnum[];
@@ -10,6 +11,7 @@ export declare class TeamGenerator {
     private static comparePlayers;
     static createRoster(country: Country): Player[];
     static createTeams(divisionId: string, country: Country): Team[];
+    static readonly BOT_SUB_BANDS: EnergyBand[];
     static createTactics(roster: Player[]): Tactics;
     private static createLineup;
 }