We need a standard mob interface

[Byakuren]

Motivation
Right now, there are multiple mob mods, providing different interfaces to modders. From other mods, there is no good way to tell if an entity "is a mob", because each mob framework effectively provides a different conception of what a mob is. I propose that we should have a common interface for mobs to expose, in addition to the functionality provided by frameworks. This interface would not replace mob frameworks, but would allow modders to treat mobs from different mods uniformly, to the extent that they implement the interface. The interface would go on top of whatever the frameworks already expose. An interface like this would have benefits, including:

• Modders will not have to use heuristics to tell whether an entity should be considered a mob.
• Modders can write mobs that don't use any framework, by just implementing the interface.
• Mods that operate on mobs can write code once that will work for mobs from any or no framework.
• Modders can experiment with new frameworks without worrying about incompatibilities with other mods

Structure
Concretely, the interface will consist of core features, which all implementors of the interface should implement, and optional features, which represent some concept that's not universal to all mobs, but may be fairly common, like mob ownership. Each optional feature will have a string id that can be referred to. The interface will have two parts: Fields of luaentitys, and a separate mod.

luaentity Fields
Part of the interface would be for mob entitys to have certain fields. An example of a core feature would be an "is_mob" flag that is always true. An example of an optional feature would be an owner method that returns the name of the current owner of the mob, or nil if there is none.

Mod
A separate mod serves two purposes. First, it can provide a nicer interface for modders interacting with mobs than just the raw luaentity features. Secondly, it provides a place to register global callbacks and similar things. An example of a core feature would be a register_on_punchmob function. I can't think of an example for an optional feature. An example of a utility function would be a owner function, which uses a mob's owner method if it exists, and otherwise returns nil.

Features
I think at least these two features should be in the core:

• luaentity boolean field is_mob: Always set to true for mobs. Can be used to tell if an entity is a mob.
• luaentity table field optional_features: A table of optional features, where the keys are the string ids of optional features, which only exist in the table if the entity supports the feature.

Other ideas
"interface mod" refers to the mod part of the interface, not implementing mods.

