AnimationDirector-Blockbench-Plugin/README.md

AnimationDirector

Blockbench tools for creating multi-actor animations and animation definitions for Needs of Nature.

Installation And Requirements

• Install AnimationDirector.js using Blockbench's Plugins > Load Plugin from File. No separate logo or asset files are required.
• Supported baseline: Blockbench 5.2.1 or newer.
• Enable the GeckoLib format plugin to create/import multi-actor animation projects.
• Create JEM Model requires CEM Template Loader. Its preset loader may require an internet connection.
• Desktop Blockbench is required for automatic import, pack folders, item props, JEM transfer, and the NoN sound and particle libraries. These actions are hidden in browser Blockbench; manual JSON import/export remains available.
• Asset Browser is optional. AnimationDirector can use its downloaded Minecraft asset cache, installed Minecraft client archives, or manually selected assets. It does not download vanilla textures itself.

Workflow

1. Use Tools > AnimationDirector Anims > Import Whole Animation to select an animdef or .animation.json from an extracted pack. A new GeckoLib project is created after reviewing actors and models.
2. Alternatively, import actors and animations manually. Actor bones use actorN_ prefixes to prevent name collisions.
3. Use Actor Preferences to set actor names, preview textures, and matching information.
4. Configure Block Requirements with live required-block/clearance previews, and Item Props with locally available assets or a PNG texture.
5. Use Animation Definition to save generator fields in the project or export an animdef. Imported definitions replace the saved fields for that animation.
6. Use Export Animations to export all physical stages and actor clips for an animation ID. Keep the Blockbench project as the editable source.

Preview Tools

• NoN Sound Library auditions cues and assigns local sound previews to imported/created sound keyframes. These preview files are not exported as animation cues.
• NoN Particle Library appears on particle keyframes and in the animation tools menu. Search/filter NoN particles and IDs discovered from remembered pack folders, local Minecraft assets, or a selected JAR/ZIP/assets folder. Choose an available project locator, then apply to selected particle keyframes or insert at the playhead. List thumbnails show the first available sprite without motion or in-game tint; particles without a resolvable sprite show a placeholder. Asset discovery is not a runtime registry check; parameterized particles need a NoN addon resolver unless NoN already handles them (such as its liquid particles).
• Particle Previews enables native timeline previews for NoN's ordinary/falling liquid, small hearts, and ripped fabric. Load their textures from a NoN JAR or extracted assets folder using the particle library. Recognized imported cues are mapped automatically when their locators exist. Previews approximate motion with neutral colors; Minecraft collisions, water interactions and gameplay effects are not simulated. Preview references are excluded from animation exports. Disable previews in the particle library or animation tools menu.
• Autoplay Stages advances non-looping clips to the next physical stage of the same animation ID. It takes priority over Blockbench's global loop toggle without changing that preference. Looping clips and custom timeline ranges remain unchanged.
• The timeline pose buttons copy the preceding stage's final pose to the current start, or copy keyed channels from a looping clip's start to its end. They remain visible but gray out when their requirements are not met.
• Mixed texture-size UV normalization is applied only to GeckoLib projects. Other formats retain their native UV sizing.
• Tools > AnimationDirector Model > Create JEM Model transfers selected additions into a CEM preset. It does not transfer animation keyframes, locators, or modifications to existing vanilla cubes. Review the resulting model and save its textures alongside the exported JEM as appropriate.

Checks

node --check AnimationDirector.js
node -e "for(const f of require('node:fs').readdirSync('test').filter(f=>f.endsWith('.test.js')))require('./test/'+f)"

The tests use Blockbench API doubles. Before release, also check real Blockbench imports, Undo/Redo, JEM texture export, mixed atlas sizes, sound playback, and plugin unload/reload.