VoxeLibre/mods/ITEMS/mcl_signs/SIGNS_API_DOC.txt

---
--- Generated by EmmyLua.
--- Created by Michieal (FaerRaven).
--- DateTime: 10/22/22 3:44 PM
---

SIGNS API

--- How to Use:

The simplest way to create a new sign is to use mcl_signs.register_sign [mcl_signs.register_sign (modname, color, _name,
ttsign)]. It's an all-in-one sign creator. It makes use of the standard textures for the signs, and colors them based on
the color code that you give it, and names it "mcl_signs:wall_sign" + _name. So, using the spruce sign to illustrate, it
would be named "mcl_signs:wall_sign_sprucewood", as we made _name equal to "_sprucewood" after the name of the
registered wood.

To create a sign with specific textures: use the mcl_signs.register_sign_custom [mcl_signs.register_sign_custom
(modname, _name, tiles, color, inventory_image, wield_image, ttsign)]. Like the register_sign() function, this is also an
all-in-one sign creation function. With this function you can designate what textures to use, and give them a specified
color. This function follows the same naming conventions.

If you wish to override / recreate one of the predefined signs, you may also do that. The reregister_sign() and
reregister_sign_custom() functions will replace an existing sign's definition with a new one. Caution, ONLY use this on
existing signs. If the sign doesn't exist, use the regular register_sign* functions.

--- What the parameters mean, and what they do:

* modname: optional (pass "" or "false" to ignore), for using mcl_signs with other mods to allow the creation of a sign
from the mod's wood (if installed). Use this to prevent failures of the specific mod is not installed that has the needed
information (textures, wood, etc.) Setting this is important, because it prevents items from being registered if the
mod in not installed.

* tiles: the texture file to use for the sign's node.

* color: color the texture file to use with this color. Use white (#FFFFFF) to negate the color, and just use the
texture as is.

* inventory_image: the texture file to use for the sign's display in inventory.

* wield_image: the texture file to use for the sign's weilded (in hand) object.

* _name: the sign's name suffix, such as "_dark" or "_sprucewood", etc., appended to "wall_sign" or "standing_sign"

* ttsign: the tool tip of the sign that gets translated. Shown when the mouse hovers the inventory sign. ttsign stands
for translated tooltip sign.

* wood_item_string: example: "mcl_core:wood", "mcl_core:sprucewood" or "mymod:mywood". This is used when defining the
recipe for the sign.

--- Other Functions of Importance:

* register_dye [mcl_signs.register_dye (modname, item_name, color_code)] -- this registers a new dye that the sign knows
about so that the player can color their signs with the dye.
Parameters:
    modname: your mod / module's name. make sure to use this for compatibility.
    item_name: the item_string of the dye to register.
    color_code: the hex code for the color to make the lettering. Also called HTML color code. Ex. "#FFFFFF" is white.

* register_sign_craft [mcl_signs.register_sign_craft(modname, wood_item_string, _name)] -- this is what creates the
recipes for the sign, and makes the sign "burnable". Typically called right after the register_sign* functions.
Parameters:
    _name: MUST be the same name as used for the sign. So, if your sign _name is "_sprucewood" then this should be too.
    wood_item_string: the item_string of the wood to use for the sign's recipe. Example: "mcl_core:wood" (default oak).
    modname: like with the other functions that has this parameter, used to make sure that nothing breaks.

* make_lbm() [mcl_signs.make_lbm()] -- This innocuous function is very important. This is the function that makes the
signs work after reloading the game. This function is the last to be called in your sign creation work flow. Note, you
do not need to call this function after every definition, just at the end of the last definition.
(See Example WorkFlow below.)

--- Example Workflow for sign creation.

* these are, at the time of writing, a selection of the actual signs' definitions. Note the functions called, and when.

-- ---------------------------- --
--   Register Signs for use.    --
-- ---------------------------- --

-- sprucewood Sign
mcl_signs.register_sign_custom("mcl_core", "_sprucewood",
        "mcl_signs_sign_dark.png","#ffffff", "default_sign_dark.png",
        "default_sign_dark.png", "Spruce Sign"
)
mcl_signs.register_sign_craft("mcl_core", "mcl_core:sprucewood", "_sprucewood")

-- darkwood Sign
mcl_signs.register_sign_custom("mcl_core", "_darkwood",
        "mcl_signs_sign_greyscale.png","#856443", "default_sign_greyscale.png",
        "default_sign_greyscale.png", "Dark Oak Sign"
)
mcl_signs.register_sign_craft("mcl_core", "mcl_core:darkwood", "_darkwood")

-- acaciawood Sign
mcl_signs.register_sign("mcl_core", "#ea7479", "_acaciawood", "Acacia Sign")
mcl_signs.register_sign_craft("mcl_core", "mcl_core:acaciawood", "_acaciawood")

-- junglewood Sign
mcl_signs.register_sign("mcl_core", "#866249", "_junglewood", "Jungle Sign")
mcl_signs.register_sign_craft("mcl_core", "mcl_core:junglewood", "_junglewood")

-- Register the LBMs for the created signs.
mcl_signs.make_lbm()

--- -----------------------------------------------------------------------------

* If you wish to use a recipe other than the standard sign recipe, you will need to define your own recipe. In doing so,
use this output line:
    output = "mcl_signs:wall_sign" .. _name .. " 3",
where _name is the same string that you have used throughout your sign's workflow. That way, when players make the recipe,
they get your sign (x3).

--- Future landmarks on the horizon for the Signs API:

* Once the forthcoming Hanging Signs are in Minecraft, and we implement the code for them in here, hanging signs will
automatically exist as part of the signs' package. You won't have to change any of your code, it'll just be more
functional. :)

* if you have suggestions, comments, etc., please contact me on VoxeLibre's Discord server.

And that... is all there is to it!

-- written by Michieal.