Add comprehensive sprite generation documentation for game development

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<string[]>
+```
+
+## 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 (
+    <div>
+      <select value={selectedStyle} onChange={(e) => setSelectedStyle(e.target.value)}>
+        {styles.map(style => (
+          <option key={style} value={style}>{style}</option>
+        ))}
+      </select>
+      <input 
+        type="text" 
+        value={description} 
+        onChange={(e) => setDescription(e.target.value)} 
+        placeholder="Describe your character"
+      />
+      <button onClick={handleGenerate}>Generate Sprite</button>
+    </div>
+  );
+}
+```
+
+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.

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,<base64-encoded-image-data>',
+  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!

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!