Files
ClassicAPI/src/animation/Object.h
T
SkeewirtandBrues e84496d036 feat(animation): the animation system - AnimationGroup, Animation, Alpha, Scale, Rotation, Translation (#89)
* feat(animation): the animation system - AnimationGroup, Animation, Alpha, Scale, Rotation, Translation

Later clients animate regions in the renderer; vanilla has none of it, and
ported UIs build on it everywhere (Zygor Guides Viewer 2.0: 25 XML groups
plus CreateAnimationGroup in its guide window's OnLoad, which stopped there).

- Util/Animation.lua (bundled addon): the runtime. Groups and animations
  with the later-client API (Play/Stop/Pause/Finish, progress and smooth
  progress, order/startDelay/endDelay/duration timeline, NONE/REPEAT/BOUNCE
  looping, NONE/IN/OUT/IN_OUT smoothing, maxFramerate, the group and
  animation scripts). One driver frame ticks playing groups; effects go
  through the region's own setters and the region's state is restored
  when the group ends, as later clients never persist them.
- animation/Bridge.cpp: CreateAnimationGroup / GetAnimationGroups /
  StopAnimating on the region base registry, forwarding to the runtime the
  bundled addon registers via _classicapi_SetAnimationRuntime.
- xml loaders: an <Animations> child becomes descriptor tables (attributes,
  <Scripts> bodies and function= names, <Origin>) handed to runtime.LoadXML
  before the builder finalizes. Adds OFF_XML_NODE_TEXT. This extends the
  node-loader hooks of the XML attributes change, which it builds on.

Known limits of the 1.12 renderer: Scale pivots on a frame's own anchor
point (exact when anchored by its center) and resizes textures anchored by
one point; Rotation needs texture:SetRotation (textures, font strings).
Group templates (inherits on an AnimationGroup, CreateAnimationGroup's
template argument) are not supported yet and are ignored.

Verified in-game (1.12.1 client via VanillaFixes, Zygor Guides Viewer 2.0):
a probe XML <Animations> group builds with Play(); every AnimationGroup and
animation method exists; a Lua-built group plays through 12 updates to
progress 1.0 and fires OnFinished; Zygor's step flash group (Alpha) plays
and stops, and its guide window finishes its OnLoad. Not checked yet:
Scale, Rotation and Translation on screen (Zygor's own groups with them
load without error, but no one has watched them play), REPEAT and BOUNCE
looping, the smoothing curves, and maxFramerate.

* refactor(animation): port 4.3.4's CSimpleAnimGroup/CSimpleAnim to C++

Replace the Lua animation runtime with a C++ port of the 4.3.4 engine
classes. Groups and animations are real 1.12 script objects (engine
header from ConstructScriptObject, our own vtable), so GetObjectType,
IsObjectType, GetName/$parent globals, SetScript/HookScript and the
shared __index dispatch all go through the engine's mechanisms.

- Group/Anim: the 4.3.4 timeline (orders, delays, looping, cosine
  smoothing, 1/30 s throttle, pause/stop/finish) and every method.
- Region: per-region state ticked from a CSimpleFrame::OnFrameUpdate
  co-hook (shown frames only); 4.3.4's alpha model (store, reset each
  tick, add change, restore when the last alpha group ends, children
  included). CreateAnimationGroup, GetAnimationGroups, StopAnimating.
- Xml: <Animations> with 4.3.4's attribute set, inherits/templates,
  script bodies and function= through SetScriptObjectScript.
- Frame::Destruction: a shared hub over the frame destructor; groups
  die with their frame, and Frame::Alpha moves onto it.

Translation, Scale and Rotation keep their values and timing but do
not move anything yet.

* feat(animation): apply Translation to what regions draw

Port 4.3.4's AddAnimTranslation: a frame hands the offset to every
texture and font string below it (or only the target), a texture moves
the four corners its draw record points at, and a font string moves its
text block's string position. Rects, anchors and mouse areas stay put.

- StoreAnimPosition / PreOnAnimUpdate / ResetPosition mirror 4.3.4,
  with the base taken from the engine's own layout (the corner store
  for textures, inset x layout scale + rect corner for font strings).
- Co-hooks on the texture and font string OnFrameSizeChanged callbacks
  move the base when the layout moves a region mid-animation and keep
  the animation's offset, as 4.3.4's own legs do.
- A frame is marked while it plays a position group, so the end of its
  last one puts everything below it back.

Scale and Rotation still keep their values without drawing.

* feat(animation): apply Scale and Rotation to textures

Port 4.3.4's AddAnimScale / AddAnimRotation with GetOriginOffset,
ApplyScaleAnim and ApplyRotationAnim on the texture's drawn corners: the
origin point on the quad, its offset turned along the bottom edge, and a
counter-clockwise positive angle. Frames hand both to every texture
below them, or only the target. Font strings do not scale or turn yet.

* feat(animation): scale and turn font strings

Port CSimpleFontString's AddAnimScale / AddAnimRotation: the animated
rotation and x scale replace the string's for the update, and the text
is baked again when they change (the engine's node invalidate, as
4.3.4 invalidates the CGxString). After the bake, the glyphs are scaled
and turned about the node origin, where 4.3.4's InitializeTextLine turns
them, with the engine's half-texel UV inset for turned glyphs. The text
is stretched rather than drawn at a larger font size.

* feat(animation): add Path and ControlPoint

