Jazz2::Scripting::Legacy::AnimationTables class

Animation tables of the level scripts of JJ2+, jjAnimSets, jjAnimations and jjAnimFrames.

Three tables, the sets by their set ID, the animations and the frames by their index. A set has a run of animations from its firstAnim, an animation a run of frames from its firstFrame - which is all the arithmetic the scripts do (jjAnimations[jjAnimSets[ANIM::BAT] + 2].firstFrame + 1). An entry is made on first use and is the only one of its index, so a change a script makes to it stays.

The sets of the original are always loaded: a set gets its animations and frames, read from the converted sprite sheets, the first time it's used. Each animation of a set of the original has the graphics of the game (Resources::GenericGraphicResource) that the actors draw it with, and those show whatever animation is at firstAnim + n of the set - after a script changes the frames, loads other animations into the set or makes an animation share the frames of another (jjAnimations[a] = jjAnimations[b]), the graphics are made of them again once the script returns (see Flush()). The number of frames of the graphics stays as the game has it, the frames of the animation are repeated over them, and a frame of its own size and hotspot gets a packed rectangle of the sheet, so nothing that keeps a pointer to the graphics notices. The graphics are restored when the tables are destroyed, so the next level gets them as they were.

An animation that isn't in the graphics of the game, e.g. one of a custom set, is drawn by scripts with a sprite sheet of its own, made on first use.

The set IDs are those of the animation file of the game (the "Set ID" of Jazz Sprite Dynamite, from 0), which differ between 1.23 and 1.24 after the dragon. The sets of plus.j2a follow, and the custom sets right after them (see GetCustomFirstSetID()).

Public static variables

static std::uint32_t SetCount constexpr
Number of set IDs, the custom sets of both versions of the game included.
static std::uint32_t MaxAnimations constexpr
Number of entries the animation table can have, jjOBJ::curAnim is 16-bit.
static std::uint32_t MaxFrames constexpr
Number of entries the frame table can have, the animation file of the game has less than 15 000.
static std::uint32_t FirstSetAnim constexpr
Index of the first animation a set gets, the ones before are empty.
static std::uint8_t TranslucentFrameAlpha constexpr
Alpha of the pixels of a transparent frame in the graphics.

Public static functions

static auto GetSetID(anim set, bool isTSF) -> std::int32_t
Returns the set ID of a set of the original, -1 if the version of the game doesn't have it.

Constructors, destructors, conversion operators

AnimationTables(bool isTSF) explicit
Creates the tables for the animation file of the given version of the game.
~AnimationTables()
Destroys the tables, restoring the graphics of the game they changed.
AnimationTables(const AnimationTables&) deleted

Public functions

