Skip to main content

Draws Governor

import { drawsGovernor } from 'tods-competition-factory';

addAdHocMatchUps​

Adds matchUps generated by generateAdHocMatchUps to specified structure within an AD_HOC drawDefinition.

engine.addAdHocMatchUps({
  structureId, // optional if there is only one structure in drawDefinition
  matchUps,
  drawId,
});

addDrawDefinitionTimeItem​

Adds a time item to a drawDefinition.

engine.addDrawDefinitionTimeItem({
  drawId, // required
  timeItem, // required - time item object
  itemType, // required - time item type
});

Purpose: Attach time-based metadata to draws.

addFinishingRounds​

Adds finishing rounds to an existing structure for placement matchUps.

engine.addFinishingRounds({
  drawId, // required
  structureId, // required
  finishingPositions, // required - array of positions to play off
});

Purpose: Add placement matchUps for specific finishing positions.

addGoesTo​

Adds a link between structures indicating progression path.

engine.addGoesTo({
  drawId, // required
  sourceStructureId, // required
  targetStructureId, // required
  roundNumber, // optional - specific round
});

Purpose: Define progression paths between structures.

adHocPositionSwap​

Swaps participant assignments in two unscored matchUps that are part of the same roundNumber in and AD_HOC structure. This method and one of the two participantIds are returned in validActions by positionActions which calls adHocMatchUpActions, meaning this method is not normally called directly.

engine.adHocPositionSwap({
  participantIds,
  structureId,
  roundNumber,
  drawId,
});

addPlayoffStructures​

Adds playoff structures to an existing drawDefinition. This method creates PLAY_OFF structures linked via LOSER links from the specified source structure.

engine.addPlayoffStructures({
  drawId,
  structureId,
  roundNumbers: [3], // required if no playoffPositions - source roundNumbers which will feed target structures, e.g. [1, 2]
  roundProfiles, // optional - source roundNumbers as Object.keys with depth as Object.values, e.g. [{ 1: 2}, {2: 1}]
  playoffPositions: [3, 4], // required if not provided roundNumbers
  playoffAttributes, // optional - mapping of exitProfile or finishingPositionRange to structure names (see Finishing Positions concept)
  exitProfileLimit, // limit playoff rounds generated by the attributes present in playoffAttributes
  playoffStructureNameBase, // optional - base word for default playoff naming, e.g. 'Playoff'
});

// example use of playoffAttributes - will generated playoff structure from 2nd round with structureName: 'BRONZE'
const playoffAttributes = {
  '0-2': { name: 'BRONZE', abbreviation: 'B' },
};
tip

For multi-level playoff trees (e.g., COMPASS topologies), use the withPlayoffs parameter on generateDrawDefinition instead of chaining multiple addPlayoffStructures calls. The withPlayoffs.roundPlayoffs field supports recursive nesting, building the entire tree in a single call. See Custom Playoff Topologies.

addQualifyingStructure​

engine.addQualifyingStructure({
  targetStructureId, // required: structure for which participants will qualify
  qualifyingPositions, // optional: specify the # of qualifyingPositions
  qualifyingRoundNumber, // optional: determine qualifyingPositions by # of matchUps in specified round; does not apply to ROUND_ROBIN
  structureOptions, // optional: specific to ROUND_ROBIN generation
  structureName, // optional
  drawSize,
  drawType, // optional: defaults to SINGLE_ELIMINATION
  drawId, // required: draw within which target structure appears
});

addVoluntaryConsolationStage​

Modifies the entryProfile for a draw to allow { entryStage: VOLUNTARY_CONSOLATION }

engine.addVoluntaryConsolationStage({
  drawSize,
  drawId,
});

addVoluntaryConsolationStructure​

Generates a new structure within a drawDefinition if any draw entries are present for { entryStage: VOLUNTARY_CONSOLATION }.

engine.addVoluntaryConsolationStructure({
  structureAbbreviation, // optional
  structureName, // optional - defaults to 'VOLUNTARY_CONSOLATION'
  drawId,
});

allPlayoffPositionsFilled​

Checks if all playoff positions for a structure have been filled.

const { allFilled } = engine.allPlayoffPositionsFilled({
  drawId, // required
  structureId, // required
});

Returns: Boolean indicating if all playoff positions are assigned.

alternateDrawPositionAssignment​

Replaces an existing drawPosition assignment with an alternateParticipantId. This method is included in validActions for positionActions

