Skip to main content
The StageData module defines the structure for stage backgrounds, props, and character placement.

​
StageData Structure

​
Core Properties

​
version
String
required
Semantic version of the stage data format
​
name
String
default:"Unknown"
Display name of the stage
​
cameraZoom
Float
default:"1.0"
Default camera zoom level for this stage
​
directory
String
default:"shared"
Asset directory for stage assets
​
props
Array<StageDataProp>
default:"[]"
Array of visual props/sprites for the stage
​
characters
StageDataCharacters
required
Positioning and rendering config for bf, dad, and gf

​
StageDataProp

Defines a visual prop or sprite in the stage.

​
Basic Properties

​
name
String
Unique identifier for script access. If omitted, prop cannot be referenced by scripts
​
assetPath
String
required
Path to the sprite asset. Can also be a hex color (e.g., "#ff0000") to create a colored rectangle
​
position
Array<Float>
required
Position as [x, y] coordinates in pixels
​
zIndex
Int
default:"0"
Stack order relative to other props and characters. Higher values render on top

​
Visual Properties

​
scale
Float | Array<Float>
default:"1.0"
Scale as a single float or [width, height] array. Use higher values on small pixel art to save memory
​
alpha
Float
default:"1.0"
Opacity from 0.0 (transparent) to 1.0 (opaque)
​
angle
Float
default:"0.0"
Rotation angle in degrees
​
isPixel
Bool
default:"false"
Set to true to disable anti-aliasing for pixel art
​
flipX
Bool
default:"false"
Whether to flip the sprite horizontally
​
flipY
Bool
default:"false"
Whether to flip the sprite vertically
​
color
String
default:"#FFFFFF"
Color overlay as hex string. #FFFFFF (white) applies no tint
​
blend
String
default:""
Blend mode (e.g., "add", "multiply", "screen"). Empty string uses normal blending

​
Scrolling & Parallax

​
scroll
Array<Float>
default:"[1, 1]"
Parallax scroll factor as [x, y]:
  • [1, 1] = moves 1:1 with camera (no parallax)
  • [0.5, 0.5] = moves half as much (background effect)
  • [0, 0] = static/fixed position

​
Animation

​
danceEvery
Float
default:"0.0"
Play idle/dance animation every X beats. Set to 0 to disable. Requires animations to be defined. Supports precision up to 0.25
​
animations
Array<AnimationData>
default:"[]"
Array of animation definitions for this prop with name, prefix, frameIndices, etc.
​
startingAnimation
String
Name of the animation to play on stage load
​
animType
String
default:"sparrow"
Animation system: "sparrow", "packer", or "animateatlas"

​
Texture Atlas Settings

​
atlasSettings
TextureAtlasData
Advanced settings for Animate Atlas props

​
TextureAtlasData

​
atlasSettings.swfMode
Bool
Enable SWF-like behavior for MovieClip symbols to play automatically
​
atlasSettings.cacheOnLoad
Bool
Cache filters and masks at load time instead of during runtime
​
atlasSettings.filterQuality
Int
Filter quality level:
  • 0 = HIGH
  • 1 = MEDIUM
  • 2 = LOW
  • 3 = RUDY
​
atlasSettings.applyStageMatrix
Bool
Apply the stage matrix from Animate. Only enable if prop was pre-positioned in Animate
​
atlasSettings.useRenderTexture
Bool
Render as single texture instead of separate limbs. Enable when using alpha changes, shaders, or blend modes

​
StageDataCharacter

Defines positioning and rendering for stage characters (bf, dad, gf).
​
position
Array<Float>
default:"[0, 0]"
Character spawn position as [x, y] in pixels
​
zIndex
Int
default:"0"
Stack order relative to props and other characters
​
scale
Float
default:"1.0"
Scale multiplier for the character on this stage
​
cameraOffsets
Array<Float>
required
Camera focus offset as [x, y] when this character is focused:
  • Boyfriend: [-100, -100] (default)
  • Dad/Opponent: [100, -100] (default)
  • Girlfriend: [0, 0] (default)
​
scroll
Array<Float>
default:"[1, 1]"
Parallax scroll factor as [x, y]. See prop scroll documentation for behavior
​
alpha
Float
default:"1.0"
Character opacity
​
angle
Float
default:"0.0"
Character rotation in degrees

​
Example: Basic Stage

{
  "version": "1.0.0",
  "name": "Main Stage",
  "cameraZoom": 1.0,
  "props": [
    {
      "name": "stageback",
      "assetPath": "stages/stageback",
      "position": [-600, -300],
      "zIndex": 0,
      "scale": 1.0,
      "scroll": [0.9, 0.9]
    },
    {
      "name": "stagefront",
      "assetPath": "stages/stagefront",
      "position": [-650, 600],
      "zIndex": 100,
      "scale": 1.1
    },
    {
      "name": "stagecurtains",
      "assetPath": "stages/stagecurtains",
      "position": [-500, -300],
      "zIndex": 200,
      "scale": 1.0
    }
  ],
  "characters": {
    "bf": {
      "position": [770, 100],
      "zIndex": 50,
      "cameraOffsets": [-100, -100]
    },
    "dad": {
      "position": [100, 100],
      "zIndex": 50,
      "cameraOffsets": [100, -100]
    },
    "gf": {
      "position": [400, -100],
      "zIndex": 10,
      "cameraOffsets": [0, 0]
    }
  }
}

​
Example: Animated Prop

{
  "name": "speaker",
  "assetPath": "stages/speakers",
  "position": [100, 200],
  "zIndex": 5,
  "animType": "sparrow",
  "danceEvery": 1.0,
  "startingAnimation": "idle",
  "animations": [
    {
      "name": "idle",
      "prefix": "speaker bump",
      "frameRate": 24,
      "looped": false
    }
  ]
}

​
Example: Color Rectangle Prop

{
  "name": "redOverlay",
  "assetPath": "#ff0000",
  "position": [0, 0],
  "scale": [1280, 720],
  "alpha": 0.5,
  "zIndex": 1000
}

​
Example: Parallax Background

{
  "name": "sky",
  "assetPath": "stages/sky",
  "position": [-400, -200],
  "zIndex": -100,
  "scroll": [0.3, 0.3],
  "scale": 1.5
}

​
Character Z-Index Reference

Common z-index layering:
  • -100 to -1: Far background props
  • 0 to 9: Background props (behind GF)
  • 10: Girlfriend (default)
  • 11 to 49: Mid-ground props
  • 50: Boyfriend and Dad (default)
  • 51 to 99: Near-ground props
  • 100+: Foreground/overlay props

​
Tips

  • Use scroll values less than [1, 1] for background parallax effects
  • Set isPixel: true on all pixel art props to avoid blurriness
  • Use negative z-index values for backgrounds that should render behind everything
  • For performance, use larger z-index gaps (e.g., 0, 100, 200) instead of sequential values
  • Color props with assetPath as hex colors use scale to determine rectangle size

Build docs developers (and LLMs) love

Get started for freeTalk to us