Pixlings — Custom Pixlings Guide

🌱

What are Custom Pixlings?

Pixlings are small animated creatures that live inside your Glyph Matrix. They're built from JSON animation files and support multiple states — idle, notification, charging, and more. If you're comfortable working directly with the LED matrix, this method gives you complete control over how your Pixling moves and glows.

Next Step

Once you've created your Pixlings, package them for distribution with the Custom Packs Guide.

🛠

Creating Animations

Build your Pixling animations using the Glyph Matrix Editor by pauwma. It lets you work directly with the glyph matrix and control the brightness of every LED.

Create your animation directly in the editor.
Export the animation as a .json file.
Include that JSON file in your Pixling zip.

📝

pack.json Structure

Every Pixling must include a pack.json file in the root of the zip. The pack.json supports optional metadata fields that enable enhanced pack management features.

Basic Example (Single Pixling)

{
  "name": "Doze",
  "subtitle": "Sleepy, gentle presence",
  "pixlings": [
    {
      "name": "Doze",
      "subtitle": "Sleepy, gentle presence",
      "description": "Calm and heavy-eyed, he often drifts into sleep.",
      "defaultIdleAnimation": "TeddyBear_Idle_Loop.json",
      "animations": {
        "Idle": [
          "TeddyBear_Idle_Enter.json",
          "TeddyBear_Idle_Loop.json",
          "TeddyBear_Idle_Blink.json"
        ],
        "Notification": [
          "TeddyBear_Enter_Bell.json",
          "TeddyBear_Loop_Bell.json",
          "TeddyBear_Exit_Bell.json"
        ],
        "Charging": [
          "TeddyBear_Enter_Charging.json",
          "TeddyBear_Loop_Charging.json",
          "TeddyBear_Exit_Charging.json"
        ],
        "LowBattery": [
          "TeddyBear_Enter_LowBattery.json",
          "TeddyBear_Loop_LowBattery.json",
          "TeddyBear_Exit_LowBattery.json"
        ],
        "Motion": [ "TeddyBear_Motion.json" ],
        "Music": [ "TeddyBear_Music.json" ]
      }
    }
  ]
}

Enhanced Example (Pack with Metadata)

{
  "name": "Elysium Starter Pack",
  "subtitle": "Official starter collection",
  "author": "Elysium Studios",
  "version": "1.0.0",
  "description": "A curated collection of 5 adorable pixlings to get you started.",
  "created": "2026-03-29",
  "updateUrl": "https://example.com/elysium-starter-pack",
  "pixlings": [
    {
      "name": "Neely",
      "subtitle": "Curious and playful",
      "description": "A bouncy friend who loves notifications.",
      "defaultIdleAnimation": "Neely_Idle_Loop.json",
      "animations": { ... }
    },
    {
      "name": "Doze",
      "subtitle": "Sleepy, gentle presence",
      "description": "Calm and heavy-eyed, he often drifts into sleep.",
      "defaultIdleAnimation": "Doze_Idle_Loop.json",
      "animations": { ... }
    }
  ]
}

Pack Metadata Benefits:

Dedicated Tab: Packs with author, version, or description get their own tab in Terrarium (e.g., "Elysium Starter Pack")
Pack Management: Export, share, and view detailed pack information
Version Tracking: Keep track of pack versions for future updates
Attribution: Credit creators with the author field
Without Metadata: Individual Pixlings are grouped in the "Custom" tab

Field	Required	Description
`name`	✅ Yes	Pack name (shown as tab title if metadata present)
`subtitle`	✅ Yes	Short description of the pack
`pixlings`	✅ Yes	Array of Pixling definitions
`author`	⚪ Optional	Pack creator name (enables pack tab)
`version`	⚪ Optional	Pack version (e.g., "1.0.0", enables pack tab)
`description`	⚪ Optional	Detailed pack description (enables pack tab)
`created`	⚪ Optional	Creation date (e.g., "2026-03-29")
`updateUrl`	⚪ Optional	URL for future pack updates

🎞

Enter / Loop / Exit Animations

All animation states support optional Enter / Loop / Exit transitions. The system automatically detects these based on filename patterns:

Filename Pattern	Type	Behavior
`_Enter`	Enter	Plays once when the state begins
`_Loop`	Loop	Repeats until the state ends
`_Exit`	Exit	Plays once when the state ends
No pattern	Loop (default)	Treated as a loop animation

How It Works

Filenames are checked case-insensitively for _enter, _loop, or _exit. Files without these patterns are treated as loop animations. You can include multiple files of each type — they'll play in sequence.

Examples

// Full Enter → Loop → Exit pattern
"Idle": [
  "Unicorn_Idle_Enter.json",    // Plays once at start
  "Unicorn_Idle_Loop.json",     // Loops continuously
  "Unicorn_Idle_Exit.json"      // Plays when leaving Idle
]

// Loop only (no enter/exit)
"Music": [ "ghost_music.json" ]

// Multiple loop variations (all treated as loop)
"Idle": [
  "Cactus_Idle_Breathing.json",
  "Cactus_Idle_Blink.json"
]

// Enter + multiple loops + Exit
"Charging": [
  "Bear_Enter_Charging.json",
  "Bear_Loop_Charging_A.json",
  "Bear_Loop_Charging_B.json",
  "Bear_Exit_Charging.json"
]

📋

Supported Animation States

Pixlings supports six animation states. All states support the Enter / Loop / Exit pattern.

State	Enter/Loop/Exit	Notes
`Idle`	✅	Default state when nothing else is happening
`Notification`	✅	Triggered by incoming notifications
`Charging`	✅	Active while device is charging
`LowBattery`	✅	Active when battery is below threshold
`Motion`	✅	Triggered by device shake/movement
`Music`	✅	Active during media playback

📁

Final Zip Structure

Put pack.json in the root of the zip. All animation files go inside an animations/ subfolder. Filenames in pack.json are plain names — no folder prefix needed.

MyPixling.zip

│

├── pack.json

└── animations/

├── TeddyBear_Idle_Enter.json

├── TeddyBear_Idle_Loop.json

├── TeddyBear_Idle_Blink.json

├── TeddyBear_Enter_Bell.json

├── TeddyBear_Loop_Bell.json

├── TeddyBear_Exit_Bell.json

├── TeddyBear_Charging.json

├── TeddyBear_Motion.json

└── TeddyBear_Music.json

💡

Tips for Better Animations

Keep silhouettes strong: Readability matters at small sizes on the glyph matrix.
Avoid overly subtle motion: Bold movement reads better on the glyph matrix.
Make loops connect smoothly: Ensure loops connect to themselves and to enter/exit transitions.
Test different brightness levels: Dim animations feel very different from full brightness.
Keep frame counts efficient: Reduce unnecessary processing with leaner animations.
Use Enter animations for "wake up" effects: And Exit for "settling down" transitions.