--- title: Limitations description: >- What is parsed but not evaluated, what breaks and how, which blend modes are approximated, and what the verification does not prove. --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.page/RafaelBarbosatec/dragonbones_flutter/llms.txt > Use this file to discover all available pages before exploring further. This is the page that decides whether the packages can carry your project. It is deliberately specific. A vague "not everything is supported" is worse than useless, because the failure mode here is silent: an unsupported feature **loads, parses and animates**, then produces subtly wrong geometry rather than an exception. If you are evaluating, check the table in [Not evaluated](#not-evaluated) against your art pipeline before anything else. Nothing in it throws — it just quietly gets the pose wrong. ## Not evaluated Each row is *parsed* by the data model but never *applied* at runtime. None of them throw. All of them will make your animation quietly wrong. | Feature | What is missing | What you will see | | --- | --- | --- | | **Path constraints** (`PathConstraint`) | `PathConstraintData` is parsed into the model; the runtime class is never built. `Armature._buildConstraints` handles IK only. | A bone meant to travel along a path stays at its own transform. | | **Binary `.dragonbones` input** (`BinaryDataParser`) | Only `ObjectDataParser` (JSON) exists. | A binary export will not parse at all — this one *does* fail loudly, which is the good kind. | ### How to tell if your asset is affected You do not have to guess — the data is in the JSON you already have. Search the skeleton JSON: | Look for | Meaning | | --- | --- | | `"path"` | Path constraints — not supported. | | `"ik"` inside an armature | IK constraints — **supported** (static since 0.3.0, animated since 0.4.0). | | `"type":1` in a `bone` entry | `BoneType.Surface` — **supported** as of 0.4.0. | | `"type":30` in a timeline | `IKConstraint` timeline — **supported** as of 0.4.0. | | `"type":40` / `41` / `42` in a timeline | Animation progress/weight/parameter — **supported** as of 0.4.0. | | `"type":50` in a timeline | `Surface` timeline — **supported** as of 0.4.0. | | `"blendType": "1d"` / `"2d"` | Animation blending — **supported** as of 0.4.0. | | `"type":23` in a `slot` timeline | `SlotZIndex` timeline — **supported** as of 0.3.0. | | `"type":24` / `"type":60` in a timeline | `SlotAlpha` / `BoneAlpha` timeline — **supported** as of 0.3.0. | (The timeline type numbers above are the ones this port uses; see `TimelineType` in `packages/dragonbones/lib/src/core/dragon_bones.dart`.) Two real examples from this repository's own fixtures, which is why the limitation was originally stated with such confidence: - The `龙` fixture has two IK constraints, but **both have `weight: 0`** — inert. They pass, and for a while they hid the fact that the `IKConstraint` class had not been written at all. - The `mecha_1406` and five `you_xin` assets declare IK **without** a `weight` field. The parser default is `1.0`, so they are active — and they were the seven assets that failed until `IKConstraint` was ported. See [Investigation findings § 9.1](/findings). ### One upstream quirk, reproduced on purpose `IKConstraintTimelineState` reads `_currentA` / `_currentB` — the value the timeline arrived at when it entered the segment — rather than the interpolated `_resultA` / `_resultB`. The official runtime does the same, so an animated IK weight **steps at frame boundaries instead of tweening**, and a keyframe with tweening disabled never applies at all. The port matches that exactly (verified frame by frame), because diverging would be a silent difference from every other DragonBones player. If you need smooth IK weight, key it on more frames. ## Approximated in the renderer | Item | Detail | | --- | --- | | **Five blend modes** | `Alpha`, `Erase`, `Invert`, `Layer` and `Subtract` have no exact counterpart in `dart:ui`, so the closest `ui.BlendMode` is used (`dstIn`, `dstOut`, `difference`, `srcOver`, `difference` respectively). The other nine — `Normal`, `Add`, `Multiply`, `Screen`, `Darken`, `Lighten`, `Overlay`, `HardLight`, `Difference` — map exactly. No fixture in the 56-asset set uses the approximated five, so they are **unverified**, not merely approximated. | | **Rotated atlas entries** | A code path exists for regions stored rotated a quarter turn in the atlas, and it is marked unverified in-source. No fixture uses one. If your atlas packs rotated regions, validate this before shipping. | The mapping is in `packages/dragonbones_flutter/lib/src/player.dart` and is easy to read if you want to check a specific mode. ## Not verifiable in this repository | Item | Why | Consequence | | --- | --- | --- | | **Appearance** | CI runners have no GPU. | The renderer tests rasterise and count painted pixels. That catches "wired wrong and drew nothing"; it cannot catch "drew it in the wrong place" or "wrong colour". Eyeballs are required. | | **Performance** | No benchmarks exist. | Allocation behaviour differs from the official runtimes because object pooling was dropped. If you run hundreds of animated characters per frame, measure it yourself before committing. | ## Deliberate deviations from upstream These are choices, not gaps — but they change behaviour, so they are listed. - **No object pooling.** Upstream implements a per-class pool (`BaseObject.borrowObject` / `returnToPool`). Dart's GC makes it unnecessary, so objects are constructed directly. This is the single biggest structural difference from the reference implementation. - **An upstream bug was NOT transcribed.** In `Slot`'s `displayFrameCount` setter, the removal branch upstream reads `for (let i = prevCount - 1; i < value; --i)` — the loop condition is never true, so the body never runs and the removal silently does nothing. The port uses `i >= value`, so the removal actually happens. Behaviour therefore *differs from upstream* in this one case, on purpose. - **JS array growth.** Upstream grows arrays with `list.length = n`, which in JS creates sparse holes. Dart cannot do that for non-nullable element types, so those sites were rewritten to append. Four crashes were traced to this during the port; see [Investigation findings § 8.4](/findings). ## What *is* verified, for contrast So the limitations above can be read against a known baseline. Verified frame by frame against the official DragonBones runtime: - bone global matrices, and bone translate/rotate/scale/all timelines, - slot draw data: world matrix, pivot, quad size, atlas region, z-order, visibility, blend mode, colour — and the slot display and colour timelines, - deform (FFD) timelines, and deformable meshes both plain and **skinned**, with posed vertices, UVs and triangle indices, - **static IK constraints**, - nested child armatures, flattened with the parent slot's matrix composed on, - **animation events**: frame events and sound events placed on the timeline, the `start` / `loopComplete` / `complete` / `fadeIn` / `fadeOut` lifecycle events, and the propagation that makes playing an animation on a parent play the same-named animation on its nested children — compared against the official runtime as a **sequence**, per fixture and per animation, in `tool/check_events_against_oracle.dart`, - z-order and action timelines, - **animated IK**: weight and `bendPositive` from an `IKConstraint` timeline, including the upstream step-at-frame-boundary behaviour, - **`Surface` bones** and `Surface` timelines: the 117-bone vertex grid, the per-cell affine transform and meshes posed through it, - **animation blending**: `AnimationProgress` / `AnimationWeight` / `AnimationParameter` child states and `AnimationBlendType.E1D`. 56 assets, 1,353,695 numeric comparisons and 1,919 events, 0 mismatches. The numbers, the method and the caveats (including that the mesh oracle is the official *Egret binding*, not the core runtime) are in [Architecture & verification](/architecture#verification) and [Investigation findings](/findings).