[Abandoned] [Mod] Generic Mobiles API [alpha release] [gma]

[Hamlet]

Manages mobiles' registration and behaviour.

Source code's license: EUPL v1.2 or later

Dependencies: none
Optional dependencies: default



Thanks

This API would not exist if I had not the chance to learn from M.I.L.A. v1.3 how a mobiles' API works. Thus I would like to thank azekill_DIABLO, Taikedz, Lone_Wolf and any other M.I.L.A.'s contributor for their work, from which I keep learning.
Although G.M.A. is not M.I.L.A. v1.4, still I consider it its spiritual successor.

I would also thank the countless mobs that died - and will die - in the process of developing this API; they have been buried alive, drowned, dropped into lava and fire, burned due to sunlight, died due to darkness, or simply slained.
May their source code rest in peace, their death has not been in vain.



How To Use This API

You will need to download the Test Mob archive and use its init.lua as documentation reference, I have extensively commented it and it should be used as template.

You will notice that the mobile definition uses alphanumeric variables instead of words - e.g. instead of "collision_box = {}" you will have "d = {}".
This serves three purposes:
1) avoid typo-bugs, i.e. "healt" instead of "health"
2) allow multilanguage templates, thanks to code comments
3) keep the code tidy

Obviously the above has a price - i.e. depending on a template - but I think it's worth it, for the aforementioned purposes.



If You Want To Contribute

Please contribute :)
Please translate the Test Mob's init.lua comments in your language.



THIS IS ALPHA SOFTWARE, EXPECT MISSING FUNCTIONALITIES AND BUGS
Downloads

Archives: .zip .tar.gz
Source code: Codeberg

Test mob archives: .zip .tar.gz
Test mob repository: Codeberg


Installation

Unzip the archive, rename the folder to gma and place it in
../minetest/mods/

If you only want this to be used in a single world, place it in
../minetest/worlds/WORLD_NAME/worldmods/

GNU+Linux - If you use a system-wide installation place it in
~/.minetest/mods/

For further information or help see:
https://wiki.minetest.net/Help:Installing_Mods

[Byakuren]

Could you briefly explain what this API does and what a Mobile is?

[Stix]

Could you briefly explain what this API does and what a Mobile is?

You do know that the word "mob" is the short-form of "mobiles", right?

[Byakuren]

Could you briefly explain what this API does and what a Mobile is?

You do know that the word "mob" is the short-form of "mobiles", right?

I did not, thank you. What is nice about this API that I would prefer it over (for example) Mobs Redo?

[Hamlet]

What is nice about this API that I would prefer it over (for example) Mobs Redo?

Currently the API lacks some basic features like:
- sound support added on 2018-09-17
- customizable chance of movement added on 2018-09-16
- swimming / flying handling
- jumping
- avoid falling
- fall damage
- search for enemies (but mobs will fight back if attacked)
- support for projectiles

On the other hand it offers these features:
- invisible / incorporeal mobs
- darkness damage
- customizable friendly / hostile group(s) (currently unused)
- optionally random temper (passive, neutral, aggressive)
- customizable name tag color
- cust. infotext
- cust. line of sight's offset
- optional random armor level (chosen between armor min and armor max)
- opt. random damage level (chosen between damage min and damage max)
- breath points ("earth beings" drown, "water beings" suffocate)
- health / breath points recovery
- opt. spawn space check (i.e. large mobs will not spawn if there isn't enough space)
- random mob ID, used for testing purposes (e.g. "Mob a-23 is drowning".)
- stuck mobile check - to be enhanced - (i.e. is a mob tries to walk into a wall its direction will be changed)
- combat pause (try attacking a mob, then build a wall between you and it, look at how it behaves)

On my agenda there are other features to be implemented, these are:
- advanced combat (dodging, teleporting, etc.)
- levelling (experience gain = better armor and/or weapon)
- dialogues (using formspecs)
- commerce (using formspecs)
- pickpocketing (player <---> mob)
- avoid obvious dangers (i.e.: if it can't swim it will avoid water, if fire hurts it it will stay away from lava, etc.)

I've tried to write the source code in a clear manner, commenting anything I felt could be useful to uderstand how the API works; I've also split it into different files, trying to separate different groups of functions (health, timers, etc.) - my policy has been: "Even a granny must be able to read it."

[Astrobe]

You will notice that the mobile definition uses alphanumeric variables instead of words - e.g. instead of "collision_box = {}" you will have "d = {}".
This serves three purposes:
1) avoid typo-bugs, i.e. "healt" instead of "health"
2) allow multilanguage templates, thanks to code comments
3) keep the code tidy

Obviously the above has a price - i.e. depending on a template - but I think it's worth it, for the aforementioned purposes.

I think you should push this logic to the maximum and use an array instead of a table. I think it would look less weird and simpler, even.

It should also simplify things behind the API, as you don't have to provide default values for missing fields because all values have to be provided.

[Hamlet]

I think you should push this logic to the maximum and use an array instead of a table. I think it would look less weird and simpler, even.

It should also simplify things behind the API, as you don't have to provide default values for missing fields because all values have to be provided.

Since I'm not familiar with arrays I've read this:
https://www.lua.org/pil/11.1.html

