Requirements

• Blender: Version 4.0 or newer
• Playdate SDK: Version 2.6 or newer (may work on previous versions but untested)

Step 1: Download Blendate

1. Download the latest Blendate release. It contains:

   • blendate_addon_vX.X.X.zip (The Blender add-on itself)
   • blendate.lua (The companion script for your Playdate project)

Step 2: Install the Blender add-on

1. Go to the main menu and select Edit > Preferences.
2. In the Preferences window, click on the Add-ons tab on the left.
3. Click the Install from Disk button located in the drop-down menu at the top-right of the Add-ons panel.
   
4. Navigate to where you downloaded the Blendate package and select the blendate_addon_vX.X.X.zip file. Do not unzip it first.
5. Click the Install Add-on button.
6. Blender will install the add-on. Search for "Blendate" in the search bar within the Add-ons panel.
7. If it is not already enabled, click the checkbox next to its name to enable it. Done!

Verification: To check if the add-on is installed correctly, select a Mesh or Armature object in the 3D Viewport. Press N to open the Sidebar (if it's not already open). You should see a new tab labeled "Blendate".

Step 3: Integrate the Lua Script (optional)

The blendate.lua script is an lua library which can load the spritesheets and metadata generated by the Blender add-on. If you prefer, you can ignore this and write your own integration code.

1. Copy the Lua File: Copy the blendate.lua file from the downloaded package into your Playdate game's source code directory. A common practice is to place utility scripts in a dedicated folder, for example:

   [Your Playdate Project]/
   ├── source/
   │   ├── main.lua
   │   ├── blendate.lua  <-- Place it here
   │   ├── images/
   │   ├── metadata.json
   │   └── ... (other game files)
   └── pdxinfo

   (Adjust the location based on your project structure if needed)
2. Import the Script: In your game's Lua code (e.g., main.lua or wherever you handle asset loading), import the Blendate script using the import function. The path should be relative to your source directory:

   import("Blendate")

3. Load Metadata: When initializing your game or loading a level, create an instance of the Blendate loader by providing the path within your game's bundle to the metadata.json file generated by the Blender add-on.

   local bd = Blendate("metadata.json")

4. Load Sprites/Animations: Use the methods provided by the Blendate object to load your assets. You'll need the base path/name of the spritesheets as generated by the add-on.
   • Loading Rotations:

     -- Load a rotation sequence (turntable)
     local anim = bd:loadRotation("images/Suzanne")

   • Loading Animations:
     • Without rotations:

       -- Load a specific animation named "idle"
       local idleAnim = bd:loadAnimation("images/Bob", "idle")

     • With rotations:

       -- Load an animation that also includes rotation data
       local rotatingRunAnim = bd:loadAnimation("images/Bob", "run")
       -- To get the correct animation loop for a specific angle:
       local currentAngle = 90 -- Example angle
       local runAnimForAngle = rotatingRunAnim:get(currentAngle)
       -- 'runAnimForAngle' is the animation.loop for the closest rendered angle