goldeneye-pc-port/docs/HANDOFF-ai-xmacro.md

> **RESOLVED — historical.** D7 closed at the compile+link milestone.
> Kept for the AI X-macro analysis. Not active work.

# HANDOFF — AI X-macro system (D7), the last build blocker

## Status

Full `ge007` build: **224 objects compile; only `chraidata.c` fails.** All other
`.c` files build clean. Findings D1–D6 are resolved and recorded in
`docs/PCPortResearch.md` §11. D7 (this file) is the remaining blocker.

Build command:
```sh
export PATH="/c/msys64/mingw64/bin:$PATH"
cd build-pc && cmake --build . --target ge007 2>&1 | grep -A3 -i "chraidata\|aicommands\|bondaicommands"
```

## The failing file and its includes

`src/game/chraidata.c` includes (lines 14–17):
```c
#include <ultra64.h>
#include <bondgame.h>
#include <bondaicommands.h>   // <- pulls in the whole AI X-macro system
#include "chrobjdata.h"
```

`bondaicommands.h` includes:
- `bondconstants.h` (which at line 17 includes `<CPPLib.h>`, and at line 731
  includes `"aicommands.def"` to build the `AI_CMD` enum)
- `aicommands2.h` (line 864) — a **pre-generated** header (from
  `tools/cmdbuilder.c`), already preprocessed.

So the failing path is the **raw** `aicommands.def` include (bondconstants.h:731)
plus the `bondaicommands.h` macros (`isSubroutine`, `SWITCH`, `CALL`, …) that
chraidata.c uses directly.

## Exact error chain (verified by rebuild)

Trigger: `CALL(GAILIST_PLAY_IDLE_ANIMATION)` at chraidata.c:114 (and similar at
123, 126, …). The chain:

1. `CALL(...)` expands to code that calls `isSubroutine(<ID>)`.
2. `isSubroutine(ID)` (bondaicommands.h:275–284) contains:
   ```c
   #define isSubroutine(ID) ((ID == GAILIST_PLAY_IDLE_ANIMATION) |\
                               (ID == GAILIST_BASH_KEYBOARD) | \
                               (ID == GAILIST_ATTACK_BOND) | \
                               (ID == GAILIST_RUN_TO_BOND) | \
                               (ID == GAILIST_STARTLE_AND_RUN_TO_BOND) | \
                               (ID == GAILIST_WAIT_ONE_SECOND) \
                               IF(NOT(DEFINED(SETUPSUBROUTINES(ID))))\
                               (\
                                   | SETUPSUBROUTINES(ID)\
                               ))
   ```
3. `DEFINED(x)` (CPPLib.h:279–280):
   ```c
   #define DEFINED(x) _DEFINED(x)
   #define _DEFINED(x) IS_PROBE(CAT(_DEFINED, _##x##_))
   ```
   With `x = SETUPSUBROUTINES(ID)`, the `##` pasting `_##x##_` tries to paste
   `_` against `SETUPSUBROUTINES(ID)` — a **macro call (multiple tokens)**, not a
   single pp-token. GCC hard-errors:
   ```
   bondaicommands.h:281:63: error: pasting ')' and '_' does not give a valid
   preprocessing token
   ```
4. CPPLib.h:287 has a special case that was *meant* to handle this:
   ```c
   #define _DEFINED_SETUPSUBROUTINES(ID) PROBE(~),
   ```
   i.e. the intent is that `_##SETUPSUBROUTINES(ID)##_` →
   `_DEFINED_SETUPSUBROUTINES(ID)_` → the defined macro above. But GCC's `##`
   requires each side to be a single pp-token, so it never reaches that special
   case. IDO's preprocessor evidently tolerated / expanded this differently.

### Secondary errors (same root family)

- `chraidata.c:183/202/249/640`: `macro 'SWITCH' requires 49 arguments, but only
  20/14/26/26 given`. The `SWITCH` macro (bondaicommands.h, ~line 776) has **49
  fixed parameters** (1 VAR + 16×3 case slots) and uses `IF_VA(NOT(IS_EMPTY(..)))`
  to detect which cases are present. Game code calls it with fewer args, relying
  on IDO leniency. GCC enforces the exact arg count.
- `aicommands.def:514:270 / 550:21 / 2846:21`: "expected expression before ','"
  / "expected '}' before 'AI_Return'" / "expected '}' before
  'AI_IFICouldSeeBond'". These are downstream of the `isSubroutine`/`DEFINED`
  failure (the `CALL` expansion aborts mid-macro, leaving dangling tokens). Note
  the reported line numbers (514/550/2846) do **not** match the raw
  `aicommands.def` lines (those are comment/brace lines) — they are positions in
  the *expanded* macro text, not the source file. Don't chase them as source
  lines.