engine.alternateDrawPositionAssignment({
  alternateParticipantId,
  drawPosition,
  structureId,
  drawId,
});

assignDrawPosition​

Low level function normally called by higher order convenience functions.

engine.assignDrawPosition({
  participantId, // optional - if assigning position to a participant
  drawPosition,
  structureId,
  qualifier, // optional boolean, if assigning a space for a qualifier
  drawId,
  bye, // optional boolean, if assigning a bye
});

assignDrawPositionBye​

engine.assignDrawPositionBye({
  structureId,
  drawId,
});

attachQualifyingStructure​

engine.attachQualifyingStructure({
  structure, // required: structure object; see `generateQualifyingStructure`
  drawId, // required: id of drawDedfinition to which structure will be attached
  link, // required
});

automatedPlayoffPositioning​

For Round Robin structures, uses Round Robin Tallies to position participants in playoff structure(s).

engine.automatedPlayoffPositioning({
  structureId: mainStructure.structureId,
  provisionalPositioning, // optional boolean, defaults to false; when true will honor provisionalOrder if no groupOrder is found in tallyResults
  applyPositioning, // optional boolean, defaults to true; when false will return positioning but not apply it to playoff structures
  drawId,
});

automatedPositioning​

Positions participants in a draw structure. See examples: Draw Operations, Basic Rollback.

See Policies.

engine.automatedPositioning({ drawId, structureId });

autoSeeding​

note

