Add documentation for C API

[gtker]

I plan on doing this myself, but there are a few things that I would like to ask so I'm opening it as an issue instead in order to potentially help people in the future.

• The wiki mentions that game object processing should always happen before map processing. What would happen if this was done out of order?
• "BVH generation" is not very descriptive of what happens at a business logic level, would it make sense to instead call it "Game Object processing"?
• What does the "Game Object CSV" do, how is it made, and is it required/recommended?
• What is the difference between pathfind_load_adt and pathfind_load_adt_at? When would it be recommended to use these instead of just pathfind_load_all_adts.
• What is actually returned by pathfind_get_zone_and_area? From my own wow_messages work I have created an enum that I call Area which seems to contain both "zones" and "areas". What is the difference between these and are the different values documented anywhere?
• For pathfind_find_heights and pathfind_find_path, is there an internal limit on the amount of values that are possible?

[namreeb]

It's been quite a while since I've updated the documentation. I'll try to do that soon and will consider the feedback above.

What would happen if this was done out of order?

I think the reason is that the maps need data from the game objects. Specifically, I compute ahead of time which map tiles are touched by each game object or doodad instance. This accelerates the process of answering the question "which objects should I load" when a tile is loaded.

"BVH generation" is not very descriptive of what happens at a business logic level, would it make sense to instead call it "Game Object processing"?

Yes. "Game Object" means something specific, but I take your point.

What does the "Game Object CSV" do, how is it made, and is it required/recommended?

This is a feature that has likely rotted. The intention was to be able to provide a list of dynamically loaded (ie server spawned) game objects to include in the navigation mesh. However following server-controlled movement rules, I believe that mobs ignore these, so I'm not sure the feature is needed.

What is the difference between pathfind_load_adt and pathfind_load_adt_at? When would it be recommended to use these instead of just pathfind_load_all_adts.

I believe one is for loading an adt (x,y) and one is for loading at a given world (x,y,z). The option to load tiles individually is for the user to decide if they want to be conservative in what they load because of the memory requirements. For example some servers load only those tiles that have players actively on them.

What is actually returned by pathfind_get_zone_and_area? From my own wow_messages work I have created an enum that I call Area which seems to contain both "zones" and "areas". What is the difference between these and are the different values documented anywhere?

It refers to zone and area as defined by the game. So if you wanted to use namigator to add proper replies to the /who command, you'd need to be able to lookup that a player is in Stormwind City, for example.

For pathfind_find_heights and pathfind_find_path, is there an internal limit on the amount of values that are possible?

I think there is, yes, but I don't remember what it is. It is large enough that if you ever encounter it, something is likely wrong. I want to say maybe 4096?

[gtker]

It's been quite a while since I've updated the documentation.

I need to write documentation for my Rust bindings anyway, so I do not mind contributing back and adding it to the C/Python API. The only problem is my lack of knowledge. :)

"Game Object" means something specific, but I take your point.

Is a "doodad" the same as a "Game Object"?

The intention was to be able to provide a list of dynamically loaded (ie server spawned) game objects to include in the navigation mesh. However following server-controlled movement rules, I believe that mobs ignore these, so I'm not sure the feature is needed.

Do any of the major emulators provide this feature, or would it only be useful for clients?

It refers to zone and area as defined by the game.

Do you know where these are defined specifically? I'm unable to find anything that goes into specifics.

I think there is, yes, but I don't remember what it is. It is large enough that if you ever encounter it, something is likely wrong. I want to say maybe 4096?

OK. I was asking because the C API has to use out parameters to return the values, and wanted to know if I could just statically allocate a specific sized array and not run into issues, but I think 4096 * 4 bytes is a little too much.