## Key facts / ground truth

- `aicommands.def` call counts: **255** `_AI_CMD(`, **119** `_AI_CMD_POLYMORPH(`,
  **2** `_AI_DEBUG(`.
- `_AI_CMD_POLYMORPH` definitions across the tree:
  - `aicommands.def:97` — 4-arg `(PRE, NAME, CMD_PARAMS_POST, POLY_PARAMS)` but
    inside a `#if 0` block (lines 88–100) → **inactive**.
  - `bondconstants.h:721` — 5-arg `(CMD, A, P, Q, D)` under `#ifdef __sgi`
    (not us).
  - `bondconstants.h:726` — **variadic `(...)`** under `#else` (this is the one
    active for GCC when building the `AI_CMD` enum at bondconstants.h:731).
  - `chrai.c:170` — 5-arg `(CMD, A, P, Q, D)`.
  - `chrai.c:915` — 5-arg `(C, N, P1, P2, D)`.
- `aicommands.def:85–87`: `#ifndef __GNUC__ #include <CPPLib.h> #endif` → for GCC
  CPPLib.h is **not** included from aicommands.def itself; it comes in via
  `bondconstants.h:17`.
- `aicommands.def:11888`: `#undef _AI_CMD_POLYMORPH` (late in the file).
- `aicommands2.h` is pre-generated (header says "Do not edit … generated by
  cmdbuilder from src/aicommands.def"). It is included by bondaicommands.h:864
  and deb_loadallmodels.c:8. It is **not** the failing path.
- `isSubroutine` is the only macro that feeds a *macro call*
  (`SETUPSUBROUTINES(ID)`) into `DEFINED()`. That is the unique trigger for the
  `##` pasting error.

## Recommended next steps (in order)

1. **Fix the `DEFINED(SETUPSUBROUTINES(ID))` pasting** — the single root cause of
   the `CALL`/`isSubroutine` errors. Preferred: a `port/` shim that redefines
   `DEFINED` (or `_DEFINED`) *after* CPPLib.h is included, special-casing the
   `SETUPSUBROUTINES(ID)` argument so it does not `##`-paste a multi-token
   macro-call. Sketch:
   ```c
   /* port/shim/... after <CPPLib.h> */
   #undef DEFINED
   #define DEFINED(x) _PORT_DEFINED(x)
   #define _PORT_DEFINED(x) /* if x is SETUPSUBROUTINES(ID) -> PROBE(~), else fall back */
   ```
   The tricky part: detecting "x is exactly `SETUPSUBROUTINES(ID)`" in the
   preprocessor. Alternative: redefine `isSubroutine` in the shim to compute the
   `SETUPSUBROUTINES` presence without `DEFINED()` (e.g. via a per-setup
   `#define HAS_SETUPSUBROUTINES 0/1` flag set before the include). Investigate
   which is less invasive before committing.
   - Constraint: `bondaicommands.h` and `CPPLib.h` are game files — do **not**
     edit them. All fixes go in `port/` (shim headers found first via include
     path) or, if truly unavoidable, a `-DPORT`-gated `src/` change with a
     `PC port:` comment.
2. **Fix the `SWITCH` 49-arg requirement** — make a shim `SWITCH` variadic (or
   pad the call sites). Verify the `IF_VA`/`IS_EMPTY` case-detection still works
   under GCC once variadic.
3. **Re-verify the aicommands.def:514/550/2846 errors disappear** once (1) and
   (2) are in — they are likely downstream of the `CALL` expansion abort, not
   independent bugs.
4. **Rebuild** and confirm `chraidata.c` compiles → full `ge007` links.
5. **Record the resolution** in `docs/PCPortResearch.md` §11 D7 (replace the
   "OPEN" / "TBD" text) and delete this handoff file.

## Do NOT

- Do not edit `tools/`, `Makefile`, `rsp/`, `ld/` (N64 build, non-negotiable).
- Do not edit `bondaicommands.h`, `bondconstants.h`, `CPPLib.h`,
  `aicommands.def`, `aicommands2.h` unless a `-DPORT`-gated, layout/semantics-
  preserving change is truly unavoidable (and then flag it `PC port:`).
- Do not chase the aicommands.def:514/550/2846 line numbers as source lines
  (they are expanded-macro positions).