signs_lib/API.md

Signs_lib API

In this text, common terms such as pos, node, or placer/digger will not be explained unless they have a different meaning than what's usually used in Minetest mods. See minetest/doc/lua_api.txt for details on these and other common terms, if necessary. Similarly, common shorthand such as int, float, etc. should require no explanation.

Registering a sign

• signs_lib.register_sign(nodename, def)

  To put it simply, where you'd have used minetest.register_node() before, just replace it with this call. The syntax is identical, and in general, all settings/items allowed there are allowed here as well. Anything that signs_lib doesn't need to override or alter will be passed straight through to register_node(), unchanged (such as description, tiles, or inventory_image).

  The supplied nodename will be prepended with ":", so that any mod can register signs under any other mod's namespace, if desired.

  Many items have default settings applied when omitted, most of which would produce something equivalent to "default:sign_wall_wood" if enough other node defintion settings were to be included.

  • drawtype = "string"

    Default: "mesh"

  • mesh = "string"

    Default: "signs_lib_standard_wall_sign.obj".

  • paramtype = "string"

    Default: "light"

  • paramtype2 = "string"

    As with any other node, this determines how param2 is interpreted. Since these are signs, only two modes make sense: "wallmounted" and "facedir". Any other string is the same as "facedir".

    Default: "wallmounted"

  • wield_image = "string"

    Default: whatever the inventory_image is set to (if anything).

  • groups = {table}

    Sets the sign's groups, as usual. In addition to whatever arbitrary groups you may have in mind, there are two presets available (both of which have attached_node removed, and sign = 1 added):

    • signs_lib.standard_wood_groups, inherited from "default:sign_wall_wood"
    • signs_lib.standard_steel_groups, inherited from "default:sign_wall_steel"

    Default: signs_lib.standard_wood_groups

  • sounds = something

    Sets the sign's sound profile, as usual. In addition to whatever sound profile you may have in mind, there are two presets available:

    • signs_lib.standard_wood_sign_sounds, inherited from "default:sign_wall_wood"
    • signs_lib.standard_steel_sign_sounds, inherited from "default:sign_wall_steel"

    Default: signs_lib.standard_wood_sign_sounds

  • drop = something

    Default: inherited from the nodename argument given to signs_lib.register_sign()

  • after_place_node = function(pos, placer, itemstack, pointed_thing, locked)

    See below under "Main functions".

    Default: signs_lib.after_place_node

  • on_rightclick = function(pos)

    See below under "Main functions".

    Default: signs_lib.construct_sign

  • on_construct = function(pos)

    See below under "Main functions".

    Default: signs_lib.construct_sign

  • on_destruct = function(pos)

    See below under "Main functions".

    Default: signs_lib.destruct_sign

  • on_receive_fields = function(pos, formname, fields, sender)

    See below under "Main functions".

    Default: signs_lib.receive_fields

  • on_punch = function(pos)

    See below under "Main functions".

    Default: signs_lib.update_sign

  • default_color = "string"

    Sets the default text color for this sign, in hexadecimal (0-9, a-f), from the standard Linux/IRC/CGA color palette. Same as the colors shown in the sign's formspec.

    Default: "0" (black)

  • number_of_lines = int

    Just what it says on the tin. How many lines you can fit will vary with overall sign node size, font size, scaling, line spacing, etc.

    Default: 6

  • horiz_scaling = float

    Scaling factor applied to the entity texture horizontal resolution. Larger values increase the resolution. Since a given sign's entity is always displayed at a fixed visual scale, increasing this setting squeezes more pixels into the same horizontal space, making the text appear narrower.

    Default: 1.0

  • vert_scaling = float

    Scaling factor applied to the entity texture's vertical resolution. Larger values increase the resolution, making the text appear shorter, and increasing the number of lines the sign can display.

    Default: 1.0

  • line_spacing = int

    Number of blank pixels to add between lines.

    Default: 1

  • font_size = int

    Selects which font to use, either 15 or 31 (pixel height). This setting directly affects the sign's vertical resolution.

    Default: 15

  • x_offset = int

    Starting X position in pixels, relative to the text entity UV map left edge.

    Default: 4

  • y_offset = int

    Starting Y position in pixels, relative to the text entity UV map top edge.

    Default: 0

  • chars_per_line = int

    Approximate number of characters that should fit on a line. This, the selected font's average character width, and the horiz_scaling together set the horizontal resolution of the text entity's texture.

    Default: 35

  • entity_info = something

    Describes the entity model and yaw table to use. May be one of:

    • A table specifying the two directly, such as:

      entity_info = {
        mesh = "signs_lib_standard_wall_sign_entity.obj",
        yaw = signs_lib.wallmounted_yaw
      }
      

      • signs_lib.standard_yaw is also available as a yaw preset, if desired.

    • "standard": just use the standard wood/steel sign model, in wallmounted mode. Equivalent to the example above.

    • If this item is nil/not set, the sign will not have a formspec, basically all text-related settings will be ignored and/or omitted entirely, and no entity will be spawned for this sign, thus the sign will not be writable. This is the default, and is of course what one would want for any sign that's just an image wrapped around a model, as in most of the signs in my street signs mod.

  • allow_hanging = bool

    If true, allow the registration function to create a "hanging from the ceiling" version of the initial, base sign node.

    Default: nil

  • allow_onpole = bool

    Allow creation of an on-pole variant of the base sign.

    Default: nil

  • allow_onpole_horizontal = bool

    Allow creation of an on-horizontal-pole variant. This flag is independent of allow_onpole; the mod may specify either or both.

    Default: nil

  • allow_widefont = bool

    Just what it says on the tin. If enabled, the formspec will have a little "on/off switch" left of the "Write" button, to select the font width.

    Default: nil

  • locked = bool

    Sets this sign to be locked/owned, like the original default steel wall sign.

    Default: nil

