From bb5acbbdfba1ee211f39231bde84bb1e55e9d42b Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Wed, 11 Nov 2026 10:41:33 -0600 Subject: [PATCH] feat(model): actor:KnockBack, the client's knockback launch on scene actors A 1.12.1 server knocks a unit back with SMSG_MOVE_KNOCK_BACK (0xEF, to its controller) or MSG_MOVE_KNOCK_BACK (0xF1, relayed): a direction pair, a horizontal speed and a vertical speed that the server negates into the client's down-positive fall speed. Both paths end in the same launch on the unit's CMovement, 0x006179C0: swimming ends (0x007C6E80), a fall starts at the vertical speed (0x007C61F0, which re-anchors with the old flags), the direction pair overwrites the heading +0x68 and the direction +0x5C with 0 in z, flag 0x2 clears and 0x8001 sets whatever the speeds, and the horizontal speed goes to +0x84. Nothing about the unit refuses it. The direction is world-absolute. Mover::KnockBack transcribes that launch on a scene body. While the body falls, the direction is not recomputed (0x007C5A20 returns early), so the flight keeps its line; the 0x8000 latch, now named FLAG_STOP_ON_LAND, makes the landing stop the move (ApplyLatches 0x0061AB20), as it does a knocked-back character's. actor:KnockBack(fromX, fromY, horizontalSpeed, verticalSpeed) stands in for the server's KnockBackFrom: the direction from the point to the actor, or the facing turned half a circle (the client's pi, 0x0081052C) on the point itself, and the actor's preparing spells stop, as the server interrupts non-melee spells. As every move event that is not the player's own, it ends a MoveTo first (ClearSpline). The acknowledgement's animation follows: AnimateMoveOpcode (0x0060E480) plays 40, Fall, for 0xF0 (0x0060E4FC, PlayAnimation 0x005FE2F0 with 0x28). A dead actor keeps its death animation, so a corpse flies in its death pose. docs/API.md documents the method next to MoveTo. --- docs/API.md | 37 +++++++++++++++++++++++++++++ src/model/Scene.h | 1 + src/model/SceneActor.cpp | 44 +++++++++++++++++++++++++++++++++++ src/model/SceneLocomotion.cpp | 4 ++++ src/model/SceneMover.cpp | 17 +++++++++++++- src/model/SceneMover.h | 11 +++++++++ 6 files changed, 113 insertions(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index fa334e10..70d5e501 100644 --- a/docs/API.md +++ b/docs/API.md @@ -910,6 +910,7 @@ build instructions. - [`actor:IsFalling()`](#actorisfalling) - [`actor:IsSwimming()`](#actorisswimming) - [`actor:MoveTo(x, y, z [, facing])`](#actormovetox-y-z--facing) + - [`actor:KnockBack(fromX, fromY, horizontalSpeed, verticalSpeed)`](#actorknockbackfromx-fromy-horizontalspeed-verticalspeed) - [`actor:SetWalking(walking)` / `actor:IsWalking()`](#actorsetwalkingwalking--actoriswalking) - [`actor:SetMovementSpeed(speedType, speed)` / `actor:GetMovementSpeed(speedType)`](#actorsetmovementspeedspeedtype-speed--actorgetmovementspeedspeedtype) - [`actor:GetCameraPivotHeight(distance)`](#actorgetcamerapivotheightdistance) @@ -20704,6 +20705,42 @@ end) guard:MoveTo(unpack(route[leg])) ``` +### `actor:KnockBack(fromX, fromY, horizontalSpeed, verticalSpeed)` + +Throws the actor away from the point (`fromX`, `fromY`), as a knockback +spell throws a character in the world. The movement of the actor must be on +([`actor:SetMovementEnabled`](#actorsetmovementenabledenabled--actorismovementenabled)). +Returns `true`, or `false` while the movement is off. + +- The actor flies away from the point at `horizontalSpeed` yards a second + along the ground. A negative `horizontalSpeed` pulls it toward the point. +- It goes up at `verticalSpeed` yards a second at the start. Then it falls + as a jump falls. +- When the actor stands on the point, it flies backward from the way that + it faces. +- The direction does not change in the air. When the actor lands, it stops. +- Walls and props block the flight, as they block any movement. +- The actor plays its fall animation. When it lands, it plays its landing + animation. An actor that plays a death animation keeps it, so a dead + actor flies in its death pose. +- A swimming actor stops swimming. + +`KnockBack` ends a move of +[`actor:MoveTo`](#actormovetox-y-z--facing). Then `OnMoveFinished` does not +run for it. It also stops the spells that the actor prepares, as +[`actor:StopSpellVisual`](#actorstopspellvisual) does. A +[movement command](#movement-commands) that you give in the air takes effect +when the actor lands, as after a jump. Give a new `MoveTo` only after the +actor lands, when [`actor:IsFalling`](#actorisfalling) returns `false`. This +is a ClassicAPI extension. + +```lua +-- An explosion at (x, y) throws the actors near it. +for _, actor in ipairs(nearby) do + actor:KnockBack(x, y, 12, 8) +end +``` + ### `actor:SetWalking(walking)` / `actor:IsWalking()` Sets whether the actor walks instead of running, when it moves forward and diff --git a/src/model/Scene.h b/src/model/Scene.h index 034e64cd..48873986 100644 --- a/src/model/Scene.h +++ b/src/model/Scene.h @@ -452,6 +452,7 @@ enum class Move : uint32_t { TeleportAck = 0xC7, StartSwim = 0xCA, StopSwim = 0xCB, + KnockBack = 0xF0, // CMSG_MOVE_KNOCK_BACK_ACK, after the launch }; // A movement message for a command the mover took, or a change the actor // made (ProcessLocalMoveEvent 0x0060E0A0 -> AnimateMoveOpcode). diff --git a/src/model/SceneActor.cpp b/src/model/SceneActor.cpp index 511af30c..fba68bd1 100644 --- a/src/model/SceneActor.cpp +++ b/src/model/SceneActor.cpp @@ -2138,6 +2138,35 @@ int __fastcall Script_MoveTo(void *L) { return 0; } +// A server's knockback (Unit::KnockBackFrom): the direction from the source +// to the unit, or its facing turned half a circle when it stands on the +// source; the vertical speed negated into the client's down-positive fall +// speed; the unit's spells interrupted (InterruptNonMeleeSpells). The client +// takes it as a move event that is not the player's own, so a MoveTo ends +// first (ClearSpline), then launches (0x006179C0) and animates the +// acknowledgement (0xF0: Fall). False without the mover. +int __fastcall Script_KnockBack(void *L) { + Actor *actor = Self(L); + if (actor == nullptr || !NumberArgs(L, 2, 4, actor->DisplayName(), + "KnockBack(fromX, fromY, horizontalSpeed, verticalSpeed)")) + return 0; + if (actor->mover == nullptr) { + Game::Lua::PushBool(L, false); + return 1; + } + Advance(*actor); + const float dx = actor->mover->position[0] - FloatArg(L, 2); + const float dy = actor->mover->position[1] - FloatArg(L, 3); + const float angle = + dx == 0.0f && dy == 0.0f ? actor->mover->facing + Game::Read(Offsets::VAR_PI) : std::atan2(dy, dx); + Casts::Stop(*actor); + Mover::ClearSpline(*actor->mover); + Mover::KnockBack(*actor->mover, std::cos(angle), std::sin(angle), FloatArg(L, 4), -FloatArg(L, 5)); + Locomotion::OnMove(*actor, Move::KnockBack); + Game::Lua::PushBool(L, true); + return 1; +} + // MSG_MOVE_SET_WALK_MODE and MSG_MOVE_SET_RUN_MODE (cases 0xF and 0xE of // UpdatePlayerMovement 0x00615C30): the run mode (SetRunMode 0x007C71C0), // which a moving body animates. @@ -2659,6 +2688,7 @@ const Game::Lua::FrameMethodEntry kMethods[] = { {"IsSwimming", &Script_IsSwimming}, {"GetCameraPivotHeight", &Script_GetCameraPivotHeight}, {"MoveTo", &Script_MoveTo}, + {"KnockBack", &Script_KnockBack}, {"SetWalking", &Script_SetWalking}, {"IsWalking", &Script_IsWalking}, {"SetMovementSpeed", &Script_SetMovementSpeed}, @@ -3095,6 +3125,19 @@ const Game::Doc::Function kStartTurningRight{"Starts the actor turning to its ri const Game::Doc::Function kStopTurning{"Stops the actor turning.", {}, kCommandRet, nullptr, true}; const Game::Doc::Function kJump{"Makes the actor jump. False when it is already in the air.", {}, kCommandRet, nullptr, true}; +const Game::Doc::Field kKnockBackArgs[] = { + Req("fromX", "number", "The point the actor is thrown away from."), + Req("fromY", "number"), + Req("horizontalSpeed", "number", "Yards a second along the ground. Negative pulls toward the point."), + Req("verticalSpeed", "number", "Yards a second up at the start."), +}; +const Game::Doc::Field kKnockBackRet[] = { + Req("launched", "bool", "False unless SetMovementEnabled is on."), +}; +const Game::Doc::Function kKnockBack{ + "Throws the actor away from a point, as a knockback spell throws a character. A MoveTo ends, and the " + "spells that the actor prepares stop. The actor flies until it lands, then stops.", + kKnockBackArgs, kKnockBackRet, nullptr, true}; const Game::Doc::Field kIsFallingRets[] = { Req("falling", "bool", "True while the actor is in the air: jumping or falling."), Opt("verticalSpeed", "number", nullptr, "Yards a second, up positive."), @@ -3296,6 +3339,7 @@ const Game::Doc::Method kMethodDocs[] = { {"IsSwimming", &kIsSwimming}, {"GetCameraPivotHeight", &kGetCameraPivotHeight}, {"MoveTo", &kMoveTo}, + {"KnockBack", &kKnockBack}, {"SetWalking", &kSetWalking}, {"IsWalking", &kIsWalking}, {"SetMovementSpeed", &kSetMovementSpeed}, diff --git a/src/model/SceneLocomotion.cpp b/src/model/SceneLocomotion.cpp index 5b366a89..6a5b30e1 100644 --- a/src/model/SceneLocomotion.cpp +++ b/src/model/SceneLocomotion.cpp @@ -183,6 +183,10 @@ void OnMove(Actor &actor, Move move) { case Move::Jump: Play(actor, Offsets::ANIM_JUMP_START, false); return; + // AnimateMoveOpcode's 0xF0 arm (0x0060E4FC): the knockback falls at once. + case Move::KnockBack: + Play(actor, Offsets::ANIM_FALL, false); + return; case Move::RunMode: case Move::WalkMode: if (actor.mover->flags & 0xF) diff --git a/src/model/SceneMover.cpp b/src/model/SceneMover.cpp index e3473433..7b903dc4 100644 --- a/src/model/SceneMover.cpp +++ b/src/model/SceneMover.cpp @@ -571,7 +571,7 @@ void StopStrafeNow(Body &b) { // 0x007C6CE0 // The deferred direction latches (0x0061AB20), applied at a landing. uint32_t ApplyLatches(Body &b) { const uint32_t entry = b.flags; - if (b.flags & 0x8000) + if (b.flags & FLAG_STOP_ON_LAND) StopMoveNow(b); if (b.flags & 0x10000) StopStrafeNow(b); @@ -2369,6 +2369,21 @@ void StopSwimming(Body &b) { } // namespace +void KnockBack(Body &body, float cosine, float sine, float speedXY, float speedZ) { + if (body.flags & FLAG_SWIMMING) + StopSwimming(body); + StartFall(body, speedZ); + // The fall start re-anchored with the old flags; the pair overwrites the + // direction it computed (0x006179E5 to 0x00617A04). + body.heading[0] = cosine; + body.heading[1] = sine; + body.direction[0] = cosine; + body.direction[1] = sine; + body.direction[2] = 0.0f; + body.flags = (body.flags & ~FLAG_BACKWARD) | FLAG_STOP_ON_LAND | FLAG_FORWARD; + body.speed = speedXY; +} + void UpdateSwimState(Body &body, bool inLiquid, float depth) { if (body.flags & 0x400) return; diff --git a/src/model/SceneMover.h b/src/model/SceneMover.h index 71e73c8f..67f62f61 100644 --- a/src/model/SceneMover.h +++ b/src/model/SceneMover.h @@ -104,6 +104,8 @@ enum : uint32_t { FLAG_PITCH_DOWN = 0x80, FLAG_FALLING = 0x2000, FLAG_FALLING_FAR = 0x4000, + // The deferred stop: a landing stops the move (ApplyLatches 0x0061AB20). + FLAG_STOP_ON_LAND = 0x8000, FLAG_SWIMMING = 0x200000, FLAG_ON_STEP = 0x4000000, }; @@ -138,6 +140,15 @@ bool StopPitch(Body &body); // 0x007C6E30 bool Jump(Body &body); // 0x007C6230 with check 1 void SetRunMode(Body &body, bool run); // 0x007C71C0 +// A server's knockback, as the client launches it (0x006179C0, from the +// drain's knockback entry and the relayed MSG_MOVE_KNOCK_BACK 0x00617A60): +// swimming ends (0x007C6E80); a fall starts at `speedZ` (0x007C61F0, down +// positive, so a launch upward is negative); the direction (cosine, sine) +// is world-absolute and becomes the heading and the direction; backward +// clears and forward sets with the stop-on-landing latch, whatever the +// speeds; `speedXY` is the speed. Nothing refuses it. +void KnockBack(Body &body, float cosine, float sine, float speedXY, float speedZ); + // The speeds a server changes (the spline speed opcodes 0x2FE to 0x303). enum class Speed { Walk, Run, RunBack, Swim, SwimBack, Turn }; // CMovement's setters: SetWalkSpeed 0x007C70D0, SetRunSpeed 0x007C7030,