Skip to main content

Draw Generation

Visual Example​

Themed visualization of draws by courthive-components.

Generating Draw Definitions​

The Competition Factory provides generateDrawDefinition() as the primary convenience method for creating draw structures. This powerful function handles most common use cases for draw generation and can create draws of arbitrary complexity.

Basic Usage​

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

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'event-123',
  drawSize: 32,
  drawType: 'SINGLE_ELIMINATION',
  drawEntries: eventEntries,
  automated: true, // Automatically place participants
});

Key Parameters​

Essential Parameters:

  • drawSize - Number of draw positions in the first structure (e.g., 16, 32, 64)
  • drawEntries - Array of participant entries (equal to or subset of event.entries)
  • drawType - Type of draw structure (see Draw Types for full list)

Participant Placement:

  • automated - Boolean or object controlling automatic placement:
    • true - Place all participants automatically
    • false - Manual placement required
    • { seedsOnly: true } - Only place seeded participants and adjacent byes
  • seededParticipants - Array of { participantId, seedNumber, seedValue }
  • seedsCount - Number of seeds to generate if seededParticipants not provided
  • seedingProfile - Positioning strategy (WATERFALL, CLUSTER, SEPARATE)

Match Configuration:

  • matchUpType - SINGLES, DOUBLES, or TEAM
  • matchUpFormat - Default CODES matchUpFormat code for all matchUps
  • tieFormat - For TEAM events: { collectionDefinitions, winCriteria }

Qualifying Integration:

  • qualifiersCount - Number of positions reserved for qualifiers
  • qualifyingProfiles - Array defining complete qualifying structures
  • qualifyingOnly - Boolean - only include QUALIFYING stage entries
  • qualifyingPlaceholder - Generate placeholder qualifying structure

Advanced Options:

  • structureOptions - For ROUND_ROBIN: { groupSize, playoffGroups }
  • playoffAttributes - Custom playoff structure naming and configuration
  • voluntaryConsolation - Add voluntary consolation structure
  • staggeredEntry - Enable non-base-2 draw sizes with feed-in positions
  • policyDefinitions - Seeding and avoidance policies

Examples​

Simple Elimination Draw​

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'singles-open',
  drawSize: 16,
  drawType: 'SINGLE_ELIMINATION',
  drawEntries: acceptedEntries,
  seedsCount: 4,
  automated: true,
});

Round Robin with Playoffs​

The finishingPositions array in each playoff group determines which group finishers advance to that bracket. See Finishing Positions for how these map to overall draw positions and ranking points.


**API Reference:** [generateDrawDefinition](/docs/governors/generation-governor#generatedrawdefinition)

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'doubles-u18',
  drawSize: 16,
  drawType: 'ROUND_ROBIN_WITH_PLAYOFF',
  drawEntries: acceptedEntries,
  structureOptions: {
    groupSize: 4,
    playoffGroups: [
      { finishingPositions: [1], structureName: 'Gold Flight', drawType: 'SINGLE_ELIMINATION' }, // group winners
      { finishingPositions: [2], structureName: 'Silver Flight', drawType: 'SINGLE_ELIMINATION' }, // group runners-up
    ],
  },
  automated: true,
});

Draw with Qualifying​


**API Reference:** [generateDrawDefinition](/docs/governors/generation-governor#generatedrawdefinition)

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'singles-championship',
  drawSize: 32,
  drawType: 'SINGLE_ELIMINATION',
  drawEntries: allEntries,
  qualifiersCount: 4,
  qualifyingProfiles: [
    {
      roundTarget: 1, // Qualifiers feed into Round 1 of main draw
      structureProfiles: [
        {
          drawSize: 16,
          seedsCount: 2,
          qualifyingPositions: 4, // Top 4 advance to main draw
        },
      ],
    },
  ],
  seedsCount: 8,
  automated: true,
});

Compass Draw​


**API Reference:** [generateDrawDefinition](/docs/governors/generation-governor#generatedrawdefinition)

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'singles-compass',
  drawSize: 8,
  drawType: 'COMPASS',
  drawEntries: acceptedEntries,
  automated: true,
});

Manual Placement (Seeds Only)​


**API Reference:** [generateDrawDefinition](/docs/governors/generation-governor#generatedrawdefinition)

const { drawDefinition } = tournamentEngine.generateDrawDefinition({
  eventId: 'singles-main',
  drawSize: 32,
  drawType: 'SINGLE_ELIMINATION',
  drawEntries: acceptedEntries,
  seededParticipants: [
    { participantId: 'player-1', seedNumber: 1, seedValue: '1' },
    { participantId: 'player-2', seedNumber: 2, seedValue: '2' },
    { participantId: 'player-3', seedNumber: 3, seedValue: '3-4' },
    { participantId: 'player-4', seedNumber: 4, seedValue: '3-4' },
  ],
  automated: { seedsOnly: true }, // Only place seeds and adjacent byes
});
// Remaining participants can be placed manually or via custom logic

Seeding Profiles​

Control how seeded participants are positioned:

WATERFALL (for Round Robin):


**API Reference:** [generateDrawDefinition](/docs/governors/generation-governor#generatedrawdefinition)

seedingProfile: {
  positioning: 'WATERFALL';
}
// Seeds distributed sequentially across groups: Group 1 gets seed 1, Group 2 gets seed 2, etc.

ADJACENT (for elimination):

seedingProfile: {
  positioning: 'ADJACENT';
}
// Seeds positioned closely together in the draw

SEPARATE (for elimination):

seedingProfile: {
  positioning: 'SEPARATE';
}
// Seeds maximally separated using standard seeding algorithm

Group Seeding Threshold:

seedingProfile: {
  positioning: 'SEPARATE',
  groupSeedingThreshold: 5  // Seeds 5+ assigned lowest value within their groups
}

Return Value​

generateDrawDefinition() returns:

{
  drawDefinition: {
    drawId: 'uuid',
    drawType: 'SINGLE_ELIMINATION',
    drawSize: 32,
    structures: [...],  // Array of structure definitions
    links: [...],       // Participant flow between structures
    entries: [...]      // Draw entries with position assignments
  },
  success: true
}

Next Steps​

After generating a draw definition:

  1. Add to Event: Use addDrawDefinition() to attach to tournament event
  2. Modify Structure: Use position actions to adjust participant placement
  3. Configure Scheduling: Set up venues, courts, and scheduling profiles
  4. Publish: Use publishEvent() to make draw visible

Sunburst Visualization​

An alternative way to visualize tournament brackets is the sunburst chart from courthive-components. The sunburst renders a radial layout where each ring represents a round, and segments represent participants progressing through the draw.