diff --git a/docs/plugins/changelayer.rst b/docs/plugins/changelayer.rst index 87c27921c..535409e90 100644 --- a/docs/plugins/changelayer.rst +++ b/docs/plugins/changelayer.rst @@ -1,60 +1,72 @@ changelayer =========== -Changes material of the geology layer under cursor to the specified inorganic -RAW material. Can have impact on all surrounding regions, not only your embark! -By default changing stone to soil and vice versa is not allowed. By default -changes only the layer at the cursor position. Note that one layer can stretch -across lots of z levels. By default changes only the geology which is linked -to the biome under the cursor. That geology might be linked to other biomes -as well, though. Mineral veins and gem clusters will stay on the map. Use -`changevein` for them. - -tl;dr: You will end up with changing quite big areas in one go, especially if -you use it in lower z levels. Use with care. - -Options: - -:all_biomes: Change selected layer for all biomes on your map. - Result may be undesirable since the same layer can AND WILL - be on different z-levels for different biomes. Use the tool - 'probe' to get an idea how layers and biomes are distributed - on your map. -:all_layers: Change all layers on your map (only for the selected biome - unless 'all_biomes' is added). - Candy mountain, anyone? Will make your map quite boring, - but tidy. -:force: Allow changing stone to soil and vice versa. !!THIS CAN HAVE - WEIRD EFFECTS, USE WITH CARE!! - Note that soil will not be magically replaced with stone. - You will, however, get a stone floor after digging so it - will allow the floor to be engraved. - Note that stone will not be magically replaced with soil. - You will, however, get a soil floor after digging so it - could be helpful for creating farm plots on maps with no - soil. -:verbose: Give some details about what is being changed. -:trouble: Give some advice about known problems. - -Examples: + +Tags: +:dfhack-keybind: + +Change the material of an entire geology layer. Note that one layer can stretch +across many z-levels, and changes to the geology layer will affect all +surrounding regions, not just your embark! Mineral veins and gem clusters will +not be affected. Use `changevein` if you want to modify those. + +tl;dr: You will end up with changing large areas in one go, especially if you +use it in lower z levels. Use this command with care! + +Usage:: + + changelayer [] + +When run without options, ``changelayer`` will: + +- only affect the geology layer at the current cursor position +- only affect the biome that covers the current cursor position +- not allow changing stone to soil and vice versa + +You can use the `probe` command on various tiles around your map to find valid +material RAW ids and to get an idea how layers and biomes are distributed. + +Options +------- + +- ``all_biomes`` + Change the corresponding geology layer for all biomes on your map. Be aware + that the same geology layer can AND WILL be on different z-levels for + different biomes. +- ``all_layers`` + Change all geology layers on your map (only for the selected biome unless + ``all_biomes`` is also specified). Candy mountain, anyone? Will make your map + quite boring, but tidy. +- ``force`` + Allow changing stone to soil and vice versa. **THIS CAN HAVE WEIRD EFFECTS, + USE WITH CARE AND SAVE FIRST**. Note that soil will not be magically replaced + with stone. You will, however, get a stone floor after digging, so it will + allow the floor to be engraved. Similarly, stone will not be magically + replaced with soil, but you will get a soil floor after digging, so it could + be helpful for creating farm plots on maps with no soil. +- ``verbose`` + Output details about what is being changed. + +Examples +-------- ``changelayer GRANITE`` - Convert layer at cursor position into granite. + Convert the layer at the cursor position into granite. ``changelayer SILTY_CLAY force`` - Convert layer at cursor position into clay even if it's stone. + Convert teh layer at the cursor position into clay, even if it's stone. ``changelayer MARBLE all_biomes all_layers`` Convert all layers of all biomes which are not soil into marble. .. note:: * If you use changelayer and nothing happens, try to pause/unpause the game - for a while and try to move the cursor to another tile. Then try again. - If that doesn't help try temporarily changing some other layer, undo your - changes and try again for the layer you want to change. Saving - and reloading your map might also help. + for a while and move the cursor to another tile. Then try again. If that + doesn't help, then try to temporarily change some other layer, undo your + changes, and try again for the layer you want to change. Saving and + reloading your map also sometimes helps. * You should be fine if you only change single layers without the use - of 'force'. Still it's advisable to save your game before messing with + of 'force'. Still, it's advisable to save your game before messing with the map. - * When you force changelayer to convert soil to stone you might experience - weird stuff (flashing tiles, tiles changed all over place etc). - Try reverting the changes manually or even better use an older savegame. - You did save your game, right? + * When you force changelayer to convert soil to stone, you might see some + weird stuff (flashing tiles, tiles changed all over place etc). Try + reverting the changes manually or even better use an older savegame. You + did save your game, right? diff --git a/plugins/changelayer.cpp b/plugins/changelayer.cpp index 79081c040..347f29b95 100644 --- a/plugins/changelayer.cpp +++ b/plugins/changelayer.cpp @@ -31,66 +31,14 @@ DFHACK_PLUGIN("changelayer"); REQUIRE_GLOBAL(world); REQUIRE_GLOBAL(cursor); -const string changelayer_help = - " Allows to change the material of whole geology layers.\n" - " Can have impact on all surrounding regions, not only your embark!\n" - " By default changing stone to soil and vice versa is not allowed.\n" - " By default changes only the layer at the cursor position.\n" - " Note that one layer can stretch across lots of z levels.\n" - " By default changes only the geology which is linked to the biome under the\n" - " cursor. That geology might be linked to other biomes as well, though.\n" - " Mineral veins and gem clusters will stay on the map.\n" - " Use 'changevein' for them.\n\n" - " tl;dr: You will end up with changing quite big areas in one go.\n\n" - "Options (first parameter MUST be the material id):\n" - " all_biomes - Change layer for all biomes on your map.\n" - " Result may be undesirable since the same layer\n" - " can AND WILL be on different z-levels for different biomes.\n" - " Use the tool 'probe' to get an idea how layers and biomes\n" - " are distributed on your map.\n" - " all_layers - Change all layers on your map.\n" - " Candy mountain, anyone?\n" - " Will make your map quite boring, but tidy.\n" - " force - Allow changing stone to soil and vice versa.\n" - " !!THIS CAN HAVE WEIRD EFFECTS, USE WITH CARE!!\n" - " Note that soil will not be magically replaced with stone.\n" - " You will, however, get a stone floor after digging so it\n" - " will allow the floor to be engraved.\n" - " Note that stone will not be magically replaced with soil.\n" - " You will, however, get a soil floor after digging so it\n" - " could be helpful for creating farm plots on maps with no soil.\n" - " verbose - Give some more details about what is being changed.\n" - " trouble - Give some advice for known problems.\n" - "Example:\n" - " changelayer GRANITE\n" - " Convert layer at cursor position into granite.\n" - " changelayer SILTY_CLAY force\n" - " Convert layer at cursor position into clay even if it's stone.\n" - " changelayer MARBLE allbiomes alllayers\n" - " Convert all layers of all biomes into marble.\n"; - -const string changelayer_trouble = - "Known problems with changelayer:\n\n" - " Nothing happens, the material stays the old.\n" - " Pause/unpause the game and/or move the cursor a bit. Then retry.\n" - " Try changing another layer, undo the changes and try again.\n" - " Try saving and loading the game.\n\n" - " Weird stuff happening after using the 'force' option.\n" - " Change former stone layers back to stone, soil back to soil.\n" - " If in doubt, use the 'probe' tool to find tiles with soil walls\n" - " and stone layer type or the other way round.\n"; - - command_result changelayer (color_ostream &out, std::vector & parameters); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &commands) { commands.push_back(PluginCommand( - "changelayer", "Change a whole geology layer.", - changelayer, false, /* true means that the command can't be used from non-interactive user interface */ - // Extended help string. Used by CR_WRONG_USAGE and the help command: - changelayer_help.c_str() - )); + "changelayer", + "Change a whole geology layer.", + changelayer)); return CR_OK; } @@ -120,13 +68,7 @@ command_result changelayer (color_ostream &out, std::vector & para { if(parameters[i] == "help" || parameters[i] == "?") { - out.print("%s",changelayer_help.c_str()); - return CR_OK; - } - if(parameters[i] == "trouble") - { - out.print("%s",changelayer_trouble.c_str()); - return CR_OK; + return CR_WRONG_USAGE; } if(parameters[i] == "force") force = true;