• (Core) lua entity method attack(puncher, time_from_last_punch, tool_capabilities, direction, owner): Implements "owned punches", where owner is a player name. Could be used for projectiles, to make sure mobs know who to become aggressive towards. If a mob doesn't use owner information, it can implement this with just a normal punch.
• (Core) luaentity method heal(amount): Heals the mob by the health given
• (Core) mod function register_on_mobdeath(func(obj, cause_of_death)): Register death callbacks for mobs, which would be required to notify the mod when they die. The interface mod could provide a notify_mobdeath function, which dying mobs need to call. cause_of_death would be some data representing what caused the mob to die (representation not determined).
• (Core) mod function register_on_punchmob(func(target, hitter, time_from_last_punch, tool_capabilities, dir, damage, owner)): similar to register_on_punchplayer, but can receive a separate owner of the punch, if it exists. An example use would be for achievements. A mob would be required to notify the mod about punches after calculating damage, but before applying it. The interface mod could provide a notify_punchmob function, which returns whether the damage mechanism should be cancelled (and the mob shouldn't apply damage if it returns true).
• (Core) mod function register_on_spawnmob(func(obj)): Called after a mob spawns and has been initialized. Not called on subsequent activations. Interface mod could provide a notify_spawnmob
• (Optional) luaentity method get_owner(): Returns the name of an owning player, if it exists.
• (Optional) luaentity method relationship("player_name"): Returns a string describing the mob's attitude toward the player, e.g. "friend", "neutral", "hostile".
• (Optional) luaentity method age(): Returns the number of seconds the mob has been alive
• (Optional) luaentity method is_adult(): Returns whether the mob is an adult
• (Optional) mod function register_on_mobbreed(func(obj1, obj2)): Called when two mobs breed. The interface mod could provide a notify_mobbreed function that should be called when two mobs breed.

Discussion
Obviously, a standard like this will fail if nobody uses it, so this thread should be used to discuss any issues with it. I especially ask any mob framework/library writers to give input.

For everybody:
Do you have any problems with a standard mob interface in principle? If so, why?
How could the structure of the interface be improved?

For modders interfacing with mobs:
Which of my examples do you agree would be useful?
What changes would you make to my examples?
What would you like to see in the interface that I haven't mentioned?
What would make the interface easiest to use?

For mob framework writers:
What can be done to make the interface easier to implement?
Is there anything that would hold you back from implementing this interface?

It's important for the success of this standard that there is somebody in line to adopt it when it arrives, so I probably won't begin any major work on the mod portion of the standard unless at least one major mob framework writer is on board and ready to collaborate to make sure that the resultant design is acceptable to them.

EDIT: Forgot to add, I'll open a github repo at some point to write the actual standard in.

[octacian]

I don't think that we need a interface. We already have one. Through LuaEntities. Yeah, someone could create a standard interface, but why when we have LuaEntities? More could be added to that existing API including booleans as you mentioned. That would not be a hard change to make to the engine. That way it could be more "official," rather than a bunch of different APIs each claiming to be better. Some type of standard would be useful in that case (e.g. entity defs must include whether it is a "mob" or not), but that, I think, should be found on the dev wiki.

[octacian]

I don't think that we need a interface. We already have one. Through LuaEntities. Yeah, someone could create a standard interface, but why when we have LuaEntities? More could be added to that existing API including booleans as you mentioned. That would not be a hard change to make to the engine. That way it could be more "official," rather than a bunch of different APIs each claiming to be better. Some type of standard would be useful in that case (e.g. entity defs must include whether it is a "mob" or not), but that, I think, should be found on the dev wiki.

Sorry, I misunderstood a lot of what you said somehow. Some of what I said is still relevant, but you already said most of it. That sounds like a great idea, and I think it should go forward. I would recommend you go on IRC and talk to a dev about it and see what they think. That's the quickest way to get action :P

[burli]

If I understand you right you don't want a mob api, but more an api for other mods to interact with mobs, e.g. if you punch a mob with a magic wand the mob is healed.

That sounds good, but before that we need some functions. A very important callback would IMHO be an "on_enter_pos" and "on_leave_pos", not only for mobs, but also for the player. An example for that is a pressure plate.

[TenPlus1]

Mobs Redo api is very powerful and can do most of what you mentioned already if you take the time to learn the api and it's contained variables.

[burli]

Mobs Redo api is very powerful and can do most of what you mentioned already if you take the time to learn the api and it's contained variables.

I think he means something different. If someone wants to write a mod with a healing wand, each mob api has to implement this function itself. In mobs redo you have to check if the magic wand mod is installed and in "on_punch" you have to check if the wand is the wield item. Just an example

With the API Byakuren suggested the wand mod can say "I want to heal the punched object" and the API calls the heal function of the mob API. Part of the mob frameworks would just be to implement a heal function

A problem with this API would be, if a modder wants to write a mod with a new function, let's say an invisibility potion, the API and all mob frameworks have to implement that function first, and I doubt that someone want's to implement these features in simple mobs or some other discontinued mod

[TenPlus1]

Mobs Redo api has an immune_to setting in mob definition that allows you to heal a mob with a special item or cause specific damage... e.g:

Code: Select all

immune_to = {
	{"default:sword_wood", 0}, -- no damage
	{"default:gold_lump", -10}, -- heals by 10 points
},

... and if the special tool/wand has to heal ALL mobs you hit with it then that's down to the on_punch setting of the wand itself (self.health = self.hp_max).

[octacian]

It doesn't seem to me as though he wants just another mod-implemented API though, and neither do I. Most of the things Byakuren mentioned he made clear should be implemented right in the engine/core. That's exactly where it should happen, and the only way to have any type of standard.

[Byakuren]

Thanks for all the feedback, everybody.

I would recommend you go on IRC and talk to a dev about it and see what they think. That's the quickest way to get action :P

I did mention the idea on IRC before posting it here, but I didn't look for someone to work with yet. The end goal though is to make this a joint project with one or two mob framework writers. (More is possible, but there aren't a lot of active mob framework writers)

If I understand you right you don't want a mob api, but more an api for other mods to interact with mobs, e.g. if you punch a mob with a magic wand the mob is healed.

