More documentation, add myself to copyright list in README.txt

mods/ENTITIES/mcl_minecarts/DOC.md

@@ -7,25 +7,35 @@ 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). The
+and indexed by a hex-encoded 128-bit universally-unique identifier (uuid). Minecart
-code for handling this storage is in [storage.lua](./storage.lua). This was
+entities store this uuid and a sequence identifier. The code for handling this
-done so that minecarts can still move while no players are connected or
+storage is in [storage.lua](./storage.lua). This was done so that minecarts can
-when out of range of players. Inspiration for this was the [Adv Trains mod](http://advtrains.de/).
+still move while no players are connected or when out of range of players. Inspiration
-This is a behavior difference when compared to minecraft, as carts there will
+for this was the [Advanced Trains mod](http://advtrains.de/). This is a behavior difference
-stop movement when out of range of players.
+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, determine which carts are moving.
+1. In a globalstep handler in [carts.lua](./carts.lua), determine which carts are
+   moving.
 2. Call `do_movement` in [movement.lua](./movement.lua) to update
-   the cart's location and handle interactions with the environment.
+   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.
+      lag. Each step is processed with `do_movement_step`
    2. Each step uses physically accurate, timestep-independent physics
-      to move the cart.
+      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.
+      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.
 
@@ -39,3 +49,4 @@ 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.
+

mods/ENTITIES/mcl_minecarts/README.txt

@@ -10,6 +10,7 @@ MIT License
 Copyright (C) 2012-2016 PilzAdam
 Copyright (C) 2014-2016 SmallJoker
 Copyright (C) 2012-2016 Various Minetest developers and contributors
+Copyright (C) 2024 teknomunk
 
 Authors/licenses of media files:
 -----------------------