CharacterData

Character data structure and rendering configuration

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