Reconstruct retail generic effect descriptors

Author: RednibCoding

documentation/exe-analysis.md

@@ -1819,6 +1819,16 @@ judgement, the complete combat packet, the authored delay, and the remaining
 constructor values. The list updater at `0x0042fd60` keeps that node until the
 handler selected by `0x00429ec0` returns zero.
 
+The low raw effect numbers do not enter the specialized controller families.
+Dispatcher `0x00429ec0` sends values `0..7` to generic initializer
+`0x0042a300` with OPTION resources `0,1,2,3,0,0,4,0`. This includes all
+shipped direct-special values `0,1,4,5,6,7`. The normal direct forms use
+30-unit bounds, whereas type six uses `[-160,-160,159,159]` and contact
+visual 21023. They project from the live owner by constructor field 21, carry
+the packet, collide with scenery and the first target, and use contact sample
+20. This makes the raw family a generic runtime actor, not a truncated form
+of effect `10001`.
+
 All twelve nonnegative effect types found in the shipped enemy records have a
 specialized branch. The dispatch covers types 1, 2, 3, 4, 5, 10, 11, 12, 13,
 14, 16, and 21. This is separate from the much simpler 21000-series receiver

reverse/shadowflare-exe/functions.csv

@@ -95,7 +95,7 @@ address,name,reconstructed_symbol,status,evidence,notes
 0x00429ce0,UpdateScenarioEntities,osf::WorldScene::update,partial,static,Every active-map dynamic entity receives its virtual update without a camera or render-clip test; objects PEOPLE enemies and settled items update offscreen in class and local-ID order while complete enemy AI remains
 0x00429dd0,CreateRuntimeEffectActor,osf::RuntimeEffectActor::initialize,partial,static,Creates a category-50000000 actor from a 126-word descriptor after the effect controller has resolved its resource position bounds chart target window packet environment collision policy and lifetime fields; all twelve specialized enemy-effect controller families now have portable actor requests and shipped live coverage
 0x00429ec0,DispatchWorldEffect,osf::CombatEffectActor::initialize / osf::EnemyEffectController::initialize,partial,static,Dispatches 10001 10002 10003 10004 10005 10010 10011 10012 10013 10014 10016 and 10021 to twelve specialized controllers and maps simple effects 21000 through 21014 plus 21019 and Heal visual 21020 to their exact Character OPTION resources; every specialized enemy controller has portable outputs and live shipped coverage
-0x0042a300,InitializeGenericEffectActor,osf::buildGenericEffectActor / osf::RuntimeEffectSystem::queueActor,implemented,static,Maps generic effects zero one three four five seven and Sonic Blade 10015 to OPTION resources and creates category-50000000 actors with effect-specific bounds origin projection speed height lifetime straight or homing motion target and environment collision contact sample twenty optional remembered targets and copied packets
+0x0042a300,InitializeGenericEffectActor,osf::buildGenericEffectActor / sf_generic_effect_actor_build / osf::RuntimeEffectSystem::queueActor,partial,static,Dispatches raw effects zero through seven to OPTION resources 0 1 2 3 0 0 4 0; the C99 direct-special descriptors cover shipped raw kinds zero one four five six and seven with exact integer projection bounds direction packet scenery and first-target expiry contact sample twenty and type-six contact visual 21023 while type two and the live fixed actor owner remain
 0x0042a860,UpdateEffect10004Controller,osf::EnemyEffectController::update,implemented,static,Update three emits warning resource 10000002 at the re-resolved source; delay ten re-resolves it again and emits two resource-10000000 chart layers samples 29 and 23 an invisible one-update area packet with contact sample 20 and the nearby eight-update magnitude-six vertical camera shake
 0x0042ae40,UpdateEffect10001Controller,osf::EnemyEffectController::update,implemented,static,Update zero emits resource 10000012 with one chart-zero lifetime at the resolved owner and constructor delay 12 re-resolves that owner then emits resource 10000010 exactly 180 units along the stored angle with fifty-unit bounds forward speed contact expiry copied packet and positional sample 19; zero negative and missing-owner timing have focused coverage
 0x0042b1c0,UpdateEffect10002Controller,osf::EnemyEffectController::update,implemented,static,Update zero emits resource 11000027 with one chart-zero lifetime at the resolved owner and constructor delay 12 re-resolves that owner then emits resource 10000040 exactly 180 units along the stored angle with fifty-unit bounds forward speed contact expiry copied packet and positional sample 94; zero positive and missing-owner timing have focused coverage

