search

hkzorman / advanced_npc

Advanced NPC for Minetest, using mobs_redo API
Other
17 stars 5 forks source link

API Documentation #22

Open BrunoMine opened 7 years ago

BrunoMine commented 7 years ago

I am trying to compile a more complete documentation on how the API works for developers. I still need to understand some API dynamics and I'd like some help with it.

My API documentation

Is it correct now?

Xaleth commented 7 years ago

I don't know yet, but take this one to heart if your goal is to make good documentation for this mod:

Bad grammar and bad english = bad documentation that is hard to understand.

Your API.txt has bad grammar and bad english; therefore, I cannot understand it.

BrunoMine commented 7 years ago

I know my english grammar is bad, but you really do not understand? A part is fully copied from the documentation on the wiki.

I'm not an expert in documentation, but I wish to improve it.

I yet have many conceptual doubts (If you can help me with this, I'm grateful). Then it is a simple start with the API documentation.

Xaleth commented 7 years ago

I created a pull request in your fork for this.

hkzorman commented 7 years ago

@BrunoMine, first of all, thanks. The link above isn't available anymore. I'm fine to take in documentation even if not in the perfect state. I'm willing to merge documentation with necessary fixes to English grammar, that's not a problem for me. Keep working in whatever you can and I can improve it in the go,

hkzorman commented 7 years ago

@BrunoMine if you open a PR to include the doc folder and its contents, I will merge it. Also, any other extra documentation you do feel free to open PRs and I will merge them and fix any English grammar that needs so, no need to worry about it!

BrunoMine commented 7 years ago

What exactly is the action parameter? A number, a function or a table value? It is strange to be a table value.

* `npc.add_action(luaentity, action, args)`: Add action into NPC actions queue
    * `luaentity` of the controled NPC
    * `action` is a command number
    * `args` is a table of args for the action command

I wish it was a string. (eg, "SIT", "USE_BED")

hkzorman commented 7 years ago

The action parameter is a number, but this can be changed. I tried to implement as an enum, and the expected usage is to always call npc.actions.cmd.*. If you propose to change the values, instead of 0, 1, 2 ... to actual string representations, it can be done.

I guess you wish something similar to this?

BrunoMine commented 7 years ago

Exactly, this will avoid repetition of the term npc.actions.cmd..

BrunoMine commented 7 years ago

npc.places.add_owned lock a node and add the place into npc? What exactly is that? npc.places.add_shared npc.places.add_owned_accessible_place(self, nodes, place_type, walkables) Can shared nodes be used by anyone?

hkzorman commented 7 years ago

Owned nodes are supposed to be used by only one NPC, like beds. This is done by adding metadata to that node and setting the owner in a variable.

Shared nodes can be used by many NPCs. The owner variable is left blank.

BrunoMine commented 7 years ago

https://github.com/hkzorman/advanced_npc/blob/master/npc.lua#L971 I'm thinking maybe this can be changed to schedule entries. It is possible? npc.add_schedule_entry(self, schedule_type, date, time, check, entries)

hkzorman commented 7 years ago

Well, it needs a better name for sure, but I think ‘entries’ will make it confusing with the term ‘schedule entry’ which is for identifying which a group of actions to be performed at a certain date and time. Maybe we can call it ‘commands’? After all, there are 4 possible “commands”: