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.
This commit is contained in:
Brues
2026-11-11 10:41:33 -06:00
parent 0825491af2
commit bb5acbbdfb
6 changed files with 113 additions and 1 deletions
+37
View File
@@ -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
+1
View File
@@ -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).
+44
View File
@@ -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<float>(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},
+4
View File
@@ -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)
+16 -1
View File
@@ -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;
+11
View File
@@ -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,