Configuration parameters for a single tileset animation. More...

#include <anim_params.hpp>

Public Member Functions
	AnimParams ()=default

const DynamicCasedName &	cased_name () const
	Returns the structured name for this animation, preserving case format information.

void	cased_name (DynamicCasedName value)

const std::string &	frame_array_identifier () const
	Returns the C identifier of the frame pointer array backing this animation.

void	frame_array_identifier (std::string value)

std::size_t	frame_factor () const
	Returns the frame factor (modulus divisor for timer).

void	frame_factor (std::size_t value)

std::size_t	frame_offset () const
	Returns the frame offset (remainder value for timer modulo check).

void	frame_offset (std::size_t value)

const std::vector< DynamicCasedName > &	frame_names () const
	Returns the unique frame definitions.

void	frame_names (std::vector< DynamicCasedName > value)

const std::vector< DynamicCasedName > &	frame_order () const
	Returns the playback sequence.

void	frame_order (std::vector< DynamicCasedName > value)

std::size_t	tile_offset () const
	Returns the VRAM tile offset for this animation.

void	tile_offset (std::size_t value)

std::size_t	tile_count () const
	Returns the number of tiles per animation frame.

void	tile_count (std::size_t value)

std::size_t	width_tiles () const
	Returns the width of animation frames in tiles.

void	width_tiles (std::size_t value)

std::size_t	height_tiles () const
	Returns the height of animation frames in tiles.

void	height_tiles (std::size_t value)

std::size_t	counter_max () const
	Returns the animation counter maximum value.

void	counter_max (std::size_t value)

const std::vector< AnimOverrideEntry > &	overrides () const
	Returns the manual override entries for this animation.

void	overrides (std::vector< AnimOverrideEntry > value)

Detailed Description

Configuration parameters for a single tileset animation.

AnimParams stores the configuration data needed to generate and interpret animation code for a tileset. These parameters control how animation frames are selected and where animation tiles are located in VRAM.

The parameters map directly to the generated C code patterns:

frame_factor: The modulus divisor in timer % frame_factor == frame_offset conditions
frame_offset: The remainder value in timer % frame_factor == frame_offset conditions
frame_names: Unique frame definitions; position in vector determines FrameN index (0-indexed)
frame_order: The playback sequence; each entry must reference a name from frame_names
tile_offset: The VRAM offset where this animation's tiles begin (in TILE_OFFSET_4BPP units)
tile_count: The number of tiles per animation frame
counter_max: The maximum timer value before wrapping (typically 256)

Definition at line 34 of file anim_params.hpp.

Constructor & Destructor Documentation

◆ AnimParams()

porytiles::AnimParams::AnimParams ( )

default

Member Function Documentation

◆ cased_name() [1/2]

const DynamicCasedName & porytiles::AnimParams::cased_name ( ) const

inline

Returns the structured name for this animation, preserving case format information.

When parsing animation code (vanilla or Porytiles-managed), the animation name is extracted from C identifiers like QueueAnimTiles_General_Water_Current_LandWatersEdge. The segment after the tileset prefix (e.g., "Water_Current_LandWatersEdge") is parsed into a DynamicCasedName that preserves the two-level segment/word structure. This enables lossless conversion to any output format: to_snake_case() for map keys, to_c_identifier() for frame variable name reconstruction, to_pascal_case() for flattened identifiers.

Replaces the former vanilla_identifier_ field, which stored the original C identifier as a plain string.

Returns: The structured name, or an empty DynamicCasedName if not set

Definition at line 50 of file anim_params.hpp.

◆ cased_name() [2/2]

void porytiles::AnimParams::cased_name ( DynamicCasedName value )

inline

Definition at line 55 of file anim_params.hpp.

◆ counter_max() [1/2]

std::size_t porytiles::AnimParams::counter_max ( ) const

inline

Returns the animation counter maximum value.

In the generated C code, this appears as sPrimaryTilesetAnimCounterMax = counter_max in the InitTilesetAnim function. Common values are 128 and 256, controlling the timer wrap-around behavior.

