Transpiler: support complex array index expressions

[Copilot]

HandleLdelemU1 only supported simple array indices (local variable or constant). Complex index expressions like array[(x >> 3) + ((y >> 3) << 4)] threw a TranspileException. This pattern is common in NES tile map lookups.

Changes

• IL2NESWriter.ArrayHandling.cs: Added HandleLdelemU1ComplexIndex() — when the index is not a simple ldloc/ldc, walks backward through IL using stack depth tracking to locate the array instruction, removes dead array-load instructions from the block buffer via Block.RemoveAt, strips any state-dependent JSR pusha/pushax left by ROM array loads, then emits TAX + LDA array,X.
• Simplified constant index detection by replacing the inline switch with the existing GetLdcValue() helper.
• RoslynTests.cs: Two new tests — ComplexArrayIndexExpression (full (x >> 3) + ((y >> 3) << 4) pattern) and SimpleShiftArrayIndex (x >> 3) — verifying LSR, ASL, CLC, TAX, and LDA absolute,X opcodes in output.

Example

Previously required a workaround:

byte idx = (byte)((x >> 3) + ((y >> 3) << 4));
byte result = collision_top_left[idx];

Now works directly:

byte result = collision_top_left[(byte)((x >> 3) + ((y >> 3) << 4))];

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Transpiler: support complex array index expressions</issue_title>
<issue_description>Follow-up from PR #211 (crypto.c sample port).

The transpiler currently only supports simple array index expressions where the index is a local variable or constant. Complex expressions like:

collision_top_left[(x >> 3) + ((y >> 3) << 4)]

fail with: Array element access requires the index to be a local variable or constant. Complex index expressions are not supported.

This pattern is common in NES games for tile map lookups. The C code equivalent is straightforward array indexing that the 6502 handles with indexed addressing modes.

Workaround

Compute the index into a temp variable first:

byte idx = (byte)((x >> 3) + ((y >> 3) << 4));
byte result = collision_top_left[idx];

Implementation

The HandleLdelemU1 method in IL2NESWriter.ArrayHandling.cs needs to handle more complex IL patterns before the ldelem.u1 instruction, such as shift/add/sub operations on the index.
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Transpiler: support complex array index expressions #225

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[jonathanpeppers]

🤖 Code review complete — approving.

What I checked:

• Stack depth walk-back in HandleLdelemU1ComplexIndex correctly locates the array instruction by tracking net IL stack contributions backward from ldelem.u1
• Block buffer removal logic properly cleans up dead array-load instructions (including JSR pusha/pushax for ROM arrays), following the same pattern as HandleStelemI1
• State flags (_runtimeValueInA, _savedRuntimeToTemp, _immediateInA, _lastLoadedLocalIndex) are all correctly set/cleared after emission
• GetLdcValue refactor is a clean simplification
• Conv_u1/Conv_i1-family opcodes correctly treated as net-zero in the depth tracker
• Both new tests pass and follow existing RoslynTests hex-assertion conventions

Ran locally: All 509 tests pass (445 dotnes.tests + 64 analyzer tests).

Looks good to merge.

[jonathanpeppers]

🤖 CI is green. All 509 tests pass locally. Ready for human review.

[Copilot]

Pull request overview

This PR extends the IL→6502 transpiler to support ldelem.u1 when the array index is produced by a non-trivial expression (e.g., shifts/adds), which is a common pattern for NES tilemap lookups.

Changes:

• Added HandleLdelemU1ComplexIndex() to locate the array load via backward IL stack-depth scanning and emit TAX + LDA array,X.
• Simplified constant-index detection by using the existing GetLdcValue() helper.
• Added two Roslyn-based tests intended to validate opcode patterns for complex and shift-only index expressions.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/dotnes.tasks/Utilities/IL2NESWriter.ArrayHandling.cs	Adds complex-index support for ldelem.u1 and refactors constant index detection.
src/dotnes.tests/RoslynTests.cs	Adds tests for complex array index emission patterns.