CharacterData

The CharacterData module defines the structure for character appearance, animations, and behavior.

CharacterData Structure

Core Properties

version

String

required

Semantic version of the character data format (current: 1.0.1)

name

String

required

Readable display name of the character

renderType

CharacterRenderType

default:"sparrow"

Rendering system to use:

"sparrow" - Single spritesheet with XML
"packer" - Single spritesheet with TXT data
"multisparrow" - Multiple spritesheets with XML
"animateatlas" - Texture atlas with JSON (Adobe Animate)
"multianimateatlas" - Multiple texture atlases
"custom" - Custom rendering via scripts

assetPath

String

required

Path to retrieve sprite assets (without extension)

Visual Properties

scale

Float

default:"1.0"

Scale multiplier for the character sprite. Use smaller sprites with higher scale values (e.g., 6x) to save memory on pixel art

offsets

Array<Float>

default:"[0, 0]"

Global position offset as [x, y] in pixels

cameraOffsets

Array<Float>

default:"[0, 0]"

Camera focus offset as [x, y] when focusing on this character

isPixel

Bool

default:"false"

Set to true to disable anti-aliasing for pixel art characters

flipX

Bool

default:"false"

Whether to flip the entire sprite horizontally

Behavior Properties

danceEvery

Float

default:"1.0"

Frequency of idle animation in beats. Supports precision up to 0.25. Higher values make the character dance less often

singTime

Float

default:"8.0"

Minimum duration (in steps) a note animation plays. Too low causes idle between notes; too high causes overhang

startingAnimation

String

default:"idle"

Name of the animation to play on spawn

Animations

animations

Array<AnimationData>

required

Array of animation definitions with name, prefix, offsets, frameIndices, etc. Each animation defines how character sprites are displayed.

Health Icon

healthIcon

HealthIconData

Configuration for the character’s health icon

HealthIconData

healthIcon.id

String

Icon asset ID (defaults to character ID)

healthIcon.scale

Float

default:"1.0"

Scale multiplier for the icon

healthIcon.flipX

Bool

default:"false"

Whether to flip the icon horizontally

healthIcon.isPixel

Bool

default:"false"

Multiply scale by 6 and disable antialiasing

healthIcon.offsets

Array<Float>

default:"[0, 25]"

Icon offset as [x, y] in pixels

Death Configuration

death

DeathData

Configuration for death animation and camera behavior

DeathData

death.cameraOffsets

Array<Float>

default:"[0, 0]"

Camera offset as [x, y] during death animation. Defaults to character’s graphic midpoint

death.cameraZoom

Float

default:"1.0"

Camera zoom multiplier during death (relative to stage’s default zoom)

death.preTransitionDelay

Float

default:"0.0"

Delay in seconds between reaching 0 health and playing death animation

Animate Atlas Properties

These properties only apply when renderType is "animateatlas" or "multianimateatlas".

applyStageMatrix

Bool

default:"false"

Whether to apply the stage matrix from Adobe Animate. Only enable if the character was pre-positioned in Animate

atlasSettings

TextureAtlasData

Advanced texture atlas configuration

TextureAtlasData

atlasSettings.swfMode

Bool

Enable SWF-like behavior for MovieClip symbols

atlasSettings.cacheOnLoad

Bool

Cache filters and masks at load time instead of runtime

atlasSettings.filterQuality

Int

Filter quality: 0 (HIGH), 1 (MEDIUM), 2 (LOW), 3 (RUDY)

atlasSettings.applyStageMatrix

Bool

Override for applyStageMatrix at the atlas level

atlasSettings.useRenderTexture

Bool

Render as single texture instead of multiple limbs. Enable for alpha changes or shaders

Example: Basic Character

