Comprehensive Documentation Update for SpriteAI: New Features, Expanded Utilities, and Getting Started Guide

docs/changelogs/changelog-2025-04-18.md

@@ -13,4 +13,4 @@
 - Enhanced `generateEnvironmentSprites()` function (modifications inferred from the context of the new function)
 
 ### Other
-- Added a test file `.github-write-test`
+- Added a test file `.github-write-test`

docs/generateItemSprites.md

@@ -0,0 +1,87 @@
+# generateItemSprites
+
+## Brief Description
+`generateItemSprites()` is a function designed to create sprite collections for game items with flexible configuration options. It generates a sprite sheet containing multiple items arranged in a grid, providing developers with a powerful tool for game asset creation.
+
+## Usage
+
+To use `generateItemSprites()`, import it from the sprite module and call it with the desired parameters:
+
+```javascript
+import { sprite } from './path/to/sprite/module';
+
+const result = await sprite.generateItemSprites(description, options);
+```
+
+## Parameters
+
+- `description` (string, required): A text description of the items to generate.
+- `options` (object, optional):
+  - `itemCount` (number): Total number of items to generate in the sprite sheet.
+  - `size` (number): Pixel dimensions of each item sprite.
+  - `style` (string): Desired sprite art style (e.g., 'pixel', 'isometric', 'realistic').
+  - `padding` (number): Space between items in the sprite sheet.
+  - `itemType` (string): Specific category of items (e.g., 'weapons', 'potions', 'tools').
+  - `background` (string): Background style for the sprite sheet.
+
+## Return Value
+
+Returns an object containing:
+- `image`: Base64-encoded image data URL of the generated item sprite sheet.
+- `url`: Direct URL to the generated sprite sheet.
+- `metadata`: Additional information about the generated sprites:
+  - `frameWidth`: Width of individual item sprites
+  - `frameHeight`: Height of individual item sprites
+  - `totalItems`: Number of items in the sprite sheet
+
+## Examples
+
+### Basic Item Sprite Generation
+```javascript
+// Generate a collection of weapon sprites
+const weaponSprites = await sprite.generateItemSprites('Fantasy RPG weapons', {
+  itemCount: 6,
+  size: 64,
+  style: 'pixel',
+  itemType: 'weapons'
+});
+
+console.log(weaponSprites.url);
+console.log(weaponSprites.metadata);
+```
+
+### Advanced Item Sprite Configuration
+```javascript
+// Generate a detailed item sprite sheet with custom configuration
+const craftingItems = await sprite.generateItemSprites('Crafting materials', {
+  itemCount: 12,
+  size: 32,
+  style: 'isometric',
+  padding: 4,
+  itemType: 'crafting',
+  background: 'transparent'
+});
+
+// Save the generated sprite sheet
+writeFile('crafting_items.png', craftingItems.image);
+```
+
+## Notes and Considerations
+
+- The function leverages AI-powered image generation for creating diverse and unique item sprites.
+- Generated sprites are optimized for game development use cases.
+- Item generation may vary between calls due to AI model creativity.
+- Performance and generation time depend on the complexity of the request and selected options.
+
+## Related Documentation
+- [generateSprite](/generateSprite)
+- [generatePixelArt](/generatePixelArt)
+- [Sprite Generation Overview](/getting-started)
+
+## Changelog
+
+### Added in Version 2025.04.18
+- Introduced `generateItemSprites()` function
+- Supports multiple configuration options
+- Generates grid-based sprite sheets
+- Provides comprehensive metadata about generated sprites

docs/generateSprite.md

@@ -2,53 +2,70 @@
 slug: /
 sidebar_position: 1
 ---
+# SpriteAI Documentation Updates
 
-# generateSprite Documentation
+## Recent Changes
 
-## Brief Description
-`generateSprite` is a function that generates a sprite sheet image based on a given description, using AI-powered image generation and analysis.
+### New Functions and Utilities
 
