Finish writing API documentation, remove drop_railcarts (replaced by try_detach_minecart), rename constants to ALL CAPS for consistency, change mcl_minecarts. to mod. for API function definitions

mods/ENTITIES/mcl_minecarts/API.md

@@ -1,18 +1,44 @@
 # Table of Contents
 1. [Useful Constants](#useful-constants)
 2. [Rail](#rail)
-3. [Cart functions](#cart-functions)
-4. [Cart-Node Interactions](#cart-node-iteractions)
+  1. [Constants](#constants)
+  2. [Functions](#functions)
+  3. [Node Definition Options](#node-definition-options)
+3. [Cart Functions](#cart-functions)
+4. [Cart Data Functions](#cart-data-functions)
+5. [Cart-Node Interactions](#cart-node-iteractions)
+6. [Train Functions](#train-functions)
 
 ## Useful Constants
 
-`mcl_minecarts.north`
-`mcl_minecarts.south`
-`mcl_minecarts.east`
-`mcl_minecarts.west`
+- `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. Default is 64.
+
+- `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
@@ -110,6 +136,20 @@ is unloaded.
 
 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.

mods/ENTITIES/mcl_minecarts/carts.lua

@@ -303,7 +303,7 @@ function DEFAULT_CART_DEF:on_death(killer)
 end
 
 -- Place a minecart at pointed_thing
-function mcl_minecarts.place_minecart(itemstack, pointed_thing, placer)
+function mod.place_minecart(itemstack, pointed_thing, placer)
 	if not pointed_thing.type == "node" then
 		return
 	end
@@ -369,7 +369,7 @@ local function dropper_place_minecart(dropitem, pos)
 	local node = minetest.get_node(pos)
 	if minetest.get_item_group(node.name, "rail") == 0 then return false end
 
-	mcl_minecarts.place_minecart(dropitem, {
+	mod.place_minecart(dropitem, {
 		above = pos,
 		under = vector.offset(pos,0,-1,0)
 	})
@@ -397,7 +397,7 @@ local function register_minecart_craftitem(itemstring, def)
 				end
 			end
 
-			return mcl_minecarts.place_minecart(itemstack, pointed_thing, placer)
+			return mod.place_minecart(itemstack, pointed_thing, placer)
 		end,
 		_on_dispense = function(stack, pos, droppos, dropnode, dropdir)
 			-- Place minecart as entity on rail. If there's no rail, just drop it.
@@ -405,7 +405,7 @@ local function register_minecart_craftitem(itemstring, def)
 			if minetest.get_item_group(dropnode.name, "rail") ~= 0 then
 				-- FIXME: This places minecarts even if the spot is already occupied
 				local pointed_thing = { under = droppos, above = vector.new( droppos.x, droppos.y+1, droppos.z ) }
-				placed = mcl_minecarts.place_minecart(stack, pointed_thing)
+				placed = mod.place_minecart(stack, pointed_thing)
 			end
 			if placed == nil then
 				-- Drop item
@@ -438,9 +438,11 @@ Register a minecart
 * on_activate_by_rail: Called when above activator rail
 * creative: If false, don't show in Creative Inventory
 ]]
-function mcl_minecarts.register_minecart(def)
-	assert( def.drop, "def.drop is required parameter" )
-	assert( def.itemstring, "def.itemstring is required parameter" )
+function mod.register_minecart(def)
+	-- Make sure all required parameters are present
+	for _,name in pairs({"drop","itemstring","entity_id"}) do
+		assert( def[name], "def."..name..", a required parameter, is missing")
+	end
 
 	local entity_id = def.entity_id; def.entity_id = nil
 	local craft = def.craft; def.craft = nil
@@ -463,7 +465,7 @@ function mcl_minecarts.register_minecart(def)
 		minetest.register_craft(craft)
 	end
 end
-local register_minecart = mcl_minecarts.register_minecart
+local register_minecart = mod.register_minecart
 
 dofile(modpath.."/carts/minecart.lua")
 dofile(modpath.."/carts/with_chest.lua")

mods/ENTITIES/mcl_minecarts/functions.lua

@@ -312,7 +312,7 @@ function mcl_minecarts:get_rail_direction(pos_, dir)
 
 	return dir
 end
-function mcl_minecarts.update_cart_orientation(self)
+function mod.update_cart_orientation(self)
 	local staticdata = self._staticdata
 
 	-- constants

mods/ENTITIES/mcl_minecarts/init.lua

@@ -6,7 +6,6 @@ mcl_minecarts.modpath = modpath
 
 -- Constants
 mod.speed_max = 10
-mod.check_float_time = 15
 mod.FRICTION = 0.4
 mod.MAX_TRAIN_LENGTH = 4
 mod.CART_BLOCK_SIZE = 64

mods/ENTITIES/mcl_minecarts/movement.lua

@@ -5,12 +5,13 @@ local S = minetest.get_translator(modname)
 
 -- Constants
 local mcl_debug,DEBUG = mcl_util.make_mcl_logger("mcl_logging_minecart_debug", "Minecart Debug")
-local friction = mcl_minecarts.FRICTION
-local MAX_TRAIN_LENGTH = mod.MAX_TRAIN_LENGTH
 --DEBUG = false
 --mcl_debug = function(msg) print(msg) end
 
 -- Imports
+local FRICTION = mcl_minecarts.FRICTION
+local MAX_TRAIN_LENGTH = mod.MAX_TRAIN_LENGTH
+local SPEED_MAX = mod.SPEED_MAX
 local train_length = mod.train_length
 local update_train = mod.update_train
 local reverse_train = mod.reverse_train
@@ -233,13 +234,13 @@ local function calculate_acceleration(staticdata)
 
 	-- Apply friction if moving
 	if staticdata.velocity > 0 then
-		acceleration = -friction
+		acceleration = -FRICTION
 	end
 
 	local pos = staticdata.connected_at
 	local node_name = minetest.get_node(pos).name
 	local node_def = minetest.registered_nodes[node_name]
-	local max_vel = mcl_minecarts.speed_max
+	local max_vel = SPEED_MAX
 
 	local ctrl = staticdata.controls or {}
 	local time_active = minetest.get_gametime() - 0.25
@@ -259,9 +260,9 @@ local function calculate_acceleration(staticdata)
 	-- Factor in gravity after everything else
 	local gravity_strength = 2.45 --friction * 5
 	if staticdata.dir.y < 0 then
-		acceleration = gravity_strength - friction
+		acceleration = gravity_strength - FRICTION
 	elseif staticdata.dir.y > 0 then
-		acceleration = -gravity_strength + friction
+		acceleration = -gravity_strength + FRICTION
 	end
 
 	return acceleration
@@ -330,7 +331,7 @@ local function do_movement_step(staticdata, dtime)
 	end
 
 	-- Truncate timestep to prevent v_1 from being larger that speed_max
-	local v_max = mcl_minecarts.speed_max
+	local v_max = SPEED_MAX
 	if (v_0 ~= v_max) and ( v_0 + a * timestep > v_max) then
 		timestep = ( v_max - v_0 ) / a
 	end
@@ -342,7 +343,7 @@ local function do_movement_step(staticdata, dtime)
 	local v_1 = v_0 + a * timestep
 	if v_1 > v_max then
 		v_1 = v_max
-	elseif v_1 < friction / 5 then
+	elseif v_1 < FRICTION / 5 then
 		v_1 = 0
 	end
 
@@ -402,7 +403,7 @@ local function do_movement_step(staticdata, dtime)
 
 		-- Update cart direction
 		staticdata.dir = next_dir
-	elseif stops_in_block and v_1 < (friction/5) and a <= 0 then
+	elseif stops_in_block and v_1 < (FRICTION/5) and a <= 0 then
 		-- Handle direction flip due to gravity
 		if DEBUG then mcl_debug("Gravity flipped direction") end
 

mods/ENTITIES/mcl_minecarts/rails.lua

@@ -16,21 +16,6 @@ local south = mod.south
 local east = mod.east
 local west = mod.west
 
-local function drop_railcarts(pos)
-	-- Scan for minecarts in this pos and force them to execute their "floating" check.
-	-- Normally, this will make them drop.
-	local objs = minetest.get_objects_inside_radius(pos, 1)
-	for o=1, #objs do
-		local le = objs[o]:get_luaentity()
-		if le then
-			-- All entities in this mod are minecarts, so this works
-			if string.sub(le.name, 1, 14) == "mcl_minecarts:" then
-				le._last_float_check = mcl_minecarts.check_float_time
-			end
-		end
-	end
-end
-
 --- Rail direction Handleres
 local function rail_dir_straight(pos, dir, node)
 	dir = vector.new(dir.x, 0, dir.z)
@@ -196,7 +181,6 @@ local BASE_DEF = {
 	after_place_node = function(pos, placer, itemstack, pointed_thing)
 		update_rail_connections(pos)
 	end,
-	after_destruct = drop_railcarts,
 	_mcl_minecarts = {
 		get_next_dir = rail_dir_straight,
 	},