Summary
The recoil mechanic is completely unstable in recent versions of the game, with even the example lines used in the documentation causing very erratic behavior.
Using an attribute of recoil=1.0 causes the player to look at the sky, then the ground, then back again repeatedly. Decreasing this value seems to have no effect at all, and there seems to be different recoil amounts applied when the player is moving vs standing still, and it seems like even their facing direction at the time of executing the mechanic plays a role in how unstable the result will be.
Steps to reproduce
ExampleItem_Templated:
Material: STONE
Skills:
- recoil{r=1.0;pitch=-1.0to-1.3} @self ~onUse
Replace the pitch and recoil values to literally anything else and keep experimenting.
Current behavior
Recoil is unpredictable and unstable. Try moving around while right-clicking the item, then standing still. Then looking in different directions while right-clicking.
Intended correct behavior
The r= attribute and pitch= attributes should actually have an impact on how much the player is recoiling.