Dive, Crawl & Gun

The largest of the four features by a wide margin, and the only one that shipped with a full Ghidra export — so unlike the rest, nothing here is inferred. Every animation, flag, bone filter, blend time and timing constant was read out of the decompile's 69 TASK_PLAY_ANIM call sites and is used verbatim.

Using it

1. Hold a movement direction and press G. You launch, land prone, and the crawl move set takes over.

2. Crawl with the movement keys. Walk, run, turn, back up — the full move set is wired.

3. Aim and fire from the ground. INPUT_ATTACK and INPUT_AIM are never disabled — that is the "& Gun" part.

4. Press jump to roll onto your back and shoot upward. Press it again, or crouch, to come off it.

5. Tap crouch to stand up.

G alone does nothing, and that is deliberate

Direction comes from IS_CONTROL_PRESSED on the four INPUT_MOVE_*_ONLY controls. No direction held means no dive at all — it stops the key firing by accident. This is the single most common support question about this resource.

You can also drop prone without diving: hold crouch for 500 ms.

The five dive directions

Five launch clips, each existing three times over — once per weapon class:

Weapon class	Dictionary	Clips
Unarmed	MECH_WEAPONS_CORE@BASE@DIVE@UNARMED@LAUNCH	dive_launch_fwd, _left, _right, _bkwl, _bkwr
Pistol	…@DIVE@PISTOL@LAUNCH	as above
Rifle	…@DIVE@RIFLE@LAUNCH	as above

Only the backward dive has two variants on a default install: a coin flip sends it out to the left when a pistol, revolver, rifle, two-handed weapon or the sawed-off is in hand, and to the right otherwise. The left dive's second variant is the Flaco clip, which needs flacoHernandezDiveAnimation on as well as the coin flip and a gun in hand — and that switch ships off, so by default a left dive always plays dive_launch_left.

There is no unarmed prone or get-up dictionary

Only eight dictionaries are preloaded, and unarmed shares the pistol set for both the prone pose and the get-up. That is the original's behaviour, not a shortcut.

The three stages carry different values throughout:

Stage	Blend in / out	Flags	ikFlags	Bone filter
Launch	2.0 / 0.5	0x30014C12	0x220	nohands_filter
Launch (Flaco)	2.0 / 0.5	0x30014C10	0x220	norightarm_filter
Prone pose	8.0 / 0.5	0x20012012	0x2000220	norightarm_filter
Get up	3.0 / 0.5	0x38014C10	0x2000220	norightarm_filter

Launch duration is picked by weapon: 954 ms for pistols and revolvers, 983 ms for long arms, unarmed and silenced weapons.

Weapon classes

Weapon class is decided by twelve IS_WEAPON_* predicates, not by IS_PED_ARMED's flag bits: pistol, revolver, rifle, repeater, sniper, shotgun, bow, two-handed, silent, melee, throwable and binoculars — with WEAPON_SHOTGUN_SAWEDOFF forced into the pistol set by hash.

GetDiveWeaponClass() returns the resulting class as 'unarmed', 'pistol', 'rifle' or 'none'.

Stamina and invincibility

	Default
minStaminaToDive	10.0	below this, no dive
diveStaminaCost	9.0	taken on launch
cooldown	800	ms between dives
underwaterStaminaDrain	6.0	per second while crawling submerged

The invincibility frames are not animation. They are SET_ENTITY_PROOFS(ped, 0x1FF, 1) for the length of the launch, cleared afterwards.

enableIFramesDuringDive ships on

It makes the player bullet, fire and melee proof for roughly a second. Good for cinematic play, exploitable in serious PvP. This is the setting to think hardest about before launch:

Config.Dive.enableIFramesDuringDive = false

Dead Eye and bullet time both ship off for the dive, and fire only while the aim button is held during the dive. Dive bullet time is 0.2, not the slide's 0.4.

Crawling

mech_crawl@base is a complete move set that shipped with the game and is never used by it. All 23 clips are wired up: idle, walk, run, four idle turns, the walk and run turn variants, four directional walk starts, the backward crawl and the two on-back clips.

Every one of them plays through nohands_filter with ikFlags 0x2000000 and its own flag word, and each transition is gated on a settled clip already playing — which is what stops the move set re-issuing itself every frame.

Movement comes from the clips' own root motion, as in the original. It never touches velocity while crawling.

	Default
crawlWalkSpeed	0.0	override — 0 leaves it to the animation
crawlRunSpeed	0.0	same
proneCapsule	0.5	SET_PED_CAPSULE while crawling, as the original

Low ceilings

