MineClone2/mods/ENTITIES/mcl_minecarts/DOC.md

On-rail Minecart Movement

Minecart movement is handled in two distinct regimes: on a rail and off. The off-rail movement is handled with minetest's builtin entity movement handling. The on-rail movement is handled with a custom algorithm. This section details the latter.

The data for on-rail minecart movement is stored entirely inside mod storage and indexed by a hex-encoded 128-bit universally-unique identifier (uuid). Minecart entities store this uuid and a sequence identifier. The code for handling this storage is in storage.lua. This was done so that minecarts can still move while no players are connected or when out of range of players. Inspiration for this was the Advanced Trains mod. This is a behavior difference when compared to minecraft, as carts there will stop movement when out of range of players.

Processing for minecart movement is as follows:

1. In a globalstep handler in carts.lua, determine which carts are moving.
2. Call do_movement in movement.lua to update each cart's location and handle interactions with the environment.
   1. Each movement is broken up into one or more steps that are completely contained inside a block. This prevents carts from ever jumping from one rail to another over a gap or thru solid blocks because of server lag. Each step is processed with do_movement_step
   2. Each step uses physically accurate, timestep-independent physics to move the cart. Calculating the acceleration to apply to a cart is broken out into its own function (calculate_acceperation).
   3. As the cart enters and leaves blocks, handlers in nearby blocks are called to allow the cart to efficiently interact with the environment. Handled by the functions handle_cart_enter and handle_cart_leave
   4. The cart checks for nearby carts and collides elastically with these. The calculations for these collisions are in the function handle_cart_collision
   5. If the cart enters a new block, determine the new direction the cart will move with mcl_minecarts:get_rail_direction in [functions.lua](./functions.lua]. The rail nodes provide a hook _mcl_minecarts.get_next_direction that provides this information based on the previous movement direction.
3. If an entity exists for a given cart, the entity will update its position while loaded in.

Cart movement when on a rail occurs regarless of whether an entity for that cart exists or is loaded into memory. As a consequence of this movement, it is possible for carts with unloaded entities to enter range of a player. To handle this, periodic checks are performed around players and carts that are within range but don't have a cart have a new entity spawned.

Every time a cart has a new entity spawned, it increases a sequence number in the cart data to allow removing old entities from the minetest engine. Any cart entity that does not have the current sequence number for a minecart gets removed once processing for that entity resumes.