Definition Ripper

Generate inert facades from node/item definitions for use in other games

Building Chat / Commands Creative Decorative API / Library

Download (26 KB)

How do I install this?

Node/Item Definition Ripper

You're making a puzzle/adventure game, and you need building materials for the scenery. It's a bother to make all original artwork, or you like the look and feel of something that already exists, but it comes with all this extra functionality that you don't want...

This mod will allow you to export the "superficial" definitions and media for selected items. This includes visuals, sounds, and basic physical properties (solid/liquid/gas, climbable, lighting) but none of the callbacks or other gameplay behavior. This makes them ideal for:

  • "inert" decorative nodes in "adventure" gameplay modes where most of the scenery is non-interactable and only a few puzzle pieces have specific mechanics.
  • exporting your sculptures and builds as playable games (e.g. using modgen to convert a build into a mapgen mod) with only carefully chosen mechanics receated (e.g. working doors for access) but without the rest.
  • pruning a complex game, with a lot of unused items, definitions, and mechanics, for smaller downloads, faster load times, and reduced memory usage.

The hope is that this mod will allow experienced creative-mode builders to use familiar tools to build scenery, backgrounds, maps and levels, and then export those things for use in games. Formats like schematics, worldedit or modgen provide the "geometry" aspect of map export; this mod can be used to get the "material" aspect.

Usage

Add the mod to a game that has all the things loaded that you want to export, instruct the mod which items to export (using chat commands), and it will dump the start of a mod that can be used to import item registrations into your game.

You will get a folder in your worldpath containing a skeletal mod:

  • All media files referenced by the items, split into textures/sounds/models.
  • An exported.lua file with each definition.
  • A mediasource.json file that identifies the mod source of each media file included, for help tracing licensing and attribution.
  • A defripper.json file that stores the configuration, and can be used to "rehydrate" the configuation in another world with the same mods installed, making it possible to incrementally extend the extracted data without needing to keep the entire original world around.

You will need to provide your own init.lua, mod.conf and other infrastructure, but the exported definitions are kept in a separate file so you can safely overwrite it later (e.g. if you add definitions) without destroying your custom logic.

exported.lua takes a register_item-like function as a file-level parameter.

  • This function will receive a single parameter with the definition table; it does NOT get an item name.
  • There is a _raw_name key inside the definition from which you will need to derive your own name in a manner you deem appropriate (you have an opportunity to customize before registration here).
  • Aliases are exported using the same format, but they will only have an _alias_to that will point to the _raw_name of the node the alias is pointing to.

Example:

local modname = minetest.get_current_modname()
loadfile(minetest.get_modpath(modname) .. "/exported.lua")(function(def)
    local myname = modname .. ":" .. def._raw_name:gsub(":", "__")
    if def._alias_to then
        local myalias = modname .. ":" .. def._alias_to:gsub(":", "__")
        return minetest.register_alias(myname, myalias)
    end
    def._raw_name = nil
    return minetest.register_item(myname, def)
end)

By keeping your custom logic and overrides in a separate set of files, and not modifying the defripper output files, you can just delete and reimport the auto-generated content any time you want to change the set of items you're exporting, or any time you pull updates from upstream and want to marge them into your own version.

Licensing Warning

You are still responsible for complying with licensing for all media files in the export. This includes:

  • Tracing the origin of each file (the names should match, and be unique in any sane setup) and identifying the author and original license.
  • Including attribution/credit in your resultant project.
  • Complying with sublicensing requirements when selecting the license for your own projet containing these media.
  • Anything else required by the license that applies to any file you use.

This tool may also rip media from "private" mods you might have installed, including things you don't actually have the right to redistribute; you are responsible for manually ensuring these are not included in any product you create using this tool.

Commands

Minetest "items" includes all nodes, craftitems and tools. The definition ripper mod supports exporting all of them, though it is more focused on nodes.

Basic Commands

Hand-pick which definitions to export.

  • /defripper - re-export all item definitions already marked for export (saved in mod storage).
  • /defripper_clear - clear all saved definitions.
  • /defripper_add <pattern> - add all definitions whose technical name (modname:item_name) matches the given lua pattern.
  • /defripper_rm <pattern> - remove all definitions whose technical name (modname:item_name) matches the given lua pattern.
  • /defripper_inv - add all definitions for items currently in the player's inventory.