reverse/shadowflare-exe/status.md

@@ -22,8 +22,25 @@ remaining authored constructor values. `0x0042fd60` updates this controller
 list and removes a node only when its selected handler returns zero.
 
 `0x00429ec0` is the controller dispatch, not a visual-resource lookup table.
-The twelve effect numbers present in shipped enemy profiles dispatch as
-follows:
+Before the `10001+` controller switch, raw effects `0..7` all dispatch to the
+generic actor initializer at `0x0042a300`. Its OPTION-resource arguments are
+`0,1,2,3,0,0,4,0`. Effects 0, 4, 5, and 7 therefore deliberately share
+resource zero; effect 1 uses resource one; and the shipped direct-special
+effect 6 uses resource four. The ordinary direct-special set is
+`0/1/4/5/6/7`, so none of those values belongs to the specialized controller
+table below.
+
+The direct generic forms project a live source by constructor argument 21,
+move at argument six, draw at height seven, use chart zero, collide with the
+environment and the first eligible target, retain the packet, and request
+sample 20 on contact. Their normal judgement is `[-30,-30,30,30]`; effect 6
+instead uses `[-160,-160,159,159]` and contact visual 21023. Effect 1 always
+draws direction eight, while the others derive direction from the stored
+angle when packet kind is eight. The integer-only C99 descriptor preserves
+the unreduced source-to-target vector and projects it without floating point.
+
+`0x00429ec0` then dispatches the twelve effect numbers present in shipped
+enemy profiles as follows:
 
 | Effect | Controller |
 |---:|---:|

roadmap.md

@@ -204,13 +204,15 @@ the main screen arena untouched, and can be rewound without touching the
 fixed framebuffer. This is a generic resource/chart boundary, not a list of
 special maps or Goblin IDs.
 
-The immediate target is the retail consumer for raw direct-special effect kinds
-`0/1/4/5/6/7`, followed by enemy presentation actions five through seven.
-Those raw kinds must not be guessed to be the already reconstructed `10001+`
-projectile controllers. Retail tracing should identify their lifetime and
-resource rules before the bounded request queue is consumed. Hit/death CAF
-presentation can then consume the reaction state already published by the
-receivers.
+The immediate target is the fixed generic-effect actor owner and its bounded
+OPTION resource bank, followed by enemy presentation actions five through
+seven. Retail dispatch is now proven: raw direct-special kinds `0/1/4/5/6/7`
+map to resources `0/1/0/0/4/0`, not the `10001+` projectile controllers. The
+integer-only descriptor boundary preserves projection, bounds, direction,
+packet and collision policy. The next slice should load only the required
+resource, advance actors without allocation, and keep their state outside the
+renderer. Hit/death CAF presentation can then consume the reaction state
+already published by the receivers.
 
 ## Where we are now
 

shadowflare/CMakeLists.txt

