Skip to main content

generateDrawDefinition

generateDrawDefinition() is the primary method for creating complete draw structures. It handles the full lifecycle: validating entries, deriving draw parameters, generating structures and links, seeding, positioning participants, and optionally adding qualifying, consolation, and playoff structures — all in a single call.

Basic Usage​

const { drawDefinition, success } = engine.generateDrawDefinition({
  tournamentRecord, // implicitly provided by engine state
  event, // implicitly provided when using eventId
  eventId: 'event-uuid',
  drawSize: 32,
  drawType: SINGLE_ELIMINATION,
  automated: true, // place participants automatically
});

Parameters​

Required (when calling via engine)​

ParameterTypeDescription
eventIdstringEvent to generate the draw for. The engine resolves tournamentRecord and event from state.

Draw Structure​

ParameterTypeDefaultDescription
drawSizenumberderived from entriesNumber of positions in the first-round structure
drawTypeDrawTypeUnionSINGLE_ELIMINATIONType of draw to generate (see Draw Types)
drawNamestringderived from drawTypeCustom name for the draw
drawIdstringauto-generatedExplicit draw ID
matchUpTypeEventTypeUnionfrom eventSINGLES, DOUBLES, or TEAM
matchUpFormatstringfrom policy/eventDefault matchUpFormatCode for all matchUps
roundsCountnumber—For AD_HOC draws, number of rounds to pre-generate
structureNamestring—Custom name for the main structure

Entries and Seeding​

ParameterTypeDefaultDescription
drawEntriesEntry[]from eventEntries for the draw; defaults to event.entries
automatedboolean | { seedsOnly }falseAuto-place participants. { seedsOnly: true } places only seeds and adjacent byes.
seedsCountnumberfrom policyNumber of seeds to generate
seedingProfileSeedingProfile—{ positioning: CLUSTER | SEPARATE | WATERFALL } and optional groupSeedingThreshold
considerEventEntriesbooleantrueUse event.entries when drawEntries not provided
placeByesbooleantrueAutomatically place byes
enforceGenderboolean—Validate participant gender against event

Qualifying​

ParameterTypeDescription
qualifyingProfilesany[]Array of qualifying structure configurations: [{ roundTarget, structureProfiles: [{ drawSize, seedsCount, qualifyingPositions }] }]
qualifyingPlaceholderbooleanGenerate a placeholder qualifying structure when qualifiers count is set but no profiles provided
qualifyingOnlybooleanOnly process entries with entryStage: QUALIFYING

Consolation and Voluntary Consolation​

ParameterTypeDescription
voluntaryConsolation{ structureName?, structureAbbreviation?, structureId? }Add a voluntary consolation structure (requires drawSize >= 4)

Playoffs and Complex Topologies​

ParameterTypeDescription
withPlayoffsWithPlayoffsArgsAdd playoff structures linked to the main structure via LOSER links. Supports arbitrary recursive nesting for COMPASS-like topologies. See Recursive Playoff Generation below.
playoffAttributesPlayoffAttributesMap of exitProfile or finishingPositionRange to { name, abbreviation } for naming generated structures

ID Management​

ParameterTypeDescription
idPrefixstringDeterministic ID generation: all IDs become {prefix}-{context} instead of random UUIDs
uuidsstring[]Pool of pre-generated UUIDs consumed via pop() for matchUpIds, structureIds, and other entities. Order-dependent and shared — see ID Assignment for details.
targetMatchUpIdsTargetMatchUpId[]Post-generation remap of specific matchUpIds by location fingerprint. See Targeted MatchUp ID Assignment below.

Policies and Options​

ParameterTypeDescription
policyDefinitionsPolicyDefinitionsSeeding, avoidance, or other policies
enforceMinimumDrawSizebooleanDefault true. Set to false to allow multi-structure draws with only 2 participants.
drawTypeCoercionbooleanCoerce multi-structure draw types to SINGLE_ELIMINATION when drawSize: 2
ignoreStageSpacebooleanIgnore wildcards count etc. when validating entries
staggeredEntrybooleanAccept non-power-of-2 draw sizes; generates feed arms for extra positions
isMockbooleanMark generated entities as mock data

TEAM Events​

ParameterTypeDescription
tieFormatTieFormat{ collectionDefinitions, winCriteria } for team/dual matchUps
tieFormatNamestringNamed tie format preset
hydrateCollectionsbooleanPropagate event category and gender to collection definitions

Return Value​

{
  drawDefinition: DrawDefinition;     // The fully generated draw
  structureId: string;                // Main structure ID
  existingDrawDefinition: boolean;    // true if draw already existed
  qualifyingConflicts?: any[];        // Conflicts during qualifying generation
  positioningReports?: any[];         // Details of automated positioning decisions
  conflicts?: any[];                  // General generation conflicts
  success: boolean;
}

Generation Pipeline​

