NpcRoleExpansion

NpcRoleExpansion is a small library mod that adds extra NPCRole JSON building blocks (BodyMotions / MotionControllers) to make custom NPC behaviors easier to author using JSON.

The goal is to provide reusable, well-documented behavior pieces that plug into the vanilla NPCRole system via Type strings — so role authors can get advanced movement and behavior with less JSON and less custom glue logic.

This project will keep expanding over time as new useful NPC behaviors come up.
If you have ideas or missing vanilla behaviors you’d like to see as JSON-friendly blocks, feel free to suggest them!

What’s Included (currently)

MotionController: `FlyFreeLook`

A flight controller that extends vanilla Fly and supports moving independently from look direction.

Compatibility: Extends MotionControllerFly and uses the same JSON fields as vanilla "fly".
Use cases: strafing/orbiting while still watching a target, drones that should keep tracking a target without constantly turning into the movement direction.

Type id: FlyFreeLook

BodyMotion: `MaintainDistanceFlyRing`

A body motion that behaves like a MaintainDistance-style motion, but designed for flying NPCs.

What it does

Maintains an NPC within a configurable XZ distance band around a target (a “ring/orbit” concept).
Supports configurable vertical offsets (can change over time).
Optional behind-target anchoring (bias the orbit angle behind the target’s movement direction).

Why it’s useful

It’s a MaintainDistance-like solution for flyers, where many setups usually require swapping between multiple motions (e.g. seek → maintain distance → re-seek).
Includes pathfinding (via the BodyMotionFindBase flow), so when a target is present it can keep pursuing while avoiding obstacles.
This can significantly reduce role JSON complexity, because you don’t need as much “glue logic” to handle chasing + spacing + obstacle handling in separate instruction branches.

Requirements

Requires Feature.AnyPosition (an upstream sensor must provide a position each tick).
Validates that the active motion controller is MotionControllerFly-compatible.

Type id: MaintainDistanceFlyRing

Example: Flying orbit + Watch (compact role snippet)

Below is a minimal-style snippet showing how these blocks are typically used inside a role:

FlyFreeLook as the motion controller
Watch as head motion (look at the target)
MaintainDistanceFlyRing as the body motion (keep spacing + orbit + obstacle handling)

Note: This snippet assumes a Target sensor (or any upstream provider) is supplying a target position.

{
  "MotionControllerList": [
    {
      "Type": "FlyFreeLook",
      "MaxHorizontalSpeed": 20,
      "MaxSinkSpeed": 10,
      "MaxClimbSpeed": 12,
      "MinAirSpeed": 0,
      "Acceleration": 7,
      "Deceleration": 15,
      "MaxRollAngle": 180,
      "MaxTurnSpeed": 360,
      "AutoLevel": true,
      "MinHeightOverGround": 0,
      "MaxHeightOverGround": 64,
      "DesiredAltitudeWeight": 0.35
    }
  ],
  "HeadMotion": {
    "Type": "Watch"
  },
  "BodyMotion": {
    "Type": "MaintainDistanceFlyRing",
    "DesiredDistanceRangeXZ": [2.5, 2.5],
    "YOffsets": [1.0, 3.0],
    "YOffsetChangeIntervalRange": [2.0, 4.0],
    "MoveThreshold": 0.35,
    "LockBehindTarget": false
  }
}

Tuning tips

Want less twitchy orbit corrections? Increase MoveThreshold.

Want smoother braking as it reaches the ring point? Increase MoveTowardsSlowdownThreshold.

Want it to prefer staying behind a moving target? Use:

LockBehindTarget: true
BehindBlend around 0.1–0.35
MinTargetSpeed to avoid random flips when the target is barely moving.

`MaintainDistanceFlyRing` Key Options (quick reference)

Required:

DesiredDistanceRangeXZ: [min, max]
YOffsets: [ ... ] (if empty, defaults to [3.0])

Common tuning:

TargetDistanceFactor (default 0.5)
MoveThreshold (default 0.7)
RelativeForwardsSpeed (default 1.0)
RelativeBackwardsSpeed (default 0.6)
MoveTowardsSlowdownThreshold (default 12.0)
HardStop (default false)

Behind anchoring:

LockBehindTarget (default true)
BehindBlend (default 0.25)
MinTargetSpeed (default 0.15)

Feedback / Suggestions

NpcRoleExpansion is meant to grow as a toolbox of reusable NPCRole behaviors. If you have a behavior you frequently re-create in JSON (or something vanilla is missing), suggest it and I’ll consider adding it as a new builder.

NPC Role Expansion