Melee Build Fixup

You are an expert at fixing build issues in the Melee decompilation project. This skill focuses on resolving compilation errors AFTER a function has been matched to its assembly - the matching work is done, but the build is broken.

When to Use This Skill

Use /decomp-fixup when:

• A matched function causes build failures
• Headers have UNK_RET/UNK_PARAMS that need real signatures
• Callers need updates after signature changes
• Struct definitions are causing type errors
• Build is failing due to missing prototypes

Use /decomp instead when:

• You need to match assembly (get 100% match)
• You're starting fresh on a function

Finding Functions That Need Fixes

# Check state for functions that may need build fixes
melee-agent state status

# Look for functions in "committed" state that may have broken builds
# Or check functions with known issues
melee-agent state status <function_name>

Diagnosing Build Errors

Step 1: Run the Build

cd <worktree> && python configure.py && ninja

The build requires function prototypes by default (same as CI). Common error types:

Error Pattern	Cause	Solution
implicit declaration of function	Missing prototype	Add to header
conflicting types for 'func'	Header/impl mismatch	Fix header signature
too few arguments to function	Signature changed	Update callers
too many arguments to function	Signature changed	Update callers
incompatible pointer type	Type mismatch	Fix types
unknown type name	Missing include/typedef	Add include

Step 2: Locate the Header

Function headers are typically in:

melee/include/melee/<module>/forward.h   # Forward declarations
melee/include/melee/<module>/<file>.h    # Full declarations

Example paths:

• ft_* functions: melee/include/melee/ft/forward.h or melee/include/melee/ft/ftcommon.h
• lb* functions: melee/include/melee/lb/forward.h
• gr* functions: melee/include/melee/gr/forward.h

Step 3: Find Callers

When you change a function's signature, find and fix all callers:

grep -r "function_name" <worktree>/src/melee/
grep -r "function_name" <worktree>/include/melee/

Common Fixes

Fix 1: Header Signature Mismatch

Problem: Header has stub declaration, implementation has real signature.

// Before (in header - stub declaration):
/* 0D7268 */ UNK_RET ftCo_800D7268(UNK_PARAMS);

// After (matches implementation):
/* 0D7268 */ void ftCo_800D7268(Fighter* fp, s32 arg1);

Steps:

1. Find the implementation in src/melee/
2. Copy the exact signature
3. Update the header declaration
4. Keep the /* address */ comment if present

Fix 2: UNK_RET to Real Return Type

// Before:
UNK_RET func(s32 x);

// After (if implementation returns void):
void func(s32 x);

// After (if implementation returns a value):
s32 func(s32 x);

Note: M2C_UNK can be used as a placeholder return type when the actual type is still being determined.

Fix 3: UNK_PARAMS to Real Parameters

// Before:
void func(UNK_PARAMS);

// After (from implementation):
void func(HSD_GObj* gobj, s32 action_id, float frame);

Fix 4: Updating Callers

When a signature changes from void foo(void) to void foo(s32 arg):

// Before (caller):
foo();

// After (caller - must pass argument):
foo(0);  // Or appropriate value based on context

Finding the right argument:

• Check assembly at call sites
• Look at r3/r4/etc register values before bl instruction
• Check if there's a pattern in similar functions

Fix 5: Missing Parameter Names

Headers need parameter names for documentation, but types must match:

// Before (missing names):
void func(s32, float, HSD_GObj*);

// After (with names):
void func(s32 action, float frame, HSD_GObj* gobj);

Fix 6: Struct/Type Issues

If a struct field type is wrong:

// Workaround in code (temporary fix):
#define DMG_X1898(fp) (*(float*)&(fp)->dmg.x1898)

// Better: Fix the struct definition in the header
// Before:
s32 x1898;
// After:
float x1898;

Workflow

Quick Fix (Single Function)

# 1. Check build error
cd <worktree> && ninja 2>&1 | head -50

# 2. Find header location
grep -r "function_name" <worktree>/include/

# 3. Find implementation
grep -r "function_name" <worktree>/src/melee/

# 4. Compare signatures and fix header

# 5. Find and fix callers if signature changed
grep -r "function_name(" <worktree>/src/melee/

# 6. Rebuild and verify
ninja

Batch Fix (Multiple Issues)

# 1. Get full error list
cd <worktree> && python configure.py && ninja 2>&1 | tee build_errors.txt

# 2. Categorize errors
grep "conflicting types" build_errors.txt
grep "implicit declaration" build_errors.txt
grep "too few arguments" build_errors.txt

# 3. Fix in dependency order (headers first, then callers)

Committing Fixes

After fixing build issues:

# Verify build passes
cd <worktree> && python configure.py && ninja

# Commit the fix (in the worktree)
git add -A
git commit -m "Fix build: update <function> signature in header"

Commit message patterns:

• Fix build: update ftCo_800D7268 signature in header
• Fix build: add missing prototype for lbColl_80008440
• Fix build: update callers for gr_800123AB signature change

Checklist Before Committing

1. Build passes
2. No merge conflict markers in files
3. Header signatures match implementations exactly
4. All callers updated if signature changed
5. No UNK_RET/UNK_PARAMS left for functions you've implemented

Common Mistakes

1. Fixing implementation instead of header - If match is 100%, don't touch the .c file
2. Forgetting callers - One signature change can break many files
3. Wrong worktree - Make sure you're in the right subdirectory worktree
4. Partial fixes - Don't commit until ALL errors are resolved
5. Changing matched code - Only fix headers/callers, not the matched implementation

Type Reference

Common types in Melee:

• s8, s16, s32 - signed integers
• u8, u16, u32 - unsigned integers
• f32, f64 - floats
• BOOL - boolean (actually s32)
• HSD_GObj* - game object pointer
• Fighter* - fighter state pointer
• Vec3 - 3D vector struct
• M2C_UNK - unknown type placeholder

What NOT to Do

1. Don't modify matched code - The .c implementation is correct, fix the header
2. Always verify build passes - Prototype requirements are enforced by default
3. Don't leave partial fixes - Fix everything or nothing
4. Don't guess signatures - Check the actual implementation
5. Don't ignore callers - They WILL break if signature changes

Troubleshooting

Issue	Solution
Can't find header	Check include/melee/<module>/forward.h
Multiple declarations	Search all .h files, update all of them
Caller in different worktree	Note the file, fix when you work on that subdirectory
Circular dependency	May need forward declaration
Build still fails after fix	Run ninja -t clean && ninja for full rebuild