Returns: The counter maximum value

Definition at line 234 of file anim_params.hpp.

◆ counter_max() [2/2]

void porytiles::AnimParams::counter_max ( std::size_t value )

inline

Definition at line 239 of file anim_params.hpp.

◆ frame_array_identifier() [1/2]

const std::string & porytiles::AnimParams::frame_array_identifier ( ) const

inline

Returns the C identifier of the frame pointer array backing this animation.

When AnimCodeParser extracts an animation from existing C code, it records the full identifier of the frame pointer array referenced by the queue function (for example "sTilesetAnims_General_SandWatersEdge"). Vanilla anim import appends "_Frame{Name}" to this identifier to locate the INCBIN frame variables, which keeps frame lookup working even when the array names use a different tileset shorthand than the tileset itself (e.g. General vs General_Frlg). Empty for AnimParams not produced by AnimCodeParser (for example params loaded from anim.json). This field is not persisted to anim.json.

Returns: The frame pointer array identifier, or an empty string if not set

Definition at line 71 of file anim_params.hpp.

◆ frame_array_identifier() [2/2]

void porytiles::AnimParams::frame_array_identifier ( std::string value )

inline

Definition at line 76 of file anim_params.hpp.

◆ frame_factor() [1/2]

std::size_t porytiles::AnimParams::frame_factor ( ) const

inline

Returns the frame factor (modulus divisor for timer).

In the generated C code, this appears as timer % frame_factor == frame_offset. Common values are 8 and 16, where 16 means the animation updates every 16 game frames.

Returns: The frame factor value

Definition at line 88 of file anim_params.hpp.

◆ frame_factor() [2/2]

void porytiles::AnimParams::frame_factor ( std::size_t value )

inline

Definition at line 93 of file anim_params.hpp.

◆ frame_names() [1/2]

const std::vector< DynamicCasedName > & porytiles::AnimParams::frame_names ( ) const

inline

Returns the unique frame definitions.

Lists all unique animation frame files. The position in this vector determines the FrameN index used in generated C code. For example, ["center", "left", "right"] means center.png is Frame0, left.png is Frame1, right.png is Frame2. Frame names can be arbitrary strings (not just numbers).

Each entry is a DynamicCasedName so that downstream code can convert losslessly to any case format (snake_case for file paths, PascalCase for C identifiers) without re-parsing.

Returns: Reference to the unique frame names vector

Definition at line 126 of file anim_params.hpp.

◆ frame_names() [2/2]

void porytiles::AnimParams::frame_names ( std::vector< DynamicCasedName > value )

inline

Definition at line 131 of file anim_params.hpp.

◆ frame_offset() [1/2]

std::size_t porytiles::AnimParams::frame_offset ( ) const

inline

Returns the frame offset (remainder value for timer modulo check).

In the generated C code, this appears as timer % frame_factor == frame_offset. Different animations in the same tileset use different offsets (0, 1, 2, ...) to stagger their updates and avoid visual sync artifacts.

Returns: The frame offset value

Definition at line 105 of file anim_params.hpp.

◆ frame_offset() [2/2]

void porytiles::AnimParams::frame_offset ( std::size_t value )

inline

Definition at line 110 of file anim_params.hpp.

◆ frame_order() [1/2]

const std::vector< DynamicCasedName > & porytiles::AnimParams::frame_order ( ) const

inline

Returns the playback sequence.

Defines the order in which animation frames are played. Each entry must reference a name from frame_names(). For example, ["center", "right", "center", "left"] means play center, then right, then center, then left. Frames can repeat in the sequence to create complex animation patterns.

Each entry is a DynamicCasedName so that downstream code can convert losslessly to any case format without re-parsing.

Returns: Reference to the frame order vector

Definition at line 147 of file anim_params.hpp.

◆ frame_order() [2/2]

void porytiles::AnimParams::frame_order ( std::vector< DynamicCasedName > value )

inline

Definition at line 152 of file anim_params.hpp.

◆ height_tiles() [1/2]

std::size_t porytiles::AnimParams::height_tiles ( ) const

