DECI-lib

Data-Driven Entity Composition Interface

Deci-Lib is a modular framework for defining fully custom mobs through data rather than code. You can create compositions of behavior, timing, and presentation, allowing complex mob encounters entirely through JSON while remaining deterministic and debuggable.

Mobs are built from features: discrete units of behavior such as melee attacks, sweeps, charges, ambush mechanics, and movement controllers. These features operate within a shared lifecycle (windup → release → recovery), which is exposed directly in data.

Animation is integrated at the lifecycle level rather than being tied to specific logic. Deci-Lib can use backends such as GeckoLib or AzureLib, but mob behavior is detached from this backend. Mob definitions remain identical regardless of whether you use a full animation system, a custom model, or alternative rendering approaches. Looping states and action animations are defined alongside behavior.

Features compete through a priority system and are gated by cooldowns and minimum cooldown thresholds, preventing uncontrolled chaining while keeping outcomes predictable. Movement modes, targeting logic, and positional constraints are all data-defined, allowing you to create mobs that behave based on their environments rather than seemingly randomly.

DISCLAIMER

Deci-Lib is best understood as an abstraction layer over entity behavior: it standardizes how mobs are constructed, how abilities are executed, and how animation is synchronized, while leaving the actual design decisions fully in the hands of the author. It is not intended for use as a low effort content generator. The best content to come from this mod is content that has intent behind it, as well as shows restraint in implementation rather than uncontrolled increase in scope.

THIS MOD INCLUDES EXAMPLE MOBS REGISTERED AND SPAWNING BY DEFAULT. LOOK IN THE CONFIG TO DISABLE IF NEEDED.

Mobs included are: Apex Predator, Shadow Fist, Dire Wolf, Rat, Scalebane Archer, Scalebane Viper, Scalebane Striker

Example Mobs (Included and spawning by default):

{
  "id": "apex_predator",
  "archetype": "bruiser",
  "theme": "beast",
  "form": "azurelib",

  "render": {
    "backend": "azurelib",
    "assets": {
      "geo":       "deci-lib:geo/bear.geo.json",
      "animation": "deci-lib:animations/bear.animations.json",
      "texture":   "deci-lib:textures/entity/bear.png"
    },
    "loops": {
      "idle": "bear.anim.idle",
      "idle_hostile": "bear.anim.idle",
      "moving": "bear.anim.moving",
      "moving_hostile": "bear.anim.moving",
      "running": "bear.anim.moving2"
    }
  },
  "scale": {
    "width": 1.2,
    "height": 2.8
  },
  "tuning": {
    "health": "HIGH",
    "damage": "HIGH",
    "speed": "MEDIUM",
    "detection": "HIGH"
  },

  "attributes": {
    "max_health": 40.0,
    "attack_damage": 10.0,
    "melee_range": 3.0,
    "knockback_resistance": 0.5
  },

  "features": [
    {
      "type": "idle",
      "mode": "wander",
      "wander_range": 6.0,
      "pause_ticks": 40,
      "scan_interval_ticks": 30
    },

    {
      "type": "charge",
      "ability_id": "ground_slam",
      "cooldown_ticks": 120,
      "min_cooldown_ticks": 80,
      "charge_speed":          0,
      "upwards_speed":         0,
      "windup_ticks": 12,
      "release_delay": 20,

      "release_type": "radial",
      "range": 4.5,
      "coeff": 2.5,

      "priority": 120,

      "on_start_particles": "smoke_burst",
      "on_complete_particles": "smoke_ring",

      "animations": {
        "on_windup": "bear.anim.slam"
      }
    },

    {
      "type": "charge",
      "ability_id": "swipe",
      "cooldown_ticks": 120,
      "min_cooldown_ticks": 80,
      "charge_speed":          0,
      "upwards_speed":         0,
      "windup_ticks": 10,
      "release_delay": 6,

      "release_type": "arc",
      "range": 4.5,
      "coeff": 1.5,

      "priority": 100,

      "on_start_particles": "smoke_burst",
      "on_complete_particles": "sweep_arc",

      "animations": {
        "on_windup": "bear.anim.swipe1"
      }
    },

    {
      "type": "melee",
      "cooldown_ticks": 15,
      "priority": 60,

      "animations": {
        "on_action": "bear.anim.swipe2"
      }
    }
  ]
}

