Merge pull request #44 from jonathan-robertson/dev

Fix Travel Through Rotated Multidim Blocks

Author: jonathan-robertson

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.4] - 2023-05-13
+
+- add dll version log message on awake
+- fix travel through rotated multidim blocks
+- update console enable/disable debug command
+- update readme with setup steps
+
 ## [1.1.3] - 2023-04-16
 
 - fix crash caused by complex multi-dim blocks

ModInfo.xml

@@ -3,7 +3,9 @@
         <Name value="Quantum Elevators" />
         <Description value="Add infinite distance, vertical-warp elevator panels." />
         <Author value="Jonathan Robertson (Kanaverum)" />
-        <Version value="1.1.3" />
+        <!-- REMINDER: this mod's DLL version will be logged on GameAwake and should reflect the same version listed here! -->
+        <!--  If troubleshooting an issue, search "Quantum Elevators DLL" in logs to confirm these two values match. -->
+        <Version value="1.1.4" />
         <Website value="https://github.com/jonathan-robertson/quantum-elevators" />
     </ModInfo>
 </xml>

QuantumElevators.dll

@@ -10,9 +10,15 @@
   - [Features](#features)
     - [Portable Quantum Elevator panels](#portable-quantum-elevator-panels)
     - [Secure Quantum Elevator panels](#secure-quantum-elevator-panels)
-  - [Compatibility](#compatibility)
-  - [Admin Commands](#admin-commands)
-  - [Acknowledgements](#acknowledgements)
+    - [Admin Commands](#admin-commands)
+  - [Setup](#setup)
+    - [Compatibility Quick Reference](#compatibility-quick-reference)
+    - [Windows PC (Single Player or Hosting P2P)](#windows-pc-single-player-or-hosting-p2p)
+      - [Critical Reminders](#critical-reminders)
+    - [Windows/Linux Installation (Server via FTP from Windows PC)](#windowslinux-installation-server-via-ftp-from-windows-pc)
+    - [Linux Server Installation (Server via SSH)](#linux-server-installation-server-via-ssh)
+    - [Troubleshooting / Common Issues](#troubleshooting--common-issues)
+  - [Special Thanks](#special-thanks)
 
 ## Summary
 
@@ -52,15 +58,7 @@ When attempting to travel, panels you are not already authenticated with or do n
 
 > [Hint] You can use this mechanic to include **hidden rooms/floors** within your base's structure without it being overly clear that such a room exists. Simply set the panel in the 'hidden' room/floor to a different password from the rest.
 
-## Compatibility
-
-Environment | Compatible | Details
---- | --- | ---
-Dedicated Server | Yes | only the server needs this mod (EAC can be **Enabled** on client and server)
-Peer-to-Peer Hosting | Yes | only the host needs this mod (EAC must be **Disabled** on host)
-Local Single Player | Yes | EAC must be **Disabled**
-
-## Admin Commands
+### Admin Commands
 
 > ℹ️ You can always search for this command or any command by running:
 >
@@ -69,11 +67,84 @@ Local Single Player | Yes | EAC must be **Disabled**
 
 primary | alternate | params | description
 :---: | :---: | :---: | ---
-quantumelevators | qe | N/A | enable/disable debug logging for this mod (disabled by default)
+quantumelevators | qe | `debug` | enable/disable debug logging for this mod (disabled by default)
+quantumelevators | qe | `push <x> <y> <z>` | recursively push entities 1 block at a time to make room; use float values from 'lp' command to let system calculate correct block coordinates for you
 
 *Note that leaving debug mode on can have a negative impact on performance. It is therefore recommended to only turn it on while troubleshooting and then disable it afterwards.*
 
-## Acknowledgements
+## Setup
+
+Without proper installation, this mod will not work as expected. Using this guide should help to complete the installation properly.
+
+If you have trouble getting things working, you can reach out to me for support via [Support](#support).
+
+### Compatibility Quick Reference
+
+Does this mod require a fresh map?
+
+> No, a fresh map is not necessary. You can add or remove the Quantum Elevators mod without having to start a new map.
+
+Environment | Compatible | Does EAC Need to be Disabled? | Who needs to install?
+--- | --- | --- | ---
+Dedicated Server | Yes | no | only server
+Peer-to-Peer Hosting | Yes | only on the host | only the host
+Single Player Game | Yes | Yes | self (of course)
+
+> 🤔 If you aren't sure what some of this means, details steps are provided below to walk you through the setup process.
+
+### Windows PC (Single Player or Hosting P2P)
+
+> ℹ️ If you plan to host a multiplayer game, only the host PC will need to install this mod. Other players connecting to your session do not need to install anything for this mod to work 😉
+
+1. 📦 Download the latest release by navigating to [this link](https://github.com/jonathan-robertson/quantum-elevators/releases/latest/) and clicking the link for `quantum-elevators.zip`
+2. 📂 Unzip this file to a folder named `quantum-elevators` by right-clicking it and choosing the `Extract All...` option (you will find Windows suggests extracting to a new folder named `quantum-elevators` - this is the option you want to use)
+3. 🕵️ Locate and create your mods folder (if missing): in another window, paste this address into to the address bar: `%APPDATA%\7DaysToDie`, then enter your `Mods` folder by double-clicking it. If no `Mods` folder is present, you will first need to create it, then enter your `Mods` folder after that
+4. 🚚 Move this new `quantum-elevators` folder into your `Mods` folder by dragging & dropping or cutting/copying & pasting, whichever you prefer
+5. ♻️ Stop the game if it's currently running, then start the game again without EAC by navigating to your install folder and running `7DaysToDie.exe`
+    - running from Steam or other launchers usually starts 7 Days up with the `7DaysToDie_EAC.exe` program instead, but running 7 Days directly will skip EAC startup
+
+#### Critical Reminders
+
+- ⚠️ it is **NECESSARY** for the host to run with EAC disabled or the DLL file in this mod will not be able to run
+- 😉 other players **DO NOT** need to disable EAC in order to connect to your game session, so you don't need to walk them through these steps
+- 🔑 it is also **HIGHLY RECOMMENDED** to add a password to your game session
+  - while disabling EAC is 100% necessary to run this mod properly, it also allows other players to run any mods they want on their end (which could be used to gain access to admin commands and/or grief you or your other players)
+
+### Windows/Linux Installation (Server via FTP from Windows PC)
+
+1. 📦 Download the latest release by navigating to [this link](https://github.com/jonathan-robertson/quantum-elevators/releases/latest/) and clicking the link for `quantum-elevators.zip`
+2. 📂 Unzip this file to a folder named `quantum-elevators` by right-clicking it and choosing the `Extract All...` option (you will find Windows suggests extracting to a new folder named `quantum-elevators` - this is the option you want to use)
+3. 🕵️ Locate and create your mods folder (if missing):
+    - Windows PC or Server: in another window, paste this address into to the address bar: `%APPDATA%\7DaysToDie`, then enter your `Mods` folder by double-clicking it. If no `Mods` folder is present, you will first need to create it, then enter your `Mods` folder after that
+    - FTP: in another window, connect to your server via FTP and navigate to the game folder that should contain your `Mods` folder (if no `Mods` folder is present, you will need to create it in the appropriate location), then enter your `Mods` folder. If you are confused about where your mods folder should go, reach out to your host.
+4. 🚚 Move this new `quantum-elevators` folder into your `Mods` folder by dragging & dropping or cutting/copying & pasting, whichever you prefer
+5. ♻️ Restart your server to allow this mod to take effect and monitor your logs to ensure it starts successfully:
+    - you can search the logs for the word `QuantumElevators`; the name of this mod will appear with that phrase and all log lines it produces will be presented with this prefix for quick reference
+
+### Linux Server Installation (Server via SSH)
+
+1. 🔍 [SSH](https://www.digitalocean.com/community/tutorials/how-to-use-ssh-to-connect-to-a-remote-server) into your server and navigate to the `Mods` folder on your server
+    - if you installed 7 Days to Die with [LinuxGSM](https://linuxgsm.com/servers/sdtdserver/) (which I'd highly recommend), the default mods folder will be under `~/serverfiles/Mods` (which you may have to create)
+2. 📦 Download the latest `quantum-elevators.zip` release from [this link](https://github.com/jonathan-robertson/quantum-elevators/releases/latest/) in whatever method you prefer
+    - example: `wget https://github.com/jonathan-robertson/quantum-elevators/releases/latest/download/quantum-elevators.zip`
+3. 📂 Unzip this file to a folder by the same name: `unzip quantum-elevators.zip -d quantum-elevators`
+    - you may need to install `unzip` if it isn't already installed: `sudo apt-get update && sudo apt-get install unzip`
+    - once unzipped, you can remove the quantum-elevators download with `rm quantum-elevators.zip`
+4. ♻️ Restart your server to allow this mod to take effect and monitor your logs to ensure it starts successfully:
+    - you can search the logs for the word `QuantumElevators`; the name of this mod will appear with that phrase and all log lines it produces will be presented with this prefix for quick reference
+    - rather than monitoring telnet, I'd recommend viewing the console logs directly because mod and DLL registration happens very early in the startup process and you may miss it if you connect via telnet after this happens
+    - you can reference your server config file to identify your logs folder
+    - if you installed 7 Days to Die with [LinuxGSM](https://linuxgsm.com/servers/sdtdserver/), your console log will be under `log/console/sdtdserver-console.log`
+    - I'd highly recommend using `less` to open this file for a variety of reasons: it's safe to view active files with, easy to search, and can be automatically tailed/followed by pressing a keyboard shortcut so you can monitor logs in realtime
+      - follow: `SHIFT+F` (use `CTRL+C` to exit follow mode)
+      - exit: `q` to exit less when not in follow mode
+      - search: `/QuantumElevators` [enter] to enter search mode for the lines that will be produced by this mod; while in search mode, use `n` to navigate to the next match or `SHIFT+n` to navigate to the previous match
+
+### Troubleshooting / Common Issues
+
+⚠️ Because QuantumElevators contains a DLL file, you may have trouble uploading to a 7 Days to Die dedicated host. Some hosts will silently *remove* DLL files from mods or prevent them from being overwritten (i.e. updated) when they are uploaded via FTP or various other methods. Please be sure to double-check that the `QuantumElevators.DLL` file is found within the `quantum-elevators` folder within your server if you don't see a reference to this DLL file in the logs on startup. In those cases, you can reach out to your host and explain the problem; most hosts will allow you to upload DLL mods and may have a special set of steps for you to follow or they may need to simply enable this functionality on your account.
+
+## Special Thanks
 
 Several people in the community have offered feedback, identified bugs, and have worked to provide me with debug logs to help move this project forward. Quantum Elevators is a cool idea and has been a lot of fun to work on, but would not be what it is today without the added effort from these incredible admins, modders, and players. *(Discord Usernames)*
 
@@ -82,3 +153,4 @@ Several people in the community have offered feedback, identified bugs, and have
 - `Blight#7410` of Pimp my House, Tea Lounge, Juggernaut, and Ragnarok submitted bug reports that helped identify and resolve a critical bug.
 - `O C#2804` reviewed and offered suggestions and advice that led to the resolution of a critical bug.
 - `vivo#0815` identified how to recreate a bug that occurred only on initial launch of a new map.
+- `Oggy#9577` identified an issue related to height detection of multi-dimensional block rotation.

README.md

@@ -14,7 +14,7 @@ internal class ConsoleCmdQuantumElevators : ConsoleCmdAbstract
         public ConsoleCmdQuantumElevators()
         {
             var dict = new Dictionary<string, string>() {
-                { "", "enable/disable debug logging for this mod" },
+                { "debug", "enable/disable debug logging for this mod" },
                 { "push <x> <y> <z>", "recursively push entities 1 block at a time to make room; use float values from 'lp' command to let system calculate correct block coordinates for you" },
             };
 
@@ -39,37 +39,38 @@ public override string GetHelp()
 
         public override void Execute(List<string> _params, CommandSenderInfo _senderInfo)
         {
-            if (_params.Count == 0)
+            if (_params.Count > 0)
             {
-                ModApi.DebugMode = !ModApi.DebugMode;
-                SdtdConsole.Instance.Output($"Debug logging is now {(ModApi.DebugMode ? "enabled" : "disabled")}.");
-                return;
-            }
-            switch (_params[0])
-            {
-                case "push":
-                    if (_params.Count != 4)
-                    {
-                        SdtdConsole.Instance.Output("Wrong number of arguments, expected 4, found " + _params.Count.ToString() + ".");
+                switch (_params[0])
+                {
+                    case "debug":
+                        ModApi.DebugMode = !ModApi.DebugMode;
+                        SdtdConsole.Instance.Output($"Debug logging is now {(ModApi.DebugMode ? "enabled" : "disabled")}.");
                         return;
-                    }
-                    if (!float.TryParse(_params[1], out var x)
-                        || !float.TryParse(_params[2], out var y)
-                        || !float.TryParse(_params[3], out var z))
-                    {
-                        SdtdConsole.Instance.Output($"Wrong type of argument, provided string could not be converted to float: {_params[1]}, {_params[2]}, {_params[3]}.");
+                    case "push":
+                        if (_params.Count != 4)
+                        {
+                            SdtdConsole.Instance.Output("Wrong number of arguments, expected 4, found " + _params.Count.ToString() + ".");
+                            return;
+                        }
+                        if (!float.TryParse(_params[1], out var x)
+                            || !float.TryParse(_params[2], out var y)
+                            || !float.TryParse(_params[3], out var z))
+                        {
+                            SdtdConsole.Instance.Output($"Wrong type of argument, provided string could not be converted to float: {_params[1]}, {_params[2]}, {_params[3]}.");
+                            return;
+                        }
+                        SdtdConsole.Instance.Output($"Pushing...");
+                        // note: one can use integer conversion to get the bottom-left of a positive coordinate,
+                        // but not for the bottom-left of a negative coordinate... these have to be rounded "down" to the *next* nearest number.
+                        // ... yes, this is how block coords are identified lol
+                        _ = CoreLogic.Push(new Vector3i(
+                            x % 1 < 0 ? x - 1 : x,
+                            y % 1 < 0 ? y - 1 : y,
+                            z % 1 < 0 ? z - 1 : z));
+                        SdtdConsole.Instance.Output($"Pushing completed.");
                         return;
-                    }
-                    SdtdConsole.Instance.Output($"Pushing...");
-                    // note: one can use integer conversion to get the bottom-left of a positive coordinate,
-                    // but not for the bottom-left of a negative coordinate... these have to be rounded "down" to the *next* nearest number.
-                    // ... yes, this is how block coords are identified lol
-                    _ = CoreLogic.Push(new Vector3i(
-                        x % 1 < 0 ? x - 1 : x,
-                        y % 1 < 0 ? y - 1 : y,
-                        z % 1 < 0 ? z - 1 : z));
-                    SdtdConsole.Instance.Output($"Pushing completed.");
-                    return;
+                }
             }
 
             SdtdConsole.Instance.Output($"Invalid number of parameters; use 'help {_commands[0]}' to verify valid options.");