That sounds good, but before that we need some functions. A very important callback would IMHO be an "on_enter_pos" and "on_leave_pos", not only for mobs, but also for the player. An example for that is a pressure plate.

This is a good idea, but I would predict to be controversial because it may be expensive to check every step. One solution would be to allow implementors to only check for a new position on a longer step than normal, though it would still require bookkeeping about the most recent rounded position.

Mobs Redo api is very powerful and can do most of what you mentioned already if you take the time to learn the api and it's contained variables.

The point of this standard isn't to create new functionality, but to have a standard interface to existing and future frameworks, and even mobs that aren't written with a framework. The interface would go on top of what these mobs already expose, and allow modders to handle mobs framework-agnostically.

I think it is important to have diversity in mob frameworks, since one framework is unlikely to do everything somebody would want, or may have additional features they don't want. Someone might simply think a framework is bloated and want to write the code directly. We do have multiple, used mob frameworks right now, including mobs and nssm. But I also think modders who deal with mobs should not have to deal with writing separate code for every existing framework, because that doesn't really scale.

In essence, the goal of this project is to determine what the Minetest community's conception of "a mob" is, and then summarize that in an standard interface that modders can use to interact with any compliant mob from any mod. A mob is to an entity as something like a pointed_thing is to a table: it is a standardized, more elaborated version that includes more details. While a pointed_thing is "just a table", we have certain expectations of it, such as having a "type" field, and having other fields depending on the type. Similarly, we can define a mob as being an entity, with some additional expectations, like having an "is_mob" flag, or triggering death callbacks when it is killed. In a language with a static type system, mobs would be a type. This doesn't mean that every mob must be implemented the same way, and it doesn't mean that every mob must only expose the interface, and nothing else. It just means they should at least expose the interface, so modders have on they can rely on. By the way, by "modders" here, I don't mean people using mob frameworks to make mobs. I mean people who want mods to interact with mobs, e.g. by attacking them with projectiles, or by adding achievements for killing them.

I don't think the currently-existing mob frameworks have mobs that are so different that there is no common interface possible. All mobs have a concept of death, even though some might be unkillable. The existing mob frameworks also have mobs that can be hostile or be attacked by the player or other mobs. Very importantly, all mobs "are a mob", something that should be checkable from an external mod, without having to know details about every mob framework that is in use.

As for features, you at least lack (from my list of examples) owned attacks, death callback registration, punch callback registration, spawn callback registration, hostility-gauging method, and breed callback registration. Note that a global callback is not the same as a callback in the entity definition, because it will run for all mobs, not just one that was defined to call it. The only way to do it with your framework currently is to loop through all the registered mobs and change their callbacks, and then override your mob creation function to change all future death callbacks. This is messy and a hack, and the solution is a global callback registration function. But this shouldn't be done as just part of one framework, because then modders will have to register a callback for every framework, and they will have to anticipate the existence of all of them. Their mod also won't work with new frameworks. If there is a standard interface that collects all the callbacks, and there are mods that use it, all a new mob writer has to do to be compatible with the old mods is to expose the standard interface.

Thank you for mentioning your issue, because I don't think I was clear enough in the OP about how this isn't asking for a new framework.

A problem with this API would be, if a modder wants to write a mod with a new function, let's say an invisibility potion, the API and all mob frameworks have to implement that function first, and I doubt that someone want's to implement these features in simple mobs or some other discontinued mod

It at least wouldn't be worse than the current situation, where only mobs from one framework would respond to invisibility potions. Maybe a more general solution to this problem would be to have a generic interface for status effects applied to entities. Then nobody has to write new code for each new effect. Mob writers wouldn't even have to implement effects themselves, since the interface mod could provide prepackaged data structures and functions for applying, cancelling, serializing the data, etc., and the mob writer would just have to call these in their callbacks.

This obviously doesn't cover all possible features someone might want mobs to have. One way to have unexpected features, building on the optional features system, would be to have non-official extensions to the standard, adding additional features. The person designing the feature can give the feature a string id that can be used like those of other optional features. For example, someone writing an invisibility potion mod could design and publish an "invisibility" feature, where all mobs implementing the feature must expose a method for turning invisible for x seconds. Unofficial extensions that are thought to be general and useful could eventually find their way into the standard.

