Relevant source files

The following files were used as context for generating this wiki page: - [packages/avatar/src/index.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/index.ts) - [packages/avatar/src/core/index.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/core/index.ts) - [packages/avatar/src/utils/validation.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/utils/validation.ts) - [packages/avatar/src/open-peeps/index.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/open-peeps/index.ts) - [packages/avatar/src/core/utils/svg.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/core/utils/svg.ts) - [packages/avatar/src/types.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/types.ts) - [packages/avatar/src/open-peeps/schema.ts](https://github.com/nextorders/avatar/blob/main/packages/avatar/src/open-peeps/schema.ts) - [test/unit/index.test.ts](https://github.com/nextorders/avatar/blob/main/test/unit/index.test.ts)

# Avatar Generation Pipeline The `@nextorders/avatar` package provides a pipeline to deterministically generate SVG avatars based on a seed string and a set of options. The generation process is based on the "Open Peeps" design set. The pipeline is initiated by a single function call, which orchestrates option validation, component selection, SVG construction, and final transformations to produce a complete SVG string. The core architecture separates the generic avatar creation logic from the specific style implementation (e.g., Open Peeps). This allows for a modular system where different avatar styles could potentially be used with the same core engine. The entire process is deterministic, meaning the same input options will always produce the same avatar. Sources: [README.md](), [packages/avatar/src/index.ts](), [packages/avatar/src/core/index.ts]() ## High-Level Generation Flow The following diagram illustrates the end-to-end process of generating an avatar, from the initial user call to the final SVG output. ```mermaid flowchart TD subgraph User Input A[createAvatar(options: AvatarOptions)] end subgraph Validation & Preparation B[validateAvatarOptions(options)] C[buildOptions(options)] end subgraph Core Engine D[createBaseAvatar(style, builtOptions)] E[Create PRNG from seed] F[style.create({prng, options})] G[Apply SVG Transformations] end subgraph SVG Output H[Assemble Final SVG String] I[Return SVG String] end A --> B B --> C C --> D D --> E E --> F F --> G G --> H H --> I ``` This diagram shows the main stages of the avatar generation pipeline. Sources: [packages/avatar/src/index.ts:15-17](), [packages/avatar/src/core/index.ts:10-69]() ## Detailed Breakdown ### 1. Entry Point and Validation The generation process begins with a call to the `createAvatar` function. This function serves as the public API for the package. Sources: [packages/avatar/src/index.ts:15]() #### `createAvatar(options: AvatarOptions)` This is the main entry point. It accepts an `options` object and returns the final SVG as a string. | Parameter | Type | Description - | | `seed` | `string` | **Required.** A string used to seed the random number generator for deterministic output. - | - `gender` | `'male'` \| `'female'` | Optional. Influences the selection of certain avatar features. - | - `clothing` | `'amber'` \| `'green'` \| `'blue'` \| `'teal'` \| `'pink'` \| `'violet'` | Optional. Sets a specific color for the clothing. - | - `emotion` | `1` to `10` | Optional. Selects a specific facial expression. - | Sources: [packages/avatar/src/types.ts:3-9](), [README.md:19-25]() The first step within `createAvatar` is to call `validateAvatarOptions`. This function performs basic checks on the provided options: - It ensures the `seed` property is present, as it is required for deterministic generation. - It verifies that `emotion`, if provided, is a number between 1 and 10. - It checks that `gender`, if provided, is either `'male'` or `'female'`. If any of these checks fail, an `Error` is thrown. Sources: [packages/avatar/src/utils/validation.ts:3-13](), [test/unit/index.test.ts:18-24]() ### 2. Options Building After validation, the `buildOptions` function is called to transform the user-friendly `AvatarOptions` into a more detailed configuration object required by the core generation engine. This function: 1. Merges in default SVG and avatar configurations (`SVG_CONFIG`, `AVATAR_CONFIG`). 2. Uses selectors (`selectGenderConfig`, `selectFaceEmotion`, `selectClothingColor`) to map the simple user inputs (like `gender: 'female'` or `emotion: 5`) to specific component names or color arrays that the Open Peeps style understands. 3. Passes the `seed` through. 4. The result is a comprehensive options object that will drive the rest of the generation process. The following diagram shows how `buildOptions` constructs the final options object. ```mermaid flowchart TD A[AvatarOptions] --> B{buildOptions}; C[SVG_CONFIG] --> B; D[AVATAR_CONFIG] --> B; E[selectGenderConfig(gender)] --> B; F[selectFaceEmotion(emotion)] --> B; G[selectClothingColor(clothing)] --> B; B --> H[Partial]; ``` Sources: [packages/avatar/src/index.ts:20-31]() ### 3. Core Avatar Creation The `createBaseAvatar` function (an alias for `createAvatar` in `core/index.ts`) is the generic engine. It is style-agnostic and orchestrates the SVG generation using a provided `style` object and the `builtOptions`. The sequence of operations is as follows: 1. **PRNG Initialization**: A pseudo-random number generator (PRNG) is created using the `seed` from the options. This ensures that all subsequent "random" choices (like picking components or colors) are deterministic. 2. **Style Creation**: It calls the `create` method on the passed `style` object (in this case, `openPeeps.create`). This method is responsible for generating the main body of the SVG, including all avatar parts. 3. **Background Generation**: It determines the background type (`solid` or `gradientLinear`) and colors. 4. **SVG Transformations**: It applies a series of transformations to the generated SVG body. These are applied in a specific order, wrapping the SVG content in `` tags with `transform` attributes. The available transformations include `scale`, `flip`, `rotate`, and `translate`. 5. **Masking & Final Assembly**: It can apply a `radius` for rounded corners via an SVG mask. Finally, it constructs the `