Merge pull request #2538 from myk002/myk_script_paths

add dfhack-config/scripts to default script paths
develop
Myk 2023-01-02 20:41:13 -08:00 committed by GitHub
commit 3ccf6034b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 35 additions and 27 deletions

@ -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.

@ -21,10 +21,11 @@ DFHack commands can be implemented in any of three ways:
same version of DFHack. They are less flexible than scripts, same version of DFHack. They are less flexible than scripts,
but used for complex or ongoing tasks because they run faster. 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>`. 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` #. Pressing a key combination set up with `keybinding`
#. From one of several `init-files`, automatically #. From one of several `init-files`, automatically
#. Using `script` to run a batch of commands from a file #. 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 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: 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 #. 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` #. :file:`data/save/{world}/raw/objects`
For each of those directories, all matching init files will be executed in 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 On startup, DFHack looks for files of the form ``dfhack*.init`` (where ``*`` is
a placeholder for any string, including the empty string). 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. 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 run. By default, the following folders are searched, in order (relative to the
root DF folder): 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 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. ``teleport.lua`` or ``teleport.rb``, and the first matching file is run.

@ -39,6 +39,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
## Misc Improvements ## Misc Improvements
- Scrollable widgets now react to mouse wheel events when the mouse is over the widget - 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 ## Documentation
- `overlay-dev-guide`: added troubleshooting tips and common development workflows - `overlay-dev-guide`: added troubleshooting tips and common development workflows

@ -2629,8 +2629,8 @@ and are only documented here for completeness:
Registers ``path`` as a `script path <script-paths>`. Registers ``path`` as a `script path <script-paths>`.
If ``search_before`` is passed and ``true``, the path will be searched before 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 Returns ``true`` if successful or ``false`` otherwise (e.g. if the path does
not exist or has already been registered). not exist or has already been registered).
@ -5466,11 +5466,11 @@ Scripts
:local: :local:
Any files with the ``.lua`` extension placed into the :file:`hack/scripts` folder 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`` * :file:`hack/scripts/gui/teleport.lua` is invoked as ``gui/teleport``
.. note:: .. note::
@ -5487,12 +5487,6 @@ the extension omitted. For example:
a mod developer would want to run a script from the console, it should a mod developer would want to run a script from the console, it should
not be placed in this folder) 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 Scripts are read from disk when run for the first time, or if they have changed
since the last time they were run. since the last time they were run.
@ -5520,7 +5514,7 @@ General script API
* ``dfhack.run_script(name[,args...])`` * ``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 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. 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 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 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 Most scripts can be made to support ``reqscript()`` without significant
changes (in contrast, ``require()`` requires the use of ``mkmodule()`` and changes (in contrast, ``require()`` requires the use of ``mkmodule()`` and

@ -60,9 +60,10 @@ For scripts with the same name, the `order of precedence <script-paths>` will
be: be:
1. ``own-scripts/`` 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 The structure of the game
------------------------- -------------------------

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