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

backend-infra-engineer: Pre-0.2.2 2024 Q4 snapshot

Browse Source
This commit is contained in:
scawful
2024-11-28 11:50:47 -05:00
parent 75bf38fa71
commit 18b7fb9abf
238 changed files with 22057 additions and 8538 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
docs/asm-style-guide.md Normal file
View File

@@ -0,0 +1,244 @@
# Asm Style Guide
65816 Assembly is the assembly language used by the Super Nintendo Entertainment System (SNES) and its Ricoh 5A22 processor. This style guide provides conventions and best practices for writing 65816 assembly code in the context of the yaze project. Following these guidelines will help maintain consistency and readability across the codebase.
This guide is based primarily on the [Oracle of Secrets](https://github.com/scawful/Oracle-of-Secrets) codebase and is meant for the [Asar](https://github.com/RPGHacker/asar) assembler and derives influence from the [Asar 1.9 Manual](https://rpghacker.github.io/asar/asar_19/manual/).
Custom assembly code applied to the game should be included through the `yaze.asm` file found in `assets/asm`. This file can be applied to the ROM by the editor using the Asar library or included into a projects codebase for use with the Asar assembler.
## Table of Contents
- [File Structure](#file-structure)
- [Labels and Symbols](#labels-and-symbols)
- [Comments](#comments)
- [Directives](#directives)
- [Instructions](#instructions)
- [Macros](#macros)
- [Loops and Branching](#loops-and-branching)
- [Data Structures](#data-structures)
- [Code Organization](#code-organization)
- [Custom Code](#custom-code)
## File Structure
- **File Extension**: Use `.asm` as the file extension for 65816 assembly files.
- **Header Comments**: Include a header comment at the beginning of each file describing its purpose and the author.
Example:
```asm
; =========================================================
; File: my_file.asm
; Purpose: [Brief description of the file’s functionality]
; Author: [Your Name]
; =========================================================
```
- **Section Headers**: Use clear and consistent section headers to divide code into logical blocks. Each major section (e.g., sprite properties, main logic, subroutines) should start with a delineated header.
Example:
```asm
; =========================================================
; Minecart Sprite Properties
; =========================================================
```
- **Macro Definitions and Includes**: Place macros and include directives at the beginning of the file to keep them organized and easily accessible.
## Labels and Symbols
- **Naming Conventions**:
- **Global Labels**: Use descriptive names in `PascalCase` for global labels (e.g., `Sprite_Minecart_Main`).
- **Local Labels**: Prefix local labels with a dot (`.`) to indicate their limited scope (e.g., `.check_direction`).
- **Constants and Flags**: Use `ALL_CAPS_WITH_UNDERSCORES` for constants and flags (e.g., `!MINECART_SPEED`, `!HARVESTING_FLAG`).
- **Variables**: Use `CamelCase` for variable names to maintain readability (e.g., `LinkInCart`, `SpriteDirection`).
- **Alignment**: Align labels to the left margin for better readability. Indent instructions and comments to separate them from labels.
Example:
```asm
Sprite_Minecart_Main:
{
JSR HandleTileDirections
JSR HandleDynamicSwitchTileDirections
RTS
}
```
## Comments
- **Purpose**: Comments should explain why the code exists and what it is intended to do, especially for complex logic.
- **Placement**:
- Comments can be placed above the code block they describe for longer explanations.
- Inline comments can be used for single lines of code where the purpose might not be immediately clear.
- **Clarity**: Avoid stating the obvious. Focus on explaining the logic rather than restating the code.
Example:
```asm
LDA $22 : SEC : SBC $3F : STA $31 ; Adjust X position for camera movement
```
## Directives
- **Organization**: Use `%macro`, `include`, and other Asar directives in a structured manner, keeping related directives grouped together.
- **Usage**: Ensure all directives are used consistently throughout the codebase, following the naming conventions and formatting rules established.
Example:
```asm
%macro InitMovement
LDA.b $22 : STA.b $3F
LDA.b $23 : STA.b $41
LDA.b $20 : STA.b $3E
LDA.b $21 : STA.b $40
endmacro
```
## Instructions
- **Single Line Instructions**: Combine multiple instructions on a single line using colons (`:`) where appropriate for related operations.
- **Separation**: Use line breaks to separate distinct sections of code logically, improving readability.
- **Optimization**: Always consider the most efficient instruction for the task at hand, especially in performance-critical sections.
Example:
```asm
LDA #$01 : STA !LinkInCart ; Set Link in cart flag
```
## Macros
- **Naming**: Use `PascalCase` for macro names, with the first letter of each word capitalized (e.g., `InitMovement`, `MoveCart`).
- **Parameters**: Clearly define and document parameters within macros to ensure they are used correctly.
- **Reuse**: Encourage the reuse of macros to avoid code duplication and simplify maintenance.
Example:
```asm
%macro HandlePlayerCamera
LDA $22 : SEC : SBC $3F : STA $31
LDA $20 : SEC : SBC $3E : STA $30
JSL Link_HandleMovingAnimation_FullLongEntry
JSL HandleIndoorCameraAndDoors
RTS
endmacro
```
## Loops and Branching
- **Branch Labels**: Use meaningful names for branch labels, prefixed with a dot (`.`) for local branches.
- **Optimization**: Minimize the number of instructions within loops and branches to improve performance.
Example:
```asm
.loop_start
LDA $00 : CMP #$10 : BEQ .end_loop
INC $00
BRA .loop_start
.end_loop
RTS
```
## Data Structures
- **Alignment**: Align data tables and structures clearly, and use comments to describe the purpose and layout of each.
- **Access**: Ensure that data structures are accessed consistently, with clear boundaries between read and write operations.
Example:
```asm
.DirectionTileLookup
{
db $02, $00, $04, $00 ; North
db $00, $00, $03, $01 ; East
db $00, $02, $00, $04 ; South
db $03, $01, $00, $00 ; West
}
```
- **Structs**: Use structs to group related data together, improving readability and maintainability.
Example:
```asm
struct AncillaAdd_HookshotData $099AF8
.speed_y: skip 4
.speed_x: skip 4
.offset_y: skip 8
.offset_x: skip 8
endstruct
AncillaAdd_Hookshot:
; $099AF0
.speed_y
db -64 ; up
db 64 ; down
db 0 ; left
db 0 ; right
; $099AFC
.speed_x
db 0 ; up
db 0 ; down
db -64 ; left
db 64 ; right
; $099B00
.offset_y
dw 4 ; up
dw 20 ; down
dw 8 ; left
dw 8 ; right
; $099B08
.offset_x
dw 0 ; up
dw 0 ; down
dw -4 ; left
dw 11 ; right
```
## Code Organization
- **Logical Grouping**: Organize code into logical sections, with related routines and macros grouped together.
- **Separation of Concerns**: Ensure that each section of code is responsible for a specific task or set of related tasks, avoiding tightly coupled code.
- **Modularity**: Write code in a modular way, making it easier to reuse and maintain.
- **Status Registers and Stack Operations**: Indent code blocks when using status register operations (REP, SEP, PHX, PLX, etc.) to improve readability.
Example:
```asm
; =========================================================
; Minecart Sprite Logic
; =========================================================
Sprite_Minecart_Main:
{
JSR HandleTileDirections
JSR HandleDynamicSwitchTileDirections
PHX
JSR HandleMinecartMovement
PLX
REP #$20
LDA !SpriteDirection : STA $00
SEP #$20
RTS
}
```
## Custom Code
- **Integration**: Include custom assembly code in the `yaze.asm` file to ensure it is applied correctly to the ROM. The module should include a define and conditional statement to allow users to disable the module if needed.
Example:
```asm
!YAZE_CUSTOM_MOSAIC = 1
if !YAZE_CUSTOM_MOSAIC != 0
incsrc "mosaic_change.asm"
endif
```

61
docs/build-instructions.md
View File

@@ -1,27 +1,58 @@
# Build Instructions
For VSCode users, use the following CMake extensions
- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
Yaze uses CMake to build the project. If you are unexperienced with CMake, please refer to the [CMake documentation](https://cmake.org/documentation/).
The gui editor is built using SDL2 and ImGui. For reference on how to use ImGui, see the [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) guide. For SDL2, see the [SDL2 documentation](https://wiki.libsdl.org/).
For those who want to reduce compile times, consider installing the dependencies on your system.
## Windows
For VSCode users, use the following CMake extensions with MinGW-w64
https://marketplace.visualstudio.com/items?itemName=twxs.cmake
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
https://www.msys2.org/
Recommended to use [msys2](https://www.msys2.org/) for a Unix-like environment on Windows.
Add to environment variables `C:\msys64\mingw64\bin`
Install the following packages using `pacman -S <package-name>`
`mingw-w64-x86_64-gcc`
`mingw-w64-x86_64-gcc-libs`
`mingw-w64-x86_64-cmake`
`mingw-w64-x86_64-glew`
`mingw-w64-x86_64-lib-png`
- `mingw-w64-x86_64-gcc`
- `mingw-w64-x86_64-gcc-libs`
- `mingw-w64-x86_64-cmake`
- `mingw-w64-x86_64-sdl2`
- `mingw-w64-x86_64-libpng`
- `mingw-w64-x86_64-abseil-cpp`
For `yaze_py` you will need Boost Python
- `mingw-w64-x86_64-boost`
# macOS
- Clang 15.0.1 x86_64-apple-darrwin22.5.0
- SDL2 Source v2.26.5
- Removed snes_spc
- Removed asar_static
Prefer to use clang provided with XCode command line tools over gcc.
Install the following packages using `brew install <package-name>`
- `cmake`
- `sdl2`
- `zlib`
- `libpng`
- `abseil`
- `boost-python3`
# iOS
Xcode is required to build for iOS. Currently testing with iOS 18 on iPad Pro.
The xcodeproject file is located in the `ios` directory.
You will need to link `SDL2.framework` and `libpng.a` to the project.
# GNU/Linux
You can use your package manager to install the same dependencies as macOS.
I trust you know how to use your package manager.

47
docs/changelog.md Normal file
View File

@@ -0,0 +1,47 @@
# Changelog
## 0.0.1 (06-08-2022)
- Started project
- Added ImGui
- Added SDL2
- Added yaze_test target with gtest
## 0.0.2 - 0.0.4
- TODO: Track changes over this time
## 0.0.5 (11-21-2023)
- DungeonEditor
- DungeonObjectRenderer
## 0.0.6 (11-22-2023)
- ScreenEditor DungeonMap
- Tile16 Editor
- Canvas updates
## 0.0.7 (01-27-2024)
- OverworldEntities
- Entrances
- Exits
- Items
- Sprites
## 0.1.0 (05-11-2024)
- TODO: Track changes over this time
## 0.2.0 (07-20-2024)
- iOS app support
- Graphics Sheet Browser
- Project Files
## 0.2.1 (08-20-2024)
- Improved MessageEditor parsing
- Added integration test window
- Bitmap bug fixes

66
docs/compression.md
View File

@@ -1,66 +0,0 @@
# LC_LZ2 Compression
The compression algorithm has multiple implementations with varying levels of quality, based primarily on the implementations made in skarsnik/sneshacking, Zarby89/ZScreamDungeon and ZCompress with optimizations made for C++.
Currently, the Compress and Uncompress methods from Hyrule Magic are used and all other compression methods are considered deprecated.
## Key Definitions
### Constants and Macros:
- `BUILD_HEADER(command, length)`: Macro to build a header from a command and a length.
- Command Constants: Constants to represent different commands like `kCommandDirectCopy`, `kCommandByteFill`, etc.
- Length and Mode Constants: Such as `kMaxLengthNormalHeader`, `kNintendoMode1`, etc.
### Data Structures:
#### 1. CompressionCommand:
- **arguments**: 2D array representing the command arguments for each possible command.
- **cmd_size**: Array storing the size of each possible command.
- **data_size**: Array storing the size of the data processed by each possible command.
#### 2. CompressionPiece:
- **command**: Represents the compression command.
- **length**: Length of the compressed data piece.
- **argument_length**: Length of the argument.
- **argument**: Argument as a string.
- **next**: Pointer to the next compression piece.
#### 3. CompressionContext (for Compression V3):
- Contains vectors to store raw and compressed data, compression pieces, and compression string.
- Various counters and flags for compression control.
- Current compression command details.
## Compression Functions
### Version 1:
- **Byte Repeat**: `CheckByteRepeat`
- **Word Repeat**: `CheckWordRepeat`
- **Increasing Byte**: `CheckIncByte`
- **Intra Copy**: `CheckIntraCopy`
- **Validation and Alternatives**: `ValidateForByteGain` & `CompressionCommandAlternative`
### Version 2:
- **Byte Repeat**: `CheckByteRepeatV2`
- **Word Repeat**: `CheckWordRepeatV2`
- **Increasing Byte**: `CheckIncByteV2`
- **Intra Copy**: `CheckIntraCopyV2`
- **Validation and Alternatives**: `ValidateForByteGainV2` & `CompressionCommandAlternativeV2`
### Version 3:
Using `CompressionContext` to handle compression.
- **Initialization**: `InitializeCompression`
- **Command Checks**: Such as `CheckByteRepeatV3`
- **Determining Best Compression**: `DetermineBestCompression`
- **Handling Direct Copy**: `HandleDirectCopy`
- **Adding Compression to Chain**: `AddCompressionToChain`
## Decompression Functions:
- `SetBuffer`: Prepares a buffer from data.
- `memfill`: Fills memory.
- **Decompression**: Such as `DecompressV2`, `DecompressGraphics`, and `DecompressOverworld`.
## Utility Functions:
- **Printing**: Such as `PrintCompressionPiece` and `PrintCompressionChain`.
- **Compression String Creation**: `CreateCompressionString`
- **Compression Result Validation**: Such as `ValidateCompressionResult` and its V3 variant.
- **Compression Piece Manipulation**: Like `SplitCompressionPiece` and its V3 variant.

139
docs/contributing.md Normal file
View File

@@ -0,0 +1,139 @@
# Contributing
This project is looking for contributors to help improve the software and enhance the user experience. If you are interested in contributing, please read the following guidelines and suggestions for areas where you can make a difference.
Discussion on the editor and its development can be found on the [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) server.
## Style Guide
When contributing to the project, please follow these guidelines to ensure consistency and readability across the codebase:
C++ Code should follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with the following exceptions:
- Boost libraries are allowed, but require cross platform compatibility.
Objective-C Code should follow the [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html).
Python Code should follow the [PEP 8 Style Guide](https://pep8.org/).
Assembly code should follow the [65816 Style Guide](docs/asm-style-guide.md).
## Testing Facilities
The project includes the `yaze_test` target which defines unit tests and an integration test window. The unit tests make use of GoogleTest and GoogleMock. The integration test window is an ImGui window build out of the yaze::app::core::Controller and yaze::test::integration::TestEditor. The integration test window can be accessed by passing the argument `integration` to the target.
New modules should define unit tests in the `src/test` directory and integration tests in the `src/test/integration` directory. The `yaze_test` target will automatically include all tests in these directories.
## Key Areas of Contribution
### 1. Extensions System
Yaze *(stylized as yaze)* emphasizes extensibility. The `yaze_ext` library allows developers to build and integrate extensions using C, C++, or Python. This system is central to yaze's modular design, enabling new features, custom editors, or tools to be added without modifying the core codebase.
- C/C++ Extensions: Utilize the `yaze_extension` interface to integrate custom functionality into the editor. You can add new tabs, manipulate ROM data, or extend the editor’s capabilities with custom tools.
- Python Extensions: Currently unimplemented, Python extensions will allow developers to write scripts that interact with the editor, modify ROM data, or automate repetitive tasks.
Examples of Extensions:
- UI enhancements like additional menus, panels, or status displays.
- Rom manipulation tools for editing data structures, such as the overworld maps or dungeon objects.
- Custom editors for specific tasks, like file format conversion, data visualization, or event scripting.
### 2. Sprite Builder System
The sprite builder system in yaze is based on the [ZSpriteMaker](https://github.com/Zarby89/ZSpriteMaker/) project and allows users to create custom sprites for use in ROM hacks. The goal is to support ZSM files and provide an intuitive interface for editing sprites without the need for writing assembly code. Contributions to the sprite builder system might include:
- Implementing new features for sprite editing, such as palette management, animation preview, or tileset manipulation.
- Extending the sprite builder interface by writing assembly code for sprite behavior.
### 3. Emulator Subsystem
yaze includes an emulator subsystem that allows developers to test their modifications directly within the editor. The emulator can currently run certain test ROMs but lacks the ability to play any complex games with audio because of timing issues with the APU and Spc700. Contributions to the emulator subsystem might include:
- Improving the accuracy and performance of the emulator to support more games and features.
- Implementing new debugging tools, such as memory viewers, breakpoints, or trace logs.
- Extending the emulator to support additional features, such as save states, cheat codes, or multiplayer modes.
### 4. Editor Management
The `EditorManager` class manages the core functionalities of YAZE, including rendering the UI, handling user input, and managing multiple editors. While this class is central to yaze's operations, it has many responsibilities. You can help by:
- Refactoring `EditorManager` to delegate responsibilities to specialized managers (e.g., `MenuManager`, `TabManager`, `StatusManager`).
- Optimizing the rendering and update loop to improve performance, especially when handling large textures or complex editors.
- Implementing new features that streamline the editing process, such as better keyboard shortcuts, command palette integration, or project management tools.
### 5. User Interface and UX
yaze's UI is built with ImGui, offering a flexible and customizable interface. Contributions to the UI might include:
- Designing and implementing new themes or layouts to improve the user experience.
- Adding new UI components, such as toolbars, context menus, or customizable panels.
- Improving the accessibility of the editor, ensuring it is usable by a wide range of users, including those with disabilities.
### 6. ROM Manipulation
The `Rom` class is at the heart of yaze's ability to modify and interact with ROM data. Contributions here might involve:
- Optimizing the loading and saving processes to handle larger ROMs or more complex modifications efficiently.
- Extensions should be able to change the way the `Rom` class interacts with the ROM data with custom pointers to expanded data structures.
### 7. Testing and Documentation
Quality assurance and documentation are critical to yaze's success. Contributions in this area include:
- Writing unit tests for new and existing features to ensure they work correctly and remain stable over time.
- Contributing to the documentation, both for end-users and developers, to make yaze easier to use and extend.
- Creating tutorials or guides that help new developers get started with building extensions or contributing to the project.
## Building the Project
For detailed instructions on building YAZE, including its dependencies and supported platforms, refer to [build-instructions.md](docs/build-instructions.md).
## Getting Started
1. Clone the Repository:
```bash
git clone https://github.com/yourusername/yaze.git
cd yaze
```
2. Initialize the Submodules:
```bash
git submodule update --init --recursive
```
3. Build the Project:
Follow the instructions in the [build-instructions.md](docs/build-instructions.md). file to configure and build the project on your target platform.
4. Run the Application:
After building, you can run the application on your chosen platform and start exploring the existing features.
## Contributing your Changes
1. Fork the Repository:
Create a fork of the project on GitHub and clone your fork to your local machine.
2. Create a Branch:
Create a new branch for your feature or bugfix.
```bash
git checkout -b feature/my-new-feature
```
3. Implement Your Changes:
Follow the guidelines above to implement new features, extensions, or improvements.
4. Test Your Changes:
Ensure your changes don’t introduce new bugs or regressions. Write unit tests where applicable.
5. Submit a Pull Request:
Push your changes to your fork and submit a pull request to the main repository. Provide a clear description of your changes and why they are beneficial.

63
docs/getting-started.md
View File

@@ -1,23 +1,60 @@
# Getting Started with YAZE
# Getting Started
This software allows you to modify the classic SNES game "The Legend of Zelda: A Link to the Past" by editing its ROM file. With this editor, you can change various aspects of the game, such as the maps, sprites, items, and more.
This software allows you to modify "The Legend of Zelda: A Link to the Past" (US or JP) ROMs.
This editor is built to be compatible with ZScream projects and is designed to be cross platform.
Please note that this project is currently a work in progress, and some features may not be fully implemented or may be subject to change.
## Prerequisites
Before you start using YAZE, make sure you have the following:
## General Tips
- A copy of "The Legend of Zelda: A Link to the Past" ROM file (US or JP)
- Basic knowledge of hexadecimal and binary data
- Experiment flags determine whether certain features are enabled or not. To change your flags, go to `File` > `Options` > `Experiment Flags` or in the Settings tab.
- Backup files are enabled by default. Each save will produce a timestamped copy of your ROM before you last saved. You can disable this feature in the settings.
## Usage
To use the Link to the Past ROM Editor, follow these steps:
## Extending Functionality
Open the ROM file using the "File" menu.
In addition to the built-in features, this software provides a pure C library interface and a Python module that can be used for building extensions and custom sprites without assembly. In the editor these can be loaded under the `Extensions` menu.
...
This feature is still in development and is not yet fully documented.
## Supported Features
| Feature | Status | Details |
|---------|--------|-------------|
| Overworld Maps | Done | Edit and save tile32 data. |
| Overworld Map Properties | Done | Edit and save map properties. |
| Overworld Entrances | Done | Edit and save entrance data. |
| Overworld Exits | Done | Edit and save exit data. |
| Overworld Sprites | In Progress | Edit sprite positions, add and remove sprites. |
| Tile16 Editing | Todo | Edit and save tile16 data. |
| Dungeon | In Progress | View dungeon room metadata and edit room data. |
| Palette | In Progress | Edit and save palettes, palette groups. |
| Graphics Sheets | In Progress | Edit and save graphics sheets. |
| Graphics Groups | Done | Edit and save graphics groups. |
| Sprite | Todo | View-only sprite data. |
| Custom Sprites | Todo | Edit and create custom sprite data. |
| Music | Todo | Edit music data. |
| Dungeon Maps | Todo | Edit dungeon maps. |
| Scad Format | Done-ish | Open and view scad files (SCR, CGX, COL) |
| Hex Editing | Done | View and edit ROM data in hex. |
| Asar Patching | In Progress | Apply Asar patches to your ROM or Project. |
## Command Line Interface
Included with the editor is a command line interface (CLI) that allows you to perform various operations on your ROMs from the command line. This aims to reduce the need for multiple tools in zelda3 hacking like Zcompress, LunarExpand, LunarAddress, Asar, and others.
| Command | Arg | Params | Status |
|---------|-----|--------|--------|
| Apply BPS Patch | -a | rom_file bps_file | In progress |
| Create BPS Patch | -c | bps_file src_file modified_file | Not started |
| Asar Patch | -asar | asm_file rom_file | In progress |
| Open ROM | -o | rom_file | Complete |
| Backup ROM | -b | rom_file [new_file] | In progress |
| Expand ROM | -x | rom_file file_size | Not started |
| Transfer Tile16 | -t | src_rom dest_rom tile32_id_list(csv) | Complete |
| Export Graphics | -e | rom_file bin_file | In progress |
| Import Graphics | -i | bin_file rom_file | Not started |
| SNES to PC Address | -s | address | Complete |
| PC to SNES Address | -p | address | Complete |
Save your changes using the "File" menu.
Backup files are enabled by default. Each save will produce a timestamped copy of your ROM before you last saved.
That's it! With these instructions, you should be able to get started with using YAZE. Happy editing!

170
docs/infrastructure.md
View File

@@ -1,140 +1,86 @@
# YAZE Infrastructure Overview
# Infrastructure Overview
For developers to reference.
The goal of yaze is to build a cross platform editor for the Legend of Zelda: A Link to the Past. The project is built using C++20, SDL2, and ImGui. The project is built using CMake and is designed to be modular and extensible. The project is designed to be built on Windows, macOS, iOS, and Linux.
## Targets
- **yaze**: Desktop application for Windows/macOS/Linux
- **z3ed**: Command Line Interface
- **yaze_c**: C Library
- **yaze_py**: Python Module
- **yaze_test**: Unit test executable
- **yaze_ios**: iOS application
## Directory Structure
- **.github/workflows**: Contains `yaze_test` workflow config.
- **assets**: Hosts assets like fonts.
- **assets**: Hosts assets like fonts, icons, assembly source, etc.
- **cmake**: Contains CMake configurations.
- **docs**: Contains documentation for users and developers.
- [Getting Started](./getting-started.md)
- [LC_LZ2 Compression](./compression.md)
- **src**: Contains source files.
- **app**: Contains the GUI editor `yaze`
- **cli**: Contains the command line interface `z3ed`
- **lib**: Contains git submodule dependencies.
- Abseil-cpp
- Asar
- ImGui
- ImGuiFileDialog
- ImGuiColorTextEdit
- imgui_memory_editor
- SDL2
- **test**: Contains testing interface `yaze_test`
- **app**: Contains the GUI editor `yaze`
- **app/emu**: Contains a standalone Snes emulator application `yaze_emu`
- **cli**: Contains the command line interface `z3ed`
- **incl**: Contains the data headers for `yaze_c`
- **ios**: Contains the iOS application `yaze_ios`
- **lib**: Contains the dependencies as git submodules
- **py**: Contains the Python module `yaze_py`
- **test**: Contains testing interface `yaze_test`
- **win32**: Contains Windows resource file and icon
### Flow of Control
## Dependencies
- [app/yaze.cc](../src/app/yaze.cc)
See [build-instructions.md](docs/build-instructions.md) for more information.
- **SDL2**: Graphics library
- **ImGui**: GUI library
- **Abseil**: C++ library
- **libpng**: Image library
- **Boost**: Python library
## Flow of Control
- app/yaze.cc
- Initializes `absl::FailureSignalHandler` for stack tracing.
- Runs the `core::Controller` loop.
- [app/core/controller.cc](../src/app/core/controller.cc)
- app/core/controller.cc
- Initializes SDLRenderer and SDLWindow
- Initializes ImGui, fonts, themes, and clipboard.
- Handles user input from keyboard and mouse.
- Updates `editor::MasterEditor`
- Renders the output to the screen.
- Handles the teardown of SDL and ImGui resources.
- [app/editor/master_editor.cc](../src/app/editor/master_editor.cc)
- Handles the main menu bar.
- File
- Open - [app::ROM::LoadFromFile](../src/app/rom.cc#l=90)
- Save - [app::ROM::SaveToFile](../src/app/rom.cc#l=301)
- Edit
- View
- Emulator
- HEX Editor
- ASM Editor
- Palette Editor
- Memory Viewer
- ImGui Demo
- GUI Tools
- Runtime Metrics
- Style Editor
- Help
- app/editor/editor_manager.cc
- Handles the main menu bar
- Handles `absl::Status` errors as popups delivered to the user.
- Dispatches messages to the various editors.
- Update all the editors in a tab view.
- [app/editor/assembly_editor.cc](../src/app/editor/assembly_editor.cc)
- [app/editor/dungeon_editor.cc](../src/app/editor/dungeon_editor.cc)
- [app/editor/graphics_editor.cc](../src/app/editor/graphics_editor.cc)
- [app/editor/music_editor.cc](../src/app/editor/music_editor.cc)
- [app/editor/overworld_editor.cc](../src/app/editor/overworld_editor.cc)
- [app/editor/screen_editor.cc](../src/app/editor/screen_editor.cc)
- [app/editor/sprite_editor.cc](../src/app/editor/sprite_editor.cc)
- app/editor/code/assembly_editor.cc
- app/editor/dungeon/dungeon_editor.cc
- app/editor/graphics/graphics_editor.cc
- app/editor/graphics/gfx_group_editor.cc
- app/editor/graphics/palette_editor.cc
- app/editor/graphics/tile16_editor.cc
- app/editor/message/message_editor.cc
- app/editor/music/music_editor.cc
- app/editor/overworld/overworld_editor.cc
- app/editor/graphics/screen_editor.cc
- app/editor/sprite/sprite_editor.cc
- app/editor/system/settings_editor.cc
## ROM
- [app/rom.cc](../src/app/rom.cc)
- [app/rom.h](../src/app/rom.h)
---
## Rom
This `ROM` class provides methods to manipulate and access data from a ROM.
- app/rom.cc
- app/rom.h
- **Key Methods**:
- `Load2BppGraphics()`: Loads 2BPP graphics data from specified sheets.
- `LoadAllGraphicsData()`: Loads all graphics data, both compressed and uncompressed, converting where necessary.
- `LoadFromFile(const absl::string_view& filename, bool z3_load)`: Loads ROM data from a file. It also handles headers and Zelda 3 specific data if requested.
- `LoadFromPointer(uchar* data, size_t length)`: Loads ROM data from a provided pointer.
- `LoadFromBytes(const Bytes& data)`: Loads ROM data from bytes.
- `LoadAllPalettes()`: Loads all color palettes used in the ROM. This includes palettes for various elements like sprites, shields, swords, etc.
- `UpdatePaletteColor(...)`: Updates a specific color within a named palette group.
The Rom class provides methods to manipulate and access data from a ROM.
- **Internal Data Structures**:
- `rom_data_`: A container that holds the ROM data.
- `graphics_bin_`: Holds the graphics data.
- `palette_groups_`: A map containing various palette groups, each having its own set of color palettes.
- **Special Notes**:
- The class interacts with various external functionalities, such as decompression algorithms (`gfx::DecompressV2`) and color conversion (`gfx::SnesTo8bppSheet`).
- Headers in the ROM data, if present, are identified and removed.
- Specific Zelda 3 data can be loaded if specified.
- Palettes are categorized into multiple groups (e.g., `ow_main`, `ow_aux`, `hud`, etc.) and loaded accordingly.
Currently implemented as a singleton with SharedRom which is not great but has helped with development velocity. Potential room for improvement is to refactor the editors to take the ROM as a parameter.
## Bitmap
- [app/gfx/bitmap.cc](../src/app/gfx/bitmap.cc)
- [app/gfx/bitmap.h](../src/app/gfx/bitmap.cc)
---
- app/gfx/bitmap.cc
- app/gfx/bitmap.h
This class is responsible for creating, managing, and manipulating bitmap data, which can be displayed on the screen using the ImGui library.
This class is responsible for creating, managing, and manipulating bitmap data, which can be displayed on the screen using SDL2 Textures and the ImGui draw list. It also provides functions for exporting these bitmaps to the clipboard in PNG format using libpng.
### Key Attributes:
1. **Width, Height, Depth, and Data Size**: These represent the dimensions and data size of the bitmap.
2. **Pixel Data**: Points to the raw data of the bitmap.
3. **Texture and Surface**: Use SDL to manage the graphical representation of the bitmap data. Both these attributes have custom deleters, ensuring proper resource management.
### Main Functions:
1. **Constructors**: Multiple constructors allow for different ways to create a Bitmap instance, like specifying width, height, depth, and data.
2. **Create**: This set of overloaded functions provides ways to create a bitmap from different data sources.
3. **CreateFromSurface**: Allows for the creation of a bitmap from an SDL_Surface.
4. **Apply**: Changes the bitmap's data to a new set of Bytes.
5. **Texture Operations**:
- **CreateTexture**: Creates an SDL_Texture from the bitmap's data for rendering.
- **UpdateTexture**: Updates the SDL_Texture with the latest bitmap data.
6. **SaveSurfaceToFile**: Saves the SDL_Surface to a file.
7. **SetSurface**: Assigns a new SDL_Surface to the bitmap.
8. **Palette Functions**:
- **ApplyPalette (Overloaded)**: This allows for the application of a SNESPalette or a standard SDL_Color palette to the bitmap.
9. **WriteToPixel**: Directly writes a value to a specified position in the pixel data.
## Z3ED cli
| Command | Arg | Params | Status |
|---------|-----|--------|--------|
| Apply BPS Patch | -a | rom_file bps_file | In progress |
| Create BPS Patch | -c | bps_file src_file modified_file | Not started |
| Open ROM | -o | rom_file | Complete |
| Backup ROM | -b | rom_file [new_file] | In progress |
| Expand ROM | -x | rom_file file_size | Not started |
| Transfer Tile16 | -t | src_rom dest_rom tile32_id_list(csv) | Complete |
| Export Graphics | -e | rom_file bin_file | In progress |
| Import Graphics | -i | bin_file rom_file | Not started |
| SNES to PC Address | -s | address | Complete |
| PC to SNES Address | -p | address | Complete |
## Further Development Ideas
- Extend `zelda3` namespace with additional functionalities.
- Optimize program performance.
- Introduce new features in the GUI editor.

63
docs/yaze.org Normal file
View File

@@ -0,0 +1,63 @@
#+TITLE: yaze todo
#+SUBTITLE: yet another zelda3 editor todo list
#+AUTHOR: @scawful
#+TODO: TODO ACTIVE FEEDBACK VERIFY | DONE
* Daily Log
<2024-11-14 Thu>
Been making lots of adjustments and cleaning up old code. Primarily improving the dungeon map editor and supporting bin graphics for my Oracle of Secrets dungeon maps. Additionally, working to support saving for resources like graphics sheets and expanded the project file system.
<2024-09-07 Sat>
Various header cleanup using the LSP in emacs to detect unused includes.
Making adjustments to font loading so the editor can be opened from terminal/emacs.
Currently the font files and the zeml files require the binary to be relative to `assets/layouts` and `assets/fonts`
I've set it up so that the macOS app bundles the resources into the `yaze.app` so that the binary can be run from anywhere. This will need to be adjusted for other platforms.
<2024-09-02 Mon>
Extracted the DisplayPalette function out of the PaletteEditor and into its own standalone function.
<2024-09-01 Sun>
Started learning spacemacs and org-mode.
* Editors
** Overworld
*** TODO ZSCustomOverworld implementation.
**** DONE Custom Overworld Map Settings Inputs
**** DONE Load ZSCOW data from ROM in OverworldMap
**** TODO Add Main Palette support
**** TODO Add Custom Area BG Color support
*** TODO Fix sprite icon draw positions
*** TODO Fix exit icon draw positions
** Dungeon
*** TODO Draw dungeon objects
** Graphics
*** TODO Tile16 Editor
- [ ] Draw tile8 to tile16 quadrant.
*** TODO Fix graphics sheet pencil drawing
** Message
*** TODO Fix Message Parsing
** Palette
*** TODO Persist color changes for saving to ROM.
** Screens
*** ACTIVE Dungeon Maps
*** ACTIVE Inventory Menu
*** TODO Overworld Map
*** TODO Title Screen
*** TODO Naming Screen
* Infrastructure
** File Handling
*** TODO Update recent files manager to bundle the recent files list with the application
*** DONE Create a util for handling file operations from the bundled resources.
** Font Loading
*** TODO Make font sizes variables so they can be reloaded by the user.
** ZEML
*** DONE Package layout files with the executable to avoid relative file lookup