porytiles::AnimCodeParser Class Reference

Parses C code to extract tileset animation parameters using callback chain discovery. More...

#include <anim_code_parser.hpp>

Public Member Functions
	AnimCodeParser (gsl::not_null< const TextFormatter * > format, gsl::not_null< const UserDiagnostics * > diag)
	Constructs an AnimCodeParser with a text formatter for error messages.
ChainableResult< std::map< DynamicCasedName, AnimParams > >	parse_from_callback (const std::filesystem::path &c_file_path, const std::string &callback_func_name, const DynamicCasedName &tileset_cased_name, bool porytiles_managed) const
	Parses animation parameters by following the callback chain.

Detailed Description

Parses C code to extract tileset animation parameters using callback chain discovery.

AnimCodeParser extracts AnimParams from C source files by following the callback chain rather than relying on hardcoded function prefixes. The discovery process works as follows:

1. Callback function (e.g., InitTilesetAnim_General): Contains assignment to the driver callback pointer
2. Driver function (e.g., TilesetAnim_General): Contains timer conditions and queue function calls
3. Queue functions: Contain AppendTilesetAnimToBuffer calls with animation parameters

The only required invariant is that animation frame arrays follow the naming convention: gTilesetAnims_{TilesetName}_{AnimName}{_OptionalSuffix}

The parser extracts:

• tile_offset from TILE_OFFSET_4BPP(X) in AppendTilesetAnimToBuffer calls
• tile_count from X * TILE_SIZE_4BPP
• frame_factor from timer % X in driver functions
• frame_offset from timer % X == Y conditions
• frames array from frame pointer array definitions (order matters)

Parsing errors produce rich diagnostics with source file context via FileHighlightPrinter.

Note: Animation frame PNG files are loaded separately by the artifact reader; this parser only extracts the configuration parameters embedded in C code.

Definition at line 43 of file anim_code_parser.hpp.

Constructor & Destructor Documentation

AnimCodeParser()

porytiles::AnimCodeParser::AnimCodeParser ( gsl::not_null< const TextFormatter * >  format, gsl::not_null< const UserDiagnostics * >  diag  )

inlineexplicit

Constructs an AnimCodeParser with a text formatter for error messages.

Parameters

format	Formatter for error message styling (non-owning, must outlive parser)
diag	UserDiagnostics for user diagnostics

Definition at line 51 of file anim_code_parser.hpp.

Member Function Documentation

parse_from_callback()

ChainableResult< std::map< DynamicCasedName, AnimParams > > porytiles::AnimCodeParser::parse_from_callback	(	const std::filesystem::path &	c_file_path,
		const std::string &	callback_func_name,
		const DynamicCasedName &	tileset_cased_name,
		bool	porytiles_managed
	)		const

Parses animation parameters by following the callback chain.

This is the primary parsing method that discovers animations automatically without requiring the caller to provide expected animation names. It follows the callback chain:

1. Parses the callback function (e.g., InitTilesetAnim_General) to find the driver function assignment
2. Parses the driver function to find timer conditions and queue function calls
3. For each queue function, finds AppendTilesetAnimToBuffer calls and extracts:
   • Animation name from the first argument (e.g., gTilesetAnims_General_Flower[i] -> "flower")
   • tile_offset from the second argument
   • tile_count from the third argument
4. Parses frame pointer arrays to get frame sequences

This approach removes the brittleness of requiring hardcoded function prefixes like TilesetAnim_ or QueueAnimTiles_. Driver and queue functions can have any name as long as they follow the calling pattern.

Parameters

c_file_path	Path to the C file containing animation code (tileset_anims.c or generated_anim_code.h)
callback_func_name	The callback function name from the tileset struct (e.g., "InitTilesetAnim_General")
tileset_cased_name	The tileset name as a DynamicCasedName (e.g., DynamicCasedName{"General"})
porytiles_managed	True if this is a Porytiles-managed tileset (uses "PorytilesManaged_" prefix)

Returns

Map of animation names (snake_case) to their parsed parameters, or error

Definition at line 715 of file anim_code_parser.cpp.

---

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

• porytiles/include/porytiles/infra/services/anim_code_parser.hpp
• porytiles/lib/infra/services/anim_code_parser.cpp