On this page
Supported Boundaries and Unsupported Operations
Applies to ECSAnimator 0.1.0-preview.1 and V6 artifacts. Updated October 3, 2026. These rules concern authoring, export and integration, not the gameplay available to players.
A successful Build does not mean that every Prefab component or Animator behavior was converted.
| Status | Meaning |
|---|---|
| Rejected | Preview, Build or runtime validation rejects the input. Repair it; do not remove validation or tamper with artifacts. |
| Omitted | Build may proceed without another confirmation. Preview/completion diagnostics and OmittedFeatures identify behavior that will not run. Supply a gameplay replacement if needed. |
| Not implemented | No complete implementation/contract exists. Not every invalid combination is necessarily detected automatically. |
| Needs verification | An implementation path or structural check exists, but target-specific runtime evidence is incomplete. Test before claiming support. |
See the conversion guide, Animator support, Shader guide and API for procedures.
1. Prefabs, multiple Animators and composition
The conversion unit is a skeletal character driven by one selected Animator, not an arbitrary GameObject tree. CharacterRuntimeAsset is the single descriptor type; no automatic GameObjectRuntimeAsset composition format exists.
| Input or operation | Boundary | Correct approach |
|---|---|---|
| A body and two child objects each have an Animator | Only the selected/first Animator is compiled. Others are omitted. There is no automatic split into three artifacts, saved composition or child spawning. | Accept the other parts having no independent animation, or create three complete single-Animator Prefabs and manage their loading, following, parameters and cleanup in gameplay. |
| Multiple Animators without a selection | First hierarchy-order Animator, including inactive objects, is selected; others are disabled only in the sampling copy. Source assets remain unchanged. | Inspect Animator used. Missing Controller on the selected Animator is an error; the tool does not silently try a second one. |
| Preset Animator Path | Selects one Controller/Avatar, not a subtree filter or multi-Animator switch. Renderer/socket/LOD discovery still traverses the full Prefab. Valid skins/bones under other Animators may be included without independent animation. | A valid path wins. Empty selects the first; an invalid path warns with CVT008_ANIMATOR_PATH_NOT_FOUND and falls back to the first. |
| One Animator, multiple valid SMRs and fixed weapons | Supported within other constraints. Multiple renderers are not multiple Animators. | Keep fixed geometry, or remove it, retain sockets and rebuild for dynamic equipment as in Demo17. |
| One Animator but only static MeshRenderers, no SMR | Rejected; Convert Character is not a static-Prefab converter. | Load rigid equipment meshes/materials through Entities Graphics; no extra Animator/artifact is required. |
| Nested Prefabs, Variants or deep Transform trees | Not universally rejected, but no recursive runtime assembly, Variant replay or automatic child instantiation contract exists. | Validate the final saved character; gameplay owns dynamic children. |
| Bones/socket owners outside the exported Prefab | Rejected when bindings leave the export hierarchy. | Keep each character's complete skeleton and valid Controller/Avatar/references within its conversion unit. |
| Manually merging artifact arrays, skeleton indices or payloads | Not implemented and invalid. Runtime retargeting to arbitrary Avatars is also absent. | Modify sources and rebuild; composed gameplay objects retain separate artifacts/lifecycles. |
Splitting multiple Animators into independent inputs does not establish an integrated multi-Animator character feature. Demo17 equipment has no Animator or runtime skinning.
2. Input hierarchy, geometry and components
| Input or assumption | Result | Remedy |
|---|---|---|
| FBX or temporary scene object as direct window input | Rejected | Save a .prefab first |
| Inactive/disabled renderer used to exclude content | Discovery includes inactive objects | Remove it from a conversion-specific Prefab or manage it separately |
| Duplicate sibling names, invalid path names, nonfinite transforms or zero scale | Rejected | Repair names/transforms and recheck animation paths |
| Missing/unreadable mesh, incomplete Position/Normal/Tangent/UV0, non-triangles or invalid vertices/weights | Rejected | Fix/reimport the mesh and enable Read/Write |
| Missing/duplicate bones, bone/bind-pose count mismatch or inconsistent root-space bind poses across renderers | Rejected | Repair binding in the authoring tool; maintain compatible LOD skeletons |
| Mesh contains BlendShapes, even at zero weight | Rejected | Use a mesh without them or another rendering route |
| Dependence on vertex colors, UV1/UV2 or custom streams | Those streams are not supported by the derived-mesh contract | Use available inputs or separately implement/validate an extension |
| Ordinary MeshRenderer, particles, trails, lines or sprites | Omitted with diagnostics, except valid fixed attachments | Manage effects separately using sockets/events |
| Rigid MeshRenderer without a valid nearest CharacterAttachmentAuthoring, unique MeshFilter/sharedMesh or valid owner | Renderer omitted; invalid socket markers can still cause errors | Follow fixed attachment setup |
| Automatic conversion of particles, physics, navigation, audio, lights, cameras or MonoBehaviours | Not provided; no user Baker invocation | Implement corresponding gameplay systems |
| Runtime Cloth, Animation Rigging or constraints on spawned ECS characters | Not implemented; External also rejects Cloth | Bake acceptable skeletal input or implement a controlled runtime system |
| MaterialPropertyBlock on exported renderers | Rejected | Use public appearance routes or different source materials/artifacts |
| Per-instance Light Probe Usage / Probe Anchor | Omitted and normalized off | Only global ambient lighting is retained |
3. Animator behavior, curves and limits
| Behavior or input | Boundary / alternative |
|---|---|
| Apply Root Motion moves the character | Omitted; gameplay writes root LocalTransform |
| StateMachineBehaviour callbacks, IK Pass, Foot IK, runtime IK targets/terrain | Omitted; migrate logic to gameplay and implement any required IK separately |
| AnimationEvent invokes MonoBehaviour SendMessage | No invocation; consume public event records. Object-reference event parameters are rejected. |
| Material, BlendShape, visibility or object-reference animation | Rejected. Only supported observable Transform and known Humanoid channels are accepted. Curves for ordinary children outside skin/socket observation can also reject; declare required sockets or separate the effect. |
| Invalid animation path is always detected | A nonexistent Transform path can follow Unity's no-op behavior; inspect actual animation and selected-Animator-relative paths |
| Nested AnimatorOverrideController chains or other Controller types | Rejected; use AnimatorController or one direct override |
| Additive/masked base layer | Rejected; base must be Override without AvatarMask |
| Sync to a later layer, itself or another sync layer | Rejected; source must be an earlier non-sync layer |
| Duplicate parameters, wrong parameter types, invalid/cyclic graphs or transitions, empty/unsupported BlendTrees | Rejected. Speed/Time/CycleOffset/blend inputs use Float; Mirror uses Bool. |
| Duplicate/nonfinite 1D thresholds, overlapping 2D points, several Simple Directional motions in one nonzero direction | Rejected; use Freeform Directional for different speeds along one direction |
| Capacity overflow with expected silent truncation/degradation | Rejected or diagnosed at runtime; reduce contributions/complexity |
| Capacity | Maximum |
|---|---|
| Animator layers | 8 |
| Motion-graph nodes / nesting depth | 1024 / 16 |
| Worst-case active contributions, including transitions/interruptions | 32 |
| Exported skeleton nodes / influences per vertex | 256 / 6 |
| Transition conditions / internal transition steps per update | 8 / 64 |
Five BlendTree types and eight layers do not imply complete Unity Animator compatibility. Humanoid Root/hand/foot inputs can influence offline sampled poses but do not provide runtime Root Motion/IK. Humanoid is the supported Mirror sampling route; arbitrary Generic mirroring is not guaranteed.
4. Sockets, equipment and LOD
| Operation or assumption | Boundary / correct approach |
|---|---|
| Duplicate/invalid socket keys, external owner bones, nonfinite/degenerate offsets | Rejected or binding fails. Use unique semantic keys, in-character bones and valid transforms, then rebuild. |
| Attaching a second sword while the first is baked into the body | Both render. Remove fixed renderers, repair LOD references, retain sockets and rebuild first. |
| Rigid equipment API takes over Parent hierarchies, child render trees, skinned or animated equipment | Not implemented; one independent rigid rendering root in the same World is supported |
| Equipment source LOD children imply runtime child-Entity support | Demo17 extracts meshes and creates one render Entity. Each source level uses a unit-transform MeshRenderer child, one submesh and the same material. |
| Multi-bone skinned weapon treated as static equipment | Independent deformation is lost. Demo17 authoring only validates single-bone weights and bind-space correction. |
| Cross-World/stale prepared/handle, unfinished spawn placeholder, duplicated root/PostTransformMatrix | Invalid binding or placement. Use resolved current identities and compose each transform once. |
| Attachment system plus Parent/another system writes LocalToWorld | Unsupported competing writers. Remove the binding before transferring ownership to physics/gameplay. |
| Destroying the character automatically destroys/unloads equipment | Not implemented. Gameplay destroys equipment first. Invalid following alone may retain its old transform; automatic equipment LOD hides an orphan but does not destroy it. |
| Automatic CharacterRigidEquipmentLod and manual callback both write MaterialMeshInfo | Remove the automatic component for manual mode. Apply current Level/Hidden immediately on first equip, not only after the next callback. |
| Invalid/unloaded LOD mesh indices or bounds covering only LOD0 | Use contiguous loaded meshes in one RenderMeshArray, fixed material/submesh and bounds covering every level. Missing levels clamp, not generate meshes. |
| Demo17 OnLodChanged is a global managed or animation-frequency callback | It observes one body's model Level/Hidden on the main thread. Do not call managed delegates from Burst; use ECS data for batches. |
| Several enabled LODGroups with exported levels, including nested independently switching groups | Rejected; at most one valid enabled group with 1–8 retained levels |
| Cross Fade, Animate Cross-fading or nonzero Fade Transition Width | Rejected; direct switching only |
| Unsupported renderer references or levels containing only them | Omitted with diagnostics; retained thresholds are kept and levels renumbered. With no valid group, all exported meshes form one level. |
| Genuine empty/null/out-of-Prefab LOD references, reused renderers/meshes | Rejected; each subsequent retained level must reduce both total vertices and triangles |
| Thresholds outside (0,1], not strictly decreasing, or invalid reference size | Rejected; correct the source LODGroup |
| Disabling LODGroup means “show only LOD0” | Without an enabled group, all exported render items may appear together. Remove unwanted levels instead. |
| Fixed model-LOD distance, or animation LOD reduces mesh/bone count | Model LOD uses screen height and depends on bounds/FOV/scale/lodBias. Animation LOD changes distance-based evaluation frequency. No runtime mesh decimation or bone-count LOD. |
| Every eight frames means 8 Hz, slow motion or guaranteed eightfold saving | Frame interval is not Hz; elapsed time accumulates, sockets reuse committed poses. Check visible animation, not counters alone. |
| Changing live shared animation LOD for one World/Product Key | Conflicting explicit Prepare settings reject. Retire all users and wait for Released before preparing the new policy. |
Demo17's equipment, automatic/manual LOD and visible Idle have local Windows D3D11 Player evidence and Unity 2022.3.1f1 Editor checks. This does not qualify multi-Animator composition, mobile or arbitrary equipment. See Demo17 and Demo18.
5. Shaders, rendering and platforms
| Assumption or operation | Boundary |
|---|---|
| Ordinary URP/Lit or vendor Shader automatically animates a converted skin | No automatic adaptation. Use ECSAnimator/Lit or the External SDK. Independent rigid equipment can use ordinary Entities Graphics materials, as in Demo17. |
| Mix PackageOwned Lit and External in one character | Rejected; use one profile per artifact |
| Transparent blending, effective queue >2450, Deferred or arbitrary extra geometry passes | Outside the current contract; queue checks reject. Changing only the queue does not make a transparent effect supported. |
| External renderer-to-root nonidentity transform, Cloth or object/skeletal motion | Rejected; identity static transform, no Cloth and Camera Motion Only are required |
| Deform Forward only and reuse ordinary URP depth/shadow passes | Incomplete adaptation. All four geometry passes need deformation and consistent clipping; inspect actual pixels. |
| Treat instance ID as character index, write metadata, include private Lit passes or draw through diagnostic GPU leases | Outside the public contract. Use the public Shader/command/observation interfaces. |
| Built-in/HDRP, OpenGL/ES or WebGL | Outside current scope. D3D12/Vulkan/Metal source paths still require target qualification. |
| External Preview/NeedsVerification or successful Shader compilation establishes cross-platform support | No. Graph Metal has a known URP compiler issue; test animation, shadows, depth, clipping and lifecycle on the target. |
| Disable required SRP Batcher, strip BRG/DOTS variants or lack instancing/AsyncGPUReadback | Rendering prerequisites are missing |
| Stereo/XR, RenderTexture or non-display-0 LOD camera; changing MainCamera tag automatically rebinds | Outside the current camera contract. Use a valid Game camera and TrySetLodCamera. |
| Zero, negative or nonuniform character-root Spawn scale for mirroring | Spawn requires finite positive uniform scale. Shader-specific mirror tests do not change that contract. |
6. Commands, loading, cleanup and rebuilding
| Operation or assumption | Correct rule |
|---|---|
| Build in Player/Task.Run or two Editors concurrently building one project | Build synchronously on the Editor main thread |
| Change sources/presets during Build; remove recovery/transactions; edit digests, payloads, generated meshes/materials | Repair sources and rebuild. Retain diagnostics and last-green data. Set scale in SpawnRequest; use exact Controller keys for animation. |
| Overwrite imported sample output as if it were locally owned build history | Use a newly named source, unique Product Key and your own empty output; do not bypass artifact-authority-invalid |
| Load/copy a descriptor without all its referenced dependencies | Load the descriptor and all transitive dependencies through your resource system |
| Built-in remote downloader, ResourcesManager, Bundle packager or Addressables reference-counting adapter | Not implemented; supply your own loader and validate its complete route |
| Different Artifact Digests under one live World/Product Key; mutate loaded artifacts | Retire all old users first. Do not change Product Key merely to mask conflicts. Rebuild V4/V5 as V6. |
| Reuse runtime/prepared/Entity/binding/request identities across Worlds or after rebuild | Reacquire all identities. Replacing plugin systems in a live World is also unsupported. |
| Cache a TryBind writer across frames or bind many targets sequentially in one frame | Bind once per client/update; use TryReserveTargets for batches/Jobs |
| Several clients write one character in one frame | Commands conflict; arbitrate gameplay priority before one writer submits |
| Wrong parameter type/key, Play to zero every frame, successful write means animation completed | Match bindings, submit playback on intent changes, match Accepted receipts, then observe consumption/events separately |
| Animator dampTime overload or direct commands to a retained Unity Animator | Neither is provided; smooth in gameplay and use public clients/writers |
| Skip RegisterProducer after scheduling, retain event/receipt buffers across frames or mutate observations | Register dependencies, read in the correct group, copy only required history values |
| Prototype customization injects managed/shared/cleanup or plugin/Transform/Rendering/Prefab/Disabled/LinkedEntityGroup/MaterialProperty types | Only supported unmanaged gameplay components/buffers are allowed. Initialize declared types only; increment revision when configuration/defaults change. |
| Release true immediately permits unloading meshes/materials/Bundles | It confirms the request only. Stop producers, dispose clients, destroy equipment/instances, release prepared data, wait for Released and ensure no other users retain dependencies. |
| Busy-wait Pending, treat Invalid/FaultedRetainedRequiresWorldRebuild as Released, dispose shared GPU/Blob data manually | Continue normal updates and follow diagnostics. Never force-release resources without proven GPU completion. |
| Clear a terminal diagnostic and keep using the failed character/World | Correct the cause, destroy/respawn a failed character, or rebuild the World after a GPU submission fault. Resource retention is intentional safety behavior. |
7. Before delivery
Test the exact Prefabs, Controllers, Shaders and loading paths your project uses. Verify visible Idle and clear movement, transitions, sockets, model/animation LOD, dynamic equipment and complete release. Use a fixed close-up camera to confirm pose changes. Omitted or unimplemented behavior needs an explicit gameplay replacement before calling the result equivalent.
Do not promise arbitrary one-click Prefab conversion, 100% Animator compatibility, guaranteed LOD speed/memory gains, or qualification of every platform and population. Measurements apply to their hardware, quality, evaluation frequency and visible workload; additional LOD resources can increase residency. Untested configurations must remain unverified rather than inheriting another scene's results.