While you are crawling, a probe runs 0.6 m above the head bone. If it hits something, jump, sprint and crouch are disabled for as long as it does — so the game's own jump, sprint and stand-up actions will not fire you into a ceiling you are lying under.

It does not stop the resource's own transitions. The crawl loop reads the disabled control states deliberately — crouch-to-stand tests IsDisabledControlPressed as well as IsControlPressed, and jump-to-roll tests the disabled press too — and the loop disables jump itself every frame while still reacting to it. So you can still roll onto your back or stand up from the crawl under a low ceiling.

The probe also only runs from inside the resource's wait loop, as in the original, never on an ordinary crawling frame, so the three controls are not disabled on every frame. There is nothing to configure. No wider capsule is applied: the port deliberately drops the original's 1.0 m capsule, and the one SET_PED_CAPSULE call sets proneCapsule (0.5) on every probe tick whether or not anything is overhead.

Crawling out from under whatever it is gives the controls straight back.

Aiming while prone

Aiming pins the heading, the same way the slide does, and picks its pose by weapon:

Weapon	Pose
Long arms, two pistols	prone_michael from script_common@other@unapproved
One pistol, quiet weapons	the mech_crawl idle, with a negative blend and a half-phase offset

holdStillWhileProneAiming is a RedM addition, and it ships on

Raising the sights while prone puts the body into a static aim pose, but the movement controls stay live — so the game starts its own crouch locomotion underneath it and the two fight. The body writhes on the spot. With this on, aiming pins you where you are and takes the movement keys away until you lower the sights; crawling then carries on exactly as before.

Turn it off for the original's behaviour, wriggle included.

On your back

Press the jump control while crawling. You roll over and can shoot upward, using onback_fwd and onback_bwd for movement. This is the jump control with no modifier — not Ctrl+Space.

The on-back aim pose depends on sittingAimForOnBackCrawling, which ships off:

sittingAimForOnBackCrawling	Weapon	Pose
off (default)	Long arms	struggle_escape_no_stab_rifle_short_vic from creatures_mammal@bear@grapple@streamed_core
off (default)	Everything else	struggle_escape_no_stab_short_vic, same dictionary
on	Long arms, two pistols	intro_0 from ai_getup@aim_from_ground@cop@pistol@on_back
on	One pistol, quiet weapons	aim_med_0 from ai_combat@aim_sweeps@cowboy@grounded@base@1h

The default pair are bear-grapple escape clips, started at phase 0.5 and held: once the clip passes 65% its speed is set to 0.0, which freezes the pose for as long as the sights are up.

The backward dive

A backward dive (S + the dive key) can end three ways, and both of the switches that change it ship off:

Config.Dive.backwardTransitionToSitting = false   -- ships off
Config.Dive.backwardTransitionToOnBack  = false   -- ships off

With both off it lands and gets up exactly like a forward, left or right dive — same landing pose, same get-up, same timing. That is what makes S + G feel like the other three directions.

The original shipped the sitting transition on

Its .ini had DivingBackwardTransitionToSittingPosition=1, which drops you into a seated firing stance and leaves you there until you crouch — so the backward dive behaves unlike the rest. Turn it back on in config.lua, or from Dive, Crawl & Gun → Sit after back dive, if you want that.

Crawl to sitting

Reached via front_to_prone from ai_getup@directional_sweep@combat@cop@pistol@front, played at 3× speed (sitAnimSpeed). After a delay of 3000 ms, or 3300 ms for long arms, the seated pose goes on: intro_0 from ai_getup@aim_from_ground@cop@pistol@on_back for long arms, aim_med_0 from ai_combat@aim_sweeps@cowboy@grounded@base@1h otherwise. Sitting up after a backward dive uses the same two clips.

The sit-up control is INPUT_INTERACT_LOCKON_ANIMAL on keyboard, INPUT_COVER on a pad.

Settings

The .ini switches keep their original names and defaults under Config.Dive:

.ini	config.lua	Default
DivingOnly	divingOnly	off
DivingOnlyNoRagdollWithGetUpAnimations	noRagdollWithGetUpAnimation	on
FlacoHernandezDiveAnimation	flacoHernandezDiveAnimation	off
DivingBackwardTransitionToSittingPosition	backwardTransitionToSitting	off
DivingBackwardTransitionToOnBackPosition	backwardTransitionToOnBack	off
UseSittingAimAnimationForOnBackCrawling	sittingAimForOnBackCrawling	off
DisableInputsIfMissionDisablesThem	disableInputsIfMissionDoes	on
EnableIFramesDuringDive	enableIFramesDuringDive	on
EnableProneCamera	enableProneCamera	on
StealthModeEnabled	stealth.enabled	on
SeeingRangeMultiplier	stealth.seeingRangeMultiplier	0.2
HearingRangeMultiplier	stealth.hearingRangeMultiplier	0.2

