Contributing RE Findings

​

Before You Start

​

Prerequisites

1. Familiarity with the tools
   • IDA Pro, Ghidra, or Binary Ninja
   • Basic understanding of x64 assembly
   • Knowledge of C/C++ structures and classes
2. Setup complete
   • Scripts installed and working
   • data.yml successfully applied to your disassembly
   • Git and GitHub account configured
3. Current game version
   • Working with the latest FFXIV patch
   • Fresh analysis of ffxiv_dx11.exe

​

What to Contribute

• New classes and structures not yet documented
• Virtual function names for existing classes
• Member function discoveries and their purposes
• Global variables and singletons
• Signatures for important functions
• Fixes for incorrect or outdated information
• Documentation improvements and comments

​

Research Workflow

​

1. Choose a Target

• Follow the code from known UI addons to find new structures
• Trace game features you understand well
• Examine vtables with unnamed virtual functions
• Look for patterns in constructor functions
• Search for strings related to game features

​

2. Document Your Findings

Class: Client::UI::AddonSomeWindow
Vtable: 0x141A23456
Base: Component::GUI::AtkUnitBase

Functions found:
- 0x14078A120: Appears to be constructor (writes vtable, initializes fields)
- 0x14078A890: Called every frame, likely Update
- vf63: Overrides base Update
- vf64: Overrides base Draw

Global instance: 0x1429C8500

Notes:
- Related to party list functionality
- Called when party composition changes
- Has array of 8 member structs (one per party member?)

​

3. Verify Your Findings

• Cross-reference addresses in multiple functions
• Test function signatures with SigScanner/sigmaker
• Verify vtable sizes match class hierarchy
• Check inheritance makes logical sense
• Confirm addresses haven’t already been documented

​

4. Update data.yml

​

Example Addition

Client::UI::AddonPartyList:
  instances:
    - ea: 0x1429C8500
  vtbls:
    - ea: 0x141A23456
      base: Component::GUI::AtkUnitBase
  vfuncs:
    63: Update
    64: Draw
    65: OnRefresh
  funcs:
    0x14078A120: ctor
    0x14078A890: UpdatePartyMemberInfo
    0x14078AB20: RefreshPartyList
    0x14078AC40: SetMemberHighlight

​

5. Test Your Changes

1. Run ffxiv_idarename.py (or equivalent for your tool)
2. Check console output for errors
3. Navigate to renamed symbols in the disassembler
4. Verify names applied correctly
5. Check for conflicts with existing entries

​

6. Generate Signatures (If Applicable)

1. Place cursor on function’s first instruction
2. Press Ctrl+Alt+S
3. Signature copied to clipboard

1. Follow the tool’s instructions
2. Generate signature for the function

# In your pull request description or comments
Client::UI::AddonPartyList.UpdatePartyMemberInfo
Signature: E8 ?? ?? ?? ?? 48 8B C8 48 89 05 ?? ?? ?? ?? EB ?? 48 8B CE

​

Submitting Your Contribution

​

Fork and Clone

1. Fork the FFXIVClientStructs repository on GitHub
2. Clone your fork:
   git clone https://github.com/YOUR_USERNAME/FFXIVClientStructs.git
   cd FFXIVClientStructs
   
3. Add upstream remote:
   git remote add upstream https://github.com/aers/FFXIVClientStructs.git
   

​

Create a Branch

git checkout -b feature/addon-partylist

• feature/addon-partylist
• fix/framework-vtable-size
• update/exd-module-vfuncs
• docs/improve-data-yml-comments

​

Make Your Changes

1. Edit data.yml:
   code ida/data.yml
   
2. Update version if needed:
   version: 2026.02.20.0000.0000  # Current patch version
   
3. Add your findings following the format guidelines
4. Test thoroughly as described above

​

Commit Your Changes

git add ida/data.yml
git commit -m "Add Client::UI::AddonPartyList structure and functions"

​

Good Commit Messages

