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)

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 36 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 54 of file anim_params.hpp.

◆ cased_name() [2/2]

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

inline

Definition at line 59 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 235 of file anim_params.hpp.

◆ counter_max() [2/2]

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

inline

Definition at line 240 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 73 of file anim_params.hpp.

◆ frame_factor() [2/2]

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

inline

Definition at line 78 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 115 of file anim_params.hpp.

◆ frame_names() [2/2]

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

inline

Definition at line 120 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 92 of file anim_params.hpp.

◆ frame_offset() [2/2]

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

inline

Definition at line 97 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 138 of file anim_params.hpp.

◆ frame_order() [2/2]

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

inline

Definition at line 143 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 216 of file anim_params.hpp.

◆ height_tiles() [2/2]

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

inline

Definition at line 221 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 254 of file anim_params.hpp.

◆ overrides() [2/2]

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

inline

Definition at line 259 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 176 of file anim_params.hpp.

◆ tile_count() [2/2]

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

inline

Definition at line 181 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 157 of file anim_params.hpp.

◆ tile_offset() [2/2]

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

inline

Definition at line 162 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 196 of file anim_params.hpp.

◆ width_tiles() [2/2]

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

inline

Definition at line 201 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_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]