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

This commit is contained in:
teknomunk 2024-04-11 07:08:25 +00:00
parent 51036b0592
commit acb246b88e
6 changed files with 67 additions and 41 deletions

View File

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

View File

@ -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")

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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,
},