• Descriptive: Explain what was added/changed
• Concise: One line summary
• Detailed: Add multi-line description if needed

Add Client::UI::AddonPartyList structure and functions

Added:
- Vtable at 0x141A23456
- Constructor and 3 member functions
- Virtual functions: Update, Draw, OnRefresh
- Global instance pointer

Fix Client::System::Framework::Framework vtable size

Corrected vfunc indices for Tick and GetUIModule.
Previously off by 1 due to misidentified dtor.

Update Component::Exd::ExdModule virtual functions

Added names for vf8-vf12 based on decompilation analysis.
All relate to sheet loading and caching.

​

Push to Your Fork

git push origin feature/addon-partylist

​

Create a Pull Request

1. Navigate to your fork on GitHub
2. Click “Pull Request” or “Compare & pull request”
3. Write a clear title:
   Add Client::UI::AddonPartyList structure
   
4. Provide detailed description:
   ## Summary
   Added reverse engineering data for the AddonPartyList UI component.
   
   ## Changes
   - Added class definition for `Client::UI::AddonPartyList`
   - Identified vtable at 0x141A23456 (inherits from AtkUnitBase)
   - Named 3 virtual functions: Update, Draw, OnRefresh
   - Named constructor and 3 member functions
   - Added global instance pointer at 0x1429C8500
   
   ## Testing
   - Ran ffxiv_idarename.py successfully in Ghidra
   - Verified all addresses in game version 2026.02.20.0000.0000
   - Cross-referenced function calls to confirm behavior
   
   ## Signatures (if applicable)
   UpdatePartyMemberInfo: `E8 ?? ?? ?? ?? 48 8B 48 18 E8 ?? ?? ?? ??`
   
   ## Notes
   - UpdatePartyMemberInfo is called when party composition changes
   - RefreshPartyList is triggered on zone change and party updates
   
5. Submit the pull request

​

Review Process

​

What to Expect

• Review time: Usually within a few days to a week
• Feedback: Maintainers may request changes or clarifications
• Testing: Others may verify your findings on their setups
• Iteration: Be prepared to make adjustments

​

Common Review Feedback

• Maintainer wants confirmation for a specific version
• Re-check the address and confirm

• Address or name already in use
• Investigate and resolve the conflict

• Include comments explaining what the function does
• Add parameter information if known

• Important function that should have a signature
• Use SigScanner or sigmaker to create one

​

Responding to Feedback

1. Make requested changes:
   # Edit files
   git add ida/data.yml
   git commit -m "Address review feedback: add parameter documentation"
   git push origin feature/addon-partylist
   
2. Reply to comments on GitHub to explain your changes
3. Be patient and collaborative - reviews help ensure quality

​

Best Practices

​

Quality Over Quantity

• One well-documented class is better than ten half-researched ones
• Verify addresses thoroughly before submitting
• Add comments to explain non-obvious findings
• Test changes in your disassembler first

​

Stay Organized

• One pull request per feature when possible
• Group related changes (e.g., all UI::Agent classes together)
• Keep commits atomic (one logical change per commit)
• Update version only once per PR

​

Documentation

• Comment tricky findings in data.yml
• Explain your methodology in the PR description
• Link to related structures when relevant
• Note uncertainties if you’re not 100% sure

​

Communication

• Ask questions if you’re unsure about something
• Join discussions on existing PRs to learn
• Share knowledge about your research process
• Be respectful of others’ work and feedback

​

Common Contribution Scenarios

​

Scenario 1: Found a New Addon Class

1. Identify the class name (from strings or context)
2. Find its vtable address (from constructor)
3. Determine base class (compare vtable layout)
4. Name visible virtual functions (especially Update/Draw)
5. Find constructor and key member functions
6. Add to data.yml and submit PR

​

Scenario 2: Named Virtual Functions in Existing Class

1. Find the class definition in data.yml
2. Add your vfunc discoveries:
   ExistingClass:
     # ... existing content ...
     vfuncs:
       0: dtor  # Already documented
       1: Initialize  # Already documented
       2: ProcessInput  # Your discovery
       3: UpdateState   # Your discovery
   
