Open Peeps: Component Selection Logic

Relevant source files

The following files were used as context for generating this wiki page:

• packages/avatar/src/open-peeps/utils/getComponents.ts
• packages/avatar/src/open-peeps/utils/pickComponent.ts
• packages/avatar/src/utils/random.ts
• packages/avatar/src/open-peeps/index.ts
• packages/avatar/src/open-peeps/types.ts
• packages/avatar/src/config/gender.ts
• packages/avatar/src/index.ts
• packages/avatar/src/utils/selectors.ts

The Open Peeps component selection logic is a core part of the @nextorders/avatar package, responsible for programmatically selecting and assembling various SVG parts to generate a complete avatar. This system uses a pseudo-random number generator (PRNG) seeded by a user-provided string to ensure deterministic outputs, meaning the same seed will always produce the same avatar. The selection process considers user-defined options, gender-specific configurations, and probabilistic rules to create a wide variety of unique avatars.

The main function orchestrating this is getComponents, which gathers all the necessary parts like head, face, and accessories. Some components, such as facialHair and accessories, are included based on a probability check, adding another layer of variation to the generated avatars.

Core Selection Flow

The component selection process is initiated within the openPeeps.create function. It calls getComponents to determine which visual elements will be part of the final SVG. getComponents then uses pickComponent for each avatar part, which leverages the PRNG to select a specific variant from a list of possibilities.

This diagram shows the high-level data flow for selecting avatar components.

getComponents Function

The getComponents function is the central orchestrator for avatar part selection. It is responsible for picking a component for each major group and applying probability rules.

Sources: packages/avatar/src/open-peeps/utils/getComponents.ts

1. Mandatory Components: It unconditionally picks one component for the head and face groups using the pickComponent utility.
2. Probabilistic Components: It also picks components for facialHair and accessories. However, their inclusion in the final avatar is determined by a boolean check against the facialHairProbability and accessoriesProbability options. If the probability check fails, the component is undefined and will not be rendered.

The function returns a ComponentPickCollection object, which maps component group names to the selected ComponentPick object or undefined.

// packages/avatar/src/open-peeps/utils/getComponents.ts:13-39
export function getComponents({
  prng,
  options,
}: Props): ComponentPickCollection {
  const headComponent = pickComponent({
    prng,
    group: 'head',
    values: options.head,
  })
  // ... similar calls for face, facialHair, accessories

  return {
    head: headComponent,
    face: faceComponent,
    facialHair: prng.bool(options.facialHairProbability)
      ? facialHairComponent
      : undefined,
    accessories: prng.bool(options.accessoriesProbability)
      ? accessoriesComponent
      : undefined,
  }
}

Sources: packages/avatar/src/open-peeps/utils/getComponents.ts:13-39

pickComponent Function

This utility function is responsible for selecting a single component variant from an array of possible values for a given group (e.g., picking one hairstyle from all available head options). It uses the prng.pick() method, which relies on the initial seed for deterministic selection.

The function retrieves the actual SVG-generating function from a dynamically imported component group file (e.g., face.ts, head.ts).

Sources: packages/avatar/src/open-peeps/utils/pickComponent.ts

The following sequence diagram illustrates the interactions during the component selection process.

Component Configuration

The available components and probabilities are defined in the OpenPeepsOptions and can be influenced by higher-level settings like gender.

Data Structures

The selection logic revolves around a few key data structures that define the options and the output.

Sources: packages/avatar/src/open-peeps/types.ts:1-21, 88-94

OpenPeepsOptions

These options control which components are available for selection and the probabilities of their appearance.

Property	Type	Description	Default (from schema)
head	Head[]	Array of allowed head/hair styles.	All Head styles
face	FaceEmotion[]	Array of allowed face emotions.	All FaceEmotion styles
facialHair	FacialHair[]	Array of allowed facial hair styles.	All FacialHair styles
facialHairProbability	number	Percentage chance (0-100) of facial hair appearing.	10
accessories	Accessories[]	Array of allowed accessory styles.	All Accessories styles
accessoriesProbability	number	Percentage chance (0-100) of accessories appearing.	20

Sources: packages/avatar/src/open-peeps/types.ts:1-21, packages/avatar/src/open-peeps/schema.ts:5-110

Gender-Specific Configurations

The gender option in the top-level createAvatar function is used to select a predefined configuration that overrides parts of the default OpenPeepsOptions. This is handled by the selectGenderConfig function.

Sources: packages/avatar/src/utils/selectors.ts:22-29

Gender	facialHairProbability	Available head components	Available facialHair components
male	10	23 styles (e.g., afro, flatTop, mohawk)	15 styles (e.g., full, goatee1, moustache1)
female	0	25 styles (e.g., bangs, bun, longCurly)	None

If no gender is specified, one is chosen randomly.

Sources: packages/avatar/src/config/gender.ts:3-36, packages/avatar/src/utils/selectors.ts:22-29

The MALE_CONFIG and FEMALE_CONFIG objects define specific subsets of head and facialHair components, and set the facialHairProbability accordingly.

// packages/avatar/src/config/gender.ts:3-19
export const MALE_CONFIG = {
  head: [
    'afro', 'dreads1', 'dreads2', 'hatHip',
    // ...
  ],
  facialHairProbability: 10,
  facialHair: [
    'chin', 'full', 'full2', 'full3', 'full4',
    // ...
  ],
} satisfies Partial<OpenPeepsOptions>

// packages/avatar/src/config/gender.ts:21-36
export const FEMALE_CONFIG = {
  facialHairProbability: 0,
  head: [
    'afro', 'dreads1', 'dreads2', 'hatHip',
    'bangs', 'bangs2', 'bantuKnots', 'bun', 'bun2', 'buns',
    // ...
  ],
} satisfies Partial<OpenPeepsOptions>

Sources: packages/avatar/src/config/gender.ts:3-36

Summary

The Open Peeps component selection logic is a flexible and deterministic system for creating varied avatars. It combines a seeded PRNG with a layered configuration system, including base defaults, gender-specific presets, and user-provided overrides. The use of probability for optional components like facial hair and accessories ensures a natural diversity in the generated output. The entire process is orchestrated by getComponents, which delegates the selection of individual parts to pickComponent, resulting in a collection of SVG parts ready for assembly.