Writing Behavior JSON¶

JSON Behavior Definition Reference¶

Top Level (Behavior)¶

Field	Type	Required	Default	Description
`name`	string	Yes	`""`	Behavior name (should be unique). Also shown in settings
`weight`	int	No	`1`	Selection weight. Higher values mean more frequent selection
`description`	string	No	—	Description text shown in the settings page
`category`	string	No	`"special"`	`"basic"` = basic behavior, `"special"` = special behavior
`reactive`	string	No	`null`	For reactive behaviors, the event name that triggers it
`pro`	bool	No	`false`	`true` marks the behavior as PRO-only
`tier`	int	No	`1`	Rarity (1–10). Higher values increase selection multiplier
`unlock`	string	No	`null`	Achievement unlock key. The behavior is not registered with the engine until the linked challenge is completed
`phases`	array	Yes	—	Array of behavior phases (at least one required)

Phase (Each Element in the phases Array)¶

Field	Type	Required	Default	Description
`duration`	number or [min, max]	Yes	—	Phase duration in seconds. Use an array for random range
`pose`	string	No	`"stand"`	Stick figure pose
`speed`	number or [min, max]	No	`0`	Movement speed (px/sec). Use an array for random range
`movement`	string	No	`null`	`"forward"` to move in current direction. `null` to stay still
`reverseAtEdge`	bool	No	`false`	`true` to reverse direction when reaching the status bar edge
`limbAnimation`	bool	No	`false`	Limb animation ON/OFF
`limbSpeed`	number	No	`8`	Limb animation speed
`jump`	object	No	`null`	Jump settings (see below)
`flipInterval`	number	No	`null`	Reverse direction at this interval (seconds)
`dogBehavior`	string	No	`null`	Command for the dog (see below). `null` for normal follow
`moveTo`	string	No	`null`	`"edge"` to move toward the nearest edge
`yOffset`	number	No	`0`	Base height offset (px). Negative values move upward. Sets the baseline altitude for the phase; can be combined with `jump`
`followers`	int	No	`0`	Number of followers (retainers). Small stick figures follow the leader at randomized positions around them
`aura`	bool	No	`false`	`true` displays rotating, pulsating rays (halo) around the head. Designed for high-tier effects
`scale`	number	No	`1.0`	Rendering scale (1.0 = normal, 2.0 = double). Used for enlarged figure effects
`projectileType`	string	No	`null` (bone)	The thrown object's shape during the `throw` pose. `"bone"` (two crossed lines) / `"frisbee"` (flattened ellipse) / `"ball"` (circle)

Jump Settings (jump Object)¶

Field	Type	Default	Description
`height`	number	`5`	Jump height (px)
`period`	number	`0.4`	Time for one jump cycle (seconds). Smaller = faster

Sample JSON¶

Basic: Simple Walk¶

{
  "name": "MyWalk",
  "weight": 2,
  "description": "A slow stroll",
  "category": "basic",
  "phases": [
    {
      "duration": [3, 6],
      "pose": "walk",
      "speed": [20, 40],
      "limbAnimation": true,
      "limbSpeed": 6,
      "movement": "forward",
      "reverseAtEdge": true
    }
  ]
}

Intermediate: Running with Dog¶

{
  "name": "RunWithDog",
  "weight": 1,
  "description": "The dog runs ahead, the stick figure chases",
  "phases": [
    {
      "duration": 0.5,
      "pose": "stand",
      "dogBehavior": "run_ahead"
    },
    {
      "duration": 3.0,
      "pose": "run",
      "speed": [80, 120],
      "limbAnimation": true,
      "limbSpeed": 14,
      "movement": "forward",
      "reverseAtEdge": true,
      "dogBehavior": "run_ahead"
    },
    {
      "duration": 0.5,
      "pose": "stand"
    }
  ]
}

Advanced: Wall Climb Challenge (Multi-phase + Dog Coordination)¶

{
  "name": "WallClimbChallenge",
  "weight": 1,
  "description": "Tries to climb a wall but slides down. The dog watches",
  "phases": [
    {
      "duration": 1.5,
      "pose": "run",
      "speed": 60,
      "limbAnimation": true,
      "limbSpeed": 12,
      "movement": "forward",
      "moveTo": "edge",
      "dogBehavior": "watch"
    },
    {
      "duration": 2.0,
      "pose": "wall_climb",
      "limbAnimation": true,
      "limbSpeed": 8,
      "jump": { "height": 10, "period": 4.0 },
      "dogBehavior": "watch"
    },
    {
      "duration": 0.3,
      "pose": "crouch",
      "dogBehavior": "watch"
    },
    {
      "duration": 1.0,
      "pose": "stand",
      "flipInterval": 0.5
    }
  ]
}

Reactive: Respond to Search Start¶

{
  "name": "ReactSearch",
  "reactive": "SearchStarted",
  "description": "Looks around nervously when a search begins",
  "phases": [
    {
      "duration": 1.5,
      "pose": "surprised",
      "flipInterval": 0.4
    },
    {
      "duration": 0.3,
      "pose": "stand"
    }
  ]
}

How to Add Custom Behaviors¶

Simply add JSON files to the stickman/ folder inside the data folder to create your own behavior patterns.

Create a .json file in the data/stickman/ folder (any filename)
Write JSON following the reference above (all 67 poses, yOffset for height effects, followers for retainers, aura for halo, and every other phase setting are available)
Restart the app — it will be automatically loaded
You can toggle behaviors ON/OFF in the settings page (Control Deck → Stickman)

Notes: - Files with an empty or missing phases array are skipped - JSON syntax errors will not crash the app — only the affected file is skipped - If multiple behaviors share the same name, all are loaded, but using unique names is recommended for easier identification in settings - For reactive behaviors, if multiple files target the same event, the last one loaded takes effect