DBetterModel

<div align="center"> ![dbettermodel-omni](https://cdn.modrinth.com/data/cached_images/a13c634669e9e… DBetterModel 6.0 "Omni": one jar for every BetterModel (1.15.x, 2.x, 3.x). </div> One jar for every BetterModel. 6.0 detects the installed BetterModel at startup and selects the matching compat layer — the per-BM-version release matrix of 5.x is gone. | BetterModel | DBetterModel | |---|---| | 1.15.x / 2.0.x–2.2.x / 3.x | 6.0.0 (this jar) | Breaking changes: none. Every 5.0 script runs unchanged.

Highlights

- Universal compat core — three statically compiled layers (v1/v2/v3), selected by BetterModel version at startup. Public BM API only, no private-field reflection. Future BM 4.x gets a best-effort probe instead of a crash. - Capability system — scripts query what the running BetterModel supports via <bm.capabilities>; unavailable features report clean errors, never stacktraces. - Blockbench keyframe signals — denizen:name{key=value} instruction keyframes fire the bm animation signal event on all supported BM lines, including 1.15.x and 2.x. - `bmsummon` — location-bound models (dummy trackers) for props and cutscenes. - Read/write bone API — 5.x write-only display state (glow, tint, billboard, view range, brightness, scale, offset, item) now reads back. - Legacy aliases restored — world_rotation, bone bm_entity, lerp_frames — pre-5.0 scripts work again.

New in the Denizen surface

- Command: bmsummon [model:<model> location:<location>] / [handle:<bmmodel> remove] (with save-entry summoned_model). - Server tags: <bm.version>, <bm.compat_layer>, <bm.capabilities>, <bm.models>, <bm.limbs>. - Events (joining the existing bm starts/finishes reload): bm animation signal, bm player animation signal, bm animation starts, bm animation ends, bm model spawns for player, bm model despawns for player, bm tracker created, bm tracker closed, bm hitbox damaged, bm hitbox interacted, bm model mounted, bm model dismounted. - Mechanism: skin on BMBoneTag — - adjust <[bone]> skin:[part=head;from=<player>], the modern take on bmpart (which stays supported). - Tags: bone getters (glow, glow_color, tint, billboard, view_range, brightness, shadow_radius, scale, offset, item), <BMBoneTag.skin_parts>, <BMModelTag.viewers>, <BMModelTag.running_animations>, <context.model> on signal events, bmmodel@dummy:<id>,<model> identity form for summoned models.

Experimental (see [docs/EXPERIMENTAL.md](https://github.com/meigoc/DBetterModel/blob/main/docs/EXP…

- Keyframe script bridge — denizen:run{script=knight_strike;damage=8} on a Blockbench keyframe starts the named task script with the metadata as definitions. Toggle: experimental.keyframe-script-bridge. - Folia readiness — all internals are region-safe and the jar declares folia-supported: true. Waiting on Denizen's own Folia support to matter on vanilla Folia; works today on force-load forks.

Fixed 5.x bugs

- Bone mechanisms fired their fulfill twice when applied via BMModelTag — now exactly once. - rotate mechanism accumulated rotation modifiers on repeated writes — now replaces. - Debug errors could be swallowed when the debug flag was off — errors always reach the console now. - Update checker rewritten: proper JSON parsing of /releases/latest, failures logged instead of ignored.

DBetterModel vs denizen-utilities (BetterModel bridge)

Both bridge BetterModel into Denizen. Verified against denizen-utilities 2.8.x (BetterModel bridge, compiled against bettermodel-bukkit-api:3.0.1): | | DBetterModel 6.0 | denizen-utilities | |---|---|---| | BetterModel support | 1.15.x + 2.x + 3.x, one jar | 3.x only | | BM API access | public API only | reflection into a BM private field (RenderedBone.itemStack via getDeclaredField/setAccessible) | | Off-thread work | Bukkit/region schedulers | a raw new Thread with Thread.sleep(100) | | Keyframe signals (bm animation signal) | fire on all BM lines, incl. 1.15/2.x | 3.x only | | Location-bound models (dummy trackers) | yes — bmsummon | no | | Skin part → bone | bmpart command and skin mechanism, resolved via BetterModel's tracked profile | .skin mechanism (their bmpart is deprecated) | | Mount / billboard | commands (bmmount, bmboard) | mechanisms (.mount, .billboard) | | Compat safety | build fails if :core touches a BM class; per-version layers | single build against one BM API | denizen-utilities is a capable, actively documented bridge; the table lists only differences that are verifiable in its source, not a quality judgement.

Testing

Verified on five automated headless stands + one manual in-game session, all green. Automated — tests/minecraft/test-headless.dsc (console-driven, spawns its own rig, DBM-RESULT OK/FAIL line): | BM | Layer | Server / Java | Result | |---|---|---|---| | 3.2.0 | v3 | Leaf 26.2 / Java 25 | 19/19 | | 3.0.1 | v3 | Leaf 26.1.2 / Java 25 | 19/19 | | 2.2.0 | v2 | Paper 1.21.10 / Java 21 | 19/19 | | 2.0.1 | v2 (reduced) | Paper 1.21.4 / Java 21 | 19/19 | | 1.15.2 | v1 | Paper 1.21.10 / Java 21 | 19/19 | Manual — tests/minecraft/test.dsc (in-game, visual + event checks): BetterModel 3.2.0 · Denizen 1.3.3-SNAPSHOT (build 7290-DEV) · SkinsRestorer 15.12.4 · Leaf 26.2 (build 17) · DBetterModel 6.0.0. All commands, tags, mechanisms, per-player animation events and keyframe signals confirmed.

Requirements

Java 21+ (Java 25 only when running BetterModel 3.x — BM 3.x itself requires it) · Paper 1.21.x+ · Denizen 1.3.1+. Docs: [wiki.meigo.pw/docs/dbettermodel](https://wiki.meigo.pw/docs/dbettermodel) and the in-repo [docs/](https://github.com/meigoc/DBetterModel/tree/main/docs) folder. Full Changelog: https://github.com/meigoc/DBetterModel/compare/v5.0.0...v…

Feat

- Added bStats metrics integration. - Added shadow_radius mechanism to control bone shadow size. - Added billboard mechanism support directly to BMBoneTag. - New tags: <BMBoneTag.local_position> and <BMBoneTag.real_position>. - BMModelTag now accepts mechanisms (tint, glow, etc.) to apply changes to the entire model at once.

Refactor

- Optimized bmpart command: skins now load asynchronously and apply immediately (removed artificial delay). - Updated <BMBoneTag.global_position> to return a standard LocationTag. - Improved internal rendering logic for better compatibility with BetterModel API. - Removed forced skin cache clearing to improve performance.

Added:

- BetterModel 1.14.0 support

Added:

- BetterModel 1.13.4 support

Bug Fixes

bmmount:* Fixed a command argument parsing error that caused a "Too many linear arguments" failure when executing the command. bmmount:* Refactored the entire command logic to use the BetterModel API directly for mounting and dismounting entities from model bones. * This resolves the core issue where the command would appear to succeed but had no effect. * The command now correctly retrieves the RenderedBone and its HitBox to perform mount/dismount actions. * Added proper error handling to inform the user if the target bone is not a valid seat (i.e., not tagged with p in the model file).

Added:

- <PlayerTag.limb>: Returns the MapTag of the player’s limb animation data. Example: map@[animation_name=roll;loop_mode=loop;default_loop_mode=play_once] - <PlayerTag.limb_bones[<model_name>]>: Returns the MapTag of all player limb bones. - BetterModel 1.13.0 support

Fixed:

- Resolved a critical state management issue where applying transformations to a bone (e.g., scale, item, offset) would reset any previously applied transformations. The bone's state is now persistent across separate commands, allowing for cumulative adjustments.

Added:

- New `offset` Mechanism: Added an offset mechanism to BMBoneTag. This allows scripters to apply a local positional offset to a bone using a LocationTag without altering its currently displayed item or scale. Syntax: adjust <bone> offset:<location>. - New `view_range` Mechanism: Added a view_range mechanism to BMBoneTag. This allows scripters to set the render distance of a bone's display entity in blocks, using a decimal value. This is useful for hiding model parts in certain camera perspectives. Syntax: adjust <bone> view_range:<#.#>.

Changed:

- The item mechanism for BMBoneTag has been refactored. It no longer accepts a LocationTag for an offset. Its sole purpose is now to set the ItemTag for the bone, preserving any existing offset or scale.

Refactored:

- Extracted core bone manipulation logic from BMBoneTag into the new net.openproject.dbettermodel.api.BMBone API class. This significantly reduces complexity in the Denizen object layer, improves code structure, and enhances reusability. - Simplified BMBoneTag to act as a lightweight proxy, delegating all mechanism logic (tint, visible, item) to the new BMBone API.

Added:

- New API Class: Introduced net.openproject.dbettermodel.api.BMBone, a high-level API for programmatic control over individual model bones. It provides simplified methods for tinting, visibility (global and per-player), item setting, and scaling. - New Mechanism: Added a scale mechanism to BMBoneTag. This allows scripters to adjust the non-uniform scale of a bone's displayed item using a LocationTag as a vector. - New Command Argument: Added an optional hide:<player> argument to the bmlimb command. This allows hiding all of the target player's active models from a specific observer player.

Changed:

- Updated the syntax of the bmlimb command to include the new optional hide argument. - Modified BMLimbCommand's processing logic to interact with the target player's EntityTrackerRegistry to apply per-player visibility changes when the hide argument is used.

for BetterModel v1.10.1, MC 1.21.4, Denizen 1.3.1 (7144)

Added:

- Bone Visibility Mechanism (`visible`): Implemented a new mechanism for BMBoneTag to control bone visibility. It supports both global toggling and per-player visibility changes via packet manipulation. [EXPERIMENTALLY, THERE ARE PROBLEMS] - Bone Item Mechanism (`item`): Introduced a mechanism for BMBoneTag that allows setting a custom ItemTag as the bone's model, with optional support for a local LocationTag offset. [This mechanism previously existed, but has been added again] - Configurable Skin Application Delay: Introduced a new option in config.yml (options.skin-apply-delay-ticks) to allow server administrators to define the delay before a player skin part is applied to a model bone via the bmpart command. This provides greater flexibility and control over the timing of asynchronous operations, enabling fine-tuning for server performance and skin-fetching reliability. - Dynamic Skin Part Command (`bmpart`): Implemented the new bmpart command to interface with BetterModel's skin and bone APIs. This command allows scripts to map a model bone to a player's skin part (e.g., head, arm), enabling dynamic model customization. The feature utilizes a custom BoneItemMapper in conjunction with SkinManager#removeCache to ensure skin textures are fetched and applied correctly, even when updated in real-time by other plugins. - SkinsRestorer Hook, new debug, new config and more