'f' for aklys

Adopt a feature mentioned in the xNetHack release announcement.
If you use the fire ('f') command when wielding a throw-and-return
weapon while your quiver is empty and the 'autoquiver' option is
Off, throw the wielded weapon instead of prompting to fill the
quiver.  It will usually return and be re-wielded, so be ready to
fire again.

Implemented from scratch.

doc/Guidebook.mn

@@ -35,7 +35,7 @@
 .ds vr "NetHack 3.7
 .ds f0 "\*(vr
 .ds f1
-.ds f2 "March 18, 2021
+.ds f2 "March 25, 2021
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -793,6 +793,10 @@ You may select ammunition with a previous \(oqQ\(cq command, or let the
 computer pick something appropriate if
 .op autoquiver
 is true.
+If your wielded weapon has the throw-and-return property, your quiver
+is empty, and
+.op autoquiver
+is false, you will throw that wielded weapon instead of filling the quiver.
 .lp ""
 See also \(oqt\(cq (throw) for more general throwing and shooting.
 .lp i
@@ -2434,6 +2438,16 @@ Arrows can be thrown by hand, but can be thrown
 much farther and will be more likely to hit when thrown while you are
 wielding a bow.
 .pg
+Some weapons will return when thrown.
+A boomerang\(emprovided it fails to hit anything\(emis an obvious example.
+If an aklys (thonged club) is thrown while it is wielded, it will return
+even when it hits something.
+A sufficiently strong hero can throw the warhammer \fIMjollnir\fP;
+when thrown by a \fIValkyrie\fP it will return too.
+However, aklyses and \fIMjollnir\fP occasionally fail to return.
+Returning thrown objects occasionally fail to be caught, sometimes even
+hitting the thrower, but when caught they become re-wielded.
+.pg
 You can simplify the throwing operation by using the \(oqQ\(cq command to
 select your preferred \(lqmissile\(rq, then using the \(oqf\(cq command to
 throw it.
@@ -2444,9 +2458,13 @@ There is also an option,
 which has NetHack choose another item to automatically fill your
 quiver (or quiver sack, or have at the ready) when the inventory slot used
 for \(oqQ\(cq runs out.
+If your quiver is empty,
+.op autoquiver
+is false, and you are wielding a weapon which returns when thrown,
+you will throw that weapon instead of filling the quiver.
 .pg
-Some characters have the ability to fire a volley of multiple items in a
+Some characters have the ability to throw or shoot a volley of multiple
-single turn.
+items (from the same stack) in a single action.
 Knowing how to load several rounds of ammunition at
 once\(emor hold several missiles in your hand\(emand
 still hit a target is not an easy task.

doc/Guidebook.tex

@@ -45,7 +45,7 @@
 %.au
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7 by Mike Stephenson and others)}
-\date{March 18, 2021}
+\date{March 25, 2021}
 
 \maketitle
 
@@ -875,8 +875,12 @@ often useful to give yourself a breather.
 Fire (shoot or throw) one of the objects placed in your quiver (or
 quiver sack, or that you have at the ready).
 You may select ammunition with a previous `{\tt Q}' command, or let the
-computer pick something appropriate if {\it autoquiver\/} is true.\\
+computer pick something appropriate if {\it autoquiver\/} is true.
+If your wielded weapon has the throw-and-return property, your quiver
+is empty, and {\it autoquiver\/}
+is false, you will throw that wielded weapon instead of filling the quiver.
 %.lp ""
+\\
 See also `{\tt t}' (throw) for more general throwing and shooting.
 %.lp
 \item[\tb{i}]
@@ -2653,6 +2657,17 @@ and your strength.  Arrows can be thrown by hand, but can be thrown
 much farther and will be more likely to hit when thrown while you are
 wielding a bow.
 
+%.pg
+Some weapons will return when thrown.
+A boomerang---provided it fails to hit anything---is an obvious example.
+If an aklys (thonged club) is thrown while it is wielded, it will return
+even when it hits something.
+A sufficiently strong hero can throw the warhammer {\it Mjollnir\/};
+when thrown by a {\it Valkyrie\/} it will return too.
+However, aklyses and {\it Mjollnir\/} occasionally fail to return.
+Returning thrown objects occasionally fail to be caught, sometimes even
+hitting the thrower, but when caught they become re-wielded.
+
 %.pg
 You can simplify the throwing operation by using the `{\tt Q}' command to
 select your preferred ``missile'', then using the `{\tt f}' command to
@@ -2663,10 +2678,14 @@ also an option,
 which has {\it NetHack\/} choose another item to automatically fill your
 quiver (or quiver sack, or have at the ready) when the inventory slot used
 for `{\tt Q}' runs out.
+If your quiver is empty, {\it autoquiver\/}
+is false, and you are wielding a weapon which returns when thrown,
+you will throw that weapon instead of filling the quiver.
 
 %.pg
-Some characters have the ability to fire a volley of multiple items in a
+Some characters have the ability to throw or shoot a volley of multiple
-single turn.  Knowing how to load several rounds of ammunition at
+items (from the same stack) in a single action.
+Knowing how to load several rounds of ammunition at
 once---or hold several missiles in your hand---and
 still hit a target is not an easy task.
 Rangers are among those who are adept

doc/fixes37.0

@@ -855,6 +855,9 @@ give feedback when boolean options are toggled interactively ('O' command)
 menu_shift_left, menu_shift_right menu command keys; default '{' and '}'
 	(curses for perm_invent only; implemented for X11 too but menus for
 	it lack horizontal scroll bars so the shifts don't work there)
+using 'f' while quiver is empty and 'autoquiver' is Off when wielding a
+	thrown-and-return weapon will throw that weapon instead of filling
+	the quiver (inspired by xNetHack)
 
 
 Platform- and/or Interface-Specific New Features

src/dothrow.c

@@ -20,6 +20,14 @@ static boolean toss_up(struct obj *, boolean);
 static void sho_obj_return_to_u(struct obj * obj);
 static boolean mhurtle_step(genericptr_t, int, int);
 
+/* uwep might already be removed from inventory so test for W_WEP instead;
+   for Valk+Mjollnir, caller needs to validate the strength requirement */
+#define AutoReturn(o,wmsk) \
+    ((((wmsk) & W_WEP) != 0                                             \
+      && ((o)->otyp == AKLYS                                            \
+          || ((o)->oartifact == ART_MJOLLNIR && Role_if(PM_VALKYRIE)))) \
+     || (o)->otyp == BOOMERANG)
+
 /* g.thrownobj (decl.c) tracks an object until it lands */
 
 int
@@ -270,18 +278,24 @@ throw_ok(struct obj *obj)
     if (!obj)
         return GETOBJ_EXCLUDE;
 
+    if (obj->bknown && welded(obj)) /* not a candidate if known to be stuck */
+        return GETOBJ_DOWNPLAY;
+
+    if (AutoReturn(obj, obj->owornmask)
+        /* to get here, obj is boomerang or is uwep and (alkys or Mjollnir) */
+        && (obj->oartifact != ART_MJOLLNIR || ACURR(A_STR) >= STR19(25)))
+        return GETOBJ_SUGGEST;
+
     if (obj->quan == 1 && (obj == uwep || (obj == uswapwep && u.twoweap)))
         return GETOBJ_DOWNPLAY;
-    /* Possible extension: return GETOBJ_SUGGEST for uwep if it will return when
-     * thrown. */
 
     if (obj->oclass == COIN_CLASS)
         return GETOBJ_SUGGEST;
 
     if (!uslinging() && obj->oclass == WEAPON_CLASS)
         return GETOBJ_SUGGEST;
-    /* Possible extension: exclude weapons that make no sense to throw, such as
+    /* Possible extension: exclude weapons that make no sense to throw,
-     * whips, bows, slings, rubber hoses. */
+       such as whips, bows, slings, rubber hoses. */
 
     if (uslinging() && obj->oclass == GEM_CLASS)
         return GETOBJ_SUGGEST;
@@ -396,23 +410,24 @@ dofire(void)
      * of asking what to throw/shoot.
      *
      * If quiver is empty, we use autoquiver to fill it when the
-     * corresponding option is on.  If the option is off or if
+     * corresponding option is on.  If the option is off and hero
-     * autoquiver doesn't select anything, we ask what to throw.
+     * is wielding a thrown-and-return weapon, use the wielded
+     * weapon.  If option is off and not wielding such a weapon or
+     * if autoquiver doesn't select anything, we ask what to throw.
      * Then we put the chosen item into the quiver slot unless
      * it is already in another slot.  [Matters most if it is a
      * stack but also matters for single item if this throw gets
-     * aborted (ESC at the direction prompt).  Already wielded
+     * aborted (ESC at the direction prompt).]
-     * item is excluded because wielding might be necessary
-     * (Mjollnir) or make the throw behave differently (aklys),
-     * and alt-wielded item is excluded because switching slots
-     * would end two-weapon combat even if throw gets aborted.]
      */
     if (!ok_to_throw(&shotlimit))
         return 0;
 
     if ((obj = uquiver) == 0) {
         if (!flags.autoquiver) {
-            You("have no ammunition readied.");
+            if (uwep && AutoReturn(uwep, uwep->owornmask))
+                obj = uwep;
+            else
+                You("have no ammunition readied.");
         } else {
             autoquiver();
             if ((obj = uquiver) == 0)
@@ -1136,10 +1151,10 @@ sho_obj_return_to_u(struct obj *obj)
 /* throw an object, NB: obj may be consumed in the process */
 void
 throwit(struct obj *obj,
-        long wep_mask,       /* used to re-equip returning boomerang */
+    long wep_mask,       /* used to re-equip returning boomerang */
-        boolean twoweap,     /* used to restore twoweapon mode if
+    boolean twoweap,     /* used to restore twoweapon mode if
-                                wielded weapon returns */
+                            wielded weapon returns */
-        struct obj *oldslot) /* for thrown-and-return used with !fixinv */
+    struct obj *oldslot) /* for thrown-and-return used with !fixinv */
 {
     register struct monst *mon;
     int range, urange;
@@ -1187,10 +1202,8 @@ throwit(struct obj *obj,
 
     g.thrownobj = obj;
     g.thrownobj->was_thrown = 1;
-    iflags.returning_missile = ((obj->oartifact == ART_MJOLLNIR
+    iflags.returning_missile = AutoReturn(obj, wep_mask) ? (genericptr_t) obj
-                                 && Role_if(PM_VALKYRIE))
+                                                         : (genericptr_t) 0;
-                                || tethered_weapon) ? (genericptr_t) obj
-                                                    : (genericptr_t) 0;
     /* NOTE:  No early returns after this point or returning_missile
        will be left with a stale pointer. */
 
@@ -1234,6 +1247,7 @@ throwit(struct obj *obj,
     } else if (obj->otyp == BOOMERANG && !Underwater) {
         if (Is_airlevel(&u.uz) || Levitation)
             hurtle(-u.dx, -u.dy, 1, TRUE);
+        iflags.returning_missile = 0; /* doesn't return if it hits monster */
         mon = boomhit(obj, u.dx, u.dy);
         if (mon == &g.youmonst) { /* the thing was caught */
             exercise(A_DEX, TRUE);
@@ -1241,6 +1255,7 @@ throwit(struct obj *obj,
             (void) encumber_msg();
             if (wep_mask && !(obj->owornmask & wep_mask)) {
                 setworn(obj, wep_mask);
+                /* moot; can no longer two-weapon with missile(s) */
                 set_twoweap(twoweap); /* u.twoweap = twoweap */
             }
             clear_thrownobj = TRUE;