From 745e6e18b5c5348c047bbba316de9ba65ae64c84 Mon Sep 17 00:00:00 2001 From: gamer147 Date: Mon, 20 Jul 2026 16:51:30 -0400 Subject: [PATCH] Document opcode 0x1fe current rotation --- docs/engine-re.md | 8 ++++++++ docs/opcode-reference.md | 9 +++++---- docs/phase-a-slice-plan.md | 20 ++++++++++++++++++++ tools/age_opcodes_himegari.py | 1 + vm-map/opcodes.toml | 22 +++++++++++----------- 5 files changed, 45 insertions(+), 15 deletions(-) diff --git a/docs/engine-re.md b/docs/engine-re.md index 7602445..f8216b5 100644 --- a/docs/engine-re.md +++ b/docs/engine-re.md @@ -493,6 +493,14 @@ independent matrix channels, not two encodings of one vec3 property. - `0x220` passes raw operands 4–6 to `gfx_object_set_translation_channel` (`0x47ecc0`), stores timing at `obj+0x44/+0x58`, and calls `0x48afb1`, which writes them into matrix entries 12–14 at `obj+0x1ac`: a **translation matrix**. +- `0x1fe(handle, axis_x, axis_y, axis_z, angle_degrees)` is the immediate-current rotation setter. + `op_0x1fe_set_rotation_current` (`0x422700`) converts operands 2–5 to floats and calls + `gfx_object_set_rotation_current` (`0x47e720`). The worker stores current axis at + `obj+0x1ec..0x1f4`, current angle in degrees at `obj+0x204`, converts the angle to radians, writes the + current axis-angle matrix at `obj+0xec`, marks transform state at `obj+0x68`, and raises retained-gfx + redraw dirty at manager `+0xb558` (`EngineCtx+0x51b6c`). It is the direct-current companion to + `0x21f`, not another timed channel. Of 187 corpus calls, 186 use Z axis `(0,0,1)`; the lone DEBUG call + uses Y axis `(0,1,0)`. SC0010 uses immediate `5`, `-5`, and `0` degree Z rotations in a wobble setup. - `0x21f` converts operands 4–7 to floats and calls `gfx_object_set_rotation_channel` (`0x47eb70`). It stores delay/duration at `obj+0x40/+0x54`, target axis at `obj+0x1f8..0x200`, target angle (degrees) at `obj+0x208`, and the target axis-angle matrix at `obj+0x12c`. Current axis/angle are diff --git a/docs/opcode-reference.md b/docs/opcode-reference.md index 03a197c..2165cac 100644 --- a/docs/opcode-reference.md +++ b/docs/opcode-reference.md @@ -371,6 +371,11 @@ The handler clears the map embedded at retained-gfx owner+0x408, resets its coun - **grounding:** source=investigation, confidence=high - **evidence:** Ghidra /v2: handler gfx_op_0x1fd_set_vec_scaled@0x422650 fetches operands 2..4, divides each by the 100.0 constant, and calls gfx_object_set_scale_current@0x47e6b0. The worker gets/creates the object, marks obj+0x68, and calls matrix4_make_scale on obj+0x6c. SC0000 sets AE001D handles to 210/210/100 and 240/240/100; without this setter their 800x800 alpha circles remain below the viewport. Both functions annotated and /v2 saved 2026-07-11. +### 0x1fe `set-current-rotation-axis-angle` (u004206C0, argc 5) +- **summary:** (handle)(axis_x)(axis_y)(axis_z)(angle_degrees) — immediately replace the retained object's current axis-angle rotation matrix. This is the direct-current companion to op 0x21f's delayed one-shot rotation target. +- **grounding:** source=investigation, confidence=high +- **evidence:** Ghidra /v2: op_0x1fe_set_rotation_current@0x422700 converts operands 2..5 to float and calls gfx_object_set_rotation_current@0x47e720. The worker gets/creates the handle, marks transform state at obj+0x68, stores current axis obj+0x1ec..0x1f4 and angle degrees obj+0x204, converts degrees to radians with pi/180, builds the current matrix at obj+0xec through matrix4_make_axis_angle, and sets retained-gfx redraw dirty owner+0xb558 (EngineCtx+0x51b6c). The finite-channel consumer composes this current matrix between scale and translation. Corpus: 186/187 calls use Z axis (0,0,1); the lone DEBUG call uses Y axis (0,1,0). + ### 0x1ff `set-current-translation` (set-gfx-geom3-c, argc 4) - **summary:** 0x1ff (handle)(x)(y)(z) — immediately replace the retained object's current translation matrix at obj+0x16c. This is the direct-current companion to 0x220's delayed target at obj+0x1ac. - **grounding:** source=investigation, confidence=high @@ -1130,10 +1135,6 @@ op 0x90 (u0041BEB0, argc 7): `0x90 x y w h tgt_a tgt_b tgt_c`. Kelebek left it " - **summary:** — - **grounding:** source=kelebek, confidence=med -### 0x1fe `u004206C0` (u004206C0, argc 5) -- **summary:** — -- **grounding:** source=kelebek, confidence=low - ### 0x205 `u00420A60` (u00420A60, argc 6) - **summary:** — - **grounding:** source=kelebek, confidence=low diff --git a/docs/phase-a-slice-plan.md b/docs/phase-a-slice-plan.md index 6faa4fa..ef30bc7 100644 --- a/docs/phase-a-slice-plan.md +++ b/docs/phase-a-slice-plan.md @@ -2132,3 +2132,23 @@ normal-path no-ops for `0xae` or a transient-only `ReadTextSkip` setting. Validation: 213 engine tests pass; opcode and EngineCtx generators/tests/lints, SC0000 coverage, vm0 RECOVER, the zero-warning Godot build, threaded self-test, and `git diff --check` are clean. + +### Slice A2b opcode `0x1fe` immediate rotation classified (2026-07-20) + +Native RE resolves `0x1fe(handle, axis_x, axis_y, axis_z, angle_degrees)` as the retained-object +immediate-current axis-angle rotation setter. The handler converts its four numeric operands to floats; +the worker stores the current axis and degree angle, rebuilds the current rotation matrix, and raises the +ordinary retained-gfx redraw flag. It neither creates a timed transition nor writes `0x21f`'s target +fields: it is rotation's direct-current companion to the implemented `0x1fd` current-scale setter. + +Corpus use reinforces the decode: 186 of 187 calls use Z axis `(0,0,1)`, with only a DEBUG call using Y +axis `(0,1,0)`. SC0010's five sites include immediate `5`, `-5`, and `0` degree Z rotations in a wobble +sequence; SC0020 and SC0030 add six and three sites respectively. The port already retains +`RotationCurrent` and composes it in native matrix order, so implementation should be a narrow generic +`GfxState` current-rotation setter plus VM dispatch and focused tests. No runtime implementation is claimed +by this investigation. + +**Next:** implement `0x1fe` through the existing retained-transform model. It requires no new host API, +storage backend, seed, or script-specific behavior. + +Validation: opcode source regenerated; opcode tests/lint and `git diff --check` are clean. diff --git a/tools/age_opcodes_himegari.py b/tools/age_opcodes_himegari.py index 515d420..3bf999f 100644 --- a/tools/age_opcodes_himegari.py +++ b/tools/age_opcodes_himegari.py @@ -53,6 +53,7 @@ INFERRED: dict[int, dict] = { 0x1f4: dict(name='stmt-begin', category='marker', noop=True, confidence='high', source='investigation', summary='zero-arg; opens scripts, pairs with stmt-end 0x1f5'), 0x1f5: dict(name='stmt-end', category='marker', noop=True, confidence='high', source='investigation', summary='zero-arg; precedes exit/next-stmt, pairs with 0x1f4'), 0x1fd: dict(name='gfx-set-scale-current', category='draw', noop=False, confidence='high', source='investigation', summary="(handle)(scale_x_percent)(scale_y_percent)(scale_z_percent) — immediately replace the retained object's current scale matrix at obj+0x6c. The handler divides each integer operand by 100.0 before calling matrix4_make_scale; this is distinct from 0x21e's delayed one-shot target scale."), + 0x1fe: dict(name='set-current-rotation-axis-angle', category='draw', noop=False, confidence='high', source='investigation', summary="(handle)(axis_x)(axis_y)(axis_z)(angle_degrees) — immediately replace the retained object's current axis-angle rotation matrix. This is the direct-current companion to op 0x21f's delayed one-shot rotation target."), 0x1ff: dict(name='set-current-translation', category='draw', noop=False, confidence='high', source='investigation', summary="0x1ff (handle)(x)(y)(z) — immediately replace the retained object's current translation matrix at obj+0x16c. This is the direct-current companion to 0x220's delayed target at obj+0x1ac."), 0x20a: dict(name='publish-adv-text-layout', category='adv', noop=False, confidence='high', source='investigation', summary='(layout_slot) - republish one ADV text layout and, while active, its current wait-indicator frame.'), 0x21b: dict(name='line-id?', category='marker', noop=True, confidence='med', source='harness', summary='1 imm; mov->0x21b->stmt-end; near save/load-messkip — likely line/stmt id, verify not msg-control'), diff --git a/vm-map/opcodes.toml b/vm-map/opcodes.toml index 23f75cf..528f7f7 100644 --- a/vm-map/opcodes.toml +++ b/vm-map/opcodes.toml @@ -4723,38 +4723,38 @@ argc = 5 abi_source = "kelebek+decode-validated" [opcode.semantics] -name = "u004206C0" -category = "unknown" -summary = "" +name = "set-current-rotation-axis-angle" +category = "draw" +summary = "(handle)(axis_x)(axis_y)(axis_z)(angle_degrees) — immediately replace the retained object's current axis-angle rotation matrix. This is the direct-current companion to op 0x21f's delayed one-shot rotation target." noop_headless = false -source = "kelebek" -confidence = "low" +source = "investigation" +confidence = "high" depends_on = [] -evidence = "" +evidence = "Ghidra /v2: op_0x1fe_set_rotation_current@0x422700 converts operands 2..5 to float and calls gfx_object_set_rotation_current@0x47e720. The worker gets/creates the handle, marks transform state at obj+0x68, stores current axis obj+0x1ec..0x1f4 and angle degrees obj+0x204, converts degrees to radians with pi/180, builds the current matrix at obj+0xec through matrix4_make_axis_angle, and sets retained-gfx redraw dirty owner+0xb558 (EngineCtx+0x51b6c). The finite-channel consumer composes this current matrix between scale and translation. Corpus: 186/187 calls use Z axis (0,0,1); the lone DEBUG call uses Y axis (0,1,0)." [[opcode.semantics.args]] i = 1 -role = "" +role = "object handle" observed_types = ["imm", "g-int", "l-int"] [[opcode.semantics.args]] i = 2 -role = "" +role = "rotation axis X" observed_types = ["imm"] [[opcode.semantics.args]] i = 3 -role = "" +role = "rotation axis Y" observed_types = ["imm"] [[opcode.semantics.args]] i = 4 -role = "" +role = "rotation axis Z" observed_types = ["imm"] [[opcode.semantics.args]] i = 5 -role = "" +role = "angle degrees" observed_types = ["imm", "l-int"] [[opcode]]