It doesn't seem to me as though he wants just another mod-implemented API though, and neither do I. Most of the things Byakuren mentioned he made clear should be implemented right in the engine/core. That's exactly where it should happen, and the only way to have any type of standard.

I think this is implementable as a mod, though it would be easier to succeed as part of the engine, since it would have canonicity. But getting it into the engine in the first place would be hard, and a standard like this may be out of the scope of the engine anyway.

I never mod about mobs or weapons, but I realy think Minetest needs something like a "damage type".

Types could be : hunger, weapon (maybe different kinds), fire, radiation, and so on.

This could ease a lot damage management on both sides (weapon and mobs).

There is already a damage type system, it just is barely used. An entity or player (by default) can only take punch damage from damage types that they have in their armor groups, and there has been very little work with armor groups. Technic mod adds a radiation damage type, which it uses for radiation damage. Armor that protects against fleshy damage in that mod typically have less or no protection against radiation. If you want to see a basic system for adding damage types to players, you can look at armor_monoid. Maybe mobs should also set armor values for registered damage types? It seems intuitive that a mob would be vulnerable by default to any damage type, not immune.

[kaeza]

https://xkcd.com/927/
This is always relevant to these discussions :P

[rubenwardy]

Well, there's a slight distinction in that there are currently a load of competing library and this aims to make a standard.

I agree that this could be useful

[Wuzzy]

As for the question whether an entity is a mob: Could we maybe just add the entity to the group “mob” and we all agree to use this group for mobs? Maybe with group ratings for mob type.

mob=1: unspecified
mob=2: peaceful (does never attack players)
mob=3: agressive (may attack players)
mob>=100: custom mob types

To check whether an entity is a mob, a modder would check against “groups.mob ~= nil” or something like this.

As long this group is not used already for something else, this should be a rather sane way, right?

If my suggestion receives positive feedback I or someone else might add it to this wiki page:
http://dev.minetest.net/Groups/Custom_groups

[burli]

I made these definitions in my mob mod for the sheep

Code: Select all

groups = {pray = 1, animal = 1, sheep = 1, mob = 1},

So predators can easily search for pray, mods can search for mobs in general and so on

[Byakuren]

As for the question whether an entity is a mob: Could we maybe just add the entity to the group “mob” and we all agree to use this group for mobs? Maybe with group ratings for mob type.

mob=1: unspecified
mob=2: peaceful (does never attack players)
mob=3: agressive (may attack players)
mob>=100: custom mob types

To check whether an entity is a mob, a modder would check against “groups.mob ~= nil” or something like this.

As long this group is not used already for something else, this should be a rather sane way, right?

If my suggestion receives positive feedback I or someone else might add it to this wiki page:
http://dev.minetest.net/Groups/Custom_groups

This is an interesting idea, which didn't occur to me since groups aren't in common use for entities. I guess this could be useful if groups become useful in the interface, similar to how they can be used for items or nodes for various things. E.g. A utility function like get_mobs_inside_radius that can accept groups and names to search for. When I first read your post I was unsure of whether "mob" should be a group rather than a field, but it would be useful if someone later makes a utilities library for entities in general, like a get_entities_inside_radius that takes groups (which would make the get_mobs_inside_radius example redundant).

I don't know if "friendliness" should be encoded in the mob group rating. The trouble I see is in allocating the custom numbers, and also that multiple ratings might make sense for a single mob. I think each kind of mob categorization should be its own group, and if multiple categories are mutually exclusive, they can share a group. For example a "friendliness" group could have your example ratings for "peaceful", "aggressive", etc.

I made these definitions in my mob mod for the sheep

Code: Select all

groups = {pray = 1, animal = 1, sheep = 1, mob = 1},

So predators can easily search for pray, mods can search for mobs in general and so on

The correct spelling is "prey". Also the same thing as earlier about mob as a group

[Byakuren]

I've written a draft, check out viewtopic.php?f=9&t=15448.