{
  "version": "1.0.1",
  "name": "Boyfriend",
  "renderType": "sparrow",
  "assetPath": "characters/BOYFRIEND",
  "scale": 1.0,
  "isPixel": false,
  "offsets": [0, 0],
  "cameraOffsets": [-100, -100],
  "startingAnimation": "idle",
  "singTime": 8.0,
  "danceEvery": 1.0,
  "flipX": false,
  "healthIcon": {
    "id": "bf",
    "scale": 1.0,
    "flipX": false,
    "offsets": [0, 25]
  },
  "animations": [
    {
      "name": "idle",
      "prefix": "BF idle dance",
      "frameRate": 24,
      "looped": false,
      "offsets": [0, 0]
    },
    {
      "name": "singLEFT",
      "prefix": "BF NOTE LEFT",
      "frameRate": 24,
      "looped": false,
      "offsets": [5, -6]
    },
    {
      "name": "singDOWN",
      "prefix": "BF NOTE DOWN",
      "frameRate": 24,
      "looped": false,
      "offsets": [-20, -51]
    },
    {
      "name": "singUP",
      "prefix": "BF NOTE UP",
      "frameRate": 24,
      "looped": false,
      "offsets": [-46, 27]
    },
    {
      "name": "singRIGHT",
      "prefix": "BF NOTE RIGHT",
      "frameRate": 24,
      "looped": false,
      "offsets": [-48, -7]
    }
  ]
}

Example: Pixel Character

{
  "version": "1.0.1",
  "name": "Spirit",
  "renderType": "sparrow",
  "assetPath": "characters/spirit",
  "scale": 6.0,
  "isPixel": true,
  "offsets": [0, 0],
  "cameraOffsets": [100, -100],
  "startingAnimation": "idle",
  "singTime": 8.0,
  "danceEvery": 1.0,
  "flipX": false,
  "healthIcon": {
    "id": "spirit",
    "scale": 1.0,
    "isPixel": true
  },
  "animations": [
    {
      "name": "idle",
      "prefix": "idle spirit",
      "frameRate": 12,
      "looped": false
    },
    {
      "name": "singLEFT",
      "prefix": "left spirit",
      "frameRate": 12,
      "looped": false
    },
    {
      "name": "singRIGHT",
      "prefix": "right spirit",
      "frameRate": 12,
      "looped": false
    },
    {
      "name": "singUP",
      "prefix": "up spirit",
      "frameRate": 12,
      "looped": false
    },
    {
      "name": "singDOWN",
      "prefix": "down spirit",
      "frameRate": 12,
      "looped": false
    }
  ]
}

Render Type Reference

Type	Description	Asset Requirements
`sparrow`	Standard Flash-style	PNG + XML atlas
`packer`	TexturePacker format	PNG + TXT atlas
`multisparrow`	Multiple spritesheets	Multiple PNG/XML pairs
`animateatlas`	Adobe Animate export	Animation.json + spritemap
`multianimateatlas`	Multiple Animate atlases	Multiple Animation.json files
`custom`	Script-based rendering	Defined in HScript/Polymod

Core

Audio

Play

Data

Modding

CharacterData Structure

Core Properties

Visual Properties

Behavior Properties

Animations

Health Icon

HealthIconData

Death Configuration

DeathData

Animate Atlas Properties

TextureAtlasData

Example: Basic Character

Example: Pixel Character

Render Type Reference

Build docs developers (and LLMs) love

Core

Audio

Play

Data

Modding

​CharacterData Structure

​Core Properties

​Visual Properties

​Behavior Properties

​Animations

​Health Icon

​HealthIconData

​Death Configuration

​DeathData

​Animate Atlas Properties

​TextureAtlasData

​Example: Basic Character

​Example: Pixel Character

​Render Type Reference

Build docs developers (and LLMs) love

CharacterData Structure

Core Properties

Visual Properties

Behavior Properties

Animations

Health Icon

HealthIconData

Death Configuration

DeathData

Animate Atlas Properties

TextureAtlasData

Example: Basic Character

Example: Pixel Character

Render Type Reference