diff --git a/API.md b/API.md index 0eda36b1..60236b70 100644 --- a/API.md +++ b/API.md @@ -1,112 +1,36 @@ # API - -This document is a WORK IN PROGRESS. Currently, it only contains some information about the used groups. - ## Groups -This section explains all the used groups in this subgame. +MineClone 2 makes very extensive use of groups. Making sure your items and objects are members of the correct group is a good and easy way to ensure compability without using any function calls. +Groups are explained in `GROUPS.md`. -### Special groups +## APIs for adding simple things +You can add simple things by calling functions in the various MineClone 2 mods. -* `not_in_creative_inventory=1`: Item will not be shown in creative inventory -* `not_in_craft_guide=1`: Item will not be shown as result or fuel item in crafting guide (but still may be shown as ingredient) +* Fences and fence gates: See `mods/ITEMS/mcl_fences/API.md`. +* Walls: See `mods/ITEMS/mcl_walls/API.md` -### Groups for interactions +### Undocumented APIs +You can also add stuff for the following thins, but the APIs are currently undocumented. These mods are very similar to Minetest Game. -* `dig_by_water=1`: Blocks with this group will drop when they are near flowing water -* `cultivatable=2`: Block will be turned into Farmland by using a hoe on it -* `cultivatable=1`: Block will be turned into Dirt by using a hoe on it -* `flammable`: Block helps spreading fire and gets destroyed by nearby fire (rating doesn't matter) -* `soil=1`: Saplings and other small plants can grow on it -* `soil_sapling=2`: Soil for saplings. Intended to be natural soil. All saplings will grow on this -* `soil_sapling=1`: Artificial soil (such as farmland) for saplings. Some saplings will not grow on this -* `soil_sugarcane=1`: Sugar canes will grow on this near water -* `soil_nether_wart=1`: Nether wart will grow on this -* `disable_suffocation=1`: Disables suffocation for full solid cubes (1) -* `destroys_items=1`: If an item happens to be *inside* this node, the item will be destroyed +* Doors: See `mods/ITEMS/doors` +* Stairs and slabs: See `mods/ITEMS/stairs` and `mods/ITEMS/mcstair` +* Beds: See `mods/ITEMS/beds` +* Buckets (for new liquids): See `mods/ITEMS/bucket` +* Panes (like glass panes and iron bars): See `mods/ITEMS/xpanes` -#### Footnotes +WARNING! These 5 mods may be renamed or changed in future releases, and compability could be broken. -1. Normally, all walkable blocks with the default 1×1×1 cube as a collision box (e.g. sand, - gravel, stone, but not fences) will damage the players while their head is inside. This - is called “suffocation”. Setting this group disables this behaviour +## Mobs +This mod uses Mobs Redo [`mobs`] by TenPlus1, a very powerful mod for adding mods of various kinds. +There are minor modificiations for MineClone 2 compability and some items have been removed or moved to other mods, but the API is identical to the original. +You can add your own mobs, spawn eggs and spawning rules with this mod. +API documnetation is included in `mods/ENTITIES/mobs/api.txt`. -### Groups (mostly) used for crafting recipes +Note that mobs in MineClone 2 are still very experimental, everything about mobs may change radically at any time! -* `sand=1`: Sand (any color) -* `sandstone=1`: (Yellow) sandstone and related nodes (chiseled and the like) (only full blocks) -* `redsandstone=1`: Red sandstone and related nodes (chiseled and the like) (only full blocks) -* `quartz_block=1`: Quartz Block and variants (chiseled, pillar, etc.) (only full blocks) -* `stonebrick=1`: Stone Bricks and related nodes (only full blocks) -* `shulker_box=1`: Block is a shulker box -* `tree=1`: Oak Wood, Birch Wood, etc. (tree trunks) -* `wood=1`: Oak Wood Planks, Birch Wood Planks, etc. (only full blocks) -* `wood_slab=1`: Slabs made out of a kind of wooden planks -* `wood_stairs=1`: Stairs made out of a kind of wooden planks -* `coal=1`: Coal of any kind (lumps only, not blocks) -* `wool=1`: Wool (only full blocks) -* `carpet=1:` (Wool) carpet -* `stick=1`: Stick +## Other APIs +* Statbars / HUD bars: See `mods/HUD/hudbars` +* Hunger: See `mods/PLAYER/mcl_hunger/API.md` -### Declarative groups -These groups are used mostly for informational purposes - -* `solid=1`: Solid block (automatically assigned) -* `not_solid=1`: Block is sold (only assign this group for nodes which are automatically detected as “solid” in error -* `water=1`: Water -* `lava=1`: Lava -* `torch`: Torch or torch-like node - * `torch=1`: Torch on floor - * `torch=2`: Torch at wall -* `liquid`: Block is a liquid - * `liquid=1`: Unspecified type - * `liquid=2`: Water - * `liquid=3`: Lava -* `fence=1`: Fence -* `fence_gate=1`: Fence gate -* `fence_wood=1`: Wooden fence -* `fence_nether_brick=1`: Nether brick fence -* `flower_pot`: Flower pot - * `flower_pot=1`: Empty flower pot - * `flower_pot=2`: Flower pot with a plant or flower -* `book=1`: Book -* `pane=1`: Node is a “pane”-like node glass pane or iron bars -* `bed=1`: Bed -* `door=1`: Door -* `door=2`: Trapdoor -* `rail=1`: Rail -* `music_record`: Music Disc (rating is track ID) -* `tnt=1`: Block is TNT -* `boat=1`: Boat -* `minecart=1`: Minecart -* `food`: Item is a comestible item which can be consumed (healthy or unhealthy) - * `food=2`: Food - * `food=3`: Drink (including soups) - * `food=1`: Other/unsure -* `eatable`: Item can be *directly* eaten by wielding + left click (`on_use=item_eat`). Rating is the satiation gain -* `cocoa`: Node is a cocoa pod (rating is growth stage, ranging from 1 to 3) -* `ammo=1`: Item is used as ammo for a weapon -* `ammo_bow=1`: Item is used as ammo for bows -* `container`: Node is a container which physically stores items within and has at least 1 inventory - * `container=2`: Has one inventory with list name `"main"`. Items can be placed and taken freely - * `container=3`: Same as `container=2`, but shulker boxes can not be inserted - * `container=4`: Furnace-like, has lists `"src"`, `"fuel"` and `"dst"` - * `container=1`: Other/unspecified container type -* `spawn_egg=1`: Spawn egg - -* `weapon=1`: Item is primarily (!) a weapon -* `tool=1`: Item is primarily (!) a tool -* `craftitem=1`: Item is primarily (!) used for crafting -* `brewitem=1`: Item is primarily (!) used in brewing -* `transport=1`: Item is used for transportation -* `building_block=1`: Block is a building block -* `deco_block=1`: Block is a decorational block - -## Fake item groups -These groups put similar items together which should all be treated by the gameplay or the GUI as a single item. -You should not add custom items to these groups for no good reason, this is likely to cause a ton of conflicts. - -* `clock=1`: Clock -* `compass`: Compass (rating doesn't matter) - -This has the following implication: If you want to use a compass or clock in a crafting recipe, you *must* -use `group:compass` or `group:clock`, respectively. +## Other things of interest +Mods found in `mods/CORE` contain important core APIs and utility functions, used throughout the subgame. diff --git a/GROUPS.md b/GROUPS.md new file mode 100644 index 00000000..52962f44 --- /dev/null +++ b/GROUPS.md @@ -0,0 +1,108 @@ +## Groups +This document explains all the groups used in this subgame. + +### Special groups + +* `not_in_creative_inventory=1`: Item will not be shown in creative inventory +* `not_in_craft_guide=1`: Item will not be shown as result or fuel item in crafting guide (but still may be shown as ingredient) + +### Groups for interactions + +* `dig_by_water=1`: Blocks with this group will drop when they are near flowing water +* `cultivatable=2`: Block will be turned into Farmland by using a hoe on it +* `cultivatable=1`: Block will be turned into Dirt by using a hoe on it +* `flammable`: Block helps spreading fire and gets destroyed by nearby fire (rating doesn't matter) +* `soil=1`: Saplings and other small plants can grow on it +* `soil_sapling=2`: Soil for saplings. Intended to be natural soil. All saplings will grow on this +* `soil_sapling=1`: Artificial soil (such as farmland) for saplings. Some saplings will not grow on this +* `soil_sugarcane=1`: Sugar canes will grow on this near water +* `soil_nether_wart=1`: Nether wart will grow on this +* `disable_suffocation=1`: Disables suffocation for full solid cubes (1) +* `destroys_items=1`: If an item happens to be *inside* this node, the item will be destroyed + +#### Footnotes + +1. Normally, all walkable blocks with the default 1×1×1 cube as a collision box (e.g. sand, + gravel, stone, but not fences) will damage the players while their head is inside. This + is called “suffocation”. Setting this group disables this behaviour + +### Groups (mostly) used for crafting recipes + +* `sand=1`: Sand (any color) +* `sandstone=1`: (Yellow) sandstone and related nodes (chiseled and the like) (only full blocks) +* `redsandstone=1`: Red sandstone and related nodes (chiseled and the like) (only full blocks) +* `quartz_block=1`: Quartz Block and variants (chiseled, pillar, etc.) (only full blocks) +* `stonebrick=1`: Stone Bricks and related nodes (only full blocks) +* `shulker_box=1`: Block is a shulker box +* `tree=1`: Oak Wood, Birch Wood, etc. (tree trunks) +* `wood=1`: Oak Wood Planks, Birch Wood Planks, etc. (only full blocks) +* `wood_slab=1`: Slabs made out of a kind of wooden planks +* `wood_stairs=1`: Stairs made out of a kind of wooden planks +* `coal=1`: Coal of any kind (lumps only, not blocks) +* `wool=1`: Wool (only full blocks) +* `carpet=1:` (Wool) carpet +* `stick=1`: Stick + +### Declarative groups +These groups are used mostly for informational purposes + +* `solid=1`: Solid block (automatically assigned) +* `not_solid=1`: Block is sold (only assign this group for nodes which are automatically detected as “solid” in error +* `water=1`: Water +* `lava=1`: Lava +* `torch`: Torch or torch-like node + * `torch=1`: Torch on floor + * `torch=2`: Torch at wall +* `liquid`: Block is a liquid + * `liquid=1`: Unspecified type + * `liquid=2`: Water + * `liquid=3`: Lava +* `fence=1`: Fence +* `fence_gate=1`: Fence gate +* `fence_wood=1`: Wooden fence +* `fence_nether_brick=1`: Nether brick fence +* `flower_pot`: Flower pot + * `flower_pot=1`: Empty flower pot + * `flower_pot=2`: Flower pot with a plant or flower +* `book=1`: Book +* `pane=1`: Node is a “pane”-like node glass pane or iron bars +* `bed=1`: Bed +* `door=1`: Door +* `door=2`: Trapdoor +* `rail=1`: Rail +* `music_record`: Music Disc (rating is track ID) +* `tnt=1`: Block is TNT +* `boat=1`: Boat +* `minecart=1`: Minecart +* `food`: Item is a comestible item which can be consumed (healthy or unhealthy) + * `food=2`: Food + * `food=3`: Drink (including soups) + * `food=1`: Other/unsure +* `eatable`: Item can be *directly* eaten by wielding + left click (`on_use=item_eat`). Rating is the satiation gain +* `cocoa`: Node is a cocoa pod (rating is growth stage, ranging from 1 to 3) +* `ammo=1`: Item is used as ammo for a weapon +* `ammo_bow=1`: Item is used as ammo for bows +* `container`: Node is a container which physically stores items within and has at least 1 inventory + * `container=2`: Has one inventory with list name `"main"`. Items can be placed and taken freely + * `container=3`: Same as `container=2`, but shulker boxes can not be inserted + * `container=4`: Furnace-like, has lists `"src"`, `"fuel"` and `"dst"` + * `container=1`: Other/unspecified container type +* `spawn_egg=1`: Spawn egg + +* `weapon=1`: Item is primarily (!) a weapon +* `tool=1`: Item is primarily (!) a tool +* `craftitem=1`: Item is primarily (!) used for crafting +* `brewitem=1`: Item is primarily (!) used in brewing +* `transport=1`: Item is used for transportation +* `building_block=1`: Block is a building block +* `deco_block=1`: Block is a decorational block + +## Fake item groups +These groups put similar items together which should all be treated by the gameplay or the GUI as a single item. +You should not add custom items to these groups for no good reason, this is likely to cause a ton of conflicts. + +* `clock=1`: Clock +* `compass`: Compass (rating doesn't matter) + +This has the following implication: If you want to use a compass or clock in a crafting recipe, you *must* +use `group:compass` or `group:clock`, respectively.