Update contributing and asm style guide docs
This commit is contained in:
scawful
@@ -23,13 +23,12 @@ Custom assembly code applied to the game should be included through the `yaze.as
|
||||
## 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.
|
||||
- **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]
|
||||
; =========================================================
|
||||
@@ -68,11 +67,10 @@ Sprite_Minecart_Main:
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
- **Purpose**: Comments should explain why the code exists and what it is intended to do, especially for complex logic.
|
||||
- **Placement**:
|
||||
- **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.
|
||||
@@ -83,22 +81,6 @@ Example:
|
||||
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.
|
||||
@@ -121,11 +103,11 @@ 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
|
||||
LDA $22 : SEC : SBC $3F : STA $31
|
||||
LDA $20 : SEC : SBC $3E : STA $30
|
||||
JSL Link_HandleMovingAnimation_FullLongEntry
|
||||
JSL HandleIndoorCameraAndDoors
|
||||
RTS
|
||||
endmacro
|
||||
```
|
||||
|
||||
@@ -137,12 +119,12 @@ endmacro
|
||||
Example:
|
||||
|
||||
```asm
|
||||
.loop_start
|
||||
LDA $00 : CMP #$10 : BEQ .end_loop
|
||||
.loop_start
|
||||
LDA $00 : CMP #$10 : BEQ .end_loop
|
||||
INC $00
|
||||
BRA .loop_start
|
||||
.end_loop
|
||||
RTS
|
||||
.end_loop
|
||||
RTS
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
@@ -155,10 +137,10 @@ 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
|
||||
db $02, $00, $04, $00 ; North
|
||||
db $00, $00, $03, $01 ; East
|
||||
db $00, $02, $00, $04 ; South
|
||||
db $03, $01, $00, $00 ; West
|
||||
}
|
||||
```
|
||||
|
||||
@@ -206,7 +188,6 @@ AncillaAdd_Hookshot:
|
||||
- **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:
|
||||
|
||||
@@ -216,22 +197,20 @@ Example:
|
||||
; =========================================================
|
||||
Sprite_Minecart_Main:
|
||||
{
|
||||
JSR HandleTileDirections
|
||||
JSR HandleDynamicSwitchTileDirections
|
||||
PHX
|
||||
JSR HandleMinecartMovement
|
||||
PLX
|
||||
PHX
|
||||
JSR HandleMinecartMovement
|
||||
PLX
|
||||
|
||||
REP #$20
|
||||
LDA !SpriteDirection : STA $00
|
||||
SEP #$20
|
||||
RTS
|
||||
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.
|
||||
- **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:
|
||||
|
||||
@@ -241,4 +220,4 @@ Example:
|
||||
if !YAZE_CUSTOM_MOSAIC != 0
|
||||
incsrc "mosaic_change.asm"
|
||||
endif
|
||||
```
|
||||
```
|
||||
|
||||
@@ -20,7 +20,7 @@ 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.
|
||||
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::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.
|
||||
|
||||
@@ -54,37 +54,6 @@ yaze includes an emulator subsystem that allows developers to test their modific
|
||||
- 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).
|
||||
|
||||
Reference in New Issue
Block a user