Usage Guide for signs_lib


This is kaeza's and my signs_lib mod, based on code from PilzAdam and thexyz. This mod, unlike the original signs included in Minetest, puts the text you've entered right onto the sign (and it also shows up when pointed at, like default signs do, in case the on-sign text isn't readable on a particular system). By default, this mod supplies your basic wooden signs in various orientations, metal wall signs in various colors, and a locked wooden sign.

sign-nodes Zoom

This mod offers 4 basic shapes of signs, and over a dozen unique nodes counting the locked and metal signs. The brass and wrought iron models seen at the far right in this were added by my Home Decor mod.
If you place a sign against any vertical surface, it becomes a regular wall sign (duh :-) ), and placing a wooden one on the ground causes it to appear standing upright on a small "stick". The "hanging from the ceiling" version appears when you place a wooden sign on any inverted horizontal (e.g. ceiling) surface. If you need to place a wooden sign on a default wood fencepost, simply do exactly that. That is to say, place a fencepost, then point at it and place a regular wooden sign. The mod will combine the two into one node. Note that at the moment, this only works with default wood fenceposts, not pine, acacia, or others, or default wooden gates.

When you dig a sign on a fencepost, you get the sign back first, then you can dig the fencepost if you need to.

The colored metal signs (seen at the far left) will only form the wall variant when placed, regardless of the surface you point at. The default metal sign can be placed on the wall, flat on the ground, or flat against the ceiling (same as the upstream one), though in the latter two orientations, the text will not be shown. Metal signs do not form yard/hanging/fencepost variants yet (this behavior will change eventually).

sign-colors Zoom

The best part of these signs is that they support full-color text! To change text colors, simply use the # sign followed by a single hexadecimal digit from 0 to f to change colors. Any number of color changes may be used on a sign.

sign-formspec Zoom

Here, you can see the "code" that was used to create the colorful example sign from the previous picture.
The signs use the standard Linux/IRC/CGA color palette, which is shown numerically at the bottom of the sign in the picture at the left. Some of the colored metal signs will default to either red or white text, as appropriate, all other signs default to black.

This sign was created by placing a default wooden sign "on" the ground, automatically forming a "yard" sign, and then just inserting several number codes among the text, as shown at the left and below.

Text automatically word-wraps when it exceeds the horizontal margins of the sign, once you commit it. To explicitly insert a line break, just press enter.

If you need a blank line, write a single space, then press enter (e.g. a space on a line by itself).

The signs offer a multi-line editor to make it easy to enter your text, but please keep the following limitations in mind when writing: The editor does not attempt to limit how much you can type in. The rendered results will usually look different from what you typed, owing to the fact that you won't see the raw "#x" codes on the sign, and of course differences between the sign's display font and the editor/formspec font.

sign-green1

Use two dark green dye and one white dye as shown here to get a green sign with a white border.
sign-green2

...you can use sheet metal in place of default metal signs in all of these recipes.
sign-yellow1

Use two yellow dye and one black dye for the yellow sign with black border.
sign-red

Use two red dye and one white dye for the red sign with white border.
sign-white-red

Use two white dye and one red dye for the white sign with red border.
sign-white-black

Use two white dye and one black dye for the white sign with black border.
sign-orange

Use two orange dye and one black dye for the orange sign with black border.
sign-blue

Use two blue dye and one white dye for the blue sign with white border.
sign-brown

Use two brown dye and one white dye for the brown sign with white border.

In addition to the wooden signs shown above, you can also craft metal signs in several color combinations, as shown at the left. Such signs are intended more for use on roadways than in the home, but since they're part of signs_lib, that's why they're described here. :-)

You can craft these signs using either a default metal sign or three pieces of sheet metal from certain forks of Zeg9's Steel mod, plus three portions of dye above it/them, as shown. When crafted with sheet metal, the recipe will yield 2.

locked-sign If you would like to make one of the locked signs seen above, craft it from five wood, one steel ingot, and one stick, in the pattern shown here. Yields 1.

This type of sign is only available in the "on wall" shape, as with the metal signs.

locked-sign You can also place a regular wooden sign and one steel ingot into the crafting grid to get a locked sign.

API