@@ -101,6 +101,7 @@ add_library(
   game/enemy_direct_impact.c
   game/game.c
   game/gameplay_service.c
+  game/generic_effect_actor.c
   game/ground_item.c
   game/inventory.c
   game/item_condition.c

shadowflare/README.md

@@ -444,10 +444,19 @@ It retains the exact entry target vector using integer coordinates, consumes
 both retail visual draws, applies the raw effect-kind packet switch, and writes
 the complete 22-argument request into a fixed eight-entry frame queue. The
 queue reports saturation and clears by resetting two small fields; it does not
-zero or allocate packet storage in the update hot path. The raw retail kinds
-`0/1/4/5/6/7` deliberately remain requests until their executable consumer is
-reconstructed, rather than being misidentified as the unrelated `10001+`
-projectile family.
+zero or allocate packet storage in the update hot path. At this enqueue
+boundary the raw retail kinds `0/1/4/5/6/7` deliberately remain requests,
+rather than being misidentified as the unrelated `10001+` projectile family.
+
+The retail consumer for those raw requests is now identified and represented
+as a separate integer-only actor descriptor. Direct kinds `0/1/4/5/6/7` map
+to OPTION resources `0/1/0/0/4/0`; the builder retains source ownership,
+packet, speed, height, exact projected origin, direction, scenery and
+first-target expiry, and contact sample 20. Kind 6 also keeps its larger
+`[-160,-160,159,159]` judgement and contact visual 21023. Asset lifetime,
+movement, collision dispatch, and drawing remain the next fixed actor-owner
+slice rather than leaking into this packet translator.
+
 Those rules live in small `game/` files and never enter movement or rendering.
 
 Only the needed cells from combat tables 7, 11, 24, 25, and 26 are retained in

shadowflare/game/generic_effect_actor.c

@@ -0,0 +1,106 @@
+/*
+ * Copyright (C) 2026 Michael Binder and contributors
+ *
+ * This file is part of OpenShadowFlare.
+ *
+ * OpenShadowFlare is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * OpenShadowFlare is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with OpenShadowFlare. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "game/generic_effect_actor.h"
+
+#include "game/movement.h"
+
+#include <limits.h>
+#include <string.h>
+
+static int32_t sf_generic_effect_resource(int32_t effect_number) {
+  static const int32_t resources[8] = {0, 1, 2, 3, 0, 0, 4, 0};
+  return effect_number >= 0 && effect_number < 8
+    ? resources[effect_number] : -1;
+}
+
+static SfObjectBounds sf_generic_effect_judgement(int32_t effect_number) {
+  if (effect_number == 6)
+    return (SfObjectBounds) {-160, -160, 159, 159};
+  return (SfObjectBounds) {-30, -30, 30, 30};
+}
+
+static bool sf_generic_effect_position(
+    const SfCombatEffectRequest *request, SfWorldPoint resolved_source,
+    SfWorldPoint *position) {
+  SfWorldPoint offset;
+  int64_t x;
+  int64_t y;
+  if (request->owner_kind == 0 && request->has_explicit_origin) {
+    *position = request->origin;
+    return true;
+  }
+  if (request->constructor_values_16_to_22[
+        SF_COMBAT_EFFECT_CONSTRUCTOR_21] < 0) return false;
+  if (!sf_movement_vector_at_distance(
+        request->direction_vector,
+        (uint32_t) request->constructor_values_16_to_22[
+          SF_COMBAT_EFFECT_CONSTRUCTOR_21], &offset)) return false;
+  x = (int64_t) resolved_source.x + offset.x;
+  y = (int64_t) resolved_source.y + offset.y;
+  if (x < INT32_MIN || x > INT32_MAX ||
+      y < INT32_MIN || y > INT32_MAX) return false;
+  *position = (SfWorldPoint) {(int32_t) x, (int32_t) y};
+  return true;
+}
+
+bool sf_generic_effect_actor_build(
+    const SfCombatEffectRequest *request, SfWorldPoint resolved_source,
+    SfGenericEffectActor *actor) {
+  const SfWorldPoint zero = {0, 0};
+  int32_t resource;
+  if (!actor) return false;
+  memset(actor, 0, sizeof(*actor));
+  if (!request || !request->valid) return false;
+  resource = sf_generic_effect_resource(request->effect_number);
+  if (resource < 0 || request->effect_number == 2) return false;
+  if (!sf_generic_effect_position(request, resolved_source, &actor->position))
+    return false;
+  actor->packet = request->packet;
+  actor->direction_vector = request->direction_vector;
+  actor->judgement = sf_generic_effect_judgement(request->effect_number);
+  actor->effect_number = request->effect_number;
+  actor->resource_id = resource;
+  actor->owner_kind = request->owner_kind;
+  actor->source_character_number = request->source_character_number;
+  actor->target_kind = request->target_kind;
+  actor->target_identifier = request->target_identifier;
+  actor->travel_speed = request->constructor_value_6;
+  actor->display_height = request->constructor_value_7;
+  actor->lifetime = -1;
+  actor->target_collision_start = 0;
+  actor->contact_effect_number = request->effect_number == 6 ? 21023 : -1;
+  actor->animation_chart = 0;
+  actor->animation_direction = request->effect_number == 1 ? 8 :
+    request->packet_kind == 8
+      ? sf_movement_direction(zero, request->direction_vector)
+      : request->packet_kind;
+  actor->target_audio_sample = 20u;
+  actor->valid = true;
+  actor->home_toward_target =
+    request->constructor_values_16_to_22[
+      SF_COMBAT_EFFECT_CONSTRUCTOR_20] == 1 && request->effect_number != 1;
+  actor->collide_with_environment = true;
+  actor->expire_on_environment_collision = true;
+  actor->expire_on_target = true;
+  actor->remember_targets = request->constructor_values_16_to_22[
+    SF_COMBAT_EFFECT_CONSTRUCTOR_22] == 1;
+  actor->has_packet = request->has_packet;
+  return true;
+}

shadowflare/game/generic_effect_actor.h

@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2026 Michael Binder and contributors
+ *
+ * This file is part of OpenShadowFlare.
+ *
+ * OpenShadowFlare is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option)
+ * any later version.
+ *
+ * OpenShadowFlare is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with OpenShadowFlare. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef SHADOWFLARE_GAME_GENERIC_EFFECT_ACTOR_H
+#define SHADOWFLARE_GAME_GENERIC_EFFECT_ACTOR_H
+
+#include "core/bounds.h"
+#include "core/coordinates.h"
+#include "game/combat_effect_request.h"
+#include "game/combat_packet.h"
+
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef struct SfGenericEffectActor {
+  SfCombatPacket packet;
+  SfWorldPoint position;
+  SfWorldPoint direction_vector;
+  SfObjectBounds judgement;
+  int32_t effect_number;
+  int32_t resource_id;
+  int32_t owner_kind;
+  int32_t source_character_number;
+  int32_t target_kind;
+  int32_t target_identifier;
+  int32_t travel_speed;
+  int32_t display_height;
+  int32_t lifetime;
+  int32_t target_collision_start;
+  int32_t contact_effect_number;
+  int32_t animation_chart;
+  int32_t animation_direction;
+  uint16_t target_audio_sample;
+  bool valid;
+  bool home_toward_target;
+  bool collide_with_environment;
+  bool expire_on_environment_collision;
+  bool expire_on_target;
+  bool remember_targets;
+  bool has_packet;
+} SfGenericEffectActor;
+
+bool sf_generic_effect_actor_build(
+  const SfCombatEffectRequest *request, SfWorldPoint resolved_source,
+  SfGenericEffectActor *actor);
+
+#endif

shadowflare/game/movement.c

@@ -115,6 +115,12 @@ bool sf_movement_point_at_distance(
   return true;
 }
 
+bool sf_movement_vector_at_distance(
+    SfWorldPoint direction, uint32_t distance, SfWorldPoint *result) {
+  return sf_movement_point_at_distance(
+    (SfWorldPoint) {0, 0}, direction, distance, result);
+}
+
 static int64_t sf_separated_edge_distance(
     int64_t first_start, int64_t first_end,
     int64_t second_start, int64_t second_end) {

shadowflare/game/movement.h

@@ -39,6 +39,8 @@ int32_t sf_movement_point_distance(SfWorldPoint first, SfWorldPoint second);
 bool sf_movement_point_at_distance(
   SfWorldPoint from, SfWorldPoint toward, uint32_t distance,
   SfWorldPoint *result);
+bool sf_movement_vector_at_distance(
+  SfWorldPoint direction, uint32_t distance, SfWorldPoint *result);
 int32_t sf_movement_bounds_distance(
   SfWorldPoint first_position, SfObjectBounds first_bounds,
   SfWorldPoint second_position, SfObjectBounds second_bounds);