Area-Scanning Commands

Automatically export all materials used in an area.

For each of these commands, if the defripper_node_inv setting is true (default false), it will descend into node meta inventories and rip items found there as well.

  • /defripper_here [rx [ry [rz]]] - rip all nodes/items within a cuboid/rectanguloid centered around the player, right now.
  • /defripper_step [rx [ry [rz [step]]]] - rip all nodes/items within a cuboid/rectanguloid centered around the player, continuously, every time the player moves step nodes, until the server is restarted or command is re-run to change it. /defripper_step 0 disables it.

Extra Media Commands

Add additional media to the export, even if not referenced directly by a definition.

This is useful if you intend to recreate some mechanics/behavior in the downstream product, and want to include the media associated with it that aren't directly referenced by the definition itself. Example: door opening/closing sounds.

  • /defripper_m_add <pattern> - add all media whose filename matches the given lua pattern.
  • /defripper_m_rm <pattern> - remove all media whose filename matches the given lua pattern.

Advanced Usage

Recreating World for Updates

It is not necessary to keep the original world you used defripper on to update your definitions, so long as you can recreate that world with the same mods.

  • The defripper export contains its config, and you can copy it all back into the corresponding dir in the recreated world to restore state.
  • defripper will warn you if there are any mods you're missing when trying to re-export. Finding the correct version, when forks exist, is still your responsibility, so you may want to keep note of which versions things were based on.
  • Media files are NOT updated by default if they already exist in the dump, so you can use alternative or texturepack versions if you want. New ones are still added, and unused ones are still pruned. If you want to force an update, remove the affected media from the export.

Custom Property Filtering

A customfilter.lua file can be loaded in the defripper dir inside the world path. If present, it will be loaded each time definitions are dumped. It must return a function, which:

  • Takes (filtered, name, def) as input parameters
  • filtered is the definition to dump, pre-filtered by defripper.
  • name is the original name of the registered item.
  • def is the original registered item definition.
  • Returns one of:
  • nil to keep the existing filtered table for the export (which can also be modified by the filter function in-place).
  • false to exclude this item entirely from export.
  • any table, to replace the filtered table in the export.

Example customfilter.lua that excludes all non-node items:

return function(filtered, name, def)
    if def.type ~= "node" then return false end
    return filtered -- or nil
end

Reviews

Review

Do you recommend this mod?

  • Picking the raisins out of the cake

    Definition ripper is a very useful mod when you have a game and want to extract just the basic building blocks out of it, trimming off the gameplay, survival elements and any other fat that'll most likely just slow things down. Take the exported definitions from the mod, put it into an empty game, drag in i3 (or your inventory mod of choice) and WorldEdit and you've gotten yourself a minimal and lightweight creative building experience.

    For my usecase, I wanted to basically scoop out all the nodes from Mineclonia to reduce as much overhead caused by the (admittedly rather heavy) game as possible for a very large map of Gothenburg, such that flying around will load mapblocks as quickly as the engine possibly can load them.

    Some notes, from when I used it:

    • This is specific to Mineclonia, but there is a bug in the current version of the game that causes this mod to crash when attempting to rip the redstone dust node due to the nodebox table being malformed. (See #754 for more details and a fix)
    • If you're ripping the entirety of a large game, you might run up against the Lua locals limit (which is 200). If a tiles table for a node is used more than once, then it will put it in a local variable for reuse. But this becomes quite an issue when ripping a large amount of nodes if it reuses more than 200 tables. Workaround would be to turn all the locals into globals (s/local //g) but the better solution would be reducing the amount of nodes you're exporting, since you most likely are ripping an excessive amount of nodes anyways. This has now been fixed as of release v02664935.
    • Aliases won't be ripped, which led to my map having cute little "Unknown Node" trees caused by Mineclonia's tree refactor. You'll have to copy any necessary aliases manually, or make sure no aliases from the game are required if you're loading an existing map.
    0 comments