Animation docs: named cells come from the image now, not a flag
4.0 removes AnimationAsset's NamedCellsMode field and its setter. Whether an
animation selects frames by name or by index is read from the image asset -
explicit mode means named cells - so the two can no longer disagree, which they
could and did: setting the flag true on an image with no named cells produced an
animation with no frames and no explanation, and re-cutting an image left the
flag asserting something the image had stopped agreeing with.
AnimationAsset Guide:
- NamedCellsMode is out of the field list, and its section is replaced by a
"Named cells" section saying where the answer actually comes from and how to
change it. getNamedCellsMode() survives as a read-only query.
- AnimationFrames and NamedAnimationFrames now state their mandatory condition
in terms of the image's ExplicitMode rather than in terms of the flag, and
the named example no longer carries NamedCellsMode="true".
- New "Changing an image's mode": switching an image between explicit and cell
mode converts the animations on it, both lists are kept so the switch is
reversible, and an entry that cannot be translated is skipped with a warning.
- A migration note, checked against the engine rather than assumed. An old file
carrying NamedCellsMode still loads and loads correctly, because the mode is
taken from the image either way. But the attribute is no longer a field, so
it is read as an ordinary dynamic field - kept, and written back out on every
subsequent save, indefinitely and silently. Round-tripped one through
TamlRead/TamlWrite to confirm: getFieldType comes back empty, the dynamic
field count is 1, and the attribute reappears in the output.
Two errors in "Additional API" that predate this, corrected while in there. The
getAnimationFrameCount headings described the getAnimationFrames LIST getters,
which return a different thing. And the section said invalid frames "are simply
dropped", which neither kind does: an out-of-range NUMBER is clamped to the
nearest valid frame, so the animation goes on playing and quietly shows the
wrong art, and a NAME that no cell answers to is kept exactly as it is and draws
nothing. That distinction decides how you detect each one - clamping changes the
value so the specified and validated lists differ, whereas a kept name leaves
them identical and needs the new getMissingFrames(). Both are now documented as
such, along with getFrameCount(), which answers in either space and so spares
script from asking which mode it is in first.
ImageAsset Guide, two corrections caused by the same change:
- "You must remember to set explicit mode to true prior to saving the asset
otherwise the explicit cell details won't be saved" is no longer true. That
sentence described a real trap - saving with the mode off deleted every cell
in the file permanently, and with them the only thing that could resolve an
animation's names. Cells are saved whenever there are any now. The knock-on
is that a file records ExplicitMode whenever it has cells, so that cells with
the mode off read back that way; a file written before this, which has cells
and says nothing, is still read as explicit mode on.
- The auto-naming paragraph said an unnamed cell is given "a frame number" as
its name. It is given "Frame" followed by its own index. The distinction is
load-bearing: getExplicitCellOffset/Width/Height dispatch between an index
and a name on the first character, so a cell literally named "0" would be
read as an index and be unreachable by name. Also documents the collision
walk, which is new - deleting a cell from the middle renumbers every cell
after it, so a wanted name is frequently already taken.
Added getExplicitCellOffset, getExplicitCellName and getExplicitCellIndex to
that section's method list. The last two are the pair that connect an image to
an animation built on it, and they answer whether or not explicit mode is
currently on, because the cells outlive the mode; the methods that change cells
still require it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Xh3XULt9PtdCtsaYHGnYE