Add central API documentation hub

Wuzzy 2017-02-21 21:28:58 +01:00
parent 0a28c15e32
commit db7a3e9f03
2 changed files with 133 additions and 101 deletions

126
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.

108
GROUPS.md Normal file

@ -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.