Sprite Data Directory

This directory contains all sprite sheet definitions, animations, and scene configurations for the sprite animation system.

Structure

data/
├── spritesheets.json     # Sprite sheet image and frame definitions
├── animations.json       # Animation sequences for entity types
└── scenes/              # Scene-specific configurations
    └── spritetest.json  # Example scene configuration

File Descriptions

spritesheets.json

Defines sprite sheet images and the coordinates of individual frames within them.

Purpose: Tell the system where to find sprite frames in image files.

When to edit: When adding new sprite sheet images or defining new frames.

animations.json

Defines animation sequences by linking sprite frames together with timing.

Purpose: Create named animations (walk, jump, idle) from sprite frames.

When to edit: When creating new animations or modifying existing ones.

scenes/[name].json

Defines entity instances, positions, behaviors, and controls for a specific scene.

Purpose: Configure what entities appear in a scene and how they behave.

When to edit: When creating new game scenes or levels.

Quick Reference

Adding a New Sprite Sheet

1. Add your image to assets/img/
2. Edit spritesheets.json:

   {
     "my_new_sprite": {
    "image": "assets/img/my_sprite.png",
    "frameWidth": 32,
    "frameHeight": 32,
    "sprites": {
      "frame_1": { "x": 0, "y": 0 },
      "frame_2": { "x": 32, "y": 0 }
    }
     }
   }
   

Adding a New Animation

Edit animations.json:

{
  "my_character": {
    "spritesheet": "my_new_sprite",
    "animations": {
      "walk": [
        { "sprite": "frame_1", "time": 0.2 },
        { "sprite": "frame_2", "time": 0.2 }
      ]
    }
  }
}

Adding an Entity to a Scene

Edit scenes/[scene].json:

{
  "entities": [
    {
      "id": "player1",
      "type": "my_character",
      "x": 100,
      "y": 200,
      "scale": 2,
      "initialAnimation": "walk"
    }
  ]
}

Data Format Documentation

See ../sprite-api.md for complete format specifications.

Validation

Before committing changes, verify:

• JSON is valid (no syntax errors)
• All sprite references exist in spritesheets.json
• All animation references use defined sprite frames
• Entity types reference existing animations
• Image paths are correct
• Coordinates are within image bounds

Tips

1. Naming Convention: Use snake_case for consistency
   • my_sprite_walk_1, enemy_idle_2
2. Organization: Group related sprites
   • Keep character sprites together
   • Keep UI sprites separate
   • Use consistent naming patterns
3. Performance: Combine sprites into atlas images when possible
   • Reduces HTTP requests
   • Improves loading time
4. Documentation: Comment complex animations
   • Use descriptive names
   • Note special timing requirements

Examples

See existing data for examples:

• Mario sprite with walking animation
• Enemy sprites with patrol behaviors
• Controllable entities with keyboard input

Future: Tool Generation

These files are designed to be generated by a sprite sheet tool. Manual editing is supported but tooling will make it easier. See ../sprite-tool-guide.md for tool development guidelines.