Add Comprehensive Documentation for Sprite Generation Functions

docs/generateEnvironmentSprites.md

@@ -0,0 +1,133 @@
+---
+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 that allows you to generate tileset images for game environments using AI. This tutorial will guide you through the process of using this function to create custom environment sprites for your game projects.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+1. Installed the required dependencies (OpenAI, axios, sharp)
+2. Set up your OpenAI API key
+3. Basic knowledge of JavaScript and async/await syntax
+
+## How to Use generateEnvironmentSprites
+
+### Basic Usage
+
+Here's a simple example of how to use the `generateEnvironmentSprites` function:
+
+```javascript
+import { generateEnvironmentSprites } from 'spriteAI';
+
+const description = "forest environment";
+const result = await generateEnvironmentSprites(description);
+
+console.log(result.original); // URL of the original image
+console.log(result.tileset); // Base64-encoded tileset image
+console.log(result.metadata); // Metadata about the generated tileset
+```
+
+### Function Parameters
+
+The `generateEnvironmentSprites` function accepts two parameters:
+
+1. `description` (string, required): A text description of the environment you want to generate.
+2. `options` (object, optional): An object containing additional configuration options.
+
+### Available Options
+
+You can customize the sprite generation by passing an options object:
+
+```javascript
+const options = {
+  elements: 4, // Number of distinct environment pieces (default: 4)
+  size: '1024x1024', // Size of the generated image (default: '1024x1024')
+  style: 'pixel-art', // Art style of the sprites (default: 'pixel-art')
+  padding: 1, // Padding between sprite elements (default: 1)
+  theme: 'fantasy', // Theme of the environment (default: 'fantasy')
+  save: true // Whether to save the generated image to disk (default: false)
+};
+
+const result = await generateEnvironmentSprites("desert oasis", options);
+```
+
+## Return Value
+
+The function returns an object containing:
+
+- `original`: URL of the original generated image
+- `tileset`: Base64-encoded image data URL of the processed tileset
+- `metadata`: Object containing information about the generated tileset
+
+Example metadata:
+
+```javascript
+{
+  elements: 4,
+  theme: 'fantasy',
+  dimensions: {
+    width: '1024',
+    height: '1024'
+  },
+  tileData: {
+    rows: 2,
+    columns: 2,
+    totalTiles: 4
+  }
+}
+```
+
+## Example: Creating a Forest Environment
+
+Let's create a forest environment tileset with 6 elements:
+
+```javascript
+import { generateEnvironmentSprites } from 'spriteAI';
+
+async function createForestEnvironment() {
+  const description = "lush forest with trees, bushes, and rocks";
+  const options = {
+    elements: 6,
+    style: 'pixel-art',
+    theme: 'fantasy',
+    save: true
+  };
+
+  try {
+    const result = await generateEnvironmentSprites(description, options);
+    console.log("Forest environment generated successfully!");
+    console.log("Tileset saved as:", `assets/${description.replace(/\s+/g, '_')}_environment.png`);
+    console.log("Metadata:", result.metadata);
+  } catch (error) {
+    console.error("Error generating forest environment:", error);
+  }
+}
+
+createForestEnvironment();
+```
+
+This example will generate a forest environment tileset with 6 distinct elements in a pixel art style, save it to the assets folder, and log the metadata.
+
+## Best Practices
+
+1. Be specific in your environment descriptions for better results.
+2. Experiment with different styles and themes to find the best fit for your game.
+3. Use the `save` option to keep a local copy of your generated tilesets.
+4. Consider the number of elements based on your game's needs and the desired variety.
+
+## Next Steps
+
+Now that you've learned how to generate environment sprites, you might want to explore:
+
+- [How to use generated sprites in your game engine](link-to-how-to-guide)
+- [Customizing sprite generation with advanced options](link-to-advanced-options-doc)
+- [Understanding the AI models behind sprite generation](link-to-explanation-doc)
+
+Happy sprite generating!

docs/generateItemSprites.md

@@ -0,0 +1,123 @@
+---
+title: Generate Item Sprites
+description: Learn how to generate item sprites using AI for your game or application.
+---
+
+# Generate Item Sprites
+
+## Introduction
+
+The `generateItemSprites` function is a powerful tool that allows you to create AI-generated item sprites for your game or application. This tutorial will guide you through the process of using this function to generate custom item sprites with various options.
+
+## Prerequisites
+
+- Node.js installed on your system
+- Access to the `spriteAI` module
+- An OpenAI API key (for image generation)
+
+## Getting Started
+
+First, let's import the necessary function from the `spriteAI` module:
+
+```javascript
+import { generateItemSprites } from './path/to/spriteAI';
+```
+
+## Basic Usage
+
+To generate a set of item sprites, you can call the `generateItemSprites` function with a description and optional parameters:
+
+```javascript
+const result = await generateItemSprites("medieval weapons", {
+  itemCount: 4,
+  style: 'pixel-art',
+  itemType: 'equipment'
+});
+
+console.log(result);
+```
+
+This will generate a set of 4 pixel-art style medieval weapon sprites.
+
+## Function Parameters
+
+The `generateItemSprites` function accepts two parameters:
+
+1. `description` (string, required): A text description of the items to generate.
+2. `options` (object, optional): An object containing various customization options.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `itemCount` | number | 4 | The number of items to generate |
+| `size` | string | '1024x1024' | The size of the generated image |
+| `style` | string | 'pixel-art' | The visual style of the sprites |
+| `padding` | number | 1 | Padding between items in the sprite sheet |
+| `itemType` | string | 'equipment' | The type of items to generate |
+| `background` | string | 'white' | The background color of the sprite sheet |
+| `save` | boolean | false | Whether to save the generated image to disk |
+
+## Advanced Usage
+
+Here's an example of generating a larger set of potion sprites with custom options:
+
+```javascript
+const potionSprites = await generateItemSprites("magical potions", {
+  itemCount: 8,
+  size: '2048x2048',
+  style: 'hand-drawn',
+  itemType: 'consumable',
+  background: 'transparent',
+  save: true
+});
+
+console.log(potionSprites.metadata);
+```
+
+This will generate 8 hand-drawn potion sprites on a transparent background and save the image to disk.
+
+## Return Value
+
+The function returns an object containing:
+
+- `original`: URL of the original AI-generated image
+- `itemSheet`: Base64-encoded data URL of the processed sprite sheet
+- `metadata`: Object containing information about the generated sprites
+
+Example metadata:
+
+```javascript
+{
+  itemCount: 8,
+  itemType: 'consumable',
+  dimensions: {
+    width: '2048',
+    height: '2048'
+  },
+  itemData: {
+    rows: 4,
+    columns: 2,
+    totalItems: 8
+  }
+}
+```
+
+## Saving Generated Sprites
+
+When the `save` option is set to `true`, the function will automatically 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.
+
+For example:
+```
+assets/magical_potions_items.png
+```
+
+## Next Steps
+
+Now that you've learned how to generate item sprites, you might want to explore:
+
+- [How to use generated sprites in your game engine](link-to-how-to-guide)
+- [Customizing sprite generation with advanced prompts](link-to-explanation-doc)
+- [API Reference for the spriteAI module](link-to-reference-doc)
+
+By mastering the `generateItemSprites` function, you can quickly create diverse and unique items for your game or application, saving time and resources in the asset creation process.