From 979404f6bfa256b3c7e2ed36d371d1d8e35942a1 Mon Sep 17 00:00:00 2001 From: "dev-docs-github-app-dev[bot]" <178211755+dev-docs-github-app-dev[bot]@users.noreply.github.com> Date: Tue, 24 Jun 2025 00:25:46 +0000 Subject: [PATCH 1/4] Create file --- docs/fetchAvailableSpriteStyles.md | 104 +++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/fetchAvailableSpriteStyles.md diff --git a/docs/fetchAvailableSpriteStyles.md b/docs/fetchAvailableSpriteStyles.md new file mode 100644 index 00000000..c2cf18c4 --- /dev/null +++ b/docs/fetchAvailableSpriteStyles.md @@ -0,0 +1,104 @@ +--- +title: fetchAvailableSpriteStyles +description: A function to retrieve available sprite styles for character generation. +--- + +# fetchAvailableSpriteStyles + +## Introduction + +The `fetchAvailableSpriteStyles` function is part of the SpriteAI module and is used to retrieve a list of available sprite styles that can be used when generating character spritesheets. This function is particularly useful when you want to provide users with style options for their sprite generation requests. + +## Usage + +To use the `fetchAvailableSpriteStyles` function, import it from the SpriteAI module and call it as an asynchronous function. + +```javascript +import { fetchAvailableSpriteStyles } from './path/to/spriteAI'; + +async function getStyles() { + const styles = await fetchAvailableSpriteStyles(); + console.log(styles); +} + +getStyles(); +``` + +## Function Signature + +```javascript +async function fetchAvailableSpriteStyles(): Promise +``` + +## Return Value + +The function returns a Promise that resolves to an array of strings. Each string in the array represents an available sprite style. + +Example return value: + +```javascript +['pixel-art', 'vector', '3d', 'hand-drawn', 'anime'] +``` + +## Example + +Here's a more comprehensive example of how you might use the `fetchAvailableSpriteStyles` function in a user interface: + +```javascript +import React, { useState, useEffect } from 'react'; +import { fetchAvailableSpriteStyles, generateCharacterSpritesheet } from './spriteAI'; + +function SpriteGenerator() { + const [styles, setStyles] = useState([]); + const [selectedStyle, setSelectedStyle] = useState(''); + const [description, setDescription] = useState(''); + + useEffect(() => { + async function loadStyles() { + const availableStyles = await fetchAvailableSpriteStyles(); + setStyles(availableStyles); + if (availableStyles.length > 0) { + setSelectedStyle(availableStyles[0]); + } + } + loadStyles(); + }, []); + + const handleGenerate = async () => { + if (description && selectedStyle) { + const result = await generateCharacterSpritesheet(description, { style: selectedStyle }); + // Handle the generated spritesheet... + } + }; + + return ( +
+ + setDescription(e.target.value)} + placeholder="Describe your character" + /> + +
+ ); +} +``` + +In this example, we use `fetchAvailableSpriteStyles` to populate a dropdown menu with available style options. The selected style is then used as an option when calling `generateCharacterSpritesheet`. + +## Notes + +- The available styles may change over time as new styles are added or removed from the SpriteAI system. +- The function is asynchronous and returns a Promise, so remember to use `await` or `.then()` when calling it. +- If no styles are available or an error occurs, the function will return an empty array. + +## See Also + +- [generateCharacterSpritesheet](./generateCharacterSpritesheet.md) - For generating character spritesheets using the available styles. +- [fetchAvailableAnimationStates](./fetchAvailableAnimationStates.md) - For retrieving available animation states for character sprites. \ No newline at end of file From 91a8f7740fb91e19b928bfcabe1b06f43b2fa15a Mon Sep 17 00:00:00 2001 From: "dev-docs-github-app-dev[bot]" <178211755+dev-docs-github-app-dev[bot]@users.noreply.github.com> Date: Tue, 24 Jun 2025 00:25:48 +0000 Subject: [PATCH 2/4] Create file --- docs/generateItemSprites.md | 108 ++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/generateItemSprites.md diff --git a/docs/generateItemSprites.md b/docs/generateItemSprites.md new file mode 100644 index 00000000..d8960056 --- /dev/null +++ b/docs/generateItemSprites.md @@ -0,0 +1,108 @@ +--- +title: Generate Item Sprites +description: Learn how to generate item sprites using the generateItemSprites function +--- + +# Generate Item Sprites + +## Introduction + +The `generateItemSprites` function is a powerful tool for creating game item sprites using AI-powered image generation. This tutorial will guide you through the process of using this function to create customized item sprites for your game. + +## Prerequisites + +Before you begin, make sure you have: + +- Node.js installed on your system +- The `spriteAI` module imported in your project +- An OpenAI API key set up in your environment + +## Getting Started + +To use the `generateItemSprites` function, you'll need to import it from the `spriteAI` module: + +```javascript +import { generateItemSprites } from './path/to/spriteAI'; +``` + +## Basic Usage + +Here's a simple example of how to generate item sprites: + +```javascript +const description = "medieval fantasy weapons"; +const result = await generateItemSprites(description); +console.log(result); +``` + +This will generate a set of medieval fantasy weapon sprites and return an object containing the original image URL, the processed item sheet, and metadata about the generated sprites. + +## Customizing Your Sprites + +The `generateItemSprites` function accepts an options object that allows you to customize various aspects of the generated sprites. Here's an example with all available options: + +```javascript +const options = { + itemCount: 6, + size: '1024x1024', + style: 'pixel-art', + padding: 2, + itemType: 'weapon', + background: 'transparent', + save: true +}; + +const result = await generateItemSprites("sci-fi gadgets", options); +``` + +Let's break down these options: + +- `itemCount`: The number of items to generate (default: 4) +- `size`: The size of the generated image (default: '1024x1024') +- `style`: The visual style of the sprites (default: 'pixel-art') +- `padding`: The padding between items in the sprite sheet (default: 1) +- `itemType`: The type of items to generate (default: 'equipment') +- `background`: The background color of the sprite sheet (default: 'white') +- `save`: Whether to save the generated image to disk (default: false) + +## Understanding the Result + +The function returns an object with the following properties: + +```javascript +{ + original: "https://example.com/original-image-url.png", + itemSheet: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", + metadata: { + itemCount: 4, + itemType: "weapon", + dimensions: { + width: "1024", + height: "1024" + }, + itemData: { + rows: 2, + columns: 2, + totalItems: 4 + } + } +} +``` + +- `original`: The URL of the original AI-generated image +- `itemSheet`: A base64-encoded data URL of the processed sprite sheet +- `metadata`: Information about the generated sprites, including dimensions and layout + +## Saving Sprites to Disk + +If you set the `save` option to `true`, the function will save the generated sprite sheet to your project's `assets` folder. The filename will be based on the description you provided, with spaces replaced by underscores. + +## Next Steps + +Now that you've learned how to generate item sprites, you might want to explore: + +- [Generating Character Spritesheets](/docs/generateCharacterSpritesheet) +- [Customizing Sprite Styles](/docs/customizingSpriteStyles) +- [Integrating Sprites in Your Game Engine](/docs/integratingSpritesinGameEngine) + +Remember, the AI-generated sprites are meant to be a starting point. Feel free to edit and refine them to perfectly fit your game's aesthetic! \ No newline at end of file From aa5fca642c9d978c16c11b8c85380a2318b67ebd Mon Sep 17 00:00:00 2001 From: "dev-docs-github-app-dev[bot]" <178211755+dev-docs-github-app-dev[bot]@users.noreply.github.com> Date: Tue, 24 Jun 2025 00:25:53 +0000 Subject: [PATCH 3/4] Create file --- docs/generateEnvironmentSprites.md | 125 +++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/generateEnvironmentSprites.md diff --git a/docs/generateEnvironmentSprites.md b/docs/generateEnvironmentSprites.md new file mode 100644 index 00000000..70fb3e41 --- /dev/null +++ b/docs/generateEnvironmentSprites.md @@ -0,0 +1,125 @@ +--- +title: Generate Environment Sprites +description: Learn how to use the generateEnvironmentSprites function to create tileset images for game environments. +sidebar_position: 4 +--- + +# Generate Environment Sprites + +## Introduction + +The `generateEnvironmentSprites` function is a powerful tool for game developers and designers to create custom environment tilesets using AI-generated images. This tutorial will guide you through using the function to generate a set of environment sprites for your game. + +## Prerequisites + +- Node.js installed on your system +- Access to the `spriteAI` module +- An OpenAI API key (for DALL-E 3 image generation) + +## Getting Started + +First, import the necessary function from the `spriteAI` module: + +```javascript +import { generateEnvironmentSprites } from './path/to/spriteAI'; +``` + +## Basic Usage + +Here's a simple example of how to use the `generateEnvironmentSprites` function: + +```javascript +const description = "medieval fantasy forest"; +const result = await generateEnvironmentSprites(description); +console.log(result); +``` + +This will generate a tileset of environment sprites based on the description "medieval fantasy forest". + +## Advanced Options + +The `generateEnvironmentSprites` function accepts an optional second parameter for more customized output: + +```javascript +const options = { + elements: 6, + size: '1024x1024', + style: 'pixel-art', + padding: 2, + theme: 'fantasy', + save: true +}; + +const result = await generateEnvironmentSprites("ancient ruins", options); +``` + +Let's break down these options: + +- `elements`: Number of distinct environment pieces to generate (default: 4) +- `size`: Size of the generated image (default: '1024x1024') +- `style`: Visual style of the sprites (default: 'pixel-art') +- `padding`: Padding between sprite elements (default: 1) +- `theme`: Theme of the environment (default: 'fantasy') +- `save`: Whether to save the generated image to disk (default: false) + +## Output + +The function returns an object with the following properties: + +```javascript +{ + original: 'https://url-to-original-image.com', + tileset: 'data:image/png;base64,', + metadata: { + elements: 6, + theme: 'fantasy', + dimensions: { + width: 1024, + height: 1024 + }, + tileData: { + rows: 3, + columns: 2, + totalTiles: 6 + } + } +} +``` + +- `original`: URL of the original AI-generated image +- `tileset`: Base64-encoded image data of the processed tileset +- `metadata`: Information about the generated tileset + +## Saving the Generated Tileset + +If you set `save: true` in the options, the function will automatically save the tileset image to your project's `assets` folder. The filename will be based on the description you provided, with spaces replaced by underscores. + +For example: + +```javascript +const result = await generateEnvironmentSprites("ancient ruins", { save: true }); +// Saves as: /path/to/your/project/assets/ancient_ruins_environment.png +``` + +## Best Practices + +1. **Be Specific**: Provide clear and detailed descriptions for best results. +2. **Experiment with Styles**: Try different style options like 'vector', '3d', or 'hand-drawn' to find the best fit for your game. +3. **Consistent Theming**: Keep your theme consistent across different environment generations for a cohesive game world. +4. **Optimize for Performance**: Generate sprites at the size you'll use in your game to avoid runtime scaling. + +## Common Pitfalls + +- Avoid overly complex descriptions, as they may lead to inconsistent results. +- Be aware that the AI may interpret your description differently than you expect. It may take a few attempts to get the desired output. +- Remember that the generated sprites are subject to OpenAI's content policy and usage terms. + +## Next Steps + +Now that you've generated your environment sprites, you might want to: + +- Learn how to [Generate Character Spritesheets](/docs/generateCharacterSpritesheet) for your game +- Explore [Generating Item Sprites](/docs/generateItemSprites) for in-game objects +- Understand how to integrate these sprites into your game engine or framework + +Happy sprite generating! \ No newline at end of file From 4bbe8bbf264c7d557f603aba65ce6c16ce10abca Mon Sep 17 00:00:00 2001 From: "dev-docs-github-app-dev[bot]" <178211755+dev-docs-github-app-dev[bot]@users.noreply.github.com> Date: Tue, 24 Jun 2025 00:25:59 +0000 Subject: [PATCH 4/4] Update file --- docs/generateSprite.md | 192 ++++++++++++++++++++++++++++++++++------- 1 file changed, 162 insertions(+), 30 deletions(-) diff --git a/docs/generateSprite.md b/docs/generateSprite.md index 8254a0c8..0a56efb2 100644 --- a/docs/generateSprite.md +++ b/docs/generateSprite.md @@ -1,54 +1,186 @@ --- +title: Generate Sprite Documentation +description: >- + Learn how to use the generateSprite function and related utilities to create + game assets programmatically. slug: / sidebar_position: 1 --- -# generateSprite Documentation +# Generate Sprite Documentation -## Brief Description -`generateSprite` is a function that generates a sprite sheet image based on a given description, using AI-powered image generation and analysis. +## Introduction -## Usage -To use `generateSprite`, import it from the sprite module and call it with a description of the character you want to generate. +This documentation covers the `generateSprite` function and related utilities for creating game assets programmatically. These functions allow you to generate character spritesheets, environment sprites, and item sprites using AI-powered image generation. + +## generateCharacterSpritesheet + +The `generateCharacterSpritesheet` function creates a character spritesheet based on a given description. + +### Usage ```javascript -import { sprite } from './path/to/sprite/module'; +import { generateCharacterSpritesheet } from 'spriteAI'; -const result = await sprite.generateSprite(description, options); +const result = await generateCharacterSpritesheet(description, options); ``` -## Parameters +### Parameters + - `description` (string, required): A text description of the character to generate. - `options` (object, optional): - - `iterations` (number): Number of sprite variations to generate. - - `size` (string): Size of the generated image (default: "1024x1024"). - - `save` (boolean): Whether to save the generated image to disk. + - `states` (array): Animation states to include (default: ['idle', 'walk', 'run', 'attack']) + - `framesPerState` (number): Number of frames per animation state (default: 6) + - `size` (string): Size of the generated image (default: "1024x1024") + - `style` (string): Art style of the sprite (default: "pixel-art") + - `padding` (number): Padding between frames (default: 1) + - `direction` (string): Direction the character faces (default: "right") + - `save` (boolean): Whether to save the generated image to disk + +### Return Value + +Returns an object containing: +- `original`: URL of the original generated image +- `spritesheet`: Base64-encoded image data URL of the processed spritesheet +- `metadata`: Object with information about the spritesheet, including states, dimensions, and frame data + +### Example -## Return Value -Returns an object or array of objects containing: -- `messages`: JSON object with frameHeight and frameWidth information. -- `image`: Base64-encoded image data URL of the generated sprite sheet. +```javascript +const result = await generateCharacterSpritesheet("A pixelated robot warrior", { + states: ['idle', 'walk', 'attack', 'die'], + framesPerState: 8, + style: 'pixel-art', + save: true +}); + +console.log(result.metadata); +console.log(result.spritesheet); +``` -## Examples +## generateEnvironmentSprites + +The `generateEnvironmentSprites` function creates a tileset of environment sprites based on a given description. + +### Usage -1. Generate a single sprite sheet: ```javascript -const result = await sprite.generateSprite("A pixelated robot"); -console.log(result.messages); -console.log(result.image); +import { generateEnvironmentSprites } from 'spriteAI'; + +const result = await generateEnvironmentSprites(description, options); ``` -2. Generate multiple variations: +### Parameters + +- `description` (string, required): A text description of the environment to generate. +- `options` (object, optional): + - `elements` (number): Number of different elements to generate (default: 4) + - `size` (string): Size of the generated image (default: "1024x1024") + - `style` (string): Art style of the sprites (default: "pixel-art") + - `padding` (number): Padding between elements (default: 1) + - `theme` (string): Theme of the environment (default: "fantasy") + - `save` (boolean): Whether to save the generated image to disk + +### Return Value + +Returns an object containing: +- `original`: URL of the original generated image +- `tileset`: Base64-encoded image data URL of the processed tileset +- `metadata`: Object with information about the tileset, including dimensions and tile data + +### Example + ```javascript -const variations = await sprite.generateSprite("A cartoon cat", { iterations: 3 }); -variations.forEach((variation, index) => { - console.log(`Variation ${index + 1}:`, variation.messages); +const result = await generateEnvironmentSprites("A lush forest with magical elements", { + elements: 6, + style: 'pixel-art', + theme: 'fantasy', + save: true }); + +console.log(result.metadata); +console.log(result.tileset); +``` + +## generateItemSprites + +The `generateItemSprites` function creates a collection of item sprites based on a given description. + +### Usage + +```javascript +import { generateItemSprites } from 'spriteAI'; + +const result = await generateItemSprites(description, options); ``` -## Notes or Considerations -- The function uses AI models (DALL-E 3 and GPT) to generate and analyze images, which may result in varying outputs for the same input. -- Generated sprites are optimized for walking animations and follow a specific layout (6 frames in a 2x3 grid). -- The function converts images to grayscale, which may affect the final output. -- When saving images, they are stored in an 'assets' folder with a filename based on the description. -- The function may take some time to complete due to API calls and image processing. +### Parameters + +- `description` (string, required): A text description of the items to generate. +- `options` (object, optional): + - `itemCount` (number): Number of different items to generate (default: 4) + - `size` (string): Size of the generated image (default: "1024x1024") + - `style` (string): Art style of the sprites (default: "pixel-art") + - `padding` (number): Padding between items (default: 1) + - `itemType` (string): Type of items to generate (default: "equipment") + - `background` (string): Background color of the sprite sheet (default: "white") + - `save` (boolean): Whether to save the generated image to disk + +### Return Value + +Returns an object containing: +- `original`: URL of the original generated image +- `itemSheet`: Base64-encoded image data URL of the processed item sheet +- `metadata`: Object with information about the item sheet, including dimensions and item data + +### Example + +```javascript +const result = await generateItemSprites("Medieval fantasy weapons and armor", { + itemCount: 8, + style: 'pixel-art', + itemType: 'equipment', + save: true +}); + +console.log(result.metadata); +console.log(result.itemSheet); +``` + +## Utility Functions + +### fetchAvailableAnimationStates + +Retrieves a list of available animation states for character sprites. + +```javascript +import { fetchAvailableAnimationStates } from 'spriteAI'; + +const states = await fetchAvailableAnimationStates(); +console.log(states); // ['idle', 'walk', 'run', 'attack', 'jump', 'fall', 'hurt', 'die'] +``` + +### fetchAvailableSpriteStyles + +Retrieves a list of available sprite styles. + +```javascript +import { fetchAvailableSpriteStyles } from 'spriteAI'; + +const styles = await fetchAvailableSpriteStyles(); +console.log(styles); // ['pixel-art', 'vector', '3d', 'hand-drawn', 'anime'] +``` + +## Notes and Considerations + +- These functions use AI models (DALL-E 3) to generate images, which may result in varying outputs for the same input. +- Generated sprites are optimized for game development and follow specific layouts based on the function used. +- When saving images, they are stored in an 'assets' folder with filenames based on the description. +- The functions may take some time to complete due to API calls and image processing. +- Ensure you have the necessary dependencies (OpenAI, axios, sharp, Jimp) installed in your project. + +## Next Steps + +- Explore the [How-To Guide](/docs/how-to/integrate-sprites) for integrating generated sprites into your game engine. +- Check out the [API Reference](/docs/api/spriteAI) for detailed information on all available functions and parameters. +- Read the [Explanation](/docs/explanation/ai-sprite-generation) to understand how AI-powered sprite generation works.