diff --git a/docs/Core.rst b/docs/Core.rst index 2296d1ab7..4fb1fdb71 100644 --- a/docs/Core.rst +++ b/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/``. - Because they don't need to be compiled, scripts are - more flexible about versions, and easier to distribute. - Most third-party DFHack addons are scripts. +:scripts: are Ruby or Lua scripts stored in ``hack/scripts/`` or other + directories in the `script-paths`. Because they don't need to + be compiled, scripts are more flexible about versions, and + they are easier to distribute. Most third-party DFHack addons + are scripts. All tools distributed with DFHack are documented `here `. @@ -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/{}/raw/scripts` (only if a save is loaded) -2. :file:`raw/scripts` -3. :file:`hack/scripts` +#. :file:`dfhack-config/scripts` +#. :file:`data/save/{}/raw/scripts` (only if a save is loaded) +#. :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. diff --git a/docs/changelog.txt b/docs/changelog.txt index eed11d6d6..19f548f30 100644 --- a/docs/changelog.txt +++ b/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 diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 5a9784d24..d1833f600 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2629,8 +2629,8 @@ and are only documented here for completeness: Registers ``path`` as a `script path `. 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 - be searched after. + the default paths (e.g. ``dfhack-config/scripts``, ``hack/scripts``); otherwise, + 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 -a script is simply the script's filename, relative to the scripts folder, with -the extension omitted. For example: +(or any other folder in your `script-paths`) are automatically made available as +DFHack commands. The command corresponding to a script is simply the script's +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 - of searching the Lua library paths (like ``hack/lua``). + searches all `script-paths` for the first matching ``name.lua`` file instead + 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 diff --git a/docs/guides/modding-guide.rst b/docs/guides/modding-guide.rst index e602e632d..9fe62bf6a 100644 --- a/docs/guides/modding-guide.rst +++ b/docs/guides/modding-guide.rst @@ -60,9 +60,10 @@ For scripts with the same name, the `order of precedence ` will be: 1. ``own-scripts/`` -2. ``data/save/*/raw/scripts/`` -3. ``raw/scripts/`` -4. ``hack/scripts/`` +2. ``dfhack-config/scripts/`` +3. ``data/save/*/raw/scripts/`` +4. ``raw/scripts/`` +5. ``hack/scripts/`` The structure of the game ------------------------- diff --git a/library/Core.cpp b/library/Core.cpp index 5b53db98f..bf16d4a7e 100644 --- a/library/Core.cpp +++ b/library/Core.cpp @@ -487,6 +487,7 @@ void Core::getScriptPaths(std::vector *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())