BinaryExporter fails when serializing multiple UserData objects containing lists

[riccardobl]

I was playing around with @copilot and it says it found this issue: #2607 (comment)

Reporting here for tracking, but i haven't validated it yet.

---

When a Spatial has multiple UserData entries containing lists (e.g., "int-list", "string-list", "float-list"), the BinaryExporter/BinaryImporter fails to deserialize correctly. The first list in the userData HashMap deserializes successfully, but subsequent lists return null and cause an ArrayIndexOutOfBoundsException during deserialization.

Steps to reproduce:

1. Set testLists=true in jme3-plugins/src/test/java/com/jme3/export/JmeExporterTest.java (line 142)
2. Run ./gradlew :jme3-plugins:test --tests "com.jme3.export.JmeExporterTest"
3. Observe that BinaryImporter (Node 1) returns null for int-list and string-list, while float-list works (being first in iteration order)

Error:

java.lang.ArrayIndexOutOfBoundsException: Index -3 out of bounds for length 4
    at com.jme3.export.binary.ByteUtils.rightAlignBytes(ByteUtils.java:554)
    at com.jme3.export.binary.BinaryInputCapsule.readInt(BinaryInputCapsule.java:834)
    at com.jme3.export.binary.BinaryInputCapsule.setContent(BinaryInputCapsule.java:154)

Notes:

• XMLExporter/XMLImporter works correctly with all lists
• Only affects BinaryExporter when multiple UserData objects with lists exist
• Appears to be a byte stream alignment issue in the binary format

[coderabbitai]

Coding Plan

Summary

• The root cause is a missing index backup in readLong() that exists in readInt(), causing byte stream misalignment
• When inflateFrom() encounters NULL_OBJECT (-1) or DEFAULT_OBJECT (-2), it reads 1 byte but returns a 4-byte array for processing compatibility
• readInt() correctly backs up the index by 4 to account for this; readLong() does not, causing subsequent reads to start at wrong positions
• The fix adds the same index compensation to readLong(), restoring correct stream alignment

Implementation Steps

Phase 1: Fix Byte Stream Index Management in BinaryInputCapsule

This phase addresses the root cause: the readLong() method advances the byte stream index incorrectly for special sentinel values, causing misalignment that corrupts subsequent reads.

Add Index Backup Logic to readLong()

Add the missing index backup behavior to readLong() that mirrors the existing pattern in readInt().

• Update jme3-core/src/plugins/java/com/jme3/export/binary/BinaryInputCapsule.java in the readLong() method (around lines 925-931)
• After computing the long value from bytes, check if it equals NULL_OBJECT or DEFAULT_OBJECT
• If so, back up the index by 4 positions to compensate for inflateFrom() returning a 4-byte array when only 1 byte was consumed from the stream
• This mirrors the exact pattern already used in readInt() at lines 836-838

🤖 Prompt for AI agents

Fix the byte stream index management in the `readLong()` method to prevent
stream misalignment when deserializing special sentinel values.

In `jme3-core/src/plugins/java/com/jme3/export/binary/BinaryInputCapsule.java`:
- Locate the `readLong()` method (around lines 925-931)
- After the long value is computed from the byte array, add a check to determine
if the value equals `NULL_OBJECT` (-1) or `DEFAULT_OBJECT` (-2)
- If the value matches either sentinel, back up the index by 4 positions to
compensate for the fact that `inflateFrom()` returns a 4-byte array even though
only 1 byte was consumed from the stream
- Use the same pattern that already exists in the `readInt()` method at lines
836-838 as a reference

This ensures that subsequent reads start at the correct position in the byte
stream, preventing the `ArrayIndexOutOfBoundsException` that occurs when
multiple UserData objects with lists are deserialized.

Phase 2: Verification

Verify the fix resolves the issue by enabling and running the previously-disabled test case.

Enable List Serialization Test

Enable the existing test case to verify multiple UserData lists serialize and deserialize correctly.

• Update jme3-plugins/src/test/java/com/jme3/export/JmeExporterTest.java at line 142
• Change testLists = false to testLists = true
• Run the test to confirm both BinaryExporter and XMLExporter correctly handle multiple list UserData entries

🤖 Prompt for AI agents

Enable the previously-disabled test case to verify that the fix correctly
handles serialization and deserialization of multiple UserData objects
containing lists.

In `jme3-plugins/src/test/java/com/jme3/export/JmeExporterTest.java`:
- Locate line 142 where `testLists = false` is set
- Change the value from `false` to `true`

This will enable the test that verifies both BinaryExporter and XMLExporter can
correctly handle multiple list UserData entries without throwing an
`ArrayIndexOutOfBoundsException`.

Research

The jMonkeyEngine binary serialization system uses BinaryInputCapsule and BinaryOutputCapsule for reading/writing objects. Integer and long values are compressed using deflate()/inflateFrom() methods that store variable-length byte representations. Special sentinel values (NULL_OBJECT = -1, DEFAULT_OBJECT = -2) are stored as single bytes but expanded to 4-byte arrays during deserialization. The readInt() method correctly compensates for this expansion by backing up the stream index, but readLong() is missing this critical adjustment, causing stream misalignment when multiple objects are deserialized.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Fix the byte stream index management in the `readLong()` method to prevent
stream misalignment when deserializing special sentinel values.

In `jme3-core/src/plugins/java/com/jme3/export/binary/BinaryInputCapsule.java`:
- Locate the `readLong()` method (around lines 925-931)
- After the long value is computed from the byte array, add a check to determine
if the value equals `NULL_OBJECT` (-1) or `DEFAULT_OBJECT` (-2)
- If the value matches either sentinel, back up the index by 4 positions to
compensate for the fact that `inflateFrom()` returns a 4-byte array even though
only 1 byte was consumed from the stream
- Use the same pattern that already exists in the `readInt()` method at lines
836-838 as a reference

This ensures that subsequent reads start at the correct position in the byte
stream, preventing the `ArrayIndexOutOfBoundsException` that occurs when
multiple UserData objects with lists are deserialized.
===============================================================================

Task: 2

Enable the previously-disabled test case to verify that the fix correctly
handles serialization and deserialization of multiple UserData objects
containing lists.

In `jme3-plugins/src/test/java/com/jme3/export/JmeExporterTest.java`:
- Locate line 142 where `testLists = false` is set
- Change the value from `false` to `true`

This will enable the test that verifies both BinaryExporter and XMLExporter can
correctly handle multiple list UserData entries without throwing an
`ArrayIndexOutOfBoundsException`.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!