Signs_lib is mostly hard-coded, but it does have an internal API with a few public options. For now, you can at least call into signs_lib to define a sign on a fencepost, and you can set a few basic properties specific to how signs_lib displays them. Other features will be added over time, including the ability to define other signs types. Be sure that you add signs_lib to your mod's depends.txt.

Start by defining a node in the usual way - just the name, textures, shape, digging groups, sound, and so on - via minetest.register_node() as you would with any other node. Your node definition need only be as "complex" as, say, a block of cobble (save for the shape of course) - you don't need to include any active code in the node definition, as signs_lib will take care of that. Design the shape of your node such that it looks like a sign attached to a fencepost. If necessary, define the fencepost also. Within the node definition for the sign, you can set a few properties.

Default shape:

If your fencepost-sign model is nodebox-based (as opposed to, say, a meshnode), signs_lib has a standard nodebox model for it that you can pass directly to your node's nodebox={} field:

	node_box = signs_lib.sign_post_model.nodebox,

If you're not using a nodebox-based model, you can just ignore this field, as with any other node.

Text position/rotation:

Like the nodebox, signs_lib provides a standard constant you can use to set the text positions and rotations of the entity that attaches to your sign. For simplicity, just add this to your node definition:

	text_pos = signs_lib.sign_post_model.textpos,

If you'd rather get more detailed, do this instead:

	text_pos = {
		{delta = { x = 0,    y = 0.07, z = -0.2 }, yaw = 0},
		{delta = { x = -0.2, y = 0.07, z = 0    }, yaw = math.pi / -2},
		{delta = { x = 0,    y = 0.07, z = 0.2  }, yaw = math.pi},
		{delta = { x = 0.2,  y = 0.07, z = 0    }, yaw = math.pi / 2},
	},

Each line here represents one of the four directions the sign can face. Since signs on fenceposts can't face up or down, we only need to worry about the four horizontal faces. These entries thus represent signs facing 0, 180, 270, and 90 degrees, and describe the offset of the text entity relative to the center of the node space, and the yaw/rotation of the text entity, in radians. Only the non-zero coordinates here matter - you'll want to leave the four zeroed-out coordinates alone. You will want to set your non-zeroed X/Z coordinates such that the text entity appears slightly in front of the surface of the node (to account for Minetest/irrlicht positioning errors).

This field does not have a default - you must set it to something meaningful.

Horizontal/vertical text scale:

	text_scale = { x=0.8, y=0.5 },

You can alter the height and width of the text entity using the above. These are also the default settings.

Default text color:

	default_color = "<hex digit>",

This item takes a single hexadecimal digit from 0 to f (in lowercase, without a preceding "#"). All text on the sign will be drawn in this color unless the person writing the sign text changes it via the above color codes. The default is 0 (black).

Restore-sign-text LBM:

Whenever a block is loaded from the map database, the Minetest engine runs any LBM's (Loading Block Modifiers), checking if any nodes need to be altered at load time. Signs_lib hooks into this feature, using it to check if any signs are missing their text entities, restoring as needed. This is so that the text eventually re-appears after something like /clearobjects (or the World Edit equivalent) is executed. To make sure your node is included in these checks, you will need to register an LBM for it, triggering signs_lib's functions, like so:

	minetest.register_lbm({
		nodenames = "<your node name>",
			-- You could also use a table of node names.
		name = "signs_lib:restore_sign_text",
		label = "Restore sign text",
		run_at_every_load = true,
		action = function(pos, node)
			signs_lib.update_sign(pos)
		end
	})

This code can go anywhere you want, but put it outside of any node definitions (for example, you could put it near the start of your init.lua, after your constants and variables).

Sign register function:

	signs_lib.register_fence_with_sign(fencepost_node_name, sign_node_name)

This will cause signs_lib to modify your node definition, adding the text-entry formspec, adding/updating the text display entity, and adding functions so that when you place a default wooden wall sign against the fencepost you chose, the fencepost will be replaced with your sign-on-fencepost node instead. As with the default wooden sign on wooden fencepost, you get the sign back when you dig, and then the fence after that if you keep digging.

Example:

	signs_lib.register_fence_with_sign("homedecor:fence_brass", "homedecor:fence_brass_with_sign")
Other stuff: There are a handful of other global functions and constants in signs_lib, but they are not intended for public use as such (they're only global because the engine needs them to be). It is recommended not to access/use them.