Example sign definition:

signs_lib.register_sign("basic_signs:sign_wall_glass", {
	description = S("Glass Sign"),
	tiles = {
		{ name = "basic_signs_sign_wall_glass.png", backface_culling = true},
		"basic_signs_sign_wall_glass_edges.png",
	},
	inventory_image = "basic_signs_sign_wall_glass_inv.png",
	default_color = "c",
	locked = true,
	entity_info = "standard",
	sounds = default.node_sound_glass_defaults(),
	groups = {cracky = 3, oddly_breakable_by_hand = 3},
	allow_hanging = true,
	allow_widefont = true,
	allow_onpole = true,
	allow_onpole_horizontal = true,
	use_texture_alpha = true,
})

Main functions used within a sign definition

• signs_lib.after_place_node(pos, placer, itemstack, pointed_thing, locked)

  Determines if the pointed_thing is a wall, floor, ceiling, or pole/post, and swaps the placed sign for the correct model.

  • locked: if set to true, the sign's meta will be tweaked to indicate its ownership by the placer.

• signs_lib.construct_sign(pos)

  Sets up the sign's formspec and infotext overlay.

• signs_lib.destruct_sign(pos)

  Deletes the sign's entity, if any, when the sign is dug.

• signs_lib.receive_fields(pos, formname, fields, sender)

  This handles the text input and wide font on/off switch, logging any actions the user takes. Bails-out silently if the user is not allowed to edit the sign. See the standard Minetest lua_api.txt for details.

• signs_lib.update_sign(pos, fields)

  If the sign's writable, this deletes any entities in the sign's node space, spawns a new one, and renders whatever text is in the sign's meta.

• signs_lib.can_modify(pos, player)

  Returns true if the player is allowed to dig, edit, or change the font width of the sign.

• signs_lib.handle_rotation(pos, node, player, mode)

  Just what it says on the tin. Limits the sign's rotation as needed (for example, a sign on a horizontal pole can only flip from one side to the other).

  • mode: the screwdriver's mode, as passed from the screwdriver mod.

  Returns false if the user tried to right-click with the screwdriver, true otherwise.

• signs_lib.make_selection_boxes(x_size, y_size, foo, x_offset, y_offset, z_offset, is_facedir)

  • x_size/y_size: dimensions in inches. One node is 39.37 inches on a side. This function uses inches instead of metric because it started out as a selection box maker for MUTCD-compliant signs, which are measured in inches.
  • x_offset/y_offset/z_offset: shift the selection box (inches, defaults to centered, with the back face flush with the back of the node).
  • is_facedir: if unset, the selection boxes will be created with the assumption that paramtype2 = "wallmounted" mode is set. Any other value creates a selection box for "facedir" mode.
  • foo is ignored (leftover from an argument that's long since been rendered obsolete.

  Returns a table suitable for the selection_box node definition entry.

Helper functions

You probably won't need to call any of these directly.

• signs_lib.read_image_size(filename)

  Returns width and height of the indicated PNG file (return values will be gibberish if it isn't a PNG).

• signs_lib.split_lines_and_words(text)

  Just what it says on the tin.

  Returns a table of lines, each line entry being a table of words.

• signs_lib.delete_objects(pos)

  Deletes all entities within the node space given by pos.

• signs_lib.spawn_entity(pos, texture)

  Spawns a new text entity at the given position and assigns the supplied texture to it, if any.

• signs_lib.check_for_pole(pos, pointed_thing)

  Attempts to determine if the pointed_thing qualifies as a vertical pole or post of some kind.

  Returns true if a suitable pole/post is found

• signs_lib.check_for_horizontal_pole(pos, pointed_thing)

  Same idea, but for horizontal poles/posts.

  Returns true if a suitable pole/post is found.

• signs_lib.check_for_ceiling(pointed_thing)

  Returns true if the pointed_thing appears to be the bottom of a node.

• signs_lib.check_for_floor(pointed_thing)

  Returns true if the pointed_thing appears to be the top of a node.

• signs_lib.set_obj_text(pos, text)

  Cooks the supplied text as needed and passes it to the entity rendering code. Essentially, this is where rendering text into an image starts.

Options for pole/post nodes

Occasionally, you'll run into a node that either looks like a pole/post, or has one in the middle of its node space (with room to fit a sign in there), but which isn't detected as a pole/post by the standard sign placement code. In these situations, some kind of special check is needed.

Supplying one or both of the following in the pole/post node's definition will cause signs_lib to skip its usual pole/post detection code, in favor of the supplied function(s).

• check_for_pole = function(pos, node, def, pole_pos, pole_node, pole_def)

  If supplied, this function will be run when the mod is looking for a normal vertical pole/post. Useful if the target node's orientation and/or shape determine what sides a sign can attach to. For example, Pipeworks uses this to figure out if a sign can be attached to a tube or pipe, depending on the tube's/pipe's number of junctions, and on its orientation and that of the placed sign.

  • def: the placed sign's node defintion
  • pole_pos: the target node's position
  • pole_node: the target node itself
  • pole_def: its node definition

  Your code must return true if the sign should attach to the target node.

  If desired, this entry may simply be set to check_for_pole = true if a sign can always attach to this node regardless of facing direction (for example, Home Decor has a round brass pole/post, which always stands vertical, and Cottages has a simple table that's basically a fencepost with a platform on top).

• check_for_horiz_pole = function(pos, node, def, pole_pos, pole_node, pole_def)

  If supplied, this does the same thing for horizontal poles.

  Your code must return true if the sign should attach to the target node.