Add Comprehensive AI Sprite Generation Documentation

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 (
+    <div>
+      <h2>Select Sprite Style</h2>
+      <select 
+        value={selectedStyle} 
+        onChange={(e) => setSelectedStyle(e.target.value)}
+      >
+        {styles.map((style) => (
+          <option key={style} value={style}>
+            {style}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+```
+
+## 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.

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.

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!