Only generates seeding. To apply engine.setParticipantScaleItems({ scaleItemsWithParticipantIds }. :::. See examples: Using Factory autoSeeding(), Seeding from Rankings, Event Type Alignment.

const { scaleItemsWithParticipantIds } = engine.autoSeeding({
  policyDefinitions, // seeding policyDefinition determines the # of seeds for given participantsCount/drawSize
  scaleAttributes, // { scaleType, scaleName, eventType, accessor }
  scaleName, // Optional - defaults to scaleAttributes.scaleName
  drawSize, // Optional - defaults to calculation based on # of entries
  eventId, // required - necessary for resolving entries
  drawId, // Optional - will use flight.drawEntries or drawDefinition.entries rather than event.entries
  stage, // Optional - filters entries by specified stage

  scaleSortMethod, // Optional - user defined sorting method
  sortDescending, // Optional - defaults to false
});

engine.setParticipantScaleItems({
  scaleItemsWithParticipantIds,
});

checkValidEntries​

Validates that entries are eligible for a draw based on event category constraints.

const { valid, errors } = engine.checkValidEntries({
  eventId, // required
  drawId, // optional
  entries, // optional - validate specific entries
});

Purpose: Validate entry eligibility before draw generation.

drawMatic​

Automated draw positioning system that intelligently assigns participants to draw positions based on seeding, geographic distribution, and conflict avoidance policies.

const result = engine.drawMatic({
  drawId, // required
  structureId, // optional - specific structure
  policyDefinitions, // optional - positioning policies
  useExistingAdjustments, // optional boolean - preserve manual adjustments
  participants, // optional - override participant data
});

Purpose: AI-driven draw positioning for optimal tournament structure.

generateAdHocMatchUps​

Generates adhoc matchUps for custom tournament structures.

const { matchUps } = engine.generateAdHocMatchUps({
  participants, // required - array of participant IDs
  matchUpsPerFlight, // optional - matchUps per round
  uuids, // optional - specific matchUp IDs
});

Purpose: Create custom matchUp structures outside standard draw types.

generateAdHocRounds​

Generates multiple rounds of adhoc matchUps.

const { rounds } = engine.generateAdHocRounds({
  participants, // required
  roundsCount, // required - number of rounds
});

Purpose: Create multi-round custom structures.

generateAndPopulatePlayoffStructures​

Generates and automatically populates playoff structures in one operation.

engine.generateAndPopulatePlayoffStructures({
  drawId, // required
  structureId, // required
  roundNumbers, // required - source rounds for playoffs
  playoffAttributes, // optional
});

Purpose: Automate playoff structure creation and population.

generateDrawDefinition​

Generates a complete draw definition from parameters.

const { drawDefinition } = engine.generateDrawDefinition({
  drawSize, // required
  drawType, // required - SINGLE_ELIMINATION, etc.
  seedsCount, // optional
  drawName, // optional
  entries, // optional
  matchUpFormat, // optional
  automated, // optional boolean - auto-position participants
});

Purpose: Core draw generation method.

generateDrawMaticRound​

Generates positioning for a specific round using drawMatic algorithm.

engine.generateDrawMaticRound({
  drawId, // required
  structureId, // required
  roundNumber, // required
  policyDefinitions, // optional
});

Purpose: AI positioning for specific draw rounds.

Generates multiple structures with linking for complex draw formats.

const { structures, links } = engine.generateDrawStructuresAndLinks({
  structuresCount, // required
  drawType, // required
  drawSize, // required
  stageSequence, // optional
});

Purpose: Create multi-structure draws with automatic linking.

generateDrawTypeAndModifyDrawDefinition​

Modifies an existing draw to change its type/structure.

engine.generateDrawTypeAndModifyDrawDefinition({
  drawId, // required
  drawType, // required - new draw type
  drawSize, // optional
});

Purpose: Convert draw to different format.

generateQualifyingStructure​

Generates a qualifying structure for a main draw.

const { structure } = engine.generateQualifyingStructure({
  drawSize, // required
  qualifyingPositions, // required
  structureName, // optional
});

Purpose: Create qualifying rounds for tournaments.

generateVoluntaryConsolation​

Generates a voluntary consolation draw structure.

const { structure } = engine.generateVoluntaryConsolation({
  drawId, // required
  drawSize, // required
  structureName, // optional
});

Purpose: Create consolation draws for eliminated players.

deleteAdHocMatchUps​

const result = engine.deleteAdHocMatchUps({
  structureId, // optional optimization - structureId of structure from which matchUps are being deleted
  matchUpIds, // array of matchUpIds identifying matchUps to be deleted
  drawId, // required - drawId of drawDefinition in which target structure is found
});

luckyLoserDrawPositionAssignment​

Replaces an existing drawPosition assignment with a luckyLoserParticipantId. This method is included in validActions for positionActions

engine.luckyLoserDrawPositionAssignment({
  luckyLoserParticipantId,
  drawPosition,
  structureId,
  drawId,
});

getAssignedParticipantIds​

Returns all participant IDs assigned to positions in a draw.

const { participantIds } = engine.getAssignedParticipantIds({
  drawId, // required
  structureId, // optional - specific structure
});

Purpose: Get all participants currently in draw.

getAvailableMatchUpsCount​

Returns count of available matchUps that can be scheduled.

const { count } = engine.getAvailableMatchUpsCount({
  drawId, // required
});

Purpose: Determine scheduling capacity.

getAvailablePlayoffProfiles​

Returns available playoff configurations based on draw structure.

const { profiles } = engine.getAvailablePlayoffProfiles({
  drawId, // required
  structureId, // required
});

Purpose: Get playoff options for structure.

getDrawDefinitionTimeItem​

Returns time items attached to a draw definition.

const { timeItem } = engine.getDrawDefinitionTimeItem({
  drawId, // required
  itemType, // required - time item type
});

Purpose: Query draw-level time metadata.

getDrawParticipantRepresentativeIds​

Returns representative participant IDs for team draws.

const { representativeIds } = engine.getDrawParticipantRepresentativeIds({
  drawId, // required
  participantId, // required
});

Purpose: Get team representatives in team competitions.

getDrawStructures​

Returns all structures in a draw.

const { structures } = engine.getDrawStructures({
  drawId, // required
  stage, // optional - filter by stage
});

Purpose: Get draw structure details.

getDrawTypeCoercion​

Determines if a draw type can be coerced to another type.

const { valid, targetDrawType } = engine.getDrawTypeCoercion({
  drawId, // required
  drawSize, // required
});

Purpose: Validate draw type conversions.

getEligibleVoluntaryConsolationParticipants​

Returns participants eligible for voluntary consolation.

const { participants } = engine.getEligibleVoluntaryConsolationParticipants({
  drawId, // required
});

Purpose: Find participants for consolation draws.

getMatchUpsMap​

Returns a map of matchUps indexed by matchUpId.

const { matchUpsMap } = engine.getMatchUpsMap({
  drawId, // required
});

Purpose: Quick matchUp lookup by ID.

getParticipantIdFinishingPositions​

Returns finishing positions for all participants in draw.

const { participantResults } = engine.getParticipantIdFinishingPositions({
  drawId, // required
});

Purpose: Get final standings from draw.

getPositionAssignments​

Returns position assignments for a structure.

const { positionAssignments } = engine.getPositionAssignments({
  drawId, // required
  structureId, // required
});

Purpose: Get participant-to-position mappings.

getPositionsPlayedOff​

Returns positions that have playoff matchUps.

const { positions } = engine.getPositionsPlayedOff({
  drawId, // required
  structureId, // required
});

Purpose: Identify playoff positions in structure.

getRandomQualifierList​

Generates randomized list of qualifiers.

const { qualifiers } = engine.getRandomQualifierList({
  qualifyingCount, // required
  participantIds, // required
});

Purpose: Random selection for qualifying positions.

getSeedingThresholds​

Returns seeding threshold values based on draw size.

const { thresholds } = engine.getSeedingThresholds({
  drawSize, // required
  policyDefinitions, // optional
});

Purpose: Determine valid seed counts for draw.

getSeedsCount​

Returns the number of seeds for a draw.

const { seedsCount } = engine.getSeedsCount({
  drawId, // required
  policyDefinitions, // optional
});

Purpose: Get seed count from draw or policy.

getStructureSeedAssignments​

Returns seed assignments for a structure.

const { seedAssignments } = engine.getStructureSeedAssignments({
  drawId, // required
  structureId, // required
});

Purpose: Get seeding information for structure.

getTeamLineUp​

Returns the lineup for a team matchUp.

const { lineup } = engine.getTeamLineUp({
  drawId, // required
  matchUpId, // required
});

Purpose: Get team member assignments for matchUp.

getValidGroupSizes​

Returns valid group size options for round robin draws.

const { groupSizes } = engine.getValidGroupSizes({
  drawSize, // required
});

Purpose: Determine valid round robin configurations.

isAdHoc​

Checks if a structure is adhoc format.

const { isAdHoc } = engine.isAdHoc({
  drawId, // required
  structureId, // required
});

Returns: Boolean indicating adhoc structure.

isCompletedStructure​

Checks if a structure has all matchUps completed.

const { isCompleted } = engine.isCompletedStructure({
  drawId, // required
  structureId, // required
});

Returns: Boolean indicating structure completion.

isValidForQualifying​

Checks if a structure can have qualifying added.

const { valid } = engine.isValidForQualifying({
  drawId, // required
  structureId, // required
});

Purpose: Validate qualifying structure eligibility.

modifyDrawDefinition​

engine.modifyDrawDefinition({
  drawUpdates: { policyDefinitions: { ...policies } },
  drawName: 'League Play',
  drawId,
});

modifySeedAssignment​

Change the display representation of a seedNumber for a specified participantId. This method is included in validActions for positionActions.

The rationale for seedValue is to be able to, for instance, represent the fifth through the eighth seed as 5-8, or simply as 5. When there are no restrictions on seed positioning seedValue allows assigning seeding to arbitrary participants.

engine.modifySeedAssignment({
  participantId,
  structureId,
  seedValue, // display representation such as '5-8'
  drawId,
});

modifyDrawName​

Changes the name of a draw.

engine.modifyDrawName({
  drawId, // required
  drawName, // required - new name
});

Purpose: Update draw display name.

positionActions​

Returns available positioning actions for a draw position.

const { validActions } = engine.positionActions({
  drawId, // required
  structureId, // required
  drawPosition, // required
  policyDefinitions, // optional
});

Purpose: Get valid participant assignment operations.

pruneDrawDefinition​

Removes empty or unused structures from a draw.

engine.pruneDrawDefinition({
  drawId, // required
});

Purpose: Clean up draw by removing unused structures.

publicFindDrawDefinition​

Finds a draw definition with privacy policies applied.

const { drawDefinition } = engine.publicFindDrawDefinition({
  drawId, // required
  policyDefinitions, // optional
});

Purpose: Get draw data for public APIs.

qualifierDrawPositionAssignment​

Replaces an existing drawPosition assignment with a qualifierParticipantId. This method is included in validActions for positionActions

engine.qualifierDrawPositionAssignment({
  qualifierParticipantId,
  drawPosition,
  structureId,
  drawId,
});

qualifierProgression​

Handles progression of qualifiers from qualifying to main draw.

engine.qualifierProgression({
  drawId, // required
  structureId, // optional - target structure
});

Purpose: Move qualifiers to main draw after qualifying completes.

removeDrawPositionAssignment​

Clear draw position and optionally replace with a BYE, change entryStatus, or decompose a PAIR participant into UNGROUPED participants (DOUBLES only).

engine.removeDrawPositionAssignment({
  drawDefinition,
  structureId,
  drawPosition,
  replaceWithBye, // optional
  entryStatus, // optional - change the entryStatus of the removed participant
  destroyPair, // optional - decompose PAIR participant into UNGROUPED participants
});

removeDrawEntries​

Removes participantIds from drawDefinition.entries (if generated) as well as any relevent flightProfile.flights.

engine.removeDrawEntries({
  autoEntryPositions, // optional - keeps entries ordered by entryStage/entryStatus and auto-increments
  participantIds
  eventId,
  stages, // optional array of stages to consider, e.g. [VOLUNTARY_CONSOLATION]
  drawId,
  });

removeRoundMatchUps​

const {
  deltedMatchUpsCount, // number
  roundRemoved, // boolean
  success, // boolean
  error, // if any
} = engine.removeRoundMatchUps({
  removeCompletedMatchUps, // optional boolean - whether to remove completed matchUps
  roundNumber, // required - roundNumber to remove
  structureId, // required
  drawId, // required
});

removeStructure​

Removes targeted drawDefinition.structure and all other child structures along with all associated drawDefinition.links.

const { removedMatchUpIds } = engine.removeStructure({
  structureId,
  drawId,
});

removeSeededParticipant​

Removes a seeded participant from draw and adjusts seeding.

engine.removeSeededParticipant({
  drawId, // required
  structureId, // required
  participantId, // required
});

Purpose: Remove participant and rebalance seeds.

renameStructures​

engine.renameStructures({
  structureDetails: [{ structureId, structureName }],
  drawId,
});

resetDrawDefinition​

engine.resetDrawDefinition({ drawId });

resetQualifyingStructure​

engine.resetQualifyingStructure({ structureId, drawId });

--

resetVoluntaryConsolationStructure​

engine.resetVoluntaryConsolationStructure({
  resetEntries, // optional - remove all { entryStage: VOLUNTARY_CONSOLATION }
  drawId,
});

resetQualifyingStructure​

engine.resetQualifyingStructure({
  drawId,
  structureId,
});

setDrawParticipantRepresentativeIds​

Set the participantIds of participants in the draw who are representing players by observing the creation of the draw.

engine.setDrawParticipantRepresentativeIds({
  representativeParticipantIds,
  drawId,
});

setPositionAssignments​

Intended to be used in conjunction with automatedPlayoffPositioning in deployments where a client instance gets the positioning which is then set on both the client and the server, to ensure that both client and server are identical. If automatedPlayoffPositioning is invoked on both client and server independently then it is likely that the positioning on client and server will be different.

// executed only on the client
const { structurePositionAssignments } = engine.automatedPlayoffPositioning({
  applyPositioning: false, // instructs factory engine to only return values, not apply them
  structureId,
  drawId,
});

// executed on both client and server
result = engine.setPositionAssignments({
  structurePositionAssignments,
  drawId,
});

setSubOrder​

Used to order ROUND_ROBIN participants when finishing position ties cannot be broken algorithmically. Assigns a subOrder value to a participant within a structure by drawPosition.

engine.setSubOrder({
  drawPosition: 1,
  subOrder: 2,
  structureId,
  drawId,
});

setStructureOrder​

Sets the display order of structures within a draw.

engine.setStructureOrder({
  drawId, // required
  structureId, // required
  orderNumber, // required - new order position
});

Purpose: Control structure display sequence.

shiftAdHocRounds​

Move roundNumber to targetRoundNumber.

tournamentEngine.shiftAdHocRounds({
  targetRoundNumber,
  roundNumber,
  structureId,
  drawId,
});

swapAdHocRounds​

Swap roundNumbers. Must provide an array of two valid roundNumbers.

tournamentEngine.swapAdHocRounds({
  roundNumbers: [2, 4],
  structureId,
  drawId,
});

swapDrawPositionAssignments​

Swaps the participantIds of two drawPositions.

engine.swapDrawPositionAssignments({
  drawPositions,
  structureId,
  drawId,
});

updateTeamLineUp​

See validateLineUp

engine.updateTeamLineUp({
  participantId, // id of the team for which lineUp is being updated
  tieFormat, // valid tieFormat - used to validate collectionIds
  lineUp, // valid lineUp array
  drawId, // required as latest lineUp modification is stored in an extension on drawDefinition
});

withdrawParticipantAtDrawPosition​

Thin wrapper around removeDrawPositionAssignment. This method is included in validActions for positionActions.

engine.withdrawParticipantAtDrawPosition({
  entryStatus = WITHDRAWN,
  replaceWithBye, // optional
  drawDefinition,
  drawPosition,
  structureId,
  destroyPair, // optional - decompose PAIR participant into UNPAIRED participants
});