scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement networking and collaboration features for z3ed

Browse Source 
- Introduced a comprehensive networking system for real-time collaboration across the yaze app, z3ed CLI, and yaze-server using WebSocket.
- Added `WebSocketClient` and `CollaborationService` classes to manage connections, session hosting, proposal submissions, and automatic ROM synchronization.
- Enhanced the z3ed CLI with commands for connecting to the server, submitting proposals, and checking approval statuses.
- Updated documentation to include detailed usage instructions for the new networking features and collaboration workflows.
- Improved CMake configuration to support necessary libraries for networking, including JSON and OpenSSL.
This commit is contained in:
scawful
2025-10-04 22:40:44 -04:00
parent c79c301329
commit 0f4d444a73
9 changed files with 2055 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
docs/04-api-reference.md
View File

@@ -1,252 +1,181 @@
# API Reference
Comprehensive reference for the YAZE C API and C++ interfaces.
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`, `incl/zelda.h`)
## C API (`incl/yaze.h`)
The C API provides a stable, language-agnostic interface for interacting with yaze's core functionalities.
### Core Library Functions
```c
// Initialization
/**
* @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);
// Version management
/**
* @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);
int yaze_get_version_number(void);
bool yaze_check_version_compatibility(const char* expected_version);
// Status utilities
const char* yaze_status_to_string(yaze_status status);
```
### ROM Operations
```c
// ROM loading and management
/**
* @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);
bool yaze_is_rom_modified(const zelda3_rom* rom);
```
### Graphics Operations
```c
// SNES color management
snes_color yaze_rgb_to_snes_color(uint8_t r, uint8_t g, uint8_t b);
void yaze_snes_color_to_rgb(snes_color color, uint8_t* r, uint8_t* g, uint8_t* b);
// Bitmap operations
yaze_bitmap* yaze_create_bitmap(int width, int height, uint8_t bpp);
void yaze_free_bitmap(yaze_bitmap* bitmap);
```
### Palette System
```c
// Palette creation and management
snes_palette* yaze_create_palette(uint8_t id, uint8_t size);
void yaze_free_palette(snes_palette* palette);
snes_palette* yaze_load_palette_from_rom(const zelda3_rom* rom, uint8_t palette_id);
```
### Message System
```c
// Message handling
zelda3_message* yaze_load_message(const zelda3_rom* rom, uint16_t message_id);
void yaze_free_message(zelda3_message* message);
yaze_status yaze_save_message(zelda3_rom* rom, const zelda3_message* message);
```
## 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`)
Complete cross-platform ROM patching with assembly code support, symbol extraction, and validation.
This class provides a complete, cross-platform interface for applying assembly patches, extracting symbols, and validating assembly code using the Asar library.
#### Quick Examples
#### CLI Examples (`z3ed`)
While the `AsarWrapper` can be used programmatically, the `z3ed` CLI is the most common way to interact with it.
**Command Line**
```bash
# Apply assembly patch to ROM
# Apply an assembly patch to a ROM file.
z3ed asar my_patch.asm --rom=zelda3.sfc
# Extract symbols without patching
z3ed extract my_patch.asm
# Validate assembly syntax
z3ed validate my_patch.asm
# 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**
#### C++ API Example
```cpp
#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 patch to ROM
// 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;
}
}
```
#### AsarWrapper Class
#### Class Definition
```cpp
namespace yaze::core {
class AsarWrapper {
public:
// Initialization
/** @brief Initializes the Asar library. */
absl::Status Initialize();
/** @brief Shuts down the Asar library. */
void Shutdown();
bool IsInitialized() const;
// Core functionality
/**
* @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 = {});
// Symbol management
std::optional<AsarSymbol> FindSymbol(const std::string& name);
std::vector<AsarSymbol> GetSymbolsAtAddress(uint32_t address);
std::map<std::string, AsarSymbol> GetSymbolTable();
// Utility functions
/**
* @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);
std::string GetVersion();
void Reset();
};
}
} // namespace yaze::core
```
#### Error Handling
## Data Structures
| Error | Cause | Solution |
|-------|-------|----------|
| `Unknown command` | Invalid opcode | Check 65816 instruction reference |
| `Label not found` | Undefined label | Define the label or check spelling |
| `Invalid hex value` | Bad hex format | Use `$1234` format |
| `Buffer too small` | ROM needs expansion | Check if ROM needs to be larger |
### Data Structures
#### ROM Version Support
```c
typedef enum zelda3_version {
ZELDA3_VERSION_US = 1,
ZELDA3_VERSION_JP = 2,
ZELDA3_VERSION_SD = 3,
ZELDA3_VERSION_RANDO = 4,
// Legacy aliases maintained for compatibility
US = ZELDA3_VERSION_US,
JP = ZELDA3_VERSION_JP,
SD = ZELDA3_VERSION_SD,
RANDO = ZELDA3_VERSION_RANDO,
} zelda3_version;
```
#### SNES Graphics
### `snes_color`
Represents a 15-bit SNES color, composed of 5 bits for each red, green, and blue component.
```c
typedef struct snes_color {
uint16_t raw; // Raw 15-bit SNES color
uint8_t red; // Red component (0-31)
uint8_t green; // Green component (0-31)
uint8_t blue; // Blue component (0-31)
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;
typedef struct snes_palette {
uint8_t id; // Palette ID
uint8_t size; // Number of colors
snes_color* colors; // Color array
} snes_palette;
```
#### Message System
### `zelda3_message`
Represents an in-game text message.
```c
typedef struct zelda3_message {
uint16_t id; // Message ID (0-65535)
uint32_t rom_address; // Address in ROM
uint16_t length; // Length in bytes
uint8_t* raw_data; // Raw ROM data
char* parsed_text; // Decoded UTF-8 text
bool is_compressed; // Compression flag
uint8_t encoding_type; // Encoding type
} 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
### Status Codes
```c
typedef enum yaze_status {
YAZE_OK = 0, // Success
YAZE_ERROR_UNKNOWN = -1, // Unknown error
YAZE_ERROR_INVALID_ARG = 1, // Invalid argument
YAZE_ERROR_FILE_NOT_FOUND = 2, // File not found
YAZE_ERROR_MEMORY = 3, // Memory allocation failed
YAZE_ERROR_IO = 4, // I/O operation failed
YAZE_ERROR_CORRUPTION = 5, // Data corruption detected
YAZE_ERROR_NOT_INITIALIZED = 6, // Component not initialized
} yaze_status;
```
The C API uses an enum `yaze_status` for error handling, while the C++ API uses `absl::Status` and `absl::StatusOr`.
### Error Handling Pattern
### C API Error Pattern
```c
yaze_status status = yaze_library_init();
if (status != YAZE_OK) {
printf("Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
fprintf(stderr, "Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
return 1;
}
zelda3_rom* rom = yaze_load_rom("zelda3.sfc");
if (rom == nullptr) {
printf("Failed to load ROM file\n");
return 1;
}
// ... operations ...
// Use ROM...
yaze_unload_rom(rom);
yaze_library_shutdown();
```
## Extension System
### Plugin Architecture
```c
typedef struct yaze_extension {
const char* name; // Extension name
const char* version; // Version string
const char* description; // Description
const char* author; // Author
int api_version; // Required API version
yaze_status (*initialize)(yaze_editor_context* context);
void (*cleanup)(void);
uint32_t (*get_capabilities)(void);
} yaze_extension;
```
### Capability Flags
```c
#define YAZE_EXT_CAP_ROM_EDITING 0x0001 // ROM modification
#define YAZE_EXT_CAP_GRAPHICS 0x0002 // Graphics operations
#define YAZE_EXT_CAP_AUDIO 0x0004 // Audio processing
#define YAZE_EXT_CAP_SCRIPTING 0x0008 // Scripting support
#define YAZE_EXT_CAP_IMPORT_EXPORT 0x0010 // Data import/export
```
## Backward Compatibility
All existing code continues to work without modification due to:
- Legacy enum aliases (`US`, `JP`, `SD`, `RANDO`)
- Original struct field names maintained
- Duplicate field definitions for old/new naming conventions
- Typedef aliases for renamed types