VoxeLibre/mods/ENTITIES/mcl_minecarts/API.md

Table of Contents

1. Useful Constants
2. Rail
   1. Constants
   2. Functions
   3. Node Definition Options
3. Cart Functions
4. Cart Data Functions
5. Cart-Node Interactions
6. Train Functions

Useful Constants

• mcl_minecarts.north
• mcl_minecarts.south
• mcl_minecarts.east
• mcl_minecarts.west

Human-readable names for the cardinal directions.

• mcl_minecarts.SPEED_MAX

Maximum speed that minecarts will be accelerated to with powered rails, in blocks per second. Defined as 10 blocks/second.

• mcl_minecarts.CART_BLOCKS_SIZE

The size of blocks to use when searching for carts to respawn. Defined as is 64 blocks.

• mcl_minecarts.FRICTION

Rail friction. Defined as is 0.4 blocks/second^2.

• mcl_minecarts.MAX_TRAIN_LENGTH

The maximum number of carts that can be in a single train. Defined as 4 carts.

• mcl_minecarts.PASSENGER_ATTACH_POSITION

Where to attach passengers to the minecarts.

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.

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)

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:is_rail(position, railtype)

Determines if the node at position is a rail. If railtype is provided, determine if the node at position is that type of rail.

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

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.attach_driver(cart, player)

This attaches (ObjectRef) player to the (LuaEntity) cart.

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.kill_cart(cart_data)

Kills a cart and drops it as an item, even if the cart entity is unloaded.

mcl_minecarts.place_minecart(itemstack, pointed_thing, placer)

Places a minecart at the location specified by pointed_thing

mcl_minecarts.register_minecart(minecart_definition)

Registers a minecart. minecart_definition defines the entity. All the options supported by normal minetest entities are supported, with a few additions:

• craft - Crafting recipe for this cart.
• drop - List of items to drop when the cart is killed. (required)
• entity_id - The entity id of the cart. (required)
• itemstring - This is the itemstring to use for this entity. (required)

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 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 as:

function(node_position, cart_luaentity, cart_direction, cart_position)

Arguments:

• node_position - position of the node the cart is interacting with
• cart_luaentity - The luaentity of the cart that is entering this block. Will be nil for minecarts moving thru unloaded blocks
• cart_direction - The direction the cart is moving
• cart_position - The location of the cart
• cart_data - Information about the cart. This will always be defined.

There are several variants of this handler:

• _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

Mods can also define global handlers that are called for every node. These handlers are defined as:

function(node_position, cart_luaentity, cart_direction, node_definition, cart_data)

Arguments:

• node_position - position of the node the cart is interacting with
• cart_luaentity - The luaentity of the cart that is entering this block. Will be nil for minecarts moving thru unloaded blocks
• cart_direction - The direction the cart is moving
• cart_position - The location of the cart
• cart_data - Information about the cart. This will always be defined.
• 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

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.