-## Usage
-To use `generateSprite`, import it from the sprite module and call it with a description of the character you want to generate.
+#### generateItemSprites()
+- Added support for creating game item sprite collections
+- Accepts parameters:
+  - `itemCount`: Number of items to generate
+  - `size`: Dimensions of sprite sheet
+  - `style`: Visual style of items
+  - `padding`: Spacing between items
+  - `itemType`: Category of items (weapons, potions, etc.)
+  - `background`: Optional background configuration
 
-```javascript
-import { sprite } from './path/to/sprite/module';
-
-const result = await sprite.generateSprite(description, options);
-```
+#### Enhanced Environment and Character Sprite Generation
+- Expanded `generateEnvironmentSprites()` function
+- New `generateCharacterSpritesheet()` with improved flexibility
 
-## Parameters
-- `description` (string, required): A text description of the character to generate.
-- `options` (object, optional):
-  - `iterations` (number): Number of sprite variations to generate.
-  - `size` (string): Size of the generated image (default: "1024x1024").
-  - `save` (boolean): Whether to save the generated image to disk.
+### Utility Functions Added
 
-## Return Value
-Returns an object or array of objects containing:
-- `messages`: JSON object with frameHeight and frameWidth information.
-- `image`: Base64-encoded image data URL of the generated sprite sheet.
+#### Sprite Transformation Utilities
+- `rotateSpritesheet()`
+- `tintSprite()`
+- `flipSprite()`
+- `createMirrorEffect()`
+- `addOutline()`
+- `addShadow()`
 
-## Examples
+#### Advanced Effects
+- `createParticleEffect()`
+- `createColorCyclingAnimation()`
+- `createPixelationEffect()`
+- `createDissolveEffect()`
+- `createShatterEffect()`
+- `createKaleidoscopeEffect()`
 
-1. Generate a single sprite sheet:
-```javascript
-const result = await sprite.generateSprite("A pixelated robot");
-console.log(result.messages);
-console.log(result.image);
-```
+## Recommended Usage
 
-2. Generate multiple variations:
 ```javascript
-const variations = await sprite.generateSprite("A cartoon cat", { iterations: 3 });
-variations.forEach((variation, index) => {
-  console.log(`Variation ${index + 1}:`, variation.messages);
+// Generate an item sprite collection
+const itemSprites = await sprite.generateItemSprites({
+  itemCount: 10,
+  size: '512x512',
+  style: 'fantasy',
+  itemType: 'weapons'
 });
+
+// Apply advanced sprite effects
+const enhancedSprite = sprite.addShatterEffect(originalSprite);
 ```
 
-## Notes or Considerations
-- The function uses AI models (DALL-E 3 and GPT) to generate and analyze images, which may result in varying outputs for the same input.
-- Generated sprites are optimized for walking animations and follow a specific layout (6 frames in a 2x3 grid).
-- The function converts images to grayscale, which may affect the final output.
-- When saving images, they are stored in an 'assets' folder with a filename based on the description.
-- The function may take some time to complete due to API calls and image processing.
+## Performance and Best Practices
+- New utility functions are optimized for performance
+- Effects can be chained for complex sprite transformations
+- Consider memory usage when generating large sprite collections
+
+## Compatibility
+- Compatible with existing SpriteAI methods
+- Supports latest sprite generation techniques
+- Cross-platform support
+
+## Future Development
+- Continued expansion of sprite generation capabilities
+- Machine learning-enhanced sprite creation
+- More granular customization options

docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started with SpriteAI
 
-Welcome to SpriteAI! This guide will walk you through the process of integrating the SpriteAI npm package into your projects.
+Welcome to SpriteAI! This guide will walk you through the process of integrating the SpriteAI npm package into your projects and explore its expanded capabilities.
 
 ## Installation
 
@@ -20,55 +20,96 @@ const spriteAI = require('spriteai');
 // Initialise a new SpriteAI instance
 const ai = new spriteAI.SpriteAI();
 
