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 (<tt>incl/yaze.h</tt>)

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

Core Library Functions

 
yaze_status yaze_library_init(void);
 
void yaze_library_shutdown(void);
 
const char* yaze_get_version_string(void);

ROM Operations

 
zelda3_rom* yaze_load_rom(const char* filename);
 
void yaze_unload_rom(zelda3_rom* rom);
 
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 (<tt>src/app/core/asar_wrapper.h</tt>)

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

CLI Examples (<tt>z3ed</tt>)

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:
    absl::Status Initialize();
 
    void Shutdown();
 
    absl::StatusOr<AsarPatchResult> ApplyPatch(
        const std::string& patch_path,
        std::vector<uint8_t>& rom_data,
        const std::vector<std::string>& include_paths = {});
 
    absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
        const std::string& asm_path,
        const std::vector<std::string>& include_paths = {});
 
    absl::Status ValidateAssembly(const std::string& asm_path);
};
 
} // namespace yaze::core

Data Structures

<tt>snes_color</tt>

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

typedef struct snes_color {
    uint16_t raw;   
    uint8_t red;    
    uint8_t green;  
    uint8_t blue;   
} snes_color;

<tt>zelda3_message</tt>

Represents an in-game text message.

typedef struct zelda3_message {
    uint16_t id;            
    uint32_t rom_address;   
    uint16_t length;        
    uint8_t* raw_data;      
    char* parsed_text;      
    bool 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();