API.md

   1 # Shifted Blocks API documentation
   2 Here's how you add a shifted block:
   3
   4 First, you always need a block which should be shifted. This block **must**
   5 have at least one texture and it **should** be a full-sized cube. Make
   6 sure this block is registered already.
   7
   8 Then, call `shifted_blocks.register_shifted_block`.
   9
  10 If for some reason you need some extra customization, you can try to use
  11 `minetest.override_item` after the block has been registered. Try to avoid
  12 this.
  13
  14 ## `shifted_blocks.register_shifted_block(itemstring, original_block, description, side_texture, help, block_texture, no_craft)`
  15 Registers a shifted block variant of an existing block (which must be
  16 registered *before* this function is called.
  17
  18 The texture on 4 sides will be shifted by a half block length. Two sides will
  19 be the “cross-section” of the block so the block has a phyically consistent
  20 look.
  21
  22 This also registers two crafting recipes of this shape
  23 (unless `no_craft==true`):
  24
  25     XX
  26
  27 * If `X` is the original block: Yields 2 shifted blocks.
  28 * If `X` is the shifted block: Yields 2 original blocks.
  29
  30 ### Parameters
  31
  32 * `itemstring`: Itemstring of the shifted block to register
  33 * `original_block`: Itemstring of the original (unshifted) block
  34 * `description`: Description of the shifted block. Recommended style:
  35     “Shifted `<name of original block>`”.
  36 * `side_texture`: Optional. If set, this is used as the texture of the
  37     “open” side of the shifted block. It is recommended to make it look
  38     like a cross-section of the block.
  39     Default: Same as the 1st texture of the original block
  40 * `help`: Optional. If set, add a custom help text for this block
  41     (for `doc_items`). You normally don't need this, there is a sane default.
  42 * `block_texture`: Optional. If set, this is the texture which should be
  43     “shifted”. Only set this if it really differs from the original.
  44     Default: 1st texture of the original block.
  45 * `no_craft`: Optional. If `true`, no crafting recipes are registered.
  46     Default: `false`
  47 * `free_rotation`: Optional: If `true`, rotation by screwdriver is unrestricted.
  48     Default: Rotation is restricted to 3 axes
  49
  50 ### Return value
  51
  52 `nil`.