Pixlings — Custom Packs Guide

📦

What are Custom Packs?

Custom Packs are collections of Pixlings with metadata like author, version, and automatic update URLs. They get their own tab in the app and support one-tap updates.

Before You Start

Familiar with creating custom Pixlings? Check the Custom Pixlings Guide if you need to learn animation basics first.

⚡

Quick Start

Create your Pixling animations
Write a pack.json file (see below)
Put animation files in an animations/ folder
ZIP them together
Create a GitHub repository and release
Upload the ZIP and pack.json to the release
Share the download link!

📝

pack.json Format

The pack.json goes in your ZIP root and defines your pack metadata and Pixlings.

Minimal Example

{
  "name": "My Pack",
  "subtitle": "Cool Pixlings",
  "author": "Your Name",
  "version": "1.0.0",
  "updateUrl": "https://github.com/user/repo/releases/latest/download/pack.json",
  "pixlings": [
    {
      "name": "My Pixling",
      "subtitle": "A friendly companion",
      "description": "Reacts to notifications and loves to dance.",
      "defaultIdleAnimation": "MyPixling_Idle.json",
      "animations": {
        "Idle": ["MyPixling_Idle.json"],
        "Notification": [
          "MyPixling_Notification_Enter.json",
          "MyPixling_Notification_Loop.json",
          "MyPixling_Notification_Exit.json"
        ]
      }
    }
  ]
}

Field	Required	Description
`name`	✅ Yes	Pack name
`subtitle`	✅ Yes	Short description
`author`	Recommended	Your name
`version`	Recommended	Version (e.g., "1.0.0")
`updateUrl`	Optional	URL for auto-updates
`pixlings`	✅ Yes	Array of Pixlings

🚀

Publishing with GitHub Releases

Free hosting with automatic updates. Create a GitHub repository, make a release, and upload your files.

1. Create a Release

In your GitHub repo, go to Releases → Create a new release. Tag it with your version (e.g., v1.0.0).

Upload two files: my-pack.zip and pack.json

2. Set Update URL

In your pack.json (inside the ZIP), add this updateUrl:

"updateUrl": "https://github.com/USER/REPO/releases/latest/download/pack.json"

3. Share with Users

Give users this link to download your pack:

https://github.com/USER/REPO/releases/latest/download/my-pack.zip

Why This Works

The /releases/latest/ URL automatically points to your newest release. When you publish an update, users see it in the app — no link changes needed.

🏷️

Versioning

Use semantic versioning (MAJOR.MINOR.PATCH):

1.0.0 → Initial release
1.0.1 → Bug fix
1.1.0 → New feature/Pixling
2.0.0 → Major redesign

When you release an update, just bump the version, create a new GitHub release with the new tag, and upload the updated files. Users will see "Update Available" in the app!

📁

ZIP Structure

my-pack.zip
├── pack.json
└── animations/
    ├── Pixling_Idle.json
    ├── Pixling_Motion.json
    └── ...

Put pack.json in the root. All animation JSONs go in animations/.

💡

Tips

Test locally first: Import your ZIP in Pixlings before publishing
Use descriptive names: "Cyberpunk Pack v2" > "Pack"
Include 3-5 Pixlings: More variety = better packs
Write release notes: Describe changes in your GitHub releases
Credit sources: If you used others' work, credit them

🔧

Troubleshooting

"Update check failed" or "HTTP 404"

Check your updateUrl is correct
Ensure you uploaded pack.json to the release
Try opening the URL in a browser to verify

"No update available" when there should be

Verify the remote version is higher (e.g., 1.1.0 > 1.0.0)
Check version numbers match exactly
Try "Check for Updates" manually in Pack Details

Pack imports but animations don't work

Check animation files are in animations/ folder
Verify filenames match exactly (case-sensitive)
Ensure animations follow the proper JSON format (489 pixels per frame)