Plugin system

Roadmap

Where the skills and models APIs are headed
View as Markdown

The skill system shipped as Slice 1 of a larger design (MythicMobs-class skills + ModelEngine-class models). This page tracks the planned waves. Everything here follows the same invariants as the shipped API: declare once in Starlark/Python, Go interprets pure data on the hot path, capabilities are enforced fail-closed at load, and no vanilla mob’s behavior or RNG stream is ever perturbed by an undeclared feature.

Skills: the road to full MythicMobs parity

Shipped (Slice 1): triggers timer/spawn/damaged/death; targeters self/nearest_player/players_in_radius/mobs_in_radius; mechanics damage/effect; condition health_below; capabilities skills.damage/skills.effects.

WaveContents
P2 — mechanic wave 2summon{mob, amount} (spawn a declared mob, under a new skills.spawn cap), heal{amount}, throw{velocity, velocityY} (velocity write), knockback (the ported LivingEntity.knockback), message{m} (system chat), sound{s, volume, pitch}, teleport, projectile/potion (arrow / splash-potion spawns with per-skill effect payloads).
P3 — meta-skills + schedulingNamed reusable skills (declare_skill(name, ...) invoked via mechanic("skill", s="...")), per-mob per-skill cooldown, delay (pending-mechanic queue), repeat.
P4 — triggers wave 2attack (post-hit on the mob’s own melee), combat (target acquired), player_kill; trigger-target threading so damaged can target its attacker (the MythicMobs @target / <trigger.name> analogue).
P5 — conditions wave 2 + mob optionstarget_within{d}, day/night, in_water; MythicMobs-style Options (KnockbackResistance, PreventOtherDrops, AlwaysShowName), per-declaration DamageModifiers, Equipment, custom Drops tables.
P6 — mob-target duration effectsGeneralize effect ticking beyond the current witch lane so effect mechanics on mob targets tick and expire (today mob targets get add + instant semantics; players already have full semantics).
P7 — random spawnsA declared-spawn table consulted by natural spawning (registry-keyed, under skills.spawn).

Reserved capability strings (documented, rejected-as-unknown today): skills.spawn, skills.projectile, skills.world, models.declare.

Persistence note: declared mobs are currently session-scoped; a future entity-persistence pass will re-attach skill runners by declaration name on world load.

Models: ModelEngine-class declared rigs (design)

The planned declare_model API brings Blockbench-style rigs — bones rendered as item displays, mounted on an invisible base mob, animated by server-side keyframe interpolation with client-side smoothing:

1declare_model(
2    name = "golem_rig",
3    bones = [
4        bone(name = "body", item = "minecraft:iron_ingot", pivot = (0.0, 1.2, 0.0)),
5        bone(name = "head", item = "...", pivot = (0.0, 2.0, 0.0), parent = "body"),
6    ],
7    animations = [
8        animation(name = "idle", loop = True, length = 40,
9            channels = [channel(bone = "head", kind = "rotation",
10                                keyframes = [(0, (0,0,0)), (20, (0,15,0)), (40, (0,0,0))])]),
11    ],
12)
13
14declare_mob(..., model = "golem_rig", ...)

Planned phases:

PhaseContents
M1Display-entity metadata port (translation/scale/rotation/interpolation synched data) + the spawn/mount seam.
M2declare_model + static rig attach — bones mounted on the base entity via passenger packets so base movement syncs bones for free.
M3Animation clips + the Go keyframe interpolator (transform pushes every 2–3 ticks with client interpolation filling the gaps — zero Starlark on the hot path).
M4Animation state machine (idle/walk selected by nav state) + the skills bridge (mechanic("play_animation", name=...)).
M5A .bbmodel importer as a Python off-tick plugin (heavy Blockbench JSON parse stays off the tick; the declared result is hot-path data).

As with skills, the MythicMobs and ModelEngine plugins are conceptual references only — they define what an operator can express, never a runtime or config-compatibility target.