On this page
ECSAnimator User Manual
Package: com.asterism.ecsanimator 0.1.0-preview.1. Updated October 4, 2026.
ECSAnimator converts skeletal animation and Animator Controllers into offline assets, then evaluates and renders characters with Unity Entities. Start with installation, convert one character, connect parameters, customize its presentation, and validate your project.
Read Supported Boundaries and Unsupported Operations before converting assets. A successful Build does not reproduce every component or behavior on a Prefab. Only one selected Animator is compiled; other Animators are omitted with warnings. Automatic splitting and assembly are not implemented.
Current preview changes
- One runtime asset: load
<PrefabName>_EntityDesc.asset(CharacterRuntimeAsset) directly.CharacterPreparedAssetholds the prepared resources. Character Template assets and gameplay alias tables have been removed; use exact Controller parameter names, layer names and full exported state keys. - Embedded animation: EntityDesc contains
CharacterAnimationData, derived meshes and materials. Textures and Shaders remain dependencies. The legacy Payload field and externalPayload.bytesloading path have been removed; rebuild older outputs from source before upgrading. - 18 focused demos: Demo17 covers independently loaded rigid equipment and its model LOD follower; Demo18 separates model LOD from animation evaluation intervals. These are different policies, not interchangeable quality settings.
- Updated sample Idle: the swordsman and crossbow guard use four-second, 24 FPS source clips with full-body breathing. The October 4 swordsman update corrects the supporting stance. Foot contact was authored offline; this does not add runtime IK support. See the Idle crowd sample.
Imported samples are project-owned copies. Updating the package alone does not refresh a previous sample import. Preserve local changes before replacing an imported version. The package version string remains 0.1.0-preview.1, so check the delivery date and included documentation when comparing archives.
Find your task
| Task | Read | Completion check |
|---|---|---|
| Install, configure URP and run a sample | Getting started | Quick Start renders and animates without related Console errors |
| Check supported combinations | Boundaries | Distinguish rejected, omitted, unimplemented and unverified behavior |
| Check a character's compatibility | Component table, Animator support | Identify exported data and required gameplay replacements |
| Use conversion tools and presets | Conversion guide | Build an EntityDesc and spawn your character |
| Load through a resource manager | Runtime loading | Retain dependencies until the prepared resource reaches Released |
| Make one character move | SimpleCharacterExample | Speed controls Idle/Run; gameplay controls movement |
| Connect AI, input and parameters | Animation integration | Match binding keys and types; submit through one writer and confirm requests |
| Adapt a Shader or Shader Graph | Shader integration | Match deformation and clipping across passes; test the target platform |
| Add weapons, effects or ECS equipment | Attachments | Configure semantic sockets and explicit ownership |
| Configure LOD or gameplay components | LOD, Component extension | Validate geometry levels and declare gameplay data explicitly |
| Rebuild, upgrade or uninstall | Rebuilding, Cleanup | Preserve sources and release resources correctly |
| Diagnose problems | Troubleshooting | Keep the diagnostic code, object path and failing stage |
| Write build tools, Jobs or advanced integrations | API reference | Use public contracts and assembly boundaries |
Suggested reading order
- Versions, dependencies, platform boundaries, settings and a working sample.
- Source preparation, conversion fields, outputs, spawning and cleanup.
- Exact Controller keys, parameter types, AI/input ownership and Shader adaptation.
- Diagnostics, recovery, rebuild conditions and upgrades.
- Receipts, events, Jobs, LOD, attachments and prototype customization.
- Serialized types and rendering diagnostics. Ordinary integrations do not need GPU or Blob internals.
Version and validation scope
| Area | Current scope |
|---|---|
| Editor | Minimum Unity 2022.3.1f1. A fresh official URP project passed Demo2 Editor Play and a visible Windows x64 Mono/D3D11 run. Earlier complete conversion regression used 2022.3.45f1c1; this is not proof for every Editor patch. |
| Dependencies | Entities / Entities Graphics 1.0.10, Burst 1.8.4, Collections 2.1.4, URP 14.0.8 and Test Framework 1.1.33. See package.json for the complete list. |
| Rendering | URP, SRP Batcher, retained BatchRendererGroup/DOTS variants, GPU instancing and AsyncGPUReadback |
| Camera | MainCamera by default; display index 0, no RenderTexture or stereo. Explicitly rebind after a camera change. |
| Graphics APIs | Source paths cover Windows D3D11/12, Android Vulkan and iOS Metal. OpenGL/ES and WebGL are outside scope. A source path is not device qualification. |
| Validated examples | Windows Editor/D3D11 evidence is available. Demo17 also has local Windows D3D11 Player evidence for equipment, automatic/manual LOD and visible Idle, plus Unity 2022.3.1f1 Editor checks. This does not qualify every sample, Player or device. |
| Shaders | ECSAnimator/Lit is the stable route. External HLSL/Graph is Preview / NeedsVerification; Graph Metal has a known URP compilation failure. |
| Animation | Skeletal presentation. Root Motion, runtime IK and StateMachineBehaviour callbacks are omitted. |
| Release state | Installable preview. Final licensing/notices, release checks and target Player/device qualification remain separate requirements. |
Documentation changes do not expand these guarantees. Sample counts and measured performance do not establish a budget for arbitrary assets or hardware.
Samples and assemblies
Import Quick Start from Package Manager > ECSAnimator > Samples. It includes a self-owned character, conversion inputs, prebuilt data and integration source. SimpleCharacterExample needs one Float parameter. The combat example has its own binding contract and cannot be applied unchanged to any Controller.
Demos contains 18 focused scenes using TownGuard and CrossbowGuard, with prebuilt resources. No external character pack is required. Use the included render-settings menu as explained in the sample README. Demo17 demonstrates independently loaded rigid equipment; it does not promise shared draw calls with the character or arbitrary equipment hierarchies.
Put gameplay code in its own asmdef and reference ECSAnimator.Runtime.Product plus the Unity assemblies it uses. Editor conversion extensions also reference ECSAnimator.Offline.Build and ECSAnimator.Package.Contract. Do not include Editor builders in a Player assembly. Reference ECSAnimator.Runtime.Product.Newcomer only when using Quick Start sample types.
Development tests, historical reports and internal GPU diagnostics are not installation dependencies.