diff --git a/docs/changelogs/changelog-2025-04-18.md b/docs/changelogs/changelog-2025-04-18.md index 131fad83..d7e4e0d0 100644 --- a/docs/changelogs/changelog-2025-04-18.md +++ b/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` \ No newline at end of file +- Added a test file `.github-write-test` diff --git a/docs/generateItemSprites.md b/docs/generateItemSprites.md new file mode 100644 index 00000000..b1280aef --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/generateSprite.md b/docs/generateSprite.md index 8254a0c8..fd3451d3 100644 --- a/docs/generateSprite.md +++ b/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 diff --git a/docs/getting-started.md b/docs/getting-started.md index bb03851d..a5a33035 100644 --- a/docs/getting-started.md +++ b/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.