Merge pull request #2538 from myk002/myk_script_paths

add dfhack-config/scripts to default script paths

dfhack-config/scripts/README.md

@@ -0,0 +1,7 @@
+You can put scripts you write or download in this folder and DFHack will find
+them.
+
+If a script in this directory has the same name as a default DFHack script, the
+ script in this directory will take precedence.
+
+Everything you add to this folder will be kept safe when you upgrade DFHack.

docs/Core.rst

@@ -21,10 +21,11 @@ DFHack commands can be implemented in any of three ways:
             same version of DFHack.  They are less flexible than scripts,
             but used for complex or ongoing tasks because they run faster.
 
-:scripts:   are Ruby or Lua scripts stored in ``hack/scripts/``.
+:scripts:   are Ruby or Lua scripts stored in ``hack/scripts/`` or other
-            Because they don't need to be compiled, scripts are
+            directories in the `script-paths`. Because they don't need to
-            more flexible about versions, and easier to distribute.
+            be compiled, scripts are more flexible about versions, and
-            Most third-party DFHack addons are scripts.
+            they are easier to distribute. Most third-party DFHack addons
+            are scripts.
 
 All tools distributed with DFHack are documented `here <tools>`.
 
@@ -37,6 +38,8 @@ DFHack commands can be executed in a number of ways:
 #. Pressing a key combination set up with `keybinding`
 #. From one of several `init-files`, automatically
 #. Using `script` to run a batch of commands from a file
+#. From an in-game command launcher interface like `gui/launcher`, the
+   `hotkeys` overlay widget, or `gui/quickcmd`.
 
 The DFHack console
 ------------------
@@ -144,7 +147,7 @@ save-specific init files in the save folders.
 DFHack looks for init files in three places each time they could be run:
 
 #. The :file:`dfhack-config/init` subdirectory in the main DF directory
-#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and
+#. :file:`data/save/{world}/raw`, where ``{world}`` is the current save, and
 #. :file:`data/save/{world}/raw/objects`
 
 For each of those directories, all matching init files will be executed in
@@ -171,7 +174,7 @@ dfhack\*.init
 On startup, DFHack looks for files of the form ``dfhack*.init`` (where ``*`` is
 a placeholder for any string, including the empty string).
 
-These files are best used for keybindings and enabling persistent plugins
+These files are best used for keybindings and enabling persistent tools
 which do not require a world to be loaded.
 
 
@@ -230,9 +233,10 @@ Script paths are folders that DFHack searches to find a script when a command is
 run. By default, the following folders are searched, in order (relative to the
 root DF folder):
 
-1. :file:`data/save/{<region folder>}/raw/scripts` (only if a save is loaded)
+#. :file:`dfhack-config/scripts`
-2. :file:`raw/scripts`
+#. :file:`data/save/{<region folder>}/raw/scripts` (only if a save is loaded)
-3. :file:`hack/scripts`
+#. :file:`raw/scripts`
+#. :file:`hack/scripts`
 
 For example, if ``teleport`` is run, these folders are searched in order for
 ``teleport.lua`` or ``teleport.rb``, and the first matching file is run.

docs/changelog.txt

@@ -39,6 +39,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 
 ## Misc Improvements
 - Scrollable widgets now react to mouse wheel events when the mouse is over the widget
+- the ``dfhack-config/scripts/`` folder is now searched for scripts by default
 
 ## Documentation
 - `overlay-dev-guide`: added troubleshooting tips and common development workflows

docs/dev/Lua API.rst

@@ -2629,8 +2629,8 @@ and are only documented here for completeness:
 
   Registers ``path`` as a `script path <script-paths>`.
   If ``search_before`` is passed and ``true``, the path will be searched before
-  the default paths (e.g. ``raw/scripts``, ``hack/scripts``); otherwise, it will
+  the default paths (e.g. ``dfhack-config/scripts``, ``hack/scripts``); otherwise,
-  be searched after.
+  it will be searched after.
 
   Returns ``true`` if successful or ``false`` otherwise (e.g. if the path does
   not exist or has already been registered).
@@ -5466,11 +5466,11 @@ Scripts
    :local:
 
 Any files with the ``.lua`` extension placed into the :file:`hack/scripts` folder
-are automatically made available as DFHack commands. The command corresponding to
+(or any other folder in your `script-paths`) are automatically made available as
-a script is simply the script's filename, relative to the scripts folder, with
+DFHack commands. The command corresponding to a script is simply the script's
-the extension omitted. For example:
+filename, relative to the scripts folder, with the extension omitted. For example:
 
-* :file:`hack/scripts/add-thought.lua` is invoked as ``add-thought``
+* :file:`dfhack-config/scripts/startup.lua` is invoked as ``startup``
 * :file:`hack/scripts/gui/teleport.lua` is invoked as ``gui/teleport``
 
 .. note::
@@ -5487,12 +5487,6 @@ the extension omitted. For example:
       a mod developer would want to run a script from the console, it should
       not be placed in this folder)
 
-Scripts can also be placed in other folders - by default, these include
-:file:`raw/scripts` and :file:`data/save/{region}/raw/scripts`, but additional
-folders can be added (for example, a copy of the
-:source-scripts:`scripts repository <>` for local development). See
-`script-paths` for more information on how to configure this behavior.
-
 Scripts are read from disk when run for the first time, or if they have changed
 since the last time they were run.
 
@@ -5520,7 +5514,7 @@ General script API
 
 * ``dfhack.run_script(name[,args...])``
 
-  Run a Lua script in :file:`hack/scripts/`, as if it were started from the
+  Run a Lua script in your `script-paths`, as if it were started from the
   DFHack command-line. The ``name`` argument should be the name of the script
   without its extension, as it would be used on the command line.
 
@@ -5562,8 +5556,8 @@ Importing scripts
 
   Loads a Lua script and returns its environment (i.e. a table of all global
   functions and variables). This is similar to the built-in ``require()``, but
-  searches all script paths for the first matching ``name.lua`` file instead
+  searches all `script-paths` for the first matching ``name.lua`` file instead
-  of searching the Lua library paths (like ``hack/lua``).
+  of searching the Lua library paths (like ``hack/lua/``).
 
   Most scripts can be made to support ``reqscript()`` without significant
   changes (in contrast, ``require()`` requires the use of ``mkmodule()`` and

docs/guides/modding-guide.rst

@@ -60,9 +60,10 @@ For scripts with the same name, the `order of precedence <script-paths>` will
 be:
 
 1. ``own-scripts/``
-2. ``data/save/*/raw/scripts/``
+2. ``dfhack-config/scripts/``
-3. ``raw/scripts/``
+3. ``data/save/*/raw/scripts/``
-4. ``hack/scripts/``
+4. ``raw/scripts/``
+5. ``hack/scripts/``
 
 The structure of the game
 -------------------------

library/Core.cpp

@@ -487,6 +487,7 @@ void Core::getScriptPaths(std::vector<std::string> *dest)
     string df_path = this->p->getPath();
     for (auto it = script_paths[0].begin(); it != script_paths[0].end(); ++it)
         dest->push_back(*it);
+    dest->push_back(df_path + "/dfhack-config/scripts");
     if (df::global::world && isWorldLoaded()) {
         string save = World::ReadWorldFolder();
         if (save.size())