Nearly finish API documentation, create mcl_minecarts.add_blocks_to_map()

This commit is contained in:
teknomunk 2024-04-11 00:04:59 +00:00
parent 077834951f
commit d3bb27c053
3 changed files with 128 additions and 13 deletions

View File

@ -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 <a name='#cart-functions'></a>
### 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.

View File

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

View File

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