Skip to main content

Packet Debugging

PacketTrace is disabled by default and stores a bounded in-memory buffer when enabled through PacketUtilsConfig.tracePackets.

PacketReflection.sendPacket(...) is staged and fail-closed. Failures identify the first failed stage: mapping resolution, node creation, buffer resolution, payload write, or enqueue. A failed stage is returned as PacketSendResult; later stages are not attempted.

RevisionHealthCheck is read-only, but PacketUtils uses its result as a startup gate. It checks the live revision, reflection shapes, every production PacketDef, and the decoded fixed/variable packet length. It never downloads or repairs mappings. A passing result proves only those structural checks in the current process; controlled live packet behavior remains separate evidence.

Packet trace:

PacketTrace.setEnabled(true);
List<PacketTraceEvent> events = PacketTrace.snapshot();
PacketTrace.clear();

Health check:

HealthCheckResult result = RevisionHealthCheck.run();
log.info(result.toSummary());

Important entries include the live client/revision, mapping label, writer/factory/buffer shapes, enqueue and legacy menu dispatch, and one length-validated entry for every mouse, movement, widget, object, NPC, player, ground-item, and dialog packet definition. Deliberately unavailable packets are reported as UNSUPPORTED and do not block otherwise healthy supported mappings.

Revision 239 artifact analysis​

Run the ASM analyzer with the exact injected client:

.\gradlew.bat analyzeRevision239 `
  -PinjectedClientJar=REFERENCE_RESOURCES/injected_clients/rev239/v1.12.32/injected-client-1.12.32.jar `
  --console plain

-PvanillaGamepackJar=<path> is optional and adds vanilla/injected inventory correlation; it does not supply or override injected-client mappings.

The report is written to build/reports/revision239/mapping-report.txt. It records class inventories, separate client-packet storage and packet-node length transforms, packet lengths, control-flow-bounded write sequences, derived byte transforms, operand provenance, client-packet call sites, menu predicates, and script-opcode predicates. Ambiguous write paths fail analysis.

The launcher RuneLite.jar is not either analysis artifact. It contains net.runelite.launcher.Launcher. A modern five-class Jagex bootstrap jar is also not a decrypted vanilla gamepack and cannot provide vanilla-to-injected correlation.

Revision 239 dialog mappings are derived from the client script-opcode handler:

  • 3104 count → jf.cd, length 4, xv.cg(int)
  • 3105 name → jf.bo, variable length, xv.bw(length) + xv.co(string)
  • 3106 string → jf.cq, variable length, xv.bw(length) + xv.co(string)
  • 3115 object → jf.bs, length 2, xv.bd(int)

RuneLite: 1.12.32 (rev239). The supported rev239 catalog uses mapping label 2026-07-08-rev239-11232-release-artifact-derived and injected artifact REFERENCE_RESOURCES/injected_clients/rev239/v1.12.32/injected-client-1.12.32.jar. The client packet length field jf.ez uses storage encoder 1722046599 and decoder 140832055; -213810509 is the separate encoder used when the decoded length is copied into jr.ap.

The artifact pass also corrected the count-dialog byte order, NPC/object target widget-id byte order, and the rev239 IF_BUTTONT, IF_BUTTONX, and IF_SUBOP buffer methods. The sailing SET_HEADING field/byte transform remains unproven. Its production mapping stays blank, health reports it as UNSUPPORTED, and direct sends fail closed rather than enqueueing a guessed packet.

Maintaining mappings for a RuneLite update​

Treat ObfuscatedNames.java and the production packet catalog as outputs of artifact-backed analysis, not constant-pool guesses. For a new revision:

  1. Save the exact released injected-client artifact under REFERENCE_RESOURCES/injected_clients/ and record its provenance.
  2. Run the revision analyzer against that artifact. The current task is analyzeRevision239; a new revision needs an equivalent explicit analysis target rather than silently reusing revision 239 assumptions.
  3. Review mapping-report.txt, update only mappings supported by bytecode and call-site evidence, and leave ambiguous packets unsupported.
  4. Run the revision artifact/parity tests and the normal build.
  5. Perform controlled in-client checks for every changed packet family before declaring the mapping production-ready.

The scheduled update-obfuscated-names.yml workflow is an advisory extraction aid. It does not establish packet transforms or live correctness, and its output must pass the same artifact review and live acceptance process.

Evidence boundaries​

  • Analyzer and artifact tests prove bytecode structure in the supplied artifacts.
  • Unit tests prove staged failure propagation and catalog consistency.
  • A decrypted vanilla gamepack is still required for true vanilla/injected correlation.
  • In-client tests are still required for mouse, movement, widget, object, NPC, player, ground-item, dialog, and sailing behavior.