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

 
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 (src/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 "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

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;   
    uint8_t red;    
    uint8_t green;  
    uint8_t blue;   
} snes_color;

zelda3_message

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();