diff --git a/docs/fetchAvailableSpriteStyles.md b/docs/fetchAvailableSpriteStyles.md new file mode 100644 index 00000000..2eb054c2 --- /dev/null +++ b/docs/fetchAvailableSpriteStyles.md @@ -0,0 +1,91 @@ +--- +title: fetchAvailableSpriteStyles +description: Learn how to use the fetchAvailableSpriteStyles function to get available sprite styles in your game development project. +--- + +# fetchAvailableSpriteStyles + +## Introduction + +The `fetchAvailableSpriteStyles` function is a new addition to our sprite generation toolkit. It allows developers to retrieve a list of available sprite styles that can be used when generating character spritesheets. This function is particularly useful for creating dynamic user interfaces or for validating user input when working with sprite generation. + +## Usage + +To use the `fetchAvailableSpriteStyles` function, you need to import it from the sprite module and call it asynchronously. + +```javascript +import { fetchAvailableSpriteStyles } from './path/to/sprite/module'; + +async function getStyles() { + const styles = await fetchAvailableSpriteStyles(); + console.log(styles); +} +``` + +## Parameters + +The `fetchAvailableSpriteStyles` function doesn't take any parameters. + +## Return Value + +The function returns a Promise that resolves to an array of strings. Each string represents an available sprite style. + +Example return value: + +```javascript +['pixel-art', 'vector', '3d', 'hand-drawn', 'anime'] +``` + +## Example + +Here's a complete example of how you might use the `fetchAvailableSpriteStyles` function in a React component: + +```javascript +import React, { useState, useEffect } from 'react'; +import { fetchAvailableSpriteStyles } from './path/to/sprite/module'; + +function SpriteStyleSelector() { + const [styles, setStyles] = useState([]); + const [selectedStyle, setSelectedStyle] = useState(''); + + useEffect(() => { + async function loadStyles() { + const availableStyles = await fetchAvailableSpriteStyles(); + setStyles(availableStyles); + if (availableStyles.length > 0) { + setSelectedStyle(availableStyles[0]); + } + } + loadStyles(); + }, []); + + return ( +
+

Select Sprite Style

