diff --git a/api.txt b/api.txt index 8048cd5..b835062 100644 --- a/api.txt +++ b/api.txt @@ -2,112 +2,212 @@ Lucky Block API =============== -Please make sure that lucky_block appears in the depends.txt file of your mod. +This guide will show you how to add schematic files and lucky blocks from +within your own mods. Please make sure that lucky_block appears in the +depends.txt file of your mod so everything work properly. -USAGE: (check blocks.lua for many examples) - -lucky_block:add_block({line}) +Function Usage +============== -LINE COMMANDS: +Purge Block List +---------------- + +lucky_block:purge_block_list() + +This command is used to clear all of the blocks in the lucky block list so that +you can add your own. --= Place Node +Add Lucky Blocks to list +------------------------ + +lucky_block:add_blocks({ block definitions here }) + +This command is used to add new blocks to the lucky block list. + +e.g. + +lucky_block:add_blocks({ + {"nod", "default:dirt", 0}, + {"dro", {"default:dirt"}, 5}, +}) + + +Purge Chest Items +----------------- + +lucky_block:purge_chest_items() + +This command is used to purge all items in the default chest list so that you +can add your own. + + +Add Items to Default Chest +-------------------------- + +lucky_block:add_chest_items({ add new default chest items here }) + +This command lets you add new items to the default chest when it appears +inside a lucky block. + +e.g. + +lucky_block:add_chest_items({ + {name = "default:apple", max = 3}, + {name = "default:steel_ingot", max = 2}, + {name = "default:pick_steel", max = 1} +}) + + +Add Schematics to List +---------------------- + +lucky_block:add_schematics({ add new schematic definitions here }) + +This command lets you add schematic files and arrays to the list so they can +be added to the lucky block list. + +e.g. check for Ethereal mod then get the path and add two of the tree's to the +schematic list and finally to the lucky block list: + +if minetest.get_modpath("ethereal") then + local path = minetest.get_modpath("ethereal") .. "/schematics/" + + lucky_block:add_schematics({ + -- name on list, schematic, offset placement + {"appletree", ethereal.appletree, {x = 1, y = 0, z = 1}}, + {"bananatree", ethereal.bananatree, {x = 3, y = 0, z = 3}}, + } + + lucky_block:add_blocks({ + {"sch", "appletree", 0, false}, + {"sch", "bananatree", 0, false}, + }) +end + + +Lucky Block Commands +==================== + +Using the lucky_block:add_blocks() command gives you access to many features +from within this mod, these are listed below using this general format: + +lucky_block:add_blocks({ + {"command", command options}, + ..etc +}) + + +Place Node +---------- + +This command will place a node in place of the lucky block or at the players +standing position. {"nod", "node name", position, chest items} e.g. -Replace Lucky Block with Dirt Block +Place a dirt block where lucky block was + {"nod", "default:dirt", 0} -Place Fire at player position - {"nod", "fire:basic_flame", 1} +Place a chest containing random items from default chest items list -Replace Lucky Block with chest containing random items from default list {"nod", "default:chest", 0} -Replace Lucky Block with chest containing random items PLUS a few extra -{"nod", "default:chest", 0, {{name="flowers:rose", max=5}, {name="default:goldblock", max=2}}} +Place chest as above only add up to 5x roses as well + + {"nod", "default:chest", 0, { {name = "flowers:rose, max = 4} }} + +Place fire at player position + + {"nod", "fire:basic_flame", 1} --= Drop Item(s) +Drop Item(s) +------------ -{"dro", {"item names"}, number to drop, random colour} +This command will throw a single or multiple items out of a lucky block, +random colours can be used also. + +{"dro", {"item names"}, how many to drop, use random colours} e.g. -Drop 5x Torches +Drop 5x torches {"dro", {"default:torch"}, 5} -Drop 10x randomly Coloured Wool (colour name added to end of item string) +Drop 10x randomly coloured wool (colour name added to end of item string) {"dro", {"wool:"}, 10, true} -Drop 5x random Tools from list - {"dro", {"default:pick_mese", "default:shovel_steel", "default:axe_diamond"}, 5} +Drop 1x random tool from list + {"dro", {"default:pick_mese", "default:shovel_steel", "default:axe_diamond"}, 1} --= Place Schematic +Place Schematic +--------------- -Add schematic file to main list before adding lucky block: - -lucky_block:add_schematics({ - {"name", schematic filename or definition, {offset}}, -end - -e.g. - -lucky_block:add_schematics({ - {"platform", platform, {x = 2, y = 0, z = 2}}, -}) - -then you can add the lucky block containing the schematic: +This command lets you place a pre-added schematic file or definition in place +of the lucky block or at the player position. {"sch", "schematic name", position, force placement} e.g. -Remove lucky block and build lucky platform in it's place -{"sch", "platform", 0, true} +Place lucky platform at player position and force placement + {"sch", "platform", 1, true} -Place apple tree at player position -{"sch", "appletree", 1, false} +Place apple tree where lucky block use to be + {"sch", "appletree", 0, false} --= Spawn Entity(s) +Spawn Entity or Mob +------------------- -{"spw", "entity name", number to spawn, tamed, owned, range} +This command allows you to place a monster, animal or other entity. + +{"spw", "entity name", how many to spawn, tamed, owned, range} e.g. Spawn 2x Dirt Monsters over a radius of 10 blocks {"spw", "mobs:dirt_monster", 2, nil, nil, 10} -Spawn 5x randomly coloured Sheep (random colour only works with sheep) +Spawn 5x randomly coloured sheep (random colour only works with Mobs Redo sheep) {"spw", "mobs:sheep", 5} -Spawn NPC who is tamed and owned by player +Spawn a single NPC who is tamed and owned by player {"spw", "mobs:npc", 1, true, true} --= Falling Blocks +Falling Blocks +-------------- -{"fal", {node list}, position, spread, range} +This command allows for a tower of blocks or blocks falling within a set area. + +{"fal", {"node list"}, position, spread, range} e.g. -Drop 2x Sand and 1x Gold Block and spread over range of 5 blocks +Drop 2x sand and 1x gold block spread over a range of 5 blocks {"fal", {"default:sand", "default:sand", "default:goldblock"}, 0, true, 5} -Drop 2x Obsidian onto player - {"fal", {"default:obsidian", "default:obsidian"}, 1} +Drop 3x obsidian onto player as a tower + {"fal", {"default:obsidian", "default:obsidian", "default:obsidian"}, 1} --= Troll Block +Troll Block +----------- -{"tro", "node name", "sound", explosion}, +This command is similar to the place node command only it allows for a sound to +be played on placement, then after two seconds the block will disappear or +can explode causing damage to nearby players. + +{"tro", "node name", "sound", explode} e.g. @@ -120,12 +220,11 @@ Add gold block with wood sound, then after 2 seconds remove with pop {"tro", "default:goldblock", "default_wood_footstep", nil} --= Explosion (no settings, Lucky Block explodes and deals damage to all nearby) +Random Teleport +--------------- -{"exp"} - - --= Teleport (no settings, player teleports +/- 10 blocks in any direction) +This command will teleport the player opening the lucky block a random number +of blocks away using a preset range. {"tel", horizontal range, vertical range} @@ -136,47 +235,36 @@ Teleport player to random position 10 blocks left/right and 5 blocks up/under {"tel", 10, 5} --= Lightning Strike (Player is hit by lightning and deals damage with fire) +Explosion +--------- + +Now we start adding the bad lucky blocks that cause damage to the player by +exploding. + +{"exp"} + + +Lightning Strike +---------------- + +This is one of my favourite commands, lightning strikes the player and hurts +everyone else nearby, can also place fire at strike position. {"lig", "fire node"} e.g. -Lightning strike with temporary fire +Strike player and place temporary fire {"lig", "fire:basic_flame"} -Lightning strike with permanent fire +Strike player and place permanent flame {"lig", "fire:permanent_flame"} -Additional Commands thanks to blert2112 +Final Words +=========== -lucky_block:purge_block_list() - -This removes all pre-defined lucky blocks and leaves the super lucky block. - - -lucky_block:purge_chest_items() - -This removes all pre-defined chest_stuff items and leaves it empty. - - -lucky_block:add_chest_items(list) - -This command adds items to the chest_stuff list for use inside of lucky chests: - -lucky_block:add_chest_items({ - {name = "default:apple", max = 3}, - {name = "default:steel_ingot", max = 2}, - {name = "default:gold_ingot", max = 2}, - {name = "default:diamond", max = 1}, - {name = "default:pick_steel", max = 1} -}) - - -lucky_block:add_schematics({line}) - -This adds a schematic to the main list before adding the actual lucky block -that contains the schematic reference name (see schems.lua for examples). +I hope this guide helps you add lucky blocks from within your own mods and for +more examples please check out the blocks.lua and schems.lua files.