-// Generate a sprite
-ai.generateSprite('player', 32, 32)
-  .then(sprite => {
-    console.log('Sprite successfully generated:', sprite);
+// Generate a character sprite
+ai.generateCharacterSpritesheet('hero', { style: 'pixel' })
+  .then(spritesheet => {
+    console.log('Character spritesheet successfully generated:', spritesheet);
   })
   .catch(error => {
     console.error('Sprite generation encountered an error:', error);
   });
 
-// Load an existing sprite
-ai.loadSprite('path/to/sprite.png')
-  .then(sprite => {
-    console.log('Sprite successfully loaded:', sprite);
+// Generate environment sprites
+ai.generateEnvironmentSprites('forest', { tilesetSize: 16 })
+  .then(tileset => {
+    console.log('Environment tileset generated:', tileset);
   })
   .catch(error => {
-    console.error('Sprite loading encountered an error:', error);
-  });
-
-// Save a sprite
-ai.saveSprite(sprite, 'path/to/save/sprite.png')
-  .then(() => {
-    console.log('Sprite saved successfully');
-  })
-  .catch(error => {
-    console.error('Sprite saving encountered an error:', error);
+    console.error('Environment sprite generation error:', error);
   });
 ```
 
 ## Key Features
 
-SpriteAI offers a range of powerful features to enhance your sprite creation and manipulation:
+SpriteAI offers an extensive range of powerful features to enhance your sprite creation and manipulation:
+
+1. **Sprite Generation**: Advanced sprite generation techniques including:
+   - Character Spritesheets
+   - Environment Tilesets
+   - Landscape Scenes
+   - Item Sprite Collections
 
-1. **Sprite Generation**: Utilise `generateSprite(name, width, height)` to programmatically create new sprites.
-2. **Sprite Loading**: Easily load existing sprites with `loadSprite(path)`.
-3. **Sprite Saving**: Preserve your sprites using `saveSprite(sprite, path)`.
+2. **Sprite Transformations**: Comprehensive sprite manipulation functions:
+   - Rotate Spritesheet
+   - Tint Sprites
+   - Flip Sprites
+   - Add Shadows
+   - Create Color Cycling Animations
+
+3. **Advanced Effects**:
+   - Particle Effects
+   - Glitch Art
+   - Pixelation
+   - Mosaic Effects
+   - Weather Effects
+   - Displacement Effects
+
+4. **Style Variations**:
+   - Pixel Art
+   - Isometric Sprites
+   - Mecha Variations
+   - Elemental Variations
+   - Lighting Variations
+
+## Sprite Style Exploration
+
+SpriteAI now provides a function to explore available sprite styles:
+
+```javascript
+const styles = await spriteAI.fetchAvailableSpriteStyles();
+console.log('Available Sprite Styles:', styles);
+```
 
 ## Advanced Techniques
 
-SpriteAI is capable of much more than basic sprite operations. You can create intricate sprite animations, apply various transformations, and unlock a world of creative possibilities. Dive into our comprehensive API documentation to explore the full potential of SpriteAI.
+SpriteAI is capable of complex sprite operations. You can create intricate sprite animations, apply various transformations, and unlock a world of creative possibilities.
+
+### Example: Advanced Sprite Manipulation
+
+```javascript
+const sprite = await ai.generateSprite('fantasy warrior');
+const enhancedSprite = sprite
+  .addShadow()
+  .createSpriteAnimation()
+  .addGlitchWaveEffect();
+```
 
 ## Next Steps
 
-To truly master SpriteAI, we recommend:
+To become a SpriteAI expert, we recommend:
 
-1. Exploring the full API documentation
-2. Experimenting with complex sprite animations
-3. Applying different transformations to your sprites
+1. Exploring the comprehensive API documentation
+2. Experimenting with sprite generation and transformation techniques
+3. Testing various style variations
 4. Joining our community forums for tips and inspiration
 
-For in-depth information and advanced usage scenarios, please refer to our extensive API documentation.
+Thank you for choosing SpriteAI. We're excited to see the amazing sprites and game assets you'll create with our enhanced package!
+
+## Version Compatibility
+
+- Requires Node.js 16.x or higher
+- Compatible with modern web and game development frameworks
+
+## Support
 
-Thank you for choosing SpriteAI. We're excited to see the amazing sprites you'll create with our package!
+For additional support, visit our documentation site or join our developer community on GitHub.