So - please correct me if I am wrong - you are suggesting to:

Current logic:

declaration and initialization:

Code: Select all

mobile_properties = {
	a = "Name",
	b = "Surname",
	c = "passive"
}

data fetching:

Code: Select all

mobile_name = mobile_properties.a or "Default name"
mobile_surname = mobile_properties.b or "Default surname"
mobile_behavior = mobile_properties.c or "neutral"

Array logic:

declaration and initialization:

Code: Select all

mobile_properties = {
	"Name",
	"Surname",
	"passive"
}

data fetching:

Code: Select all

mobile_name = mobile_properties[1]
mobile_surname = mobile_properties[2]
mobile_beavior = mobile_properties[3]

Am I right?
If so, let's assume that one entry is not used, e.g.:

declaration and initialization:

Code: Select all

mobile_properties = {
	"Name",
	"passive",
}

data fetching:

Code: Select all

mobile_name = mobile_properties[1] -- correct: "Name"
mobile_surname = mobile_properties[2] -- wrong: "passive" instead of "Default surname"

As you have said, one should provide all the values to avoid such a situation; thus it seems to me that on the end-user (i.e. mob developer) side it would be worse than with the current logic.

Think about creating the classic mouse mob: instead of having to provide a bunch of custom values (mesh, hp, texture, collision box) leaving the other values to their defaults you would have to provide all of them - about 50 - making your code way longer and bug prone.

If I've mistaken what you meant then nevermind all of the above, and, could you please give me an example?

[Byakuren]

You could take a table as input for the mob definition and then convert it to an array with defaults filled in. I wouldn't do it however unless accessing the table fields is demonstrated to be a significant performance bottleneck.

[Hamlet]

You could take a table as input for the mob definition and then convert it to an array with defaults filled in.

Could you give me an example please? I have difficulty following coding tips without code examples.

I wouldn't do it however unless accessing the table fields is demonstrated to be a significant performance bottleneck.

I would not even know how to perform such a check. :/
However, speaking of performance, so far I am satisfied with it:
using the /status command, max_lag tends to settle around 0.20 or lower, with about 10 mobs walking around.

[Hamlet]

sound support added on 2018-09-17
customizable chance of movement added on 2018-09-16

[Astrobe]

As you have said, one should provide all the values to avoid such a situation; thus it seems to me that on the end-user (i.e. mob developer) side it would be worse than with the current logic.

Think about creating the classic mouse mob: instead of having to provide a bunch of custom values (mesh, hp, texture, collision box) leaving the other values to their defaults you would have to provide all of them - about 50 - making your code way longer and bug prone.

If I've mistaken what you meant then nevermind all of the above, and, could you please give me an example?

Oh, sorry, I wasn't sure I should make that suggestion so I kind of forgot I did post it...

You got it right. The user has to provide all values; one missing value screws everything -- which is a good thing. The reason you did it that way was because a typo would result in a field taking a default value without a warning. With an array, your API can check for the size of the array and issue a warning. Another thing that can happen is swapping fields; this can be detected to some extend by checking the type of the value.

Also, one thing I've see in some MobsRedo definitions are multiple values for the same field. This one is evil because if you do a search from the top of the file, you find the first definition but the API will use the second one... Variations of this mistake is having e.g. knock_back=0 and knockback=0 (typo + duplication). As soon as you allow a definition not to be explicit and comprehensive that sort of thing can happen and you can easily sink an hour in figuring out what's wrong.

The way I see it, the user would copy/paste from a template with all default values and edit them. Copy/paste is what people prefer to do anyway. So the risk for a missing field or swapped values is very low, in my opinion.

Code length is not an issue. 50 fields will probably result in 100-200 lines with basic documentation. That's fine because both parameter values and their meaning are in the same place, no need to lookup an api.txt file most of the times. Being interrupted in what you were doing is one of the reasons why mistakes happen ("I must not forget to initialize this [phone call] Where was I? Oh right, I've just finished target handling; let's do runaway handling now")

The one thing that's problematic is that all mob definitions will break if you change the definition part of the API. This can be worked around by providing a new definition function and have the old definition fill in the missing values (which always be at the end of the def because arrays) and pass the corrected definition to the new definition function internally.

PS: yes you also get better performance both in CPU and RAM, but that's not the main motivation.

[Hamlet]

Oh, sorry, I wasn't sure I should make that suggestion so I kind of forgot I did post it...

:) I am open to any suggestion.

At a first look your idea seemed strange to me, now that you have explained the pros and the cons I've started to see its potential.

I think that I will adopt it.

Thanks for sharing your experience :)

[azekill_DIABLO]

hey how's going my spiritual successor? :D
--btw i'm not here this post is invisible to everyone except Hamlet

[jas]

Could you briefly explain what this API does and what a Mobile is?

You do know that the word "mob" is the short-form of "mobiles", right?

Mind blown.

[Hamlet]

Released v0.1.1
Changed:
mod.conf for MT v5.0

[reflipd]

What about NPC driving?

[Saturn]

What about NPC driving?

This mod is outdated, it uses deprecated code (see lua_api.txt about Initial properties) and it is no longer maintained.

Please use Mobs Redo, or Creatures Mob Engine, or Mobkit. They are being maintained and developed.