The Rubble script loader is a small piece of code Rubble uses to load DFHack scripts and script modules from the save directory. Without this loader you can still load commands from the save directory, but not modules.
The thing is, if you want your mod to have lots of DFHack powered reactions/workshops/etc you need a lot of scripts, and most of those scripts will either duplicate each other or you will have custom modules with shared APIs. The problem is "how do you install these modules?" By default they need to be placed in the "hack/lua" directory, which works fine most of the time, but for custom modules you either need to distribute a preinstalled version of your mod or you need to make sure your users install the required scripts. Another big problem is the fact that you can only share saves with other users that have the required modules installed, which is something of a pain.
This loader fixes all that.
This loader was written for use with Rubble (hence the name) but there is no real reason it can't be used by itself, so here it is (complete with extra comments to make up for not having the Rubble documentation).
The new loader (needed to use scripts from Rubble):
--
-- Rubble pseudo-module loader.
--
-- This code provides support for functionality sorta like `dfhack.script_environment`, but with a
-- syntax and usage much more like the Lua default "require" mechanism. In addition automatic
-- unloading is provided for modules that need it.
--
-- This loader also provides "live reloading", basically this makes the scripting system think the world
-- was unloaded, then reloaded, refreshing the scripts. This is invaluable when debugging a module.
-- Sadly this feature does not refresh the entire scripting state, as that would be basically impossible.
--
-- A pseudo-module is structured mostly like a module that you would use with the default require, but
-- with the following differences:
--
-- * Use `rubble.mkmodule` rather than `mkmodule`
-- * You can provide an optional onUnload function that will be called when the world is unloaded.
-- * You can provide an optional onStateChange function that will be called for all state change events
-- *except* `SC_WORLD_LOADED` and `SC_WORLD_UNLOADED` (don't look at me, it's a DFHack bug).
--
-- Using a pseudo-module is the same as using a default module, with the following difference:
--
-- * Use `rubble.require` instead of `require`.
--
-- `rubble.require` is fairly talented, if it can't find a module it will try `dfhack.script_environment`
-- and finally the default `require`, so you can just use it in all cases and it will load the module no
-- matter what underlying module mechanism was used.
--
-- Important Globals and Loader Functions
-- This little song-and-dance creates a new global table named "rubble".
dfhack.BASE_G.rubble = {}
-- Don't touch, internal.
rubble.__modules = {}
-- Don't touch, internal.
function rubble.__load_module(name)
local modfile = SAVE_PATH.."/raw/modules/"..name..".lua"
-- If the given pseudo module does not exist first try "dfhack.script_environment" and then "require".
if not dfhack.filesystem.exists(modfile) then
if not dfhack.findScript(name) then
return require(name), nil
end
return dfhack.script_environment(name), nil
end
env = {}
setmetatable(env, { __index = dfhack.BASE_G })
local f, perr = loadfile(modfile, 't', env)
if f then
local ok, module = pcall(f)
if not ok or not module then
return nil, module
end
rubble.__modules[name] = module
return module, nil
end
return nil, perr
end
-- Registers a single value as a module, useful for making small modules for special purposes.
-- Unlike the other module functions you can overwrite existing modules with this.
function rubble.forcemodule(name, module)
rubble.__modules[name] = module
end
-- Use exactly like "mkmodule"
-- If called with the name of an existing module it will return a reference to the existing module.
function rubble.mkmodule(name)
if rubble.__modules[name] ~= nil then
return rubble.__modules[name]
end
env = {}
setmetatable(env, { __index = dfhack.BASE_G })
return env
end
-- "Extend" an existing module.
-- Makes a new module that has the API of the old module, plus whatever you add to it,
-- the old module is not modified.
-- This should work even if the parent uses "dfhack.script_environment" or the default
-- "require" mechanism.
function rubble.extendmodule(parent, name)
if rubble.__modules[name] ~= nil then
return rubble.__modules[name]
end
local parentmod = rubble.__modules[parent]
if parentmod == nil then
-- rubble.require errors out if the module does not exist in any form.
parentmod = rubble.require(parent)
end
env = {}
setmetatable(env, { __index = parentmod })
return env
end
-- Use like "require", but for modules made with "rubble.mkmodule".
-- If the module does not exist this fails over to trying to load the module with
-- "dfhack.script_environment", then the default "require". If both of those fail
-- loading aborts with an error.
function rubble.require(name)
if rubble.__modules[name] == nil then
local mod, err = rubble.__load_module(name)
if err ~= nil then
qerror(err)
end
return mod
end
return rubble.__modules[name]
end
-- Refresh any DFHack startup scripts and Rubble pseudo-modules.
-- Some scripts may not like this! In general the only problems will be scripts
-- that start global actions and do not handle being called multiple times gracefully.
-- If your script can be called twice in a row with no ill effect then it should be
-- fine.
-- I don't/can't fully refresh the scripting system, as there is far too much room for
-- error, so in general the only things that get refreshed are pseudo modules and save
-- init scripts, which is generally sufficient, particularly since this is for use with
-- Rubble, which makes heavy use of both.
--
-- Oddly DFHack does not appear to call `onStateChange` for the `SC_WORLD_LOADED` *or*
-- `SC_WORLD_UNLOADED` events. Upon further consideration there is really no reason to,
-- as scripts are run on load, and `onUnload` is called when the world is unloaded, but
-- this behavior seems strange and may be a bug.
function rubble.refresh()
-- Amazingly this is all that is needed.
-- For some odd reason unloading is carried out for both events, I guess as insurance
-- for missed unload events.
dfhack.onStateChange.DFHACK_PER_SAVE(SC_WORLD_LOADED)
end
function onUnload()
for _, module in pairs(rubble.__modules) do
if module.onUnload ~= nil then
module.onUnload()
end
end
rubble.__modules = {}
end
function onStateChange(state)
for _, module in pairs(rubble.__modules) do
if module.onStateChange ~= nil then
module.onStateChange(state)
end
end
end
The old loader (needed if you want to use some of the old scripts I have posted)
----------------------------------------------------------------------------------------------------
--Begin-Rubble-Script-Loader------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------
-- This code will load any Lua scripts from "raw/dfhack" whenever you load a world.
--
-- I feel safe in saying that, with my work on powered workshops, I probably have more experience with
-- loading lots of DFHack script at once than any other modder. This experience has shown me that the
-- default mechanisms are cumbersome when you are loading more than 4-5 scripts (and I often load
-- many, many more than that). This loader in intended to make it easy to load lots of scripts with
-- minimal modder effort.
--
-- Scripts that end with ".mod.lua" will be loaded as modules (you can use them with rubble.require)
-- whereas scripts that end with ".start.lua" will be loaded directly when the world loads.
-- You can use module files ("raw/dfhack/*.mod.lua") with normal commands (scripts in "raw/scripts"),
-- not just start scripts ("raw/dfhack/*.start.lua").
--
-- You do not need to worry about when a world loads or unloads (in most cases), as the loader takes
-- care of these details for you, just create an unload function (as described later) if you need to
-- and let to loader do the work.
--
-- ".mod.lua" files may have an "onUnload" function that is automatically called when the world is
-- unloaded, ".start.lua" files may add a function to the "rubble.unloaders" table to accomplish the
-- same thing. This is a convenience, as you could do the same thing by hooking the state change event
-- yourself.
--
-- This loader is somewhat similar to "dfhack.script_environment", but it is far more flexible, with
-- special support for cleanup, refreshing (during development), and automatic startup without having
-- to register scripts individually.
--
-- When you have 50+ scripts not having to list them all in the onload.init file is a great time saver
-- and it can also prevent bugs related to renaming a script and forgetting to update the onload.init
-- or forgetting to list a required script. Also being able to easily and quickly refresh the scripts
-- (via the ":lua rubble.reload_scripts()" command) is an invaluable help during mod development, as
-- it makes it easy to make changes to a script and see them immediately in game.
--
-- While most (if not all) of the things this loader can do can also be done with the vanilla mechanisms,
-- this loader does them in a more elegant and simple fashion. Since I use this code with all my mods
-- (most of which include large amounts of DFHack Lua code) it is highly optimized for ease of use.
-- Important Globals and Loader Functions
-- This little song-and-dance creates a new global table named "rubble".
dfhack.BASE_G.rubble = {}
-- The save directory path, stored here as a little used convenience.
rubble.savedir = SAVE_PATH
-- Don't touch, internal.
rubble.modules = {}
-- You can add functions to this table to be called when the world is unloaded, not needed for modules
-- (they have their own onUnload functions), but useful for start scripts.
rubble.unloaders = {}
-- Don't touch, internal.
function rubble.load_script(name)
env = {}
setmetatable(env, { __index = dfhack.BASE_G })
local f, perr = loadfile(name, 't', env)
if f then
return safecall(f)
end
dfhack.printerr(" Error: "..perr)
end
-- Don't touch, internal.
function rubble.load_module(name)
env = {}
setmetatable(env, { __index = dfhack.BASE_G })
local f, perr = loadfile(rubble.savedir.."/raw/dfhack/"..name..".mod.lua", 't', env)
if f then
local ok, module = pcall(f)
if not ok or not module then
return nil, module
end
rubble.modules[name] = module
return module, nil
end
return nil, perr
end
-- Registers a single value as a module, useful for making small modules for special purposes.
-- Unlike the other module functions you can overwrite existing modules with this.
function rubble.forcemodule(name, module)
rubble.modules[name] = module
end
-- Use exactly like "mkmodule"
-- If called with the name of an existing module it will return a reference to the existing module.
function rubble.mkmodule(name)
if rubble.modules[name] ~= nil then
return rubble.modules[name]
end
env = {}
setmetatable(env, { __index = dfhack.BASE_G })
return env
end
-- Use like "require", but for modules made with "rubble.mkmodule"
function rubble.require(name, path)
if rubble.modules[name] == nil then
local mod, err = rubble.load_module(name)
if err ~= nil then
qerror(err)
end
return mod
end
return rubble.modules[name]
end
-- Called when the world is unloaded to take care of any cleanup that may be needed.
function rubble.unload_scripts()
for _, unload in pairs(rubble.unloaders) do
unload()
end
for _, module in pairs(rubble.modules) do
if module.onUnload ~= nil then
module.onUnload()
end
end
rubble.modules = {}
rubble.unloaders = {}
end
-- This function will load all the scripts, feel free to call this as often as you like on loaded
-- worlds to refresh the scripts.
function rubble.reload_scripts()
rubble.unload_scripts()
local scrlist = dfhack.internal.getDir(rubble.savedir.."/raw/dfhack/")
if scrlist then
table.sort(scrlist)
for i,name in ipairs(scrlist) do
if string.match(name,'%.start.lua$') then
print(" "..name)
rubble.load_script(rubble.savedir.."/raw/dfhack/"..name)
end
end
else
print(" No startup scripts installed.")
end
end
rubble.reload_scripts()
-- Use this instead of onUnload so that other users of init.lua can use onUnload without problems.
dfhack.onStateChange.Rubble_Loader = function(code)
if code == SC_WORLD_UNLOADED then
rubble.unload_scripts()
dfhack.onStateChange.Rubble_Loader = nil
end
end
----------------------------------------------------------------------------------------------------
--End-Rubble-Script-Loader--------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------
From now on any script modules I upload will use this loader, as it is too hard to maintain Rubble and vanilla versions of everything.
Author
Topic: Rubble Script Loader: In-save DFHack script and module loader. (Read 3115 times)