When called, generateDrawDefinition executes this pipeline:

  1. Validate and derive — resolve draw size, type, policies, seeding profile from params and event context
  2. Resolve scoring format — determine matchUpFormat and tieFormat from params, policies, or event defaults
  3. Generate or fetch existing — create the base draw definition with structures, links, entries, and optionally seed and position participants
  4. Qualifying generation — add qualifying structures and links if qualifyingProfiles specified
  5. Voluntary consolation — add voluntary consolation structure if requested and drawSize >= 4
  6. Recursive playoff generation — process withPlayoffs to add playoff/COMPASS structures (see below)
  7. Hydrate round names — apply round naming policy if configured
  8. Remap matchUp IDs — apply targetMatchUpIds if provided (see below)

Recursive Playoff Generation​

The withPlayoffs parameter enables building complex multi-structure topologies (COMPASS, OLYMPIC, or custom) in a single call. It supports arbitrary nesting through the roundPlayoffs field.

How It Works​

  1. addPlayoffStructures() creates playoff structures for the specified roundProfiles against the source structure
  2. New LOSER links are detected by diffing drawDefinition.links before and after the call
  3. For each entry in roundPlayoffs, the matching link's target structureId is found
  4. The process recurses into the child WithPlayoffsArgs using that target structure

Simple Example — 3rd/4th Place Match​

const { drawDefinition } = engine.generateDrawDefinition({
  drawSize: 16,
  eventId,
  withPlayoffs: {
    roundProfiles: [{ 4: 1 }], // losers from semifinal (round 4) → 1-round playoff
    playoffAttributes: {
      '0-4': { name: 'Bronze Medal Match', abbreviation: 'BM' },
    },
  },
});
// Result: 2 structures (Main + Bronze), 1 LOSER link

Full COMPASS Example — 8 Structures​

const { drawDefinition } = engine.generateDrawDefinition({
  drawSize: 32,
  drawType: SINGLE_ELIMINATION,
  drawName: 'East',
  eventId,
  withPlayoffs: {
    roundProfiles: [{ 1: 1 }, { 2: 1 }, { 3: 1 }],
    playoffAttributes: {
      '0-1': { name: 'West', abbreviation: 'W' },
      '0-2': { name: 'North', abbreviation: 'N' },
      '0-3': { name: 'Northeast', abbreviation: 'NE' },
    },
    roundPlayoffs: {
      1: {
        roundProfiles: [{ 1: 1 }, { 2: 1 }],
        playoffAttributes: {
          '0-1': { name: 'South', abbreviation: 'S' },
          '0-2': { name: 'Southwest', abbreviation: 'SW' },
        },
        roundPlayoffs: {
          1: {
            roundProfiles: [{ 1: 1 }],
            playoffAttributes: {
              '0-1': { name: 'Southeast', abbreviation: 'SE' },
            },
          },
        },
      },
      2: {
        roundProfiles: [{ 1: 1 }],
        playoffAttributes: {
          '0-1': { name: 'Northwest', abbreviation: 'NW' },
        },
      },
    },
  },
});
// Result: 8 structures, 7 LOSER links, 72 matchUps

Partial topologies work the same way — simply omit branches you don't need.

ID Assignment​

uuids (Pool-Based)​

The uuids parameter provides a shared pool of IDs consumed via pop() (LIFO) during generation. IDs are used for:

  • structureIds — consumed first for each structure
  • matchUpIds — consumed as matchUps are built round-by-round
  • drawIds, courtIds, eventIds — in specific generation contexts

Because consumption order depends on draw type and structure count, uuids is not suitable for targeting specific matchUps. Use targetMatchUpIds instead.

idPrefix (Deterministic)​

With idPrefix, all IDs are generated deterministically:

  • MatchUps: {prefix}-{roundNumber}-{roundPosition}
  • Structures: {prefix}-{structureName}-{suffix}

Useful for testing and reproducibility, but IDs are synthetic — not suitable for preserving external IDs.

targetMatchUpIds (Targeted)​

The targetMatchUpIds parameter remaps specific matchUpIds after the draw is fully generated. Each target specifies:

type TargetMatchUpId = {
  matchUpId: string;       // the ID to assign
  roundNumber: number;     // required — which round
  roundPosition: number;   // required — which position within the round
  stage?: string;          // optional — 'MAIN', 'CONSOLATION', 'QUALIFYING', etc.
  stageSequence?: number;  // optional — 1, 2, etc.
  exitProfile?: string;    // optional — '0', '0-1', '0-1-2', etc. (see Exit Profiles)
  structureId?: string;    // optional — target a known structure directly
};

This is the recommended approach for preserving external matchUp IDs when importing draws from other tournament management systems. See remapDrawDefinitionMatchUpIds for the standalone function and detailed use cases.

Example:

const { drawDefinition } = engine.generateDrawDefinition({
  drawSize: 8,
  eventId,
  targetMatchUpIds: [
    { matchUpId: 'ext-101', roundNumber: 1, roundPosition: 1 },
    { matchUpId: 'ext-102', roundNumber: 1, roundPosition: 2 },
    { matchUpId: 'ext-201', roundNumber: 2, roundPosition: 1 },
    { matchUpId: 'ext-final', roundNumber: 3, roundPosition: 1 },
  ],
});
// Targeted matchUps get external IDs; untargeted matchUps get generated UUIDs