auto operator=(const AnimationTables&) -> AnimationTables& deleted
auto GetCustomFirstSetID() const -> std::uint32_t
Returns the set ID of ANIM::CUSTOM[0], right after the sets of plus.j2a.
auto GetSet(std::uint32_t setID) -> jjANIMSET*
Returns the entry of a set, AddRef'd, or nullptr with a script exception if there's no such set.
auto GetAnimation(std::uint32_t index) -> jjANIMATION*
Returns the entry of an animation, AddRef'd, or nullptr with a script exception if it's out of the table.
auto GetFrame(std::uint32_t index) -> jjANIMFRAME*
Returns the entry of a frame with its image read, AddRef'd, or nullptr with a script exception if it's out of the table.
auto GetFirstAnim(std::int32_t setID) -> std::uint32_t
Returns the index of the first animation of a set, 0 if the set isn't loaded.
auto GetAnimationFrames(std::uint32_t animIndex, std::uint32_t& frameCount, std::uint32_t& firstFrame) -> bool
Returns the frame count and the first frame of an animation, false if there's no such animation.
auto GetFrameBounds(std::uint32_t frameIndex, Recti& frameRect, Recti& pixelBounds) -> bool
Returns the rectangle of a frame and the one of its pixels, both from its hotspot.
auto GetAnimationImage(std::uint32_t animIndex, std::int32_t maxFrames, SmallVectorImpl<std::uint32_t>& colors, Vector2i& cellSize, Vector2i& hotspot, std::int32_t& frameCount, std::int32_t& fps, bool& changed) -> bool
Returns the frames of an animation in colors, for a picture of it outside of the scripts.
auto IsAnimationChanged(std::uint32_t animIndex) -> bool
Returns true if a script changed any frame of an animation or gave it frames of another one.
auto GetFramesImage(std::uint32_t firstFrame, std::int32_t frameCount, const std::uint32_t* palette, SmallVectorImpl<std::uint32_t>& colors, Vector2i& cellSize, Vector2i& hotspot, bool& changed) -> bool
The same for frames of the frame table from firstFrame, 8-bit ones in the colors of palette, the palette of the sprites for nullptr.
auto GetFrameSpots(std::uint32_t frameIndex, Recti& frameRect, Vector2i& coldSpot) -> bool
Returns the rectangle of a frame from its hotspot and its coldspot as JJ2 stores it, false if there's no such frame.
auto FindChangedFrame(std::int32_t setID, std::uint32_t animation, std::uint32_t frame) const -> std::int32_t
Returns the index in the frame table of a frame of a set that a script changed, -1 if it's as it was or the set isn't loaded.
auto LoadSet(jjANIMSET& set, std::uint32_t fileSetID, StringView filename, std::int32_t firstAnimToOverwrite, std::int32_t firstFrameToOverwrite) -> bool
Loads a set of an animation file into a set, as jjANIMSET::load().
void AllocateSet(jjANIMSET& set, ArrayView<const std::uint32_t> frameCounts)
Gives a set new animations with empty frames, as jjANIMSET::allocate().
void AssignAnimation(jjANIMATION& target, const jjANIMATION& source)
Makes an animation the same as another one, as jjANIMATION::operator=().
void SetFirstFrame(jjANIMATION& anim, std::uint32_t firstFrame)
Changes the first frame of an animation.
void AssignFrame(jjANIMFRAME& target, const jjANIMFRAME& source)
Makes a frame the same as another one, as jjANIMFRAME::operator=().
void SetFramePixels(jjANIMFRAME& frame, const std::uint8_t* pixels, std::uint32_t width, std::uint32_t height)
Replaces the image of a frame by palette indices, width × height of them.
void RecolorFrame(jjANIMFRAME& frame, const std::uint8_t* colors)
Gives every pixel of a frame the palette index colors has at its index, as jjPIXELMAP::recolor() and saving it back.
void SetFrameColors(jjANIMFRAME& frame, const jjPALCOLOR* colors, const std::uint8_t* indices, std::uint32_t width, std::uint32_t height)
Replaces the image of a frame by colors with alpha, width × height of them, a 32-bit frame of JJ2+.
void OnPaletteChanged()
Tells the tables the palette of the sprites changed, so do the 8-bit frames of true color graphics.
void MarkChanged(jjANIMFRAME& frame)
Tells the tables a frame changed in a way they can't see themselves.
auto DoFramesCollide(const jjANIMFRAME& frame1, std::int32_t x1, std::int32_t y1, std::int32_t direction1, const jjANIMFRAME& frame2, std::int32_t x2, std::int32_t y2, std::int32_t direction2, bool always, const Recti* clip = nullptr) -> bool
Returns whether two frames collide at the given positions, as jjANIMFRAME::doesCollide().
auto ResolveSprite(std::int32_t setID, std::int32_t animation, std::int32_t frame, std::int32_t& cell, bool* translucent = nullptr) -> Resources::GenericGraphicResource*
Returns the graphics to draw a frame of an animation of a set with, and the frame of the graphics.
auto ResolveFrame(std::uint32_t frameIndex, std::int32_t& cell, bool* translucent = nullptr) -> Resources::GenericGraphicResource*
Returns the graphics to draw a frame of the frame table with, and the frame of the graphics.
auto FindAnimationOfGraphics(const Resources::GenericGraphicResource* graphics) -> std::uint32_t
Returns the animation of the animation table that graphics of the game show, or 0.
auto ResolveAnimation(std::uint32_t animIndex, std::int32_t& cellCount) -> Resources::GenericGraphicResource*
Returns the graphics that play an animation of the animation table, for an actor that draws it.
void Flush()
Brings the graphics of the game up to date with what scripts changed.
void RestoreNativeGraphics()
Gives the graphics of the game back as they were, and writes no more into them.

Function documentation

std::uint32_t Jazz2::Scripting::Legacy::AnimationTables::GetCustomFirstSetID() const

Returns the set ID of ANIM::CUSTOM[0], right after the sets of plus.j2a.

The first custom sets fit in uint8, as in JJ2+ - scripts pass them to jjOBJ::determineCurAnim() so.

jjANIMSET* Jazz2::Scripting::Legacy::AnimationTables::GetSet(std::uint32_t setID)

Returns the entry of a set, AddRef'd, or nullptr with a script exception if there's no such set.

A set of the original gets its animations here, on first use.

bool Jazz2::Scripting::Legacy::AnimationTables::GetFrameBounds(std::uint32_t frameIndex, Recti& frameRect, Recti& pixelBounds)