inline

Returns the height of animation frames in tiles.

When non-zero, this specifies the number of 8x8 tile rows in animation frame PNGs. This value is used when writing animation frames back to disk to preserve the original grid layout. A value of 0 means dimensions were not specified and the default single-row layout is used.

Returns: The frame height in tiles, or 0 if unspecified

Definition at line 217 of file anim_params.hpp.

◆ height_tiles() [2/2]

void porytiles::AnimParams::height_tiles ( std::size_t value )

inline

Definition at line 222 of file anim_params.hpp.

◆ overrides() [1/2]

const std::vector< AnimOverrideEntry > & porytiles::AnimParams::overrides ( ) const

inline

Returns the manual override entries for this animation.

When using FrameLinking::manual mode, these entries explicitly map metatile positions to animation subtiles, bypassing key.png-based frame linking. Empty when using automatic mode.

Returns: Reference to the override entries vector

Definition at line 251 of file anim_params.hpp.

◆ overrides() [2/2]

void porytiles::AnimParams::overrides ( std::vector< AnimOverrideEntry > value )

inline

Definition at line 256 of file anim_params.hpp.

◆ tile_count() [1/2]

std::size_t porytiles::AnimParams::tile_count ( ) const

inline

Returns the number of tiles per animation frame.

In the generated C code, this appears as tile_count * TILE_SIZE_4BPP in the AppendTilesetAnimToBuffer call. This is determined by the dimensions of the animation frame PNGs.

Returns: The number of tiles per frame

Definition at line 181 of file anim_params.hpp.

◆ tile_count() [2/2]

void porytiles::AnimParams::tile_count ( std::size_t value )

inline

Definition at line 186 of file anim_params.hpp.

◆ tile_offset() [1/2]

std::size_t porytiles::AnimParams::tile_offset ( ) const

inline

Returns the VRAM tile offset for this animation.

In the generated C code, this appears as TILE_OFFSET_4BPP(tile_offset) in the AppendTilesetAnimToBuffer call. This value is computed by Porytiles based on where the animation's keyframe tiles are placed in tiles.png.

Returns: The VRAM tile offset

Definition at line 164 of file anim_params.hpp.

◆ tile_offset() [2/2]

void porytiles::AnimParams::tile_offset ( std::size_t value )

inline

Definition at line 169 of file anim_params.hpp.

◆ width_tiles() [1/2]

std::size_t porytiles::AnimParams::width_tiles ( ) const

inline

Returns the width of animation frames in tiles.

When non-zero, this specifies the number of 8x8 tiles per row in animation frame PNGs. This value is used when writing animation frames back to disk to preserve the original grid layout. A value of 0 means dimensions were not specified and the default single-row layout is used.

Returns: The frame width in tiles, or 0 if unspecified

Definition at line 199 of file anim_params.hpp.

◆ width_tiles() [2/2]

void porytiles::AnimParams::width_tiles ( std::size_t value )

inline

Definition at line 204 of file anim_params.hpp.

The documentation for this class was generated from the following file:

porytiles/include/porytiles/domain/models/anim_params.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AnimParams()

Member Function Documentation

◆ cased_name() [1/2]

◆ cased_name() [2/2]

◆ counter_max() [1/2]

◆ counter_max() [2/2]

◆ frame_array_identifier() [1/2]

◆ frame_array_identifier() [2/2]

◆ frame_factor() [1/2]

◆ frame_factor() [2/2]

◆ frame_names() [1/2]

◆ frame_names() [2/2]

◆ frame_offset() [1/2]

◆ frame_offset() [2/2]

◆ frame_order() [1/2]

◆ frame_order() [2/2]

◆ height_tiles() [1/2]

◆ height_tiles() [2/2]

◆ overrides() [1/2]

◆ overrides() [2/2]

◆ tile_count() [1/2]

◆ tile_count() [2/2]

◆ tile_offset() [1/2]

◆ tile_offset() [2/2]

◆ width_tiles() [1/2]

◆ width_tiles() [2/2]