PSX Research

docs/usecode-jelyhack-analysis.md

@@ -9,6 +9,23 @@ Current generated pseudocode lives at:
 - `USECODE/EUSECODE_extracted/pseudocode/JELYHACK/slot_01_use.txt`
 - `USECODE/EUSECODE_extracted/pseudocode/JELYH2/slot_01_use.txt`
 
+## Plain-language answer
+
+If you want the short version first:
+
+- `JELYHACK` does not look like the object that contains the real island gameplay script.
+- It looks more like a small anchor object that gives the engine a `referent` identity and a tiny shared `use` stub.
+- When the player uses it, the stub appears to register a generic interaction/info value (`0x0207`) and then immediately exits.
+- The richer gameplay behavior is more likely carried by nearby event-bearing records such as `REE_BOOT`, `SURCAMEW`, or `SFXTRIG`.
+
+So in easy words: `JELYHACK` currently looks less like "the script that does the JELYHACK puzzle" and more like "the map object or anchor that other real trigger objects point at or work beside."
+
+That also answers "what uses it" in the safest current sense:
+
+- the referent/owner side of the runtime uses it as an anchor-like record
+- the player can still `use` it, but that `use` body is tiny and generic
+- the surrounding event-bearing attachment records are the more likely carriers of the actual gameplay logic
+
 ## Direct decompilation result
 
 Current readable decompilation for `JELYHACK::use`:
@@ -38,15 +55,77 @@ Byte-faithful decode of the same body:
 00EE: 50 ret
 ```
 
-The parser still sees bytes after `ret`, but on the current readable pass they are intentionally elided because control has already returned. Those post-`ret` bytes are identical between `JELYHACK` and `JELYH2`, so they do not currently support any class-specific behavioral claim.
+That readable pseudocode is currently hiding one important detail: there is a small trailer after `ret`.
+
+Pentagram's older disassembly shows the body like this:
+
+```text
+Func_1 (Event 1) JELYHACK::use():
+        0001: 5A init 00
+        0003: 5C symbol info offset 001Ch = "JELYHACK"
+        000F: 0B push 0207h
+        0012: 40 push dword [BP+06h]
+        0014: 4C push indirect 02h bytes
+        0016: 77 set info
+        0017: 78 process exclude
+        0018: 5B line number 219 (00DBh)
+        001B: 50 ret
+00: 01 type=69 (i) [BP+00h] (00) 00 referent
+        002A: 7A end
+```
+
+So the extra bytes are not currently best read as hidden live code. The strongest reading is:
+
+- executable body ends at `ret`
+- one post-return debug/local-symbol record follows
+- that record names one slot/argument as `referent`
+- then the body terminates with `0x7A end`
+
+That matters because it argues against the dramatic interpretation that we found a chopped-off second script. Right now the evidence fits "metadata trailer" much better than "cut content."
+
+## What the trailer most likely represents
+
+Current best explanation of the bytes after `ret`:
+
+- they are post-return symbol/debug metadata, not a second reachable instruction stream
+- they preserve the name `referent`, which matches the descriptor-side picture where `JELYHACK` only exposes a `referent` field
+- they reinforce the idea that this class is an anchor/owner record, not a rich event script
+
+In practical terms, the trailer is telling us something like: "this body knows about one meaningful value here, and that value is called `referent`."
+
+That is useful evidence, but it is not new gameplay logic.
+
+## Suggested readable pseudocode form
+
+For human reading, the most honest pseudocode form is probably this:
+
+```text
+function jelyhack_use() /* entry=277 class_id=0x04D3 slot=0x01 */
+{
+    set_info(0x0207, *(arg_06));
+    process_exclude();
+    return;
+
+    /* post-return metadata (not executable):
+         debug_symbol referent [BP+00h] type=0x69
+    */
+}
+```
+
+That presentation keeps the important distinction visible:
+
+- the function really returns where it looks like it returns
+- there is still meaningful trailer data after that return
+- the trailer is metadata, not currently credible as reachable lost code
 
 ## What is directly supported
 
 1. `JELYHACK` is not an active event hub in the same sense as `EVENT`, `NPCTRIG`, or `_BOOT` classes.
 2. Its only non-zero slot is `0x01` (`use`), with `raw_event_entry_word = 0x002A`, `raw_code_offset = 0x00000001`, and body range `0x00D4..0x00FE` (`42` bytes).
-3. The actual readable body before return is tiny: one `set_info(0x0207, *(arg_06))`, one `process_exclude()`, then return.
+3. The actual executable body is tiny: one `set_info(0x0207, *(arg_06))`, one `process_exclude()`, then return.
 4. `JELYH2` is the same script body for practical purposes. The only pre-return differences are the symbol label string and line-number metadata; control flow and active ops are otherwise the same.
-5. `JELYHACK` still exposes only the `referent` field on the descriptor side, which keeps it in the `referent-anchor` category rather than the event-bearing category.
+5. A post-return trailer still preserves `referent` metadata, which lines up with the descriptor-side fact that `JELYHACK` only exposes `referent`.
+6. `JELYHACK` still exposes only the `referent` field on the descriptor side, which keeps it in the `referent-anchor` category rather than the event-bearing category.
 
 ## Comparison against the exported pseudocode corpus
 
@@ -74,6 +153,13 @@ Current safest reading:
 
 The unresolved part is the exact gameplay meaning of `set_info(0x0207, *(arg_06))`. The exported corpus shows this exact pattern in multiple unrelated classes, so `0x0207` currently looks more like a shared UI/message/interaction setup code than a JELYHACK-specific action.
 
+That leads to the simplest current gameplay explanation:
+
+- the object can be "used"
+- the engine records a generic interaction fact about that use
+- the object then gets out of the way
+- anything interesting that happens next probably belongs to a neighboring event-bearing attachment, not to `JELYHACK` itself
+
 ## What it probably does not do
 
 The current evidence argues against several stronger claims:
@@ -81,6 +167,15 @@ The current evidence argues against several stronger claims:
 - It is probably not the main script that drives the JELYHACK gameplay behavior by itself.
 - It is probably not the actual event-bearing payload that reaches the richer runtime opcode lanes recovered around `000d:208b`, `000d:21ed`, and `000d:22bc`.
 - It is probably not a unique script template specialized only for the JELYHACK object.
+- The bytes after `ret` are probably not a hidden reachable second branch or a simple "return was moved upward" cut-content remnant.
+
+If this were cut executable content, we would want to see stronger signs such as:
+
+- a branch target that lands in the trailer
+- a sensible opcode stream after `ret`
+- different trailers between `JELYHACK` and `JELYH2` that might hint at divergent behavior
+
+At the moment we have the opposite pattern: a small named metadata record, a clean `end`, and strong similarity across the twin classes.
 
 ## Relationship to JELYH2 and the surrounding island
 
@@ -120,6 +215,7 @@ The decompiled `JELYHACK::use` body is important mainly because it supports a ne
 
 - `JELYHACK` is not hiding a large active event script in its only live slot
 - its visible `use` handler is a minimal generic stub shared with several other classes
+- the bytes after `ret` look like a metadata trailer naming `referent`, not like secret live code
 - the interesting gameplay semantics around the JELYHACK island are still more likely to live in neighboring event-bearing descriptors attached to the same referent context
 
 So the current best human-readable model remains: