Add documentation for sprite generation functions

docs/generateNinja.md

@@ -0,0 +1,50 @@
+# generateNinja
+
+## Brief Description
+`generateNinja` is a function that generates ninja-themed sprites with predefined states and customizable options.
+
+## Usage
+To use `generateNinja`, import it from the sprite module and call it with optional configuration parameters.
+
+```javascript
+import { generateNinja } from './spriteAI/index.js';
+
+const result = await generateNinja(options);
+```
+
+## Parameters
+- `options` (object, optional): Configuration for ninja sprite generation
+  - `states` (array): Animation states to generate. Default: `['idle', 'walk', 'run', 'attack', 'sneak']`
+  - `framesPerState` (number): Number of frames for each animation state. Default: `6`
+  - `style` (string): Art style for the sprite. Default: `'pixel-art'`
+
+## Return Value
+Returns an object containing:
+- `original`: Direct URL to the original generated image.
+- `spritesheet`: Base64-encoded image data URL of the processed spritesheet.
+- `metadata`: Object containing details about the spritesheet.
+
+## Examples
+
+1. Generate a default ninja spritesheet:
+```javascript
+const result = await generateNinja();
+console.log(result.spritesheet); // Base64-encoded spritesheet
+```
+
+2. Generate a ninja with custom options:
+```javascript
+const options = {
+  states: ['idle', 'run', 'attack'],
+  framesPerState: 8,
+  style: 'anime'
+};
+const result = await generateNinja(options);
+console.log(result.metadata);
+```
+
+## Notes
+- Uses DALL-E 3 AI model for image generation
+- Generates spritesheets with predefined ninja character animations
+- Supports customization of animation states and sprite style
+- Image generation may vary between calls due to AI model characteristics

docs/generateRobot.md

@@ -0,0 +1,62 @@
+# generateRobot
+
+## Brief Description
+`generateRobot` is a function that creates a robot character with various animation states using AI-powered image generation.
+
+## Usage
+To use the `generateRobot` function, import it directly from the sprite module:
+
+```javascript
+import { generateRobot } from './spriteAI/index.js';
+
+// Basic usage
+const robotSprites = await generateRobot();
+
+// Usage with custom options
+const customRobotSprites = await generateRobot({
+  states: ['idle', 'walk', 'run', 'attack', 'power-up'],
+  framesPerState: 8,
+  style: 'pixel-art'
+});
+```
+
+## Parameters
+- `options` (object, optional):
+  - `states` (array of strings): Animation states to include in the spritesheet. Default: `['idle', 'walk', 'run', 'attack', 'power-up']`
+  - `framesPerState` (number): Number of frames for each animation state. Default: `6`
+  - `style` (string): Art style for the generated robot. Default: `'pixel-art'`
+
+## Features
+- Generates a robot character with default states
+- Customizable animation states and sprite style
+- Uses AI-powered image generation
+- Generates a spritesheet with predefined states
+
+## Examples
+
+1. Generate a basic robot character with default settings:
+```javascript
+const basicRobot = await generateRobot();
+console.log(basicRobot.spritesheet); // Base64-encoded spritesheet image
+```
+
+2. Generate a robot character with custom options:
+```javascript
+const customRobot = await generateRobot({
+  states: ['idle', 'walk', 'power-up'],
+  framesPerState: 4,
+  style: 'pixel-art'
+});
+console.log(customRobot.metadata); // Detailed metadata about the spritesheet
+```
+
+## Notes and Considerations
+- The function uses AI image generation, so results may vary
+- Spritesheets are organized with each row representing a different animation state
+- Ensure you have the necessary API credentials for image generation
+- Generation may take some time due to API calls and image processing
+
+## Related Functions
+- `generateNinja()`: Generate ninja character spritesheets
+- `generateSpaceman()`: Generate spaceman character spritesheets
+- `generateCharacterSpritesheet()`: Advanced character sprite generation

docs/generateSpaceman.md

@@ -0,0 +1,66 @@
+# generateSpaceman
+
+## Brief Description
+`generateSpaceman` is a function that generates a character sprite sheet for a spaceman or astronaut character with various animation states, using AI-powered image generation.
+
+## Usage
+To use `generateSpaceman`, import it from the sprite module and call it with optional customization parameters.
+
+```javascript
+import { generateSpaceman } from 'spriteai';
+
+const result = await generateSpaceman(options);
+```
+
+## Parameters
+- `options` (object, optional):
+  - `states` (array of strings): Animation states to include in the sprite sheet. Default: `['idle', 'walk', 'run', 'float']`.
+  - `framesPerState` (number): Number of frames for each animation state. Default: `6`.
+  - `size` (string): Size of the output image in format 'widthxheight'. Default: `'1024x1024'`.
+  - `style` (string): Art style for the character. Default: `'pixel-art'`.
+  - `padding` (number): Padding between frames. Default: `1`.
+  - `direction` (string): Direction the character faces. Default: `'right'`.
+  - `save` (boolean): Whether to save the generated image to disk.
+
+## Return Value
+Returns an object containing:
+- `original`: Direct URL to the originally generated image.
+- `spritesheet`: Base64-encoded image data URL of the processed sprite sheet.
+- `metadata`: An object containing information about the sprite sheet:
+  - `states`: Array of animation state names.
+  - `framesPerState`: Number of frames per animation state.
+  - `totalFrames`: Total number of frames in the sprite sheet.
+  - `dimensions`: Width and height of the sprite sheet.
+  - `frameData`: Object with information about each animation state's position in the sprite sheet.
+
+## Examples
+
+1. Generate a default spaceman sprite sheet:
+```javascript
+const result = await generateSpaceman();
+console.log(result.spritesheet); // Base64-encoded image data URL
+```
+
+2. Generate a custom spaceman sprite sheet:
+```javascript
+const result = await generateSpaceman({
+  states: ['idle', 'walk', 'float', 'die'],
+  framesPerState: 8,
+  style: '3d',
+  save: true
+});
+console.log(result.metadata.frameData); // Access frame data for animations
+```
+
+## Notes or Considerations
+- The function uses the DALL-E 3 AI model to generate images, which may result in varying outputs.
+- Generated sprite sheets are organized with each row representing a different animation state.
+- When saving images, they are stored in the assets directory with a filename based on the description.
+- Available animation states can be retrieved using the `fetchAvailableAnimationStates()` function.
+- Available sprite styles can be retrieved using the `fetchAvailableSpriteStyles()` function.
+- The function may take some time to complete due to API calls and image processing.
+- Ensure you have the necessary API credentials and permissions to use the OpenAI image generation service.
+
+## Related Functions
+- [`generateNinja()`](/docs/generateNinja.md): Generate ninja character sprite sheets
+- [`generateRobot()`](/docs/generateRobot.md): Generate robot character sprite sheets