From 51036b05928ce6dc3b86a4a5640eeb1d0abca546 Mon Sep 17 00:00:00 2001 From: teknomunk Date: Thu, 11 Apr 2024 00:04:59 +0000 Subject: [PATCH] Nearly finish API documentation, create mcl_minecarts.add_blocks_to_map() --- mods/ENTITIES/mcl_minecarts/API.md | 115 +++++++++++++++++++++++- mods/ENTITIES/mcl_minecarts/carts.lua | 14 ++- mods/ENTITIES/mcl_minecarts/storage.lua | 12 +++ 3 files changed, 128 insertions(+), 13 deletions(-) diff --git a/mods/ENTITIES/mcl_minecarts/API.md b/mods/ENTITIES/mcl_minecarts/API.md index 16db4878d..52e639231 100644 --- a/mods/ENTITIES/mcl_minecarts/API.md +++ b/mods/ENTITIES/mcl_minecarts/API.md @@ -1,6 +1,6 @@ # Table of Contents -1. Useful Constants -2. Rail +1. [Useful Constants](#useful-constants) +2. [Rail](#rail) 3. [Cart functions](#cart-functions) 4. [Cart-Node Interactions](#cart-node-iteractions) @@ -33,6 +33,11 @@ and the following named options: highest store is selected. - `can_slope` - true if the result of this rule can be converted into a slope. +`mcl_minecarts.RAIL_GROUPS.STANDARD` +`mcl_minecarts.RAIL_GROUPS.CURVES` + +These constants are used to specify a rail node's `group.rail` value. + ### Functions `mcl_minecarts.get_rail_connections(node_position, options)` @@ -46,6 +51,19 @@ Calculate the rail adjacency information for rail placement. Arguments are: - `ignore_neightbor_connections` - if true, don't check that a cart could leave the neighboring node from this direction. +`mcl_minecarts.register_rail(itemstring, node_definition)` + +Registers a rail with a few sensible defaults and if a craft recipe was specified, +register that as well. + +`mcl_minecarts.register_straight_rail(base_name, tiles, node_definition)` + +Registers a rail with only straight and sloped variants. + +`mcl_minecarts.register_curves_rail(base_name, tiles, node_definition)` + +Registers a rail with straight, sloped, curved, tee and cross variants. + `mcl_minecarts.update_rail_connections(node_position, options)` Converts the rail at `node_position`, if possible, another variant (curve, etc.) @@ -57,7 +75,25 @@ passed thru to `mcl_minecarts.get_rail_connections()` 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 +### Node Definition Options + +`_mcl_minecarts.railtype` + +This declares the variant type of the rail. This will be one of the following: + +- "straight" - two connections opposite each other and no vertical change. +- "sloped" - two connections opposite each other with one of these connections + one block higher. +- "corner" - two connections at 90 degrees from each other. +- "tee" - three connections +- "cross" - four connections allowing only straight-thru movement + +#### Hooks +`_mcl_minecarts.get_next_dir = function(node_position, current_direction, node)` + +Called to get the next direction a cart will travel after passing thru this node. + +## Cart Functions `mcl_minecarts.detach_minecart(cart_data)` @@ -70,6 +106,10 @@ at the same speed it was moving at before it detaches. Compute the location of a minecart from its cart data. This works even when the entity is unloaded. +`mcl_minecarts.kill_cart(cart_data)` + +Kills a cart and drops it as an item, even if the cart entity is unloaded. + `mcl_minecarts.reverse_cart_direction(cart_data)` Force a minecart to start moving in the opposite direction of its current direction. @@ -82,7 +122,36 @@ Returns a valid cart movement direction that has the smallest angle between it a Updates the rotation of a cart entity to match the cart's data. -## Cart-Node interactions +## Cart Data Functions + +`mcl_minecarts.destroy_cart_data(uuid)` + +Destroys the data for the cart with the identitfier in `uuid`. + +`mcl_minecarts.find_carts_by_block_map(block_map)` + +Returns a list of cart data for carts located in the blocks specified in `block_map`. Used +to respawn carts entering areas around players. + +`mcl_minecarts.add_blocks_to_map(block_map, min_pos, max_pos)` + +Add blocks that fully contain `min_pos` and `max_pos` to `block_map` for use by + `mcl_minecarts.find_cart_by_block_map`. + +`mcl_minecarts.get_cart_data(uuid)` + +Loads the data for the cart with the identitfier in `uuid`. + +`mcl_minecarts.save_cart_data(uuid)` + +Saves the data for the cart with the identifier in `uuid`. + +`mcl_minecart.update_cart_data(data)` + +Replaces the cart data for the cart with the identifier in `data.uuid`, then saves +the data. + +## Cart-Node Interactions As the cart moves thru the environment, it can interact with the surrounding blocks thru a number of handlers in the block definitions. All these handlers are defined @@ -126,3 +195,41 @@ The available hooks are: 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`. + +## Train Functions + +`mcl_minecarts.break_train_at(cart_data)` + +Splits a train apart at the specified cart. + +`mcl_minecarts.distance_between_cars(cart1_data, cart2_data)` + +Returns the distance between two carts even if both entities are unloaded, or nil if either +cart is not on a rail. + +`mcl_minecarts.is_in_same_train(cart1_data, cart2_data)` + +Returns true if cart1 and cart2 are a part of the same train and false otherwise. + +`mcl_minecarts.link_cart_ahead(cart_data, cart_ahead_data)` + +Given two carts, link them together into a train, with the second cart ahead of the first. + +`mcl_minecarts.train_cars(cart_data)` + +Use to iterate over all carts in a train. Expected usage: + +`for cart in mcl_minecarts.train_cars(cart) do --[[ code ]] end` + +`mcl_minecarts.reverse_train(cart)` + +Make all carts in a train reverse and start moving in the opposite direction. + +`mcl_minecarts.train_length(cart_data)` + +Compute the current length of the train containing the cart whose data is `cart_data`. + +`mcl_minecarts.update_train(cart_data)` + +When provided with the rear-most cart of a tain, update speeds of all carts in the train +so that it holds together and moves as a unit. diff --git a/mods/ENTITIES/mcl_minecarts/carts.lua b/mods/ENTITIES/mcl_minecarts/carts.lua index 6371c860a..7080a5dea 100644 --- a/mods/ENTITIES/mcl_minecarts/carts.lua +++ b/mods/ENTITIES/mcl_minecarts/carts.lua @@ -513,15 +513,11 @@ local function try_respawn_carts() local players = minetest.get_connected_players() for _,player in pairs(players) do local pos = player:get_pos() - local min = vector.floor(vector.divide(vector.offset(pos,-CART_BLOCK_SIZE,-CART_BLOCK_SIZE,-CART_BLOCK_SIZE), CART_BLOCK_SIZE)) - local max = vector.floor(vector.divide(vector.offset(pos, CART_BLOCK_SIZE, CART_BLOCK_SIZE, CART_BLOCK_SIZE), CART_BLOCK_SIZE)) + vector.new(1,1,1) - for z = min.z,max.z do - for y = min.y,max.y do - for x = min.x,max.x do - block_map[ vector.to_string(vector.new(x,y,z)) ] = true - end - end - end + mod.add_blocks_to_map( + block_map, + vector.offset(pos,-CART_BLOCK_SIZE,-CART_BLOCK_SIZE,-CART_BLOCK_SIZE), + vector.offset(pos, CART_BLOCK_SIZE, CART_BLOCK_SIZE, CART_BLOCK_SIZE) + ) end -- Find all cart data that are in these blocks diff --git a/mods/ENTITIES/mcl_minecarts/storage.lua b/mods/ENTITIES/mcl_minecarts/storage.lua index c68942778..91926835d 100644 --- a/mods/ENTITIES/mcl_minecarts/storage.lua +++ b/mods/ENTITIES/mcl_minecarts/storage.lua @@ -72,6 +72,18 @@ function mod.find_carts_by_block_map(block_map) return cart_list end +function mod.add_block_map(block_map, min_pos, max_pos) + local min = vector.floor(vector.divide(min_pos), CART_BLOCK_SIZE) + local max = vector.floor(vector.divide(max_pos), CART_BLOCK_SIZE) + vector.new(1,1,1) + for z = min.z,max.z do + for y = min.y,max.y do + for x = min.x,max.x do + block_map[ vector.to_string(vector.new(x,y,z)) ] = true + end + end + end +end + minetest.register_on_shutdown(function() for uuid,_ in pairs(cart_data) do save_cart_data(uuid)