Add Documentation Files

api_reference.md

@@ -0,0 +1,247 @@
+# SpriteAI API Reference
+
+This API reference provides comprehensive documentation for the SpriteAI library, covering all public functions, their parameters, return values, and usage examples. The reference is organized into three main categories: character generation, landscape generation, and utility functions.
+
+## Table of Contents
+
+1. [Character Generation](#character-generation)
+2. [Landscape Generation](#landscape-generation)
+3. [Utility Functions](#utility-functions)
+
+## Character Generation
+
+### generateCharacter(options)
+
+Generates a character sprite based on the provided options.
+
+**Parameters:**
+
+- `options` (Object): Configuration options for character generation
+  - `style` (String): The visual style of the character (e.g., "pixel", "cartoon", "realistic")
+  - `gender` (String): The gender of the character ("male", "female", "neutral")
+  - `race` (String): The race or species of the character (e.g., "human", "elf", "orc")
+  - `class` (String): The character's class or profession (e.g., "warrior", "mage", "thief")
+  - `equipment` (Array): List of equipment items to include in the sprite
+
+**Returns:**
+
+- (Buffer): A buffer containing the generated character sprite image
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const characterOptions = {
+  style: "pixel",
+  gender: "female",
+  race: "elf",
+  class: "mage",
+  equipment: ["staff", "robe", "hat"]
+};
+
+const characterSprite = await SpriteAI.generateCharacter(characterOptions);
+```
+
+### customizeCharacter(baseCharacter, customizations)
+
+Customizes an existing character sprite with specific modifications.
+
+**Parameters:**
+
+- `baseCharacter` (Buffer): The original character sprite to be customized
+- `customizations` (Object): Customization options
+  - `hairColor` (String): New hair color (e.g., "blonde", "brown", "red")
+  - `skinTone` (String): New skin tone (e.g., "light", "medium", "dark")
+  - `outfit` (Object): Changes to the character's outfit
+    - `top` (String): New top style
+    - `bottom` (String): New bottom style
+    - `accessories` (Array): List of accessories to add or remove
+
+**Returns:**
+
+- (Buffer): A buffer containing the customized character sprite image
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const baseCharacter = await SpriteAI.generateCharacter(/* ... */);
+
+const customizations = {
+  hairColor: "red",
+  skinTone: "medium",
+  outfit: {
+    top: "leather_armor",
+    bottom: "cloth_pants",
+    accessories: ["amulet", "bracers"]
+  }
+};
+
+const customizedCharacter = await SpriteAI.customizeCharacter(baseCharacter, customizations);
+```
+
+## Landscape Generation
+
+### generateLandscape(options)
+
+Generates a landscape sprite based on the provided options.
+
+**Parameters:**
+
+- `options` (Object): Configuration options for landscape generation
+  - `biome` (String): The type of environment (e.g., "forest", "desert", "tundra")
+  - `time` (String): Time of day (e.g., "day", "night", "sunset")
+  - `weather` (String): Weather conditions (e.g., "clear", "rainy", "snowy")
+  - `size` (Object): Dimensions of the generated landscape
+    - `width` (Number): Width of the landscape in pixels
+    - `height` (Number): Height of the landscape in pixels
+
+**Returns:**
+
+- (Buffer): A buffer containing the generated landscape sprite image
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const landscapeOptions = {
+  biome: "forest",
+  time: "sunset",
+  weather: "clear",
+  size: {
+    width: 800,
+    height: 600
+  }
+};
+
+const landscapeSprite = await SpriteAI.generateLandscape(landscapeOptions);
+```
+
+### addLandscapeElements(baseLayer, elements)
+
+Adds specific elements to an existing landscape sprite.
+
+**Parameters:**
+
+- `baseLayer` (Buffer): The original landscape sprite
+- `elements` (Array): List of elements to add to the landscape
+  - Each element is an object with properties:
+    - `type` (String): Type of element (e.g., "tree", "rock", "building")
+    - `position` (Object): Position of the element
+      - `x` (Number): X-coordinate
+      - `y` (Number): Y-coordinate
+    - `size` (Object): Size of the element
+      - `width` (Number): Width of the element
+      - `height` (Number): Height of the element
+
+**Returns:**
+
+- (Buffer): A buffer containing the landscape sprite with added elements
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const baseLandscape = await SpriteAI.generateLandscape(/* ... */);
+
+const elements = [
+  {
+    type: "tree",
+    position: { x: 100, y: 200 },
+    size: { width: 50, height: 100 }
+  },
+  {
+    type: "rock",
+    position: { x: 300, y: 400 },
+    size: { width: 30, height: 30 }
+  }
+];
+
+const enhancedLandscape = await SpriteAI.addLandscapeElements(baseLandscape, elements);
+```
+
+## Utility Functions
+
+### resizeSprite(sprite, newSize)
+
+Resizes a sprite to the specified dimensions.
+
+**Parameters:**
+
+- `sprite` (Buffer): The original sprite image
+- `newSize` (Object): New dimensions for the sprite
+  - `width` (Number): New width in pixels
+  - `height` (Number): New height in pixels
+
+**Returns:**
+
+- (Buffer): A buffer containing the resized sprite image
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const originalSprite = await SpriteAI.generateCharacter(/* ... */);
+
+const newSize = {
+  width: 64,
+  height: 64
+};
+
+const resizedSprite = await SpriteAI.resizeSprite(originalSprite, newSize);
+```
+
+### mergeLayers(layers)
+
+Combines multiple sprite layers into a single image.
+
+**Parameters:**
+
+- `layers` (Array): An array of sprite buffers to be merged
+
+**Returns:**
+
+- (Buffer): A buffer containing the merged sprite image
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+const backgroundLayer = await SpriteAI.generateLandscape(/* ... */);
+const characterLayer = await SpriteAI.generateCharacter(/* ... */);
+
+const mergedScene = await SpriteAI.mergeLayers([backgroundLayer, characterLayer]);
+```
+
+### exportSprite(sprite, format)
+
+Exports a sprite to a specific file format.
+
+**Parameters:**
+
+- `sprite` (Buffer): The sprite image to be exported
+- `format` (String): The desired output format (e.g., "png", "jpg", "webp")
+
+**Returns:**
+
+- (Buffer): A buffer containing the sprite image in the specified format
+
+**Example:**
+
+```javascript
+const SpriteAI = require('spriteAI');
+const fs = require('fs');
+
+const characterSprite = await SpriteAI.generateCharacter(/* ... */);
+
+const pngSprite = await SpriteAI.exportSprite(characterSprite, "png");
+fs.writeFileSync("character.png", pngSprite);
+```
+
+This concludes the API reference for the SpriteAI library. For more detailed information on specific use cases or advanced techniques, please refer to the other sections of our documentation.

character_spritesheet_generation.md

@@ -0,0 +1,131 @@
+# Character Spritesheet Generation
+
+This guide explains how to generate character spritesheets using SpriteAI. We'll cover the `generateCharacterSpritesheet` function, its parameters, options, and how to customize the output. Examples of different character types and animation states are also included.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [The generateCharacterSpritesheet Function](#the-generatecharacterspritesheet-function)
+3. [Parameters](#parameters)
+4. [Options](#options)
+5. [Customizing Output](#customizing-output)
+6. [Examples](#examples)
+   - [Basic Character](#basic-character)
+   - [Fantasy Character](#fantasy-character)
+   - [Sci-Fi Character](#sci-fi-character)
+7. [Animation States](#animation-states)
+8. [Best Practices](#best-practices)
+
+## Introduction
+
+SpriteAI is a powerful tool for generating character spritesheets programmatically. This guide will help you understand how to use the `generateCharacterSpritesheet` function to create diverse and customizable character sprites for your game or application.
+
+## The generateCharacterSpritesheet Function
+
+The `generateCharacterSpritesheet` function is the core of SpriteAI's character generation capabilities. It allows you to create a complete spritesheet with various animation states for a single character.
+
+```javascript
+const SpriteAI = require('spriteAI');
+
+async function createCharacter() {
+  const spritesheet = await SpriteAI.generateCharacterSpritesheet(options);
+  // Use the generated spritesheet
+}
+```
+
+## Parameters
+
+The `generateCharacterSpritesheet` function takes a single `options` object as its parameter. This object contains all the necessary configuration for your character spritesheet.
+
+## Options
+
+Here are the key options you can specify:
+
+- `characterType`: String - The type of character (e.g., 'human', 'elf', 'robot')
+- `style`: String - The visual style (e.g., 'pixel', 'cartoon', 'realistic')
+- `size`: Object - The dimensions of each sprite frame (e.g., { width: 64, height: 64 })
+- `animationStates`: Array - List of animation states to generate (e.g., ['idle', 'walk', 'run', 'jump'])
+- `palette`: Array - Color palette to use for the character
+- `accessories`: Array - List of accessories to add to the character
+
+## Customizing Output
+
+You can customize the output of your character spritesheet by adjusting the options. Here are some ways to customize:
+
+1. Change the `characterType` to create different kinds of characters.
+2. Modify the `style` to alter the visual appearance.
+3. Adjust the `size` for different sprite resolutions.
+4. Add or remove `animationStates` to control which animations are generated.
+5. Specify a custom `palette` to control the character's colors.
+6. Add `accessories` to give your character unique items or features.
+
+## Examples
+
+### Basic Character
+
+```javascript
+const options = {
+  characterType: 'human',
+  style: 'pixel',
+  size: { width: 32, height: 32 },
+  animationStates: ['idle', 'walk'],
+  palette: ['#FF0000', '#00FF00', '#0000FF'],
+  accessories: ['hat']
+};
+
+const basicCharacter = await SpriteAI.generateCharacterSpritesheet(options);
+```
+
+### Fantasy Character
+
+```javascript
+const options = {
+  characterType: 'elf',
+  style: 'cartoon',
+  size: { width: 64, height: 64 },
+  animationStates: ['idle', 'walk', 'cast_spell'],
+  palette: ['#8B4513', '#228B22', '#4682B4'],
+  accessories: ['staff', 'cloak']
+};
+
+const fantasyCharacter = await SpriteAI.generateCharacterSpritesheet(options);
+```
+
+### Sci-Fi Character
+
+```javascript
+const options = {
+  characterType: 'robot',
+  style: 'realistic',
+  size: { width: 128, height: 128 },
+  animationStates: ['idle', 'walk', 'transform'],
+  palette: ['#C0C0C0', '#FF4500', '#4B0082'],
+  accessories: ['laser_gun', 'jetpack']
+};
+
+const sciFiCharacter = await SpriteAI.generateCharacterSpritesheet(options);
+```
+
+## Animation States
+
+Animation states define the different actions or poses your character can perform. Common animation states include:
+
+- `idle`: The character's resting pose
+- `walk`: Walking animation
+- `run`: Running animation
+- `jump`: Jumping animation
+- `attack`: Attack animation
+- `crouch`: Crouching pose
+- `climb`: Climbing animation
+
+You can define custom animation states based on your game's needs.
+
+## Best Practices
+
+1. Start with a basic character and gradually add complexity.
+2. Use consistent sizes and styles across related characters.
+3. Test generated spritesheets in your game engine to ensure they work as expected.
+4. Create a library of common options for quick character generation.
+5. Experiment with different palettes and accessories to create unique characters.
+
+By following this guide, you should now be able to generate a wide variety of character spritesheets using SpriteAI's `generateCharacterSpritesheet` function. Experiment with different options to create the perfect characters for your project!