> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trysulfur.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trysulfur.net/_mcp/server.

# Roadmap

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`.

| Wave                                     | Contents                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **P2 — mechanic wave 2**                 | `summon{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 + scheduling**        | Named reusable skills (`declare_skill(name, ...)` invoked via `mechanic("skill", s="...")`), per-mob per-skill `cooldown`, `delay` (pending-mechanic queue), `repeat`.                                                                                                                                                                                  |
| **P4 — triggers wave 2**                 | `attack` (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 options** | `target_within{d}`, `day`/`night`, `in_water`; MythicMobs-style Options (`KnockbackResistance`, `PreventOtherDrops`, `AlwaysShowName`), per-declaration `DamageModifiers`, `Equipment`, custom `Drops` tables.                                                                                                                                          |
| **P6 — mob-target duration effects**     | Generalize 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 spawns**                   | A 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:

```python
declare_model(
    name = "golem_rig",
    bones = [
        bone(name = "body", item = "minecraft:iron_ingot", pivot = (0.0, 1.2, 0.0)),
        bone(name = "head", item = "...", pivot = (0.0, 2.0, 0.0), parent = "body"),
    ],
    animations = [
        animation(name = "idle", loop = True, length = 40,
            channels = [channel(bone = "head", kind = "rotation",
                                keyframes = [(0, (0,0,0)), (20, (0,15,0)), (40, (0,0,0))])]),
    ],
)

declare_mob(..., model = "golem_rig", ...)
```

Planned phases:

| Phase  | Contents                                                                                                                                                      |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **M1** | Display-entity metadata port (translation/scale/rotation/interpolation synched data) + the spawn/mount seam.                                                  |
| **M2** | `declare_model` + static rig attach — bones mounted on the base entity via passenger packets so base movement syncs bones for free.                           |
| **M3** | Animation clips + the Go keyframe interpolator (transform pushes every 2–3 ticks with client interpolation filling the gaps — zero Starlark on the hot path). |
| **M4** | Animation state machine (idle/walk selected by nav state) + the skills bridge (`mechanic("play_animation", name=...)`).                                       |
| **M5** | A `.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.