Returns the rectangle of a frame and the one of its pixels, both from its hotspot.

Returns false if there's no such frame or it has no pixels.

bool Jazz2::Scripting::Legacy::AnimationTables::GetAnimationImage(std::uint32_t animIndex, std::int32_t maxFrames, SmallVectorImpl<std::uint32_t>& colors, Vector2i& cellSize, Vector2i& hotspot, std::int32_t& frameCount, std::int32_t& fps, bool& changed)

Returns the frames of an animation in colors, for a picture of it outside of the scripts.

At most maxFrames frames in a row of cells of cellSize, each placed by its hotspot, which is at hotspot in every cell; colors are 0xAABBGGRR, 8-bit frames in the colors of the palette of the sprites. fps is the speed of the animation, changed whether a script changed any of the frames. Returns false if there's no such animation or nothing is in it. Raises no script exception.

void Jazz2::Scripting::Legacy::AnimationTables::SetFrameColors(jjANIMFRAME& frame, const jjPALCOLOR* colors, const std::uint8_t* indices, std::uint32_t width, std::uint32_t height)

Replaces the image of a frame by colors with alpha, width × height of them, a 32-bit frame of JJ2+.

indices are the nearest palette indices of the colors, 0 where there's no alpha, for what reads the frame as palette indices. The graphics an animation with such a frame is drawn with are true color, its 8-bit frames are in the colors of the palette, made again when it changes (see OnPaletteChanged()).

bool Jazz2::Scripting::Legacy::AnimationTables::DoFramesCollide(const jjANIMFRAME& frame1, std::int32_t x1, std::int32_t y1, std::int32_t direction1, const jjANIMFRAME& frame2, std::int32_t x2, std::int32_t y2, std::int32_t direction2, bool always, const Recti* clip = nullptr)

Returns whether two frames collide at the given positions, as jjANIMFRAME::doesCollide().

The frames are placed by their hotspots and flipped by their directions (SPRITE::Direction). With always a single common pixel is enough, otherwise it takes a few.

Resources::GenericGraphicResource* Jazz2::Scripting::Legacy::AnimationTables::ResolveSprite(std::int32_t setID, std::int32_t animation, std::int32_t frame, std::int32_t& cell, bool* translucent = nullptr)

Returns the graphics to draw a frame of an animation of a set with, and the frame of the graphics.

The frame is taken modulo the frame count of the animation, as JJ2+ does. Returns nullptr if there's nothing to draw.

Resources::GenericGraphicResource* Jazz2::Scripting::Legacy::AnimationTables::ResolveFrame(std::uint32_t frameIndex, std::int32_t& cell, bool* translucent = nullptr)

Returns the graphics to draw a frame of the frame table with, and the frame of the graphics.

translucent tells whether the frame is transparent, drawn with the alpha of TranslucentFrameAlpha in the graphics - JJ2+ draws it so only in SPRITE::NORMAL.

std::uint32_t Jazz2::Scripting::Legacy::AnimationTables::FindAnimationOfGraphics(const Resources::GenericGraphicResource* graphics)

Returns the animation of the animation table that graphics of the game show, or 0.

An object of the game is drawn with the graphics of an animation of a set of the original, which is the one at firstAnim + n of the set - also after a script put another animation there. 0 for graphics of no animation of the original, e.g. those of the remastered content.

Resources::GenericGraphicResource* Jazz2::Scripting::Legacy::AnimationTables::ResolveAnimation(std::uint32_t animIndex, std::int32_t& cellCount)

Returns the graphics that play an animation of the animation table, for an actor that draws it.

The graphics have cellCount frames, which play the animation from the first one.

void Jazz2::Scripting::Legacy::AnimationTables::Flush()

Brings the graphics of the game up to date with what scripts changed.

Called after every call of a script, it costs nothing while nothing changed. A change a script makes by a method is known right away, the values a script writes to the properties are found out here, by comparing them to what they were.

void Jazz2::Scripting::Legacy::AnimationTables::RestoreNativeGraphics()

Gives the graphics of the game back as they were, and writes no more into them.

Called once the level is left (see LevelScriptLoader::OnReplacing()), before the next one loads the same graphics, and when the tables go.

Variable documentation

static std::uint32_t Jazz2::Scripting::Legacy::AnimationTables::FirstSetAnim constexpr

Index of the first animation a set gets, the ones before are empty.

The table of JJ2+ has no animation of a set at a small index, scripts take a small one for an animation of a set of their own (MLLE-Weapons.asc adds the first animation of the set to one below 200) - and an object of curAnim = 1 shows nothing (scripts hide parts of objects so).