yaze/docs/E3-api-reference.md

API Reference

This document provides a reference for the yaze C and C++ APIs, intended for developers creating extensions or contributing to the core application.

C API (incl/yaze.h)

The C API provides a stable, language-agnostic interface for interacting with yaze's core functionalities.

Core Library Functions

/**
 * @brief Initializes the yaze library. Must be called before any other API function.
 * @return YAZE_OK on success, or an error code on failure.
 */
yaze_status yaze_library_init(void);

/**
 * @brief Shuts down the yaze library and releases all resources.
 */
void yaze_library_shutdown(void);

/**
 * @brief Gets the current version of the yaze library as a string.
 * @return A constant string representing the version (e.g., "0.3.2").
 */
const char* yaze_get_version_string(void);

ROM Operations

/**
 * @brief Loads a Zelda 3 ROM from a file.
 * @param filename The path to the ROM file.
 * @return A pointer to a zelda3_rom object, or NULL on failure.
 */
zelda3_rom* yaze_load_rom(const char* filename);

/**
 * @brief Unloads a ROM and frees associated memory.
 * @param rom A pointer to the zelda3_rom object to unload.
 */
void yaze_unload_rom(zelda3_rom* rom);

/**
 * @brief Saves a ROM to a file.
 * @param rom A pointer to the ROM to save.
 * @param filename The path to save the file to.
 * @return YAZE_OK on success.
 */
yaze_status yaze_save_rom(zelda3_rom* rom, const char* filename);

C++ API

The C++ API offers a more powerful, object-oriented interface. The primary entry point for many operations is the yaze::core::AsarWrapper class.

AsarWrapper (src/app/core/asar_wrapper.h)

This class provides a complete, cross-platform interface for applying assembly patches, extracting symbols, and validating assembly code using the Asar library.

CLI Examples (z3ed)

While the AsarWrapper can be used programmatically, the z3ed CLI is the most common way to interact with it.

# Apply an assembly patch to a ROM file.
z3ed asar my_patch.asm --rom=zelda3.sfc

# For more complex operations, use the AI agent.
z3ed agent chat --rom zelda3.sfc

Prompt: "Apply the patch mosaic_change.asm to my ROM."

C++ API Example

#include "app/core/asar_wrapper.h"
#include <vector>
#include <string>

// Assume rom_data is a std::vector<uint8_t> holding the ROM content.
yaze::core::AsarWrapper wrapper;
wrapper.Initialize();

// Apply a patch to the ROM data in memory.
auto result = wrapper.ApplyPatch("patch.asm", rom_data);

if (result.ok() && result->success) {
    // On success, print the symbols generated by the patch.
    for (const auto& symbol : result->symbols) {
        std::cout << symbol.name << " @ $" << std::hex << symbol.address << std::endl;
    }
}

Class Definition

namespace yaze::core {

class AsarWrapper {
public:
    /** @brief Initializes the Asar library. */
    absl::Status Initialize();

    /** @brief Shuts down the Asar library. */
    void Shutdown();

    /**
     * @brief Applies an assembly patch to ROM data.
     * @param patch_path Path to the main .asm file.
     * @param rom_data A vector of bytes representing the ROM data.
     * @param include_paths Optional paths for Asar to search for included files.
     * @return A StatusOr containing the patch result, including success status and symbols.
     */
    absl::StatusOr<AsarPatchResult> ApplyPatch(
        const std::string& patch_path,
        std::vector<uint8_t>& rom_data,
        const std::vector<std::string>& include_paths = {});

    /**
     * @brief Extracts symbols from an assembly file without patching.
     * @param asm_path Path to the .asm file.
     * @return A StatusOr containing a vector of extracted symbols.
     */
    absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
        const std::string& asm_path,
        const std::vector<std::string>& include_paths = {});

    /**
     * @brief Validates the syntax of an assembly file.
     * @param asm_path Path to the .asm file.
     * @return An OK status if syntax is valid, or an error status if not.
     */
    absl::Status ValidateAssembly(const std::string& asm_path);
};

} // namespace yaze::core

Data Structures

snes_color

Represents a 15-bit SNES color, composed of 5 bits for each red, green, and blue component.

typedef struct snes_color {
    uint16_t raw;   //!< Raw 15-bit BGR color value (0bbbbbgggggrrrrr).
    uint8_t red;    //!< Red component (0-31).
    uint8_t green;  //!< Green component (0-31).
    uint8_t blue;   //!< Blue component (0-31).
} snes_color;

zelda3_message

Represents an in-game text message.

typedef struct zelda3_message {
    uint16_t id;            //!< The message ID (0-65535).
    uint32_t rom_address;   //!< The address of the message data in the ROM.
    uint16_t length;        //!< The length of the raw message data in bytes.
    uint8_t* raw_data;      //!< A pointer to the raw, compressed message data.
    char* parsed_text;      //!< The decoded, human-readable UTF-8 text.
    bool is_compressed;     //!< Flag indicating if the message data is compressed.
}
zelda3_message;

Error Handling

The C API uses an enum yaze_status for error handling, while the C++ API uses absl::Status and absl::StatusOr.

C API Error Pattern

yaze_status status = yaze_library_init();
if (status != YAZE_OK) {
    fprintf(stderr, "Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
    return 1;
}

// ... operations ...

yaze_library_shutdown();