Update documentation for SpriteAI index.js file

docs/spriteai/index-js-technical-brief.md

@@ -0,0 +1,175 @@
+# SpriteAI: index.js Technical Brief
+
+## Overview
+
+## Key Functions
+
+### 1. generateCharacterSpritesheet
+
+```javascript
+export const generateCharacterSpritesheet = async function(description, options = {}) {
+  // ... implementation details
+}
+```
+
+This function generates a character spritesheet based on a given description and options.
+
+#### Parameters:
+
+* `description`: A string describing the character.
+
+* `options`: An object containing configuration options such as:
+
+  * `states`: Array of animation states (default: \['idle', 'walk', 'run', 'attack'])
+
+  * `framesPerState`: Number of frames per animation state (default: 6)
+
+  * `size`: Image size (default: '1024x1024')
+
+  * `style`: Art style (default: 'pixel-art')
+
+  * `padding`: Padding between frames (default: 1)
+
+  * `direction`: Character facing direction (default: 'right')
+
+#### Returns:
+
+An object containing:
+
+* `original`: URL of the original generated image
+
+* `spritesheet`: Base64 encoded spritesheet
+
+* `metadata`: Detailed information about the spritesheet
+
+### 2. fetchAvailableAnimationStates
+
+```javascript
+export const fetchAvailableAnimationStates = async function() {
+  // ... implementation details
+}
+```
+
+This function returns an array of available animation states for character sprites.
+
+#### Returns:
+
+An array of strings representing animation states: \['idle', 'walk', 'run', 'attack', 'jump', 'fall', 'hurt', 'die']
+
+### 3. fetchAvailableSpriteStyles
+
+```javascript
+export const fetchAvailableSpriteStyles = async function() {
+  // ... implementation details
+}
+```
+
+This function returns an array of available sprite styles.
+
+#### Returns:
+
+An array of strings representing sprite styles: \['pixel-art', 'vector', '3d', 'hand-drawn', 'anime']
+
+### 4. generateEnvironmentSprites
+
+```javascript
+export const generateEnvironmentSprites = async function(description, options = {}) {
+  // ... implementation details
+}
+```
+
+This function generates environment sprites based on a given description and options.
+
+#### Parameters:
+
+* `description`: A string describing the environment.
+
+* `options`: An object containing configuration options such as:
+
+  * `elements`: Number of distinct environment pieces (default: 4)
+
+  * `size`: Image size (default: '1024x1024')
+
+  * `style`: Art style (default: 'pixel-art')
+
+  * `padding`: Padding between elements (default: 1)
+
+  * `theme`: Environment theme (default: 'fantasy')
+
+#### Returns:
+
+An object containing:
+
+* `original`: URL of the original generated image
+
+* `tileset`: Base64 encoded tileset
+
+* `metadata`: Detailed information about the tileset
+
+### 5. generateItemSprites
+
+```javascript
+export const generateItemSprites = async function(description, options = {}) {
+  // ... implementation details
+}
+```
+
+This function generates item sprites based on a given description and options.
+
+#### Parameters:
+
+* `description`: A string describing the items.
+
+* `options`: An object containing configuration options such as:
+
+  * `itemCount`: Number of distinct items (default: 4)
+
+  * `size`: Image size (default: '1024x1024')
+
+  * `style`: Art style (default: 'pixel-art')
+
+  * `padding`: Padding between items (default: 1)
+
+  * `itemType`: Type of items (default: 'equipment')
+
+  * `background`: Background color (default: 'white')
+
+#### Returns:
+
+An object containing:
+
+* `original`: URL of the original generated image
+
+* `itemSheet`: Base64 encoded item sheet
+
+* `metadata`: Detailed information about the item sheet
+
+## Utility Functions
+
+### removeBackgroundColor
+
+```javascript
+async function removeBackgroundColor(inputPath, outputPath, targetColor, colorThreshold = 0, options = {}) {
+  // ... implementation details
+}
+```
+
+This internal function removes a specified background color from an image.
+
+## Dependencies
+
+The module relies on several external libraries:
+
+* OpenAI: For AI-powered image generation
+
+* axios: For making HTTP requests
+
+* sharp: For image processing
+
+* Jimp: For image manipulation
+
+* fs and path: For file system operations
+
+## Conclusion
+
+The `index.js` file provides a comprehensive set of functions for generating game assets using AI. It offers flexibility in terms of customization options and covers various aspects of game asset creation, including character animations, environment tiles, and item sprites.