Port 4.3.4's CSimplePathAnim and CSimpleControlPoint: a Path moves the
region's drawing through its control points with AddAnimTranslation,
the points spread evenly over the progress, in straight lines (NONE) or
on 4.3.4's Catmull-Rom spline (SMOOTH). ControlPoint is its own script
object with offset, order and SetParent; BuildSpline keeps 4.3.4's
order shuffle when an order is taken. XML reads `curve` and
<ControlPoints>, with templates for CreateControlPoint and `inherits`.

One deviation from the decompiled CreateControlPoint: a point made
without an order takes the highest order + 1 (as SetParent does), so
points made one after another keep their creation order.

* fix(texture): keep shape changes made during a position animation

Texture:SetRotation and SetVertexOffset wrote the drawn corners, which
the next animation update replaced with the corners stored when the
group started. While a position group plays they now write the stored
corners, so the new shape shows with the animation on top and stays
after the group ends. FontString:SetRotation on text an animation has
turned or scaled bakes the glyphs again instead of re-turning them in
place, so the bake applies both.

---------

Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
2026-10-19 20:44:31 -05:00

124 lines
5.3 KiB
C++

// This file is part of ClassicAPI.
//
// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
// of the GNU General Public License as published by the Free Software Foundation, either
// version 3 of the License, or (at your option) any later version.
//
// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
#pragma once
#include "Game.h"
#include <cstdint>
#include <string>
// Animation groups and animations as real 1.12 script objects.
//
// 4.3.4's CSimpleAnimGroup and CSimpleAnim are CScriptObjects: the engine
// hands them to Lua as the same kind of table as a frame (`t[0]` = the
// object, metatable `__framescript_meta`), finds their methods through the
// object's vtable, resolves `self` with the object's IsA, and stores their
// scripts in {handler, context} slots it finds through the object's script
// resolver. 1.12 has the same machinery (benilla-re ui/methods, ui/script):
// - ConstructScriptObject (0x00701AE0) builds the 0x24-byte header below;
// DestructScriptObject (0x00701B40) releases it;
// - LockScriptObject / UnlockScriptObject (0x00701BD0 / 0x00701CD0) make and
// free the object's table and its name global;
// - `__framescript_meta.__index` (0x007020B0) calls vtable+0x08 (L, name)
// to push a method; ResolveTypedObject's type test calls vtable+0x10;
// - SetScriptObjectScript (0x007025C0) compiles an XML script body into
// the slot vtable+0x0C returns, and FrameScriptReleaseScript (0x00702670)
// frees a slot.
// So an animation object is an engine script object whose vtable is ours.
// It has no C++ virtual functions - its first bytes are the engine header -
// and its class (Class) carries what differs per type.
namespace Animation {
// The 1.12 script-object header, as ConstructScriptObject fills it.
struct ScriptObjectHeader {
void **vtable;
int32_t holders; // +0x04, LockScriptObject's count
int32_t luaRef; // +0x08, the table's registry ref (-2 when none)
uint32_t onEvent[2]; // +0x0C, the base OnEvent slot
uint32_t events[4]; // +0x14, the event index array
};
static_assert(sizeof(ScriptObjectHeader) == 0x24, "the engine's script-object header");
struct Class {
const char *typeName; // GetObjectType, IsObjectType
const Class *base;
// The class's own script names, lower case; a slot per name.
const char *const *scriptNames;
int scriptCount;
const Game::Lua::FrameMethodEntry *methods;
int methodCount;
int typeId; // from the engine's type counter, on first use
int methodsRef; // registry ref of the method table, per Lua state
};
constexpr int kMaxScripts = 8;
class Object : public ScriptObjectHeader {
public:
const Class *cls;
// The script object this one hangs from: a group's region, an
// animation's group (GetParent, "$parent").
void *parent;
std::string name;
uint32_t scripts[kMaxScripts][2] = {}; // {handler ref, context}
// The object's script slot for `name` (any case), or nullptr.
uint32_t *ScriptSlot(const char *name);
bool HasScript(int index) const { return scripts[index][0] != 0; }
// Runs script `index` with `nargs` values pushed on top of the stack,
// and pops them.
void RunScript(int index, int nargs);
const char *Name() const { return name.empty() ? nullptr : name.c_str(); }
// While set, a destroyed object leaves the engine alone: its table and
// handlers belonged to a Lua state that is gone (/reload leftovers).
static bool s_detached;
const char *DisplayName() const { return name.empty() ? "<unnamed>" : name.c_str(); }
protected:
// Registers the object's table, under its name when it has one ("$parent"
// resolved from `parent`).
Object(const Class &cls, void *parent, const char *name);
~Object();
};
// The class's type id (the engine's counter, assigned on first use).
int TypeId(Class &cls);
// The object at `idx` when it is of `cls` or a class derived from it, else
// raises the engine's errors (as every method does) and returns nullptr.
Object *Resolve(void *L, int idx, Class &cls);
// Pushes the object's table.
void Push(void *L, Object *object);
// Whether a script object is one of ours.
bool IsOurs(const void *object);
// 4.3.4's CScriptObject::CreateName: "$parent" at the start of `source`
// becomes the nearest named ancestor's name, "Top" when none.
std::string CreateName(const char *source, const void *parent);
// Builds every class's method table in the current Lua state.
void RegisterClass(Class &cls);
// The base methods every class has (4.3.4's CScriptObject methods), and the
// script methods groups and animations share.
int __fastcall Script_GetObjectType(void *L);
int __fastcall Script_IsObjectType(void *L);
int __fastcall Script_GetName(void *L);
int __fastcall Script_GetParent(void *L);
int __fastcall Script_HasScript(void *L);
int __fastcall Script_GetScript(void *L);
int __fastcall Script_SetScript(void *L);
int __fastcall Script_HookScript(void *L);
} // namespace Animation