3. Submit PR with explanations of what each function does

​

Scenario 3: Found Global Variables

1. Identify the variable’s purpose
2. Determine its type if possible
3. Add to globals section:
   globals:
     0x1429D8ABC: g_Client::UI::CurrentFocusedAddon  # Pointer to currently focused UI window
     0x1429D8AC4: g_Client::UI::KeyboardInputEnabled  # bool
   
4. Submit PR

​

Scenario 4: Fixed Incorrect Data

1. Document the error (wrong address, wrong name, etc.)
2. Provide correct information
3. Explain how you verified the fix:
   ## Fix Framework.GetUIModule address
   
   The previous address 0x140091FA0 is incorrect.
   Correct address is 0x140092120.
   
   Verified by:
   - Checking xrefs from multiple UI addon constructors
   - Confirming return type matches UIModule vtable
   - Testing signature still works with new address
   

​

Scenario 5: Updated for New Patch

1. Compare old and new game versions
2. Use version tracking tools if available
3. Update changed addresses:
   # Updated for patch 2026.02.20
   functions:
     0x140092120: GetUIModule  # Was 0x140091FA0 in previous patch
   
4. Update version field
5. Submit PR noting which addresses changed

​

Advanced Topics

​

Working with RTTI Data

Vftable,Methods,Flags,Type,Hierarchy
40CFDA44,8,,DropTarget,"DropTarget: ComBase<IDropTarget,..."

• Validate class hierarchies against old builds
• Find historical names for classes
• Understand inheritance relationships

​

Cross-Referencing with Lumina

1. Check sheet definitions in Lumina
2. Match sheet indices to names
3. Document getter functions accordingly

functions:
  0x14080D050: GetEventItemName  # Sheet index 0x15 = EventItem
  0x14080D1E0: GetItemIcon        # Sheet index 0x0D = Item

​

Using Version Control History

# See all changes to data.yml
git log -p ida/data.yml

# Find when an address was added
git log -S "0x1400901D0" ida/data.yml

# See recent contributions
git log --since="1 month ago" ida/data.yml

​

Troubleshooting

​

My PR was closed without merging

• Already documented by someone else
• Incorrect information that couldn’t be verified
• Out of date with current game version
• Doesn’t follow contribution guidelines

​

I found a conflict during git pull

# Update your fork
git fetch upstream
git rebase upstream/main

# Resolve conflicts in data.yml
# Edit file to fix conflicts, then:
git add ida/data.yml
git rebase --continue
git push origin feature/my-branch --force-with-lease

​

Script errors after my changes

1. Syntax error in YAML:
   • Check indentation (use spaces, not tabs)
   • Verify colons and formatting
   • Validate with a YAML linter
2. Invalid address:
   • Ensure 0x prefix on all addresses
   • Check address is in valid range
   • Verify address exists in executable
3. Missing base class:
   • Add placeholder entry for base class
   • Or remove base reference if incorrect
4. Duplicate entry:
   • Search data.yml for existing address/name
   • Resolve conflict or remove duplicate

​

Getting Help

​

Resources

• GitHub Issues: Ask questions about the project
• Pull Request Comments: Get feedback on your contribution
• Discord/Community: Join FFXIV modding communities
• Documentation: Review all RE documentation pages

​

Asking Good Questions

• Be specific: “How do I find vtable addresses?” not “How does this work?”
• Show your work: Share what you’ve tried already
• Provide context: Game version, tool used, error messages
• Include examples: Screenshots or code snippets help

​

Recognition

• Git commit history preserves your authorship
• Pull request discussions show your contributions
• Community recognition from helping advance the project

​

Next Steps

• Review the data.yml format in detail
• Practice with IDA scripts or Ghidra scripts
• Study existing data.yml entries to learn patterns
• Start with small contributions and work your way up
• Join the community and learn from other reverse engineers