sacred_k/docs/wasd.md

WASD movement (src/mods/wasd.cpp)

How the game moves the hero

Movement is a creature order: cEvent_creature (vtable 0x88e95c, 0x44 bytes), command 4 = walk, sent with cEngine::SendCreatureOrder (0x6170d0, (creature, event)), which snaps a ground target to a walkable point and passes the order to creature->vf18 (cCreature::ReceiveOrder, 0x52e400).

Offset	Field
+4	command (4 walk, 0x105 ...)
+0x10	target object id (attacks)
+0x14	2: x, y are a ground point; 0: no target
+0x18 / +0x1c	ground point (world units, same as creature +0x1c / +0x20)
+0x20	1: re-aim while a mouse button is held; 2: skip target snapping

The controlled creature's object id is at cEngine+0x13c; objects come from cObjectManager::GetObject (0x5fe060, manager *0xad3bc0), cast with __RTDynamicCast to cCreature. Hero state: +0xfc action mode (2 while following a held mouse button), +0x150 movement (1 walking, 2 arriving, 0 standing).

Mouse, measured with an order log:

• click (cEngine::HandleMouseButton 0x617360): one walk order to the ground point, then engine flag +0x54 |= 0x10 (button held);
• while held: every mouse event re-sends a plain walk order (+0x20 = 0) to the point under the cursor, dozens per tick; the hero stays in mode 2 and walks smoothly. cEngine::Tick (0x60f1d0, 10 Hz) additionally sends a re-aim order (+0x20 = 1) per tick after 0.4 s of walking;
• release after > 0.5 s: a walk order without target (+0x14 = 0), which stops the hero in place.

What the mod does

Direction movement (2026-10-18)

Request: "lets go all in with directional vector movement". The keys steer the hero directly instead of sending walk orders 10 times per second, which stuttered and stopped on weapon switches.

