Update API documentation

This commit is contained in:
Pierre-Yves Rollo 2018-12-11 14:58:11 +01:00
parent d073c9edb8
commit b98e97157c

35
API.md

@ -1,38 +1,38 @@
# Display Lib API # Display API
This document describes Display Lib API. Display Lib allows to add a dynamic display on a node. Display Lib limits node rotations. For wallmounted, only vertical positionning is available, and for facedir, only first four position are availabel (those with default axis). This document describes Display API. Display API allows to add a dynamic display on a node. Display API limits node rotations. For wallmounted, only vertical positionning is available. For facedir, only first four position are availabel (those with default axis).
## Provided methods ## Provided methods
### update\_entities ### update\_entities
**display\_lib.update\_entities(pos)** **display\_api.update\_entities(pos)**
This method triggers entities update for the display node at pos. Actual entity update is made by `on_display_update` callback associated to the entity. This method triggers entities update for the display node at pos. Actual entity update is made by `on_display_update` callback associated to the entity.
`pos`: Position of the node `pos`: Position of the node
### register\_display\_entity ### register\_display\_entity
**display\_lib.register\_display\_entity(entity_name)** **display\_api.register\_display\_entity(entity_name)**
This is a helper to register entities used for display. This is a helper to register entities used for display.
`entity_name`: Name of the entity to register. `entity_name`: Name of the entity to register.
## Provided callback implementations ## Provided callback implementations
### on_place ### on_place
**display\_lib.on\_place(itemstack, placer, pointed\_thing)** **display\_api.on\_place(itemstack, placer, pointed\_thing)**
`on_place` node callback implementation. Display nodes should have this callback (avoid placement of horizontal display node). `on_place` node callback implementation. Display nodes should have this callback (avoid placement of horizontal display node).
### on_construct ### on_construct
**display\_lib.on\_construct(pos)** **display\_api.on\_construct(pos)**
`on_construct` node callback implementation. Display nodes should have this callback (creates, places and updates display entities on node construction). `on_construct` node callback implementation. Display nodes should have this callback (creates, places and updates display entities on node construction).
### on_destruct ### on_destruct
**display\_lib.on_destruct(pos)** **display\_api.on_destruct(pos)**
`on_destruct` node callback implementation. Display nodes should have this callback (removes display entities on node destruction). `on_destruct` node callback implementation. Display nodes should have this callback (removes display entities on node destruction).
### on_rotate ### on_rotate
**display\_lib.on\_rotate(pos, node, user, mode, new_param2)** **display\_api.on\_rotate(pos, node, user, mode, new_param2)**
`on_rotate` node callback implementation. Display nodes should have this callback (restricts rotations and rotates display entities associated with node). `on_rotate` node callback implementation. Display nodes should have this callback (restricts rotations and rotates display entities associated with node).
### on_activate ### on_activate
**display\_lib.on_activate(entity, staticdata)** **display\_api.on_activate(entity, staticdata)**
`On_activate` entity callback implementation for display entities. No need of this method if display entities have been registered using `register_display_entity` (callback is already set). `On_activate` entity callback implementation for display entities. No need of this method if display entities have been registered using `register_display_entity` (callback is already set).
@ -40,17 +40,16 @@ This is a helper to register entities used for display.
* Register display entities with `register_display_entity` * Register display entities with `register_display_entity`
* Register node with : * Register node with :
- `on_place`, `on_construct`, `on_destruct` and `on_rotate` callbacks using display_api callbacks. - `on_place`, `on_construct`, `on_destruct` and `on_rotate` callbacks using display_api callbacks.\
- `display_api` group. This will make this node have their entities updated as soon as the mapblock is loaded (Useful after /clearobjects). - `display_api` group. This will make this node have their entities updated as soon as the mapblock is loaded (Useful after /clearobjects).\
- a `display_entities` field in node definition containing a entity name indexed table. See below for description of each display_entities fields. - a `display_entities` field in node definition containing a entity name indexed table. See below for description of each display_entities fields.\
### Display_entities fields ### Display_entities fields
`on_display_update` is a callback in charge of setting up entity texture. If not set, entity will have no texture and will be displayed as unknown item. `on_display_update` is a callback in charge of setting up entity texture. If not set, entity will have no texture and will be displayed as unknown item.\
`depth`, `right` and `height`: Entity position regarding to node facedir/wallmounted main axis.\
`depth`, `right` and `height`: Entity position regarding to node facedir/wallmounted main axis. Values for these fields can be any number between -1.5 and 1.5 (default value is 0). Position 0,0,0 is the center of the node.\
Values for these fields can be any number between -1.5 and 1.5 (default value is 0). `depth` goes from front (-0.5) to rear (0.5), `height` goes from bottom (-0.5) to top (0.5) and `right` goes from left (-0.5) to right (0.5).\
Position 0,0,0 is the center of the node. `yaw`: Entity yaw in radians, regarding to main axis. Default is 0, aligned to node face.
`depth` goes from front (-0.5) to rear (0.5), `height` goes from bottom (-0.5) to top (0.5) and `right` goes from left (-0.5) to right (0.5).
In order to avoid flickering text, it's better to have text a little behind node surface. A good spacing value is given by `display_api.entity_spacing` variable. In order to avoid flickering text, it's better to have text a little behind node surface. A good spacing value is given by `display_api.entity_spacing` variable.