API Documentation

[BrunoMine]

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]

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]

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]

I created a pull request in your fork for this.

[hkzorman]

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

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

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]

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]

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

[BrunoMine]

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]

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]

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]

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”:

• action
• task
• property change
• query