Measured (Place hook, watchpoints on the hero's x and on g_creatureNewPosition):

• The only writer of a creature's position is cObjectManager::Place (0x5fcd10, thiscall (id, position*), ret 8). For walking it is called from cCreature::Update (0x594110, thiscall (u8), ret 4) at 0x59653a, about 40 times per second on the engine thread.
• Update steps the creature along its path:
  • waypoints {x, y} at +0x2ed + i * 8, segment index +0x36d, count +0x371, sub-unit remainder +0x37d / +0x381;
  • speed +0x375 (337 for the battlemage) times the elapsed time.
• The step goes into g_creatureNewPosition (0xad2368, {u16 area, x, y, u8 level}; written at 0x5953da and 0x5955f7). It then passes through cCreature::CanStepTo (0x593c50, thiscall (x, y, position*), ret 0xc), which refuses a step into another cell that cCreature::IsCellWalkable (0x4f7b20, thiscall (cell*), ret 4, read-only) rejects. On refusal the new position is reset to the current one (0x59631a). Cells are 53.66563 world units.
• Walking straight into a fence, 27 of 28 steps were refused: the hero ran on the spot at 2 units per update.

Now (src/mods/wasd.cpp, hook on cCreature::Update for the controlled creature, before the original):

• Held keys give a unit direction in world axes: up (-1,-1), down (1,1), left (-1,1), right (1,-1); combinations are summed and normalised.

• Walking: the path is replaced by one segment from the hero's position, 1000 units along the direction (index 0, count 2). The game's own step moves the hero at its own speed and animation, and it never arrives.

• Obstacles: the way 1.25 cells ahead is probed at quarter cells with IsCellWalkable. If it is blocked, the direction turned by 30, 60 and 90 degrees is tried, the side last slid to first, so the hero slides along walls. If all are blocked: stop order.

• The facing (+0x70 / +0x74, float unit vector in world axes) is set to the direction each update. The game turns it towards the path gradually; on a reversal that took about 300 ms and swung through the side, so the hero walked backwards for a moment (user report: "direction change east/west is not instant").

• Idle (start, after an attack, cast or weapon switch): a walk order 300 units ahead, and right after it the two steps cCreature::Think (vf04, 0x537430, thiscall (float), ret 4) would take on its next run: cCreature::StartPendingWalk (0x4ede70: pending action +0xfc 2 with the parameters at +0x100 becomes action 1 with +0x154) and cCreature::WalkAction (0x4f45b0, phase 0 → 1: path, walk animation). Measured: Think runs only about every 110 ms per creature, so the walk started 16..125 ms after the order. Now it starts in the same update. If a status effect holds the hero, the order is retried at most every 150 ms.

• Other actions (attack, cast, shot): left alone until they end.

• Rapid key changes (user report: "not 100% smooth when rapidly changing directions"). Measured: a moment without any key (30 ms in the test) sent the stop order. The hero then went through the game's stop: walk phase 0x64, action 2 with the stop animation, idle about 110 ms later, and only then started again (about 125 ms standing per change). Now:

  • the stop order waits until the keys have been released for 50 ms;
  • a stop requested but not begun (walk, phase 0x64) goes back to phase 1 when keys are held again;
  • a running stop (action 2) restarts like standing idle.

  Mouse walking has the same uneven steps (4/6 units per update) and paired updates, so those are the game's own rhythm.

• Keys released: the target-less walk order (stops in place), unless a mouse button is held.

Autotest (battlemage, each key 1.5 s): about 250 units per second and almost no refused steps. The hero faces the key direction and plays the walk animation.

Superseded: the walk order per cEngine::Tick (10 Hz). Dead ends, for the record:

• re-aim orders (+0x20 = 1) on their own stop the hero after two orders;
• far targets (2000 units) are rejected or followed badly;
• targets near the stepwise-updated position make the hero arrive and stop;
• setting the walk mode +0xfc to 2 (as while a mouse button is held) does not change the speed.

Hotkeys

Keys reach the game as cEvent_key (category 4; key at +6/+8, modifiers at +0xa) through the kernel queue to cEngine::ReceiveEvent (0x618130), which offers them to cUI_Manager::ReceiveEvent (0x757120) first. Both compare toupper(key) (0x84aa86). Presses come from WM_CHAR (the character), releases from WM_KEYUP (the virtual key), so keys without a character (F-keys) never reach the hotkeys. The key bindings (src/mods/input.cpp) handle the raw WM_KEYDOWN/WM_KEYUP instead: W/A/S/D and the digit row are kept from the game, bound keys post the original hotkey's key event (Kernel_Instance 0x808490, cKernel::PostEvent 0x808930); the temporary bindings for the old W/A/S actions are listed in docs/todo.md.

Hotkeys found: engine A (pick up nearby), P (pause), Q/W/E/R/B/Space (cEngine::UseActionSlot), ^ (console), Esc, Ctrl+B/F/X/Z (Z quicksave); UI manager C F H I L M N O S T (S save game window). Arrow keys in cEngine::ScrollInput (0x610650) walk object #2 or scroll the camera; not reachable in normal play.

Text fields (2026-10-18)

Request: in character creation and the save window, bound keys were ignored or typed something else (K -> s: K posts the game's S hotkey).

Measured (key-press log): the UI manager's dialog slot (+0x144) held a hidden cUI_BusyDlg in both cases, so the old "dialog shown + focused edit control" test never found the field. The focused control (+0x148) is the right cUI_EditControl, but neither the focus nor the control's flags (0x8005) change when its window closes, and the control has no parent at +0x50. The save window draws two edit controls per frame.

Now (src/mods/input.cpp, FocusedTextField): keys pass to the game while the focused control is a writable edit control that cUI_EditControl::Render (0x737ae0, thiscall (renderer), ret 4, returns at once while hidden) drew in the last 250 ms. The render hook only notes the focused control.

Weapon set switch while walking (2026-10-18)

Request: the hero stops for a moment when switching weapon sets (F-keys) while walking with WASD.

Measured (state per tick + orders): cUI_Taskbar2::SelectWeaponSet (0x6e1440, ret 8) sends order 0x114 (set, items) and 0x107; between melee sets the walk goes on, between a melee and a bow set the hero drops to idle for one tick: the weapon class changed, and the switch resets the hero's animation state (0x54e540(1, 0)). The next WASD tick restarts the walk.

Measured again with a watchpoint on the action word: on a weapon class change cCreature::ResetToIdle (0x54e540) plays the idle animation and sets action 0, phase 1, pending action 0. A user report ("still little stops, weapon to no weapon and back") came after the restart through a walk order, which waited for the next Think (up to 110 ms). Now direction movement starts the walk in the same update (see above). The SelectWeaponSet hook with ResumeWalk was removed.