{
  "id": "shadow_fist",
  "archetype": "skirmisher",
  "theme": "sand",
  "form": "azurelib",
  "render": {
    "backend": "azurelib",
    "assets": {
      "geo":       "deci-lib:geo/shadow_fist.geo.json",
      "animation": "deci-lib:animations/rogue.animations.json",
      "texture":   "deci-lib:textures/entity/shadow_fist.png"
    },
    "loops": {
      "idle":   "animation.mob.idle_calm",
      "idle_hostile":   "animation.mob.idle",
      "moving": "animation.mob.walk_calm",
      "moving_hostile": "animation.mob.walk",
      "running": "animation.mob.running"

    }
  },
  "tuning": {
    "health":    "MEDIUM",
    "damage":    "LOW",
    "speed":     "HIGH",
    "detection": "MEDIUM"
  },
  "attributes": {
    "max_health": 40.0,
    "attack_damage": 5.0,
    "melee_range":   2.0
  },
  "features": [
    {
      "type":         "idle",
      "mode":         "wander",
      "wander_range": 5.0,
      "pause_ticks":  20
    },
    {
      "type":           "melee",
      "cooldown_ticks": 20,
      "animations": {
        "on_action": "animation.mob.swing1"
      }
    },
    {
      "type":                  "ambush_attack",
      "ability_id":            "sand_vanish",
      "cooldown_ticks":        200,
      "min_cooldown_ticks":    60,
      "hidden_duration_ticks": 40,
      "movement_mode":         "strafe",
      "surface_mode":          "behind",
      "strafe_radius":         4.5,
      "burrow_mode":           true,
      "priority":              18,
      "on_tick_particles":     "dust_trail",
      "on_interrupt_particles":"smoke_burst",
      "animations": {
        "on_complete": "animation.mob.swing1"
      }
    },
    {
      "type":                  "charge",
      "ability_id":            "sand_dash",
      "cooldown_ticks":        80,
      "windup_ticks":          4,
      "release_delay":         10,
      "release_type":          "arc",
      "half_angle_deg":        50.0,
      "range":                 3.0,
      "coeff":                 0.9,
      "charge_speed":          2.2,
      "upwards_speed":         0.1,
      "on_start_particles":    "poof_burst",
      "on_complete_particles": "sweep_arc",
      "animations": {
        "on_windup":  "animation.mob.trickster.roll",
        "on_release": "animation.mob.slashtwo"
      }
    },
    {
      "type":           "sweep",
      "ability_id":     "sand_swipe",
      "cooldown_ticks": 28,
      "min_cooldown":   8,
      "half_angle_deg": 55.0,
      "range":          2.5,
      "coeff":          0.75,
      "animations": {
        "on_action": "animation.mob.slashtwo"
      }
    }
  ]
}

Spawning Data:

{
  "mob_id": "shadow_fist",
  "category": "monster",
  "spawns": [
    {
      "weight": 5,
      "group_size": [1, 1],
      "biomes": ["#minecraft:is_forest", "#minecraft:is_jungle"],
      "dimension": "minecraft:overworld",
      "light_level": { "min": 0, "max": 7 },
      "conditions": ["on_ground", "natural_only"]
    },
    {
      "weight": 5,
      "group_size": [2, 3],
      "biomes": ["minecraft:dark_forest"],
      "dimension": "minecraft:overworld",
      "light_level": { "min": 0, "max": 11 },
      "conditions": ["on_ground", "natural_only"]
    }
  ]
}

{
  "mob_id": "apex_predator",
  "category": "monster",
  "spawns": [
    {
      "weight": 5,
      "group_size": [1, 1],
      "biomes": ["#minecraft:is_forest", "#minecraft:is_jungle"],
      "dimension": "minecraft:overworld",
      "light_level": { "min": 0, "max": 7 },
      "conditions": ["on_ground", "natural_only"]
    }
  ]
}

Datapack Structure:

deci-lib_datapack/
├── pack.mcmeta
└── data/
    └── deci-lib/
        ├── mob_spawns/
        │   ├── apex_predator.json
        │   └── shadow_fist.json
        └── mobs/
            ├── apex_predator.json
            └── shadow_fist.json