From 9781627bb20948c0d9957da99bf8e2006885f370 Mon Sep 17 00:00:00 2001 From: teknomunk Date: Wed, 10 Apr 2024 23:30:03 +0000 Subject: [PATCH] Continue writing API documentation, update call signatures for a couple of API functions --- mods/ENTITIES/mcl_minecarts/API.md | 92 ++++++++++++++++++++++- mods/ENTITIES/mcl_minecarts/functions.lua | 4 +- 2 files changed, 90 insertions(+), 6 deletions(-) diff --git a/mods/ENTITIES/mcl_minecarts/API.md b/mods/ENTITIES/mcl_minecarts/API.md index b43af1af7..16db4878d 100644 --- a/mods/ENTITIES/mcl_minecarts/API.md +++ b/mods/ENTITIES/mcl_minecarts/API.md @@ -1,3 +1,87 @@ +# Table of Contents +1. Useful Constants +2. Rail +3. [Cart functions](#cart-functions) +4. [Cart-Node Interactions](#cart-node-iteractions) + +## Useful Constants + +`mcl_minecarts.north` +`mcl_minecarts.south` +`mcl_minecarts.east` +`mcl_minecarts.west` + +Human-readable names for the cardinal directions. + +## Rail + +### Constants + +`mcl_minecarts.HORIZONTAL_CURVES_RULES` +`mcl_minecarts.HORIZONTAL_STANDARD_RULES` + +Rail connection rules. Each rule is an table with the following indexes: + +1. `node_name_suffix` - The suffix added to a node's `_mcl_minecarts.base_name` to + get the name of the node to use for this connection. +2. `param2_value` - The value of the node's param2. Used to specify rotation. + +and the following named options: + +- `mask` - Directional connections mask +- `score` - priority of the rule. If more than one rule matches, the one with the + highest store is selected. +- `can_slope` - true if the result of this rule can be converted into a slope. + +### Functions + +`mcl_minecarts.get_rail_connections(node_position, options)` + +Calculate the rail adjacency information for rail placement. Arguments are: + +- `node_position` - the location of the node to calculate adjacency for. +- `options` - A table containing any of these options: + - `legacy`- if true, don't check that a connection proceeds out in a direction + a cart can travel. Used for converting legacy rail to newer equivalents. + - `ignore_neightbor_connections` - if true, don't check that a cart could leave + the neighboring node from this direction. + +`mcl_minecarts.update_rail_connections(node_position, options)` + +Converts the rail at `node_position`, if possible, another variant (curve, etc.) +and rotates the node as needed so that rails connect together. `options` is +passed thru to `mcl_minecarts.get_rail_connections()` + +`mcl_minecarts:get_rail_direction(rail_position, cart_direction)` + +Returns the next direction a cart traveling in the direction specified in `cart_direction` +will travel from the rail located at `rail_position`. + +## Cart functions + +`mcl_minecarts.detach_minecart(cart_data)` + +This detaches a minecart from any rail it is attached to and makes it start moving +as an entity affected by gravity. It will keep moving in the same direction and +at the same speed it was moving at before it detaches. + +`mcl_minecarts.get_cart_position(cart_data)` + +Compute the location of a minecart from its cart data. This works even when the entity +is unloaded. + +`mcl_minecarts.reverse_cart_direction(cart_data)` + +Force a minecart to start moving in the opposite direction of its current direction. + +`mcl_minecarts.snap_direction(direction_vector)` + +Returns a valid cart movement direction that has the smallest angle between it and `direction_vector`. + +`mcl_minecarts:update_cart_orientation(cart)` + +Updates the rotation of a cart entity to match the cart's data. + ## Cart-Node interactions As the cart moves thru the environment, it can interact with the surrounding blocks @@ -35,10 +119,10 @@ Arguments: - `node_definition` - The definition of the node at `node_position` The available hooks are: -`_mcl_minecarts.on_enter` - The cart enters this block -`_mcl_minecarts.on_enter_below` - The cart enters above this block -`_mcl_minecarts.on_enter_above` - The cart enters below this block -`_mcl_minecarts.on_enter_side` - The cart enters beside this block +- `_mcl_minecarts.on_enter` - The cart enters this block +- `_mcl_minecarts.on_enter_below` - The cart enters above this block +- `_mcl_minecarts.on_enter_above` - The cart enters below this block +- `_mcl_minecarts.on_enter_side` - The cart enters beside this block Only a single function can be installed in each of these handlers. Before installing, preserve the existing handler and call it from inside your handler if not `nil`. diff --git a/mods/ENTITIES/mcl_minecarts/functions.lua b/mods/ENTITIES/mcl_minecarts/functions.lua index 40d5cd2d3..7fdc2e195 100644 --- a/mods/ENTITIES/mcl_minecarts/functions.lua +++ b/mods/ENTITIES/mcl_minecarts/functions.lua @@ -285,7 +285,7 @@ local function is_ahead_slope(pos, dir) local node_name = force_get_node(below).name return minetest.get_item_group(node_name, "rail_slope") ~= 0 end -function mcl_minecarts:get_rail_direction(pos_, dir, ctrl, old_switch, railtype) +function mcl_minecarts:get_rail_direction(pos_, dir) local pos = vector.round(pos_) -- Handle new track types that have track-specific direction handler @@ -312,7 +312,7 @@ function mcl_minecarts:get_rail_direction(pos_, dir, ctrl, old_switch, railtype) return dir end -function mcl_minecarts:update_cart_orientation() +function mcl_minecarts.update_cart_orientation(self) local staticdata = self._staticdata -- constants