RedM-only switches, not in the original:

	Default
enableDiveWhenOnlyAiming	off	require aim to be held to dive
overrideDefaultCombatDive	off
enableDeadeyeAutomatically	off
enableBulletTimeDuringDive	off
enableDiveCamera	on	the dive gets its own camera
holdStillWhileProneAiming	on	see above

disableInputsIfMissionDoes applies in exactly one place — the hold-crouch prone input — and nowhere else. With it on, a mission-disabled crouch will not drop you prone. On keyboard the dive key reads the disabled press as well, so a mission-disabled dive key still fires a dive whatever this setting says. On a pad it does not — the controller branch reads the pressed state only, so a mission that disables the grapple button does stop the dive there, unless overrideDefaultCombatDive is on. The stealth double-tap reads only IsControlJustPressed, so it is unaffected either way.

Flaco dive uses a cutscene clip (jump_to_side_famousgunslinger from script_rc@gun2@stage_01@ig4) for the left direction, with its own flag word and bone filter.

One thing the port cannot do

The original grunts on a dive (EXERT_LOW) and on landing (PAIN_LOW or PAIN_MEDIUM, chosen by a coin flip). Those grunts are dropped here.

Why

Every ambient-speech native in RDR3 takes an Any* pointing at an eight-qword struct whose first field is itself a pointer to the speech name. InvokeNative will pass a Lua string as a char*, but there is no way to place the address of one Lua string inside the bytes of another — so the struct is not constructible from Lua. Passing the fields flat does not fail gracefully; it throws a native exception and takes the frame down:

SCRIPT ERROR: native 8e04fedd28d42462: exception at address ...

The grunt is cosmetic and nothing depends on it. CS.PlayAmbientSpeech in client/natives.lua is the single place to change if a flat-argument speech native ever appears.

Menu rows

Combat Moves → Dive, Crawl & Gun, or the Dive tab.

Section	Rows
(no heading)	Enabled
Diving	Diving only, Stand up after dive, Only while aiming, Flaco dive, Invincible mid-dive, Dead Eye on dive, Bullet time, Bullet time scale, Cooldown
Crawling	Crawl speed override, Crawl run speed override, Prone hold time, Underwater stamina drain, Sit after back dive, Hold still to aim prone
Prone camera	Prone camera, Preview it now, Distance, Shoulder offset, Height, Pitch, Field of view, Near clip, Motion blur, Ease in, Ease out, Reset camera
Dive camera	Dive camera, Preview it now, Distance, Shoulder offset, Height, Pitch, Field of view, Near clip, Motion blur, Ease in, Ease out, Reset dive camera
Stealth	Stealth mode, Toggle stealth now, Stealth overhaul, Apply while crouching, Seeing range, Hearing range, Noise while prone
Fix	Stand up now

Stand up now is the recovery row — use it if a player reports being stuck prone, crawling, on their back or sitting. It is the only menu row that calls StopDive.

/unstuck will not get them up. It releases the menu's input grab, closes the menu, resets gun tricks, stops a slide, clears ped tasks and hides the gun-trick HUD, but it never calls StopDive, so the dive state machine keeps running and the crawl loop re-issues the pose. Use Stand up now, or the StopDive() export.

Framing the two cameras is covered on Cameras.

Checking the animations in game

/cs_diveanim

It loads every dictionary and prints the real duration of each clip; anything red is a clip that dictionary does not contain. GET_ANIM_DURATION returns 0.0 for a clip that is not in its dictionary, which makes it a reliable "does this exist" oracle without playing anything.

cs_dive gives a live read-out of state, weapon class and eight of the weapon predicates — pistol, revolver, rifle, repeater, shotgun, bow, two-handed and silent. Sniper, melee, throwable and binoculars are not printed. cs_divetest <class> <dir> forces one specific dive without needing the movement keys. See Debug commands.

Exports

exports.rm_combat_moves:IsDiving()
exports.rm_combat_moves:GetDiveState()        -- idle | launch | crawl | aim | onback | sit
exports.rm_combat_moves:GetDiveWeaponClass()  -- unarmed | pistol | rifle | none
exports.rm_combat_moves:Dive()                -- false if not idle
exports.rm_combat_moves:GoProne()
exports.rm_combat_moves:GetUpFromDive()
exports.rm_combat_moves:StopDive()            -- recovery, from any state
exports.rm_combat_moves:SetDiveEnabled(false)
exports.rm_combat_moves:IsDiveEnabled()