From 1ee97a2e736345784e092249dc548fd2536211b0 Mon Sep 17 00:00:00 2001 From: teknomunk Date: Sat, 31 Aug 2024 09:41:17 -0500 Subject: [PATCH] Add API documentation, minor API cleanup --- mods/ITEMS/mcl_bows/arrow.lua | 2 +- mods/ITEMS/vl_projectile/api.md | 81 +++++++++++++++++++++++++++++++ mods/ITEMS/vl_projectile/init.lua | 8 ++- 3 files changed, 85 insertions(+), 6 deletions(-) create mode 100644 mods/ITEMS/vl_projectile/api.md diff --git a/mods/ITEMS/mcl_bows/arrow.lua b/mods/ITEMS/mcl_bows/arrow.lua index 42dde0b7c..ba2edf811 100644 --- a/mods/ITEMS/mcl_bows/arrow.lua +++ b/mods/ITEMS/mcl_bows/arrow.lua @@ -158,7 +158,7 @@ local arrow_entity = { return true end, sounds = { - on_entity_collision = function(self, _, _, obj) + on_entity_collision = function(self, _, _, _, obj) if obj:is_player() then return {{name="mcl_bows_hit_player", gain=0.1}, {to_player=self._shooter:get_player_name()}, true} end diff --git a/mods/ITEMS/vl_projectile/api.md b/mods/ITEMS/vl_projectile/api.md new file mode 100644 index 000000000..bddcbebbe --- /dev/null +++ b/mods/ITEMS/vl_projectile/api.md @@ -0,0 +1,81 @@ +# Projectiles API + +## `vl_projectile.register(entity_name, def)` + +Registers a projectile entity. + +Arguments: + +* `entity_name`: The name the entity will be refered to by the minetest engine +* `def`: Projectile defintion. Supports all fields that standard minetest entities support. + Must include the field `_vl_projectile` for projectile-specific behaviors. These are the supported + fields: + * `survive_collision`: if this field is `false` or `nil`, the projectile will be removed after a collision. + * `sticks_in_players`: if true, the projectile will stick into players after colliding with them. + * `damage_groups`: damage group information to use for `punch()`. May be a function of type `function(projectile, entity_def, projectile_def, obj)` + that returns dynamic damange group information. + * `allow_punching`: will the projectile punch entities it collieds with. May be a function of type `function(projectile, entity_def, projectile_def, obj)`. + * `behaviors`: a list of behavior callbacks that define the projectile's behavior. This mod provides two + behaviors: `vl_projectiles.collides_with_solids` and `vl_projectiles.collides_with_entities` + * `sounds`: sounds for this projectile. All fields take a table with three parameters corresponding to the + three parameters for `minetest.play_sound()`. Supported sounds are: + * `on_collision`: played when no other more specific sound is defined. May be a function of type `function(projectile, entity_def, projectile_def, type, ...)` + * `on_solid_collision`: played when the projectile collides with a solid node. May be a function of type + `funciton(projectile, entity_def, projectile_def, type, pos, node, node_def)` with `type = "node"` + * `on_entity_collision`: played when the projectile collieds with another entity. May be a function of type + `function(projectile, entity_def, projectile_def, type, entity)` with `type = "entity"` + * `on_collide_with_solid`: callback of type `function(projectile, pos, node, node_def)` used when the projectile collides with a solid node. Requires + `vl_projectile.collides_with_solids` in `behaviors` list. + * `on_collide_with_entity`: callback of type `function(projectile, pos, obj)` used when the projectile collides with an entity. Requires + `vl_projectile.collides_with_entities` in `behaviors` list. + +## `vl_projectile.update_projectile(self, dtime)` + +Performs standard projectile update logic and runs projectile behaviors. + +Arguments: +* `self`: The lua entity of the projectile to update +* `dtime`: The amount of time that has passed since the last update. Nomally the `dtime` + parameter of the entity's `on_step(self, dtime)` callback. + +## `vl_projectile.raycast_collides_with_entities(self, dtime, entity_def, projectile_def` + +Performs collision detection of entities via a racast and then handles the collisions. + +Arguments: +* `self`: The lua entity of the projectile to update +* `dtime`: The amount of time that has passed since the last update. Nomally the `dtime` + parameter of the entity's `on_step(self, dtime)` callback. +* `entity_def`: The definition from `minetest.registered_entities` for the projectile. +* `projectile_def`: Same as `entity_def._vl_projectile` + +## `vl_projectile.create(entity_id, options)` + +Creates a projectile and performs convenience initialization. + +Arguments: +* `entity_id`: The name the entity as passed to `vl_projectile.register()` +* `options`: A table with optional parameters. Supported fields are: + * `dir`: direction the projectile is moving in + * `velocity`: scalar velocity amount + * `drag`: scalar resistence to velocity + * `owner`: passed thru unmodified + * `extra`: passed thru unmodified + +## Custom Projectile Behaviors + +The projectile API supports specifying the behaviors that a projectile will exhibit. There are two +standard behaviors provided with the API: `vl_projectile.collides_with_solids` and `vl_projectile.collides_with_entities`. +Custom behaviors can be provided by adding a function with the signature `function(self, dtime, entity_def, projectile_def)` +to the list of behaviors a projectile supports. + +Arguments: + +* `self`: The lua entity of the projectile +* `dtime`: The amount of time that has passed since the last update. Nomally the `dtime` + parameter of the entity's `on_step(self, dtime)` callback. +* `entity_def`: The definition from `minetest.registered_entities` for the projectile. +* `projectile_def`: Same as `entity_def._vl_projectile` + + + diff --git a/mods/ITEMS/vl_projectile/init.lua b/mods/ITEMS/vl_projectile/init.lua index 81dfe6ae2..30d82cf71 100644 --- a/mods/ITEMS/vl_projectile/init.lua +++ b/mods/ITEMS/vl_projectile/init.lua @@ -169,6 +169,7 @@ function mod.collides_with_solids(self, dtime, entity_def, projectile_def) -- Play sounds local sounds = projectile_def.sounds or {} local sound = sounds.on_solid_collision or sounds.on_collision + if type(sound) == "function" then sound = sound(self, entity_def, projectile_def, "node", pos, node, node_def) end if sound then local arg2 = table.copy(sound[2]) arg2.pos = pos @@ -240,8 +241,8 @@ local function handle_entity_collision(self, entity_def, projectile_def, entity) -- Play sounds local sounds = (projectile_def.sounds or {}) - local sound = sounds.on_entity_collide or sounds.on_collision - if type(sound) == "function" then sound = sound(self, entity_def, projectile_def, entity) end + local sound = sounds.on_entity_collion or sounds.on_collision + if type(sound) == "function" then sound = sound(self, entity_def, projectile_def, "entity", entity) end if sound then local arg2 = table.copy(sound[2]) arg2.pos = pos @@ -321,9 +322,6 @@ function mod.create(entity_id, options) extra = options.extra, } - -- Make the update function easy to get to - luaentity.update_projectile = mod.update_projectile - -- And provide the caller with the created object return obj end