+ +
+ ); +} +``` + +## Notes and Considerations + +- The `fetchAvailableSpriteStyles` function is asynchronous, so remember to use `await` or `.then()` when calling it. +- The available styles may change in future updates, so it's a good practice to always fetch the latest styles rather than hardcoding them in your application. +- If you're using this function in a server-side environment, make sure your runtime supports top-level await or use an asynchronous wrapper function. + +## Related Functions + +- `generateCharacterSpritesheet`: Use this function to generate a character spritesheet using one of the available styles. +- `fetchAvailableAnimationStates`: This function fetches available animation states for character sprites. + +By using `fetchAvailableSpriteStyles` in conjunction with other sprite-related functions, you can create a robust and flexible sprite generation system for your game or application. \ No newline at end of file diff --git a/docs/generateEnvironmentSprites.md b/docs/generateEnvironmentSprites.md new file mode 100644 index 00000000..66e936b2 --- /dev/null +++ b/docs/generateEnvironmentSprites.md @@ -0,0 +1,117 @@ +--- +title: Generate Environment Sprites +description: Learn how to use the generateEnvironmentSprites function to create tileset images for game environments. +--- + +# Generate Environment Sprites + +## Introduction + +The `generateEnvironmentSprites` function is a powerful tool for game developers to quickly generate tileset images for game environments using AI-powered image generation. This tutorial will guide you through using the function to create custom 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) + +## Tutorial: Creating a Forest Environment Tileset + +Let's create a forest environment tileset using the `generateEnvironmentSprites` function. + +### Step 1: Import the function + +First, import the `generateEnvironmentSprites` function from the `spriteAI` module: + +```javascript +import { generateEnvironmentSprites } from './path/to/spriteAI'; +``` + +### Step 2: Set up the function call + +Now, let's call the `generateEnvironmentSprites` function with a description of our forest environment: + +```javascript +const description = "A lush forest environment with trees, bushes, and rocks"; +const options = { + elements: 6, + size: '1024x1024', + style: 'pixel-art', + padding: 2, + theme: 'fantasy' +}; + +async function createForestTileset() { + try { + const result = await generateEnvironmentSprites(description, options); + console.log("Tileset generated successfully!"); + console.log("Original image URL:", result.original); + console.log("Tileset data URL:", result.tileset); + console.log("Metadata:", result.metadata); + } catch (error) { + console.error("Error generating tileset:", error); + } +} + +createForestTileset(); +``` + +### Step 3: Run the code + +Execute the code, and the function will generate a forest environment tileset based on your description. + +### Step 4: Use the generated tileset + +The function returns an object with the following properties: + +- `original`: The URL of the original AI-generated image +- `tileset`: A data URL containing the processed tileset image +- `metadata`: Information about the generated tileset + +You can use the `tileset` data URL to display or save the image, and use the `metadata` to understand the structure of your tileset. + +## Function Reference + +### `generateEnvironmentSprites(description, options)` + +Generates a tileset of environment sprites based on the given description. + +#### Parameters + +- `description` (string): A text description of the environment to generate. +- `options` (object): Configuration options for the sprite generation. + - `elements` (number): Number of distinct environment pieces 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 sprite elements (default: 1). + - `theme` (string): Theme of the environment (default: 'fantasy'). + +#### Return Value + +Returns a Promise that resolves to an object containing: + +- `original` (string): URL of the original AI-generated image. +- `tileset` (string): Data URL of the processed tileset image. +- `metadata` (object): Information about the generated tileset. + - `elements` (number): Number of distinct elements in the tileset. + - `theme` (string): Theme of the environment. + - `dimensions` (object): Width and height of the tileset image. + - `tileData` (object): Information about the tile layout. + +## Customization Options + +You can customize the generated environment sprites by adjusting the `options` object: + +- Change the `elements` value to generate more or fewer distinct environment pieces. +- Modify the `size` to create larger or smaller tilesets. +- Experiment with different `style` values (e.g., 'vector', '3d', 'hand-drawn') for various art styles. +- Adjust the `padding` to control the space between sprite elements. +- Try different `theme` values to generate environments for various game settings. + +## Next Steps + +- Explore the [fetchAvailableSpriteStyles](/docs/fetchAvailableSpriteStyles) function to see all available sprite styles. +- Learn how to [generate character spritesheets](/docs/generateCharacterSpritesheet) for your game. +- Check out the [generateItemSprites](/docs/generateItemSprites) function to create item sprites for your game inventory. + +By using the `generateEnvironmentSprites` function, you can quickly create custom environment tilesets for your game, saving time and resources in the development process. \ No newline at end of file diff --git a/docs/generateItemSprites.md b/docs/generateItemSprites.md new file mode 100644 index 00000000..3e1d870f --- /dev/null +++ b/docs/generateItemSprites.md @@ -0,0 +1,120 @@ +--- +title: Generate Item Sprites +description: Learn how to use the generateItemSprites function to create customized item sprites for your game. +--- + +# Generate Item Sprites + +## Introduction + +The `generateItemSprites` function is a powerful tool that allows you to create customized item sprites for your game using AI-generated images. This tutorial will guide you through the process of using this function to generate a collection of item sprites with various customization options. + +## Prerequisites + +Before you begin, make sure you have: + +- Node.js installed on your machine +- The necessary dependencies installed (OpenAI, axios, sharp) +- An OpenAI API key set up in your environment + +## Getting Started + +First, let's import the required function: + +```javascript +import { generateItemSprites } from './path/to/spriteAI'; +``` + +## Basic Usage + +Here's a simple example of how to use the `generateItemSprites` function: + +```javascript +const description = "medieval weapons"; +const result = await generateItemSprites(description); +console.log(result); +``` + +This will generate a collection of medieval weapon sprites using default settings. + +## Customizing Your Sprites + +The `generateItemSprites` function accepts an options object as its second parameter, allowing you to customize various aspects of the generated sprites. + +### Available Options + +- `itemCount`: Number of items to generate (default: 4) +- `size`: Size of the generated image (default: "1024x1024") +- `style`: Art style of the sprites (default: "pixel-art") +- `padding`: Padding between sprites (default: 1) +- `itemType`: Type of items to generate (default: "equipment") +- `background`: Background color of the sprite sheet (default: "white") + +### Example with Custom Options + +```javascript +const description = "space exploration tools"; +const options = { + itemCount: 6, + size: "2048x2048", + style: "vector", + itemType: "gadgets", + background: "transparent" +}; + +const result = await generateItemSprites(description, options); +console.log(result); +``` + +This will generate 6 vector-style space exploration gadgets on a transparent background. + +## Understanding the Result + +The `generateItemSprites` function returns an object with the following properties: + +- `original`: URL of the original AI-generated image +- `itemSheet`: Base64-encoded image data URL of the processed sprite sheet +- `metadata`: Object containing information about the generated sprites + +### Example Metadata + +```javascript +{ + itemCount: 6, + itemType: "gadgets", + dimensions: { + width: 2048, + height: 2048 + }, + itemData: { + rows: 3, + columns: 2, + totalItems: 6 + } +} +``` + +## Saving the Sprite Sheet + +If you want to save the generated sprite sheet to disk, you can use the `save` option: + +```javascript +const options = { + // ... other options ... + save: true +}; + +const result = await generateItemSprites("fantasy potions", options); +``` + +This will save the sprite sheet as a PNG file in the `assets` folder of your project, with a filename based on the description. + +## Next Steps + +Now that you've learned how to generate item sprites, you might want to explore: + +- [How to use sprite sheets in your game engine](link-to-how-to-guide) +- [Advanced sprite customization techniques](link-to-explanation-doc) +- [API Reference for the spriteAI module](link-to-reference-doc) + +Happy sprite generating! \ No newline at end of file diff --git a/docs/generateSprite.md b/docs/generateSprite.md index 8254a0c8..d2be4773 100644 --- a/docs/generateSprite.md +++ b/docs/generateSprite.md @@ -1,54 +1,156 @@ --- +title: Sprite Generation with AI +description: >- + Learn how to generate character spritesheets, environment sprites, and item + sprites using AI-powered functions. slug: / sidebar_position: 1 --- -# generateSprite Documentation +# Sprite Generation with AI -## 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 tutorial will guide you through using our AI-powered sprite generation functions to create character spritesheets, environment sprites, and item sprites for your game development projects. These tools leverage advanced AI models to generate high-quality, customizable sprites based on text descriptions. + +## Prerequisites + +- Node.js installed on your system +- Basic understanding of JavaScript and async/await syntax +- An OpenAI API key (for accessing the DALL-E 3 model) + +## Getting Started + +First, install the required dependencies: + +```bash +npm install openai axios sharp jimp fs path +``` + +Then, import the necessary functions in your project: + +```javascript +import { + generateCharacterSpritesheet, + generateEnvironmentSprites, + generateItemSprites, + fetchAvailableAnimationStates, + fetchAvailableSpriteStyles +} from './path/to/spriteAI'; +``` + +## Generating a Character Spritesheet + +Let's create a character spritesheet for a pixelated robot: + +```javascript +const description = "A futuristic pixelated robot"; +const options = { + states: ['idle', 'walk', 'run', 'attack'], + framesPerState: 6, + size: '1024x1024', + style: 'pixel-art', + direction: 'right', + save: true +}; + +try { + const result = await generateCharacterSpritesheet(description, options); + console.log("Spritesheet generated:", result.spritesheet); + console.log("Metadata:", result.metadata); +} catch (error) { + console.error("Error generating spritesheet:", error); +} +``` + +This will generate a spritesheet with four animation states (idle, walk, run, attack) for the described robot character. + +## Creating Environment Sprites + +Now, let's generate some environment sprites for a fantasy forest: ```javascript -import { sprite } from './path/to/sprite/module'; +const envDescription = "Fantasy forest environment"; +const envOptions = { + elements: 6, + size: '1024x1024', + style: 'pixel-art', + theme: 'fantasy', + save: true +}; -const result = await sprite.generateSprite(description, options); +try { + const envResult = await generateEnvironmentSprites(envDescription, envOptions); + console.log("Environment tileset generated:", envResult.tileset); + console.log("Environment metadata:", envResult.metadata); +} catch (error) { + console.error("Error generating environment sprites:", error); +} ``` -## 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. +This will create a tileset with six different fantasy forest environment elements. + +## Generating Item Sprites + +Let's create some item sprites for magical artifacts: + +```javascript +const itemDescription = "Magical artifacts and potions"; +const itemOptions = { + itemCount: 8, + size: '1024x1024', + style: 'pixel-art', + itemType: 'equipment', + save: true +}; + +try { + const itemResult = await generateItemSprites(itemDescription, itemOptions); + console.log("Item spritesheet generated:", itemResult.itemSheet); + console.log("Item metadata:", itemResult.metadata); +} catch (error) { + console.error("Error generating item sprites:", error); +} +``` + +This will generate a spritesheet with eight different magical artifacts and potions. + +## Customizing Your Sprites -## 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. +### Available Animation States -## Examples +To see what animation states are available for character spritesheets: -1. Generate a single sprite sheet: ```javascript -const result = await sprite.generateSprite("A pixelated robot"); -console.log(result.messages); -console.log(result.image); +const availableStates = await fetchAvailableAnimationStates(); +console.log("Available animation states:", availableStates); ``` -2. Generate multiple variations: +### Available Sprite Styles + +To check the available sprite styles: + ```javascript -const variations = await sprite.generateSprite("A cartoon cat", { iterations: 3 }); -variations.forEach((variation, index) => { - console.log(`Variation ${index + 1}:`, variation.messages); -}); +const availableStyles = await fetchAvailableSpriteStyles(); +console.log("Available sprite styles:", availableStyles); ``` -## 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. +Use these lists to customize your `options` object when generating sprites. + +## Outcome + +After running these functions, you'll have: + +1. A character spritesheet with multiple animation states +2. An environment tileset with various elements +3. An item spritesheet with multiple game items + +All generated images will be saved in the `assets` folder of your project (if the `save` option is set to `true`). + +## Next Steps + +- Explore the `removeBackgroundColor` function to process your sprites further +- Learn how to integrate these sprites into your game engine +- Check out our How-To guides for advanced sprite manipulation techniques + +By following this tutorial, you've learned how to generate various types of sprites using AI. Experiment with different descriptions and options to create unique assets for your game!