From 5f43e111be962a3bf7c0bc185228a4e03175d262 Mon Sep 17 00:00:00 2001
From: OlegTheSnowman <123775785+OlegTheSnowman@users.noreply.github.com>
Date: Sat, 11 Jul 2026 00:14:52 +0300
Subject: [PATCH] Add toggleable numpad movement (Alt+Enter)

Ports the zMUD/CMUD numpad.set convention: plain numpad for normal
movement, Ctrl+numpad for moving up a level in that direction, and
Ctrl+Alt+numpad for moving down a level, all sent as literal MUD
commands via Accelerator. Alt+Enter toggles the whole set on/off (with
a sound + spoken confirmation) by clearing/restoring the accelerators,
so a disabled numpad types normally instead of doing nothing.

Cleared the numbers/*/-/+ entries in the world's native <keypad> block
since they'd otherwise double-send alongside the new Accelerator-based
bindings - left "." and "/" (hide/inventory) alone since those aren't
part of this feature. Documented the full three-layer key list and the
toggle in the readme.
---
 .../worlds/Cosmic Rage/cosmic rage.MCL        |  18 +--
 cosmic rage/worlds/plugins/NumpadMovement.xml | 107 ++++++++++++++++++
 readme.md                                     |  45 ++++++++
 3 files changed, 157 insertions(+), 13 deletions(-)
 create mode 100644 cosmic rage/worlds/plugins/NumpadMovement.xml

diff --git a/cosmic rage/worlds/Cosmic Rage/cosmic rage.MCL b/cosmic rage/worlds/Cosmic Rage/cosmic rage.MCL
index 80725e9..84a0535 100644
--- a/cosmic rage/worlds/Cosmic Rage/cosmic rage.MCL	
+++ b/cosmic rage/worlds/Cosmic Rage/cosmic rage.MCL	
@@ -312,44 +312,38 @@
    date_saved="2026-07-10 23:31:00"
   >
 
+  <!-- Numbers, *, -, and + are handled by NumpadMovement.xml (Accelerator-
+       based, toggleable with Alt+Enter) rather than here, so the two
+       systems can't double-send. Left blank rather than removed so the
+       keypad dialog still shows the full grid. -->
   <key name="0" >
-  <send>exits</send>
   </key>
 
   <key name="1" >
-  <send>sw</send>
   </key>
 
   <key name="2" >
-  <send>south</send>
   </key>
 
   <key name="3" >
-  <send>se</send>
   </key>
 
   <key name="4" >
-  <send>west</send>
   </key>
 
   <key name="5" >
-  <send>look</send>
   </key>
 
   <key name="6" >
-  <send>east</send>
   </key>
 
   <key name="7" >
-  <send>nw</send>
   </key>
 
   <key name="8" >
-  <send>north</send>
   </key>
 
   <key name="9" >
-  <send>ne</send>
   </key>
 
   <key name="." >
@@ -361,15 +355,12 @@
   </key>
 
   <key name="*" >
-  <send>score</send>
   </key>
 
   <key name="-" >
-  <send>up</send>
   </key>
 
   <key name="+" >
-  <send>down</send>
   </key>
 
   <key name="Ctrl+0" >
@@ -457,6 +448,7 @@
 <include name="Reconnecter.xml" plugin="y" />
 <include name="Repeat_Command.xml" plugin="y" />
 <include name="GagManager.xml" plugin="y" />
+<include name="NumpadMovement.xml" plugin="y" />
 <include name="LuaAudio.xml" plugin="y" />
 <include name="CosmicRage.xml" plugin="y" />
 </muclient>
diff --git a/cosmic rage/worlds/plugins/NumpadMovement.xml b/cosmic rage/worlds/plugins/NumpadMovement.xml
new file mode 100644
index 0000000..71d2f9a
--- /dev/null
+++ b/cosmic rage/worlds/plugins/NumpadMovement.xml	
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE muclient>
+
+<muclient>
+<plugin
+   name="NumpadMovement"
+   author="Antigravity"
+   id="3f8a1c6e7b2d49f0a5c8e6d1"
+   save_state="y"
+   language="Lua"
+   purpose="Toggleable numpad movement: plain numpad for normal movement, Ctrl for up-movement, Ctrl+Alt for down-movement."
+   requires="4.82"
+   version="1.0"
+   >
+</plugin>
+
+<!--  Script  -->
+<script>
+<![CDATA[
+-- Three layers of numpad bindings, matching the classic zMUD numpad.set
+-- convention: plain numpad for level movement, Ctrl+numpad for moving up
+-- a level while heading that direction, Ctrl+Alt+numpad for moving down
+-- a level while heading that direction. Alt+Enter toggles the whole set
+-- on/off, so the numpad can be freed up for typing numbers when needed.
+--
+-- Accelerator(key, "") clears a binding, and Accelerator(key, "command")
+-- with a plain string sends that command as if typed - this plugin just
+-- flips all of them on or off together rather than gating each key
+-- individually, so a disabled numpad behaves exactly like an unbound one
+-- (keys type normally) instead of silently swallowing keystrokes.
+
+local NUMPAD_BINDINGS = {
+  -- plain numpad - normal movement
+  { "Numpad1", "southwest" },
+  { "Numpad2", "south" },
+  { "Numpad3", "southeast" },
+  { "Numpad4", "west" },
+  { "Numpad5", "look" },
+  { "Numpad6", "east" },
+  { "Numpad7", "northwest" },
+  { "Numpad8", "north" },
+  { "Numpad9", "northeast" },
+  { "Numpad0", "exits" },
+  { "Multiply", "in" },
+  { "Ctrl+Multiply", "out" },
+  { "Subtract", "up" },
+  { "Add", "down" },
+
+  -- Ctrl+numpad - move up a level while heading that direction
+  { "Ctrl+Numpad1", "southwestup" },
+  { "Ctrl+Numpad2", "southup" },
+  { "Ctrl+Numpad3", "southeastup" },
+  { "Ctrl+Numpad4", "westup" },
+  { "Ctrl+Numpad6", "eastup" },
+  { "Ctrl+Numpad7", "northwestup" },
+  { "Ctrl+Numpad8", "northup" },
+  { "Ctrl+Numpad9", "northeastup" },
+  { "Ctrl+Subtract", "upstairs" },
+  { "Ctrl+Add", "downstairs" },
+
+  -- Ctrl+Alt+numpad - move down a level while heading that direction
+  { "Ctrl+Alt+Numpad1", "southwestdown" },
+  { "Ctrl+Alt+Numpad2", "southdown" },
+  { "Ctrl+Alt+Numpad3", "southeastdown" },
+  { "Ctrl+Alt+Numpad4", "westdown" },
+  { "Ctrl+Alt+Numpad5", "go" },
+  { "Ctrl+Alt+Numpad6", "eastdown" },
+  { "Ctrl+Alt+Numpad7", "northwestdown" },
+  { "Ctrl+Alt+Numpad8", "northdown" },
+  { "Ctrl+Alt+Numpad9", "northeastdown" },
+  { "Ctrl+Alt+Subtract", "climbup" },
+  { "Ctrl+Alt+Add", "climbdown" },
+}
+
+local function set_numpad_bindings(enabled)
+  for _, binding in ipairs(NUMPAD_BINDINGS) do
+    local key, command = binding[1], binding[2]
+    Accelerator(key, enabled and command or "")
+  end
+end
+
+function toggle_numpad()
+  local enabled = GetVariable("numpad_movement") ~= "0"
+  enabled = not enabled
+  SetVariable("numpad_movement", enabled and "1" or "0")
+  set_numpad_bindings(enabled)
+
+  if enabled then
+    ppi.play(dir.."sounds/ogg/general/misc/on.ogg", 0, 0, 100)
+    Execute("tts_interrupt Numpad movement enabled.")
+  else
+    ppi.play(dir.."sounds/ogg/general/misc/off.ogg", 0, 0, 100)
+    Execute("tts_interrupt Numpad movement disabled.")
+  end
+end
+
+function OnPluginInstall()
+  Accelerator("alt+enter", "toggle_numpad")
+  -- Enabled by default, matching the always-on native keypad behaviour
+  -- this plugin replaces.
+  local enabled = GetVariable("numpad_movement") ~= "0"
+  set_numpad_bindings(enabled)
+end
+]]>
+</script>
+
+</muclient>
diff --git a/readme.md b/readme.md
index 7b75854..ddea1e5 100644
--- a/readme.md
+++ b/readme.md
@@ -109,6 +109,17 @@ The soundpack mirrors game text into a separate notepad-style window titled "out
 ### Gag Manager
 - **Alt + F2**: Open the Gag Configuration menu (see [Gag Manager](#gag-manager) below)
 
+### Numpad Movement
+See [Numpad Movement](#numpad-movement) below for the full breakdown - summary:
+- **Alt + Enter**: Toggle numpad movement on/off
+- **Numpad 1-9, 0**: Move (with Numpad 5 as look, Numpad 0 as exits)
+- **Numpad \* / Ctrl + Numpad \***: In / out
+- **Numpad - / Numpad +**: Up / down
+- **Ctrl + Numpad 1-9** (except 5): Move up a level in that direction
+- **Ctrl + Numpad - / Ctrl + Numpad +**: Upstairs / downstairs
+- **Ctrl + Alt + Numpad 1-9**: Move down a level in that direction (Ctrl+Alt+Numpad 5 is "go")
+- **Ctrl + Alt + Numpad - / Ctrl + Alt + Numpad +**: Climb up / climb down
+
 
 ## Gag Manager
 
@@ -135,6 +146,40 @@ Press **Alt + F2** to open the Gag Configuration menu. From there you can:
 
 Your gags are saved to `gags.lua`, next to your world file (`worlds/Cosmic Rage/gags.lua`). It's a plain, human-readable file, so you can copy it to share your gag list with someone else or keep it as a backup. To load someone else's list, drop their `gags.lua` into your own `worlds/Cosmic Rage/` folder - this replaces your existing gags, so back yours up first if you want to keep it.
 
+
+## Numpad Movement
+
+The numpad can be dedicated entirely to movement, freeing you from typing full direction commands. It's on by default and works in three layers depending on what modifier you hold.
+
+### Plain numpad - normal movement
+- **Numpad 7 / 8 / 9**: Northwest / North / Northeast
+- **Numpad 4 / 5 / 6**: West / Look / East
+- **Numpad 1 / 2 / 3**: Southwest / South / Southeast
+- **Numpad 0**: Exits
+- **Numpad \***: In
+- **Ctrl + Numpad \***: Out
+- **Numpad -**: Up
+- **Numpad +**: Down
+
+### Ctrl + numpad - move up a level while heading that direction
+- **Ctrl + Numpad 7 / 8 / 9**: Northwest-up / North-up / Northeast-up
+- **Ctrl + Numpad 4 / 6**: West-up / East-up
+- **Ctrl + Numpad 1 / 2 / 3**: Southwest-up / South-up / Southeast-up
+- **Ctrl + Numpad -**: Upstairs
+- **Ctrl + Numpad +**: Downstairs
+
+### Ctrl + Alt + numpad - move down a level while heading that direction
+- **Ctrl + Alt + Numpad 7 / 8 / 9**: Northwest-down / North-down / Northeast-down
+- **Ctrl + Alt + Numpad 4 / 6**: West-down / East-down
+- **Ctrl + Alt + Numpad 1 / 2 / 3**: Southwest-down / South-down / Southeast-down
+- **Ctrl + Alt + Numpad 5**: Go
+- **Ctrl + Alt + Numpad -**: Climb up
+- **Ctrl + Alt + Numpad +**: Climb down
+
+### Turning it off
+
+Press **Alt + Enter** to toggle numpad movement on or off - useful if you need the numpad free for typing numbers instead. You'll hear a confirmation sound and a spoken message each time you toggle it. When it's off, the numpad keys behave normally again rather than doing nothing.
+
 ## FAQ
 
 **Q: My soundpack isn't working. What should I do?**