From 05dfaaad789516cde47e544b210d52eaf9be9875 Mon Sep 17 00:00:00 2001 From: teknomunk Date: Thu, 11 Apr 2024 07:08:25 +0000 Subject: [PATCH] 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 | 52 ++++++++++++++++++++--- mods/ENTITIES/mcl_minecarts/carts.lua | 18 ++++---- mods/ENTITIES/mcl_minecarts/functions.lua | 2 +- mods/ENTITIES/mcl_minecarts/init.lua | 1 - mods/ENTITIES/mcl_minecarts/movement.lua | 19 +++++---- mods/ENTITIES/mcl_minecarts/rails.lua | 16 ------- 6 files changed, 67 insertions(+), 41 deletions(-) diff --git a/mods/ENTITIES/mcl_minecarts/API.md b/mods/ENTITIES/mcl_minecarts/API.md index 52e639231..978654a32 100644 --- a/mods/ENTITIES/mcl_minecarts/API.md +++ b/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. diff --git a/mods/ENTITIES/mcl_minecarts/carts.lua b/mods/ENTITIES/mcl_minecarts/carts.lua index 7080a5dea..f6c2a1436 100644 --- a/mods/ENTITIES/mcl_minecarts/carts.lua +++ b/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") diff --git a/mods/ENTITIES/mcl_minecarts/functions.lua b/mods/ENTITIES/mcl_minecarts/functions.lua index 7fdc2e195..c4694cc06 100644 --- a/mods/ENTITIES/mcl_minecarts/functions.lua +++ b/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 diff --git a/mods/ENTITIES/mcl_minecarts/init.lua b/mods/ENTITIES/mcl_minecarts/init.lua index 6a6f93318..dbc5897a4 100644 --- a/mods/ENTITIES/mcl_minecarts/init.lua +++ b/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 diff --git a/mods/ENTITIES/mcl_minecarts/movement.lua b/mods/ENTITIES/mcl_minecarts/movement.lua index 31e95a4e9..3c4ba5e83 100644 --- a/mods/ENTITIES/mcl_minecarts/movement.lua +++ b/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 diff --git a/mods/ENTITIES/mcl_minecarts/rails.lua b/mods/ENTITIES/mcl_minecarts/rails.lua index 22b26cd8e..632e7859e 100644 --- a/mods/ENTITIES/mcl_minecarts/rails.lua +++ b/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, },