BL Coding Where can I find annotations/documentations of vanilla Bannerlord files?

Users who are viewing this thread

NamingIsHard

Regular
M&BWBWF&SNWVC
As I can remember, several months ago TW has said that they will release API for vanilla BL files in the future, are the documents released now? If so, where can I find those documents?
 

NamingIsHard

Regular
M&BWBWF&SNWVC
I'm not sure I know what you mean by API. What are you trying to modify specifically?
ah, I might be using false term, usually confused about those terms. I mean annotations and documentations(both overall and in-line) for functions and codes.

Example from my personal repository
Python:
def nn_update(model, eta):
    """ Update NN weights.
    :param model: Dictionary of all the weights.
    :param eta: Learning rate
    :return: None
    """

Or this in-line annotation started by #
 
Upvote 0

Bloc

Archduke
WB
Modding for BL is not simply referencing Taleworlds DLLs and using those DLLs like you would do for most of the software projects. Modding would be cleaner and less painful in this scenario but it also limits people and code itself is nowhere there yet. And that's why even if they add annotations ( more specifically, generate XML documentation for the assembly ) you still won't get much information out of it because you still need to use decompiler for your "patches"

If you had a chance to reference the actual source code of the TW gameplay codes, then you would be able to do everything you want to do + read the code easily without using dirty tricks like dnSpy or dotPeek. If they had summaries for their functions that would also work out of the box without requiring them to generate XML for the summaries. So for that, you usually require open-sourced code so that you can have all the summary/comments for that and simply hover over to learn more about it. But I asked this question in here and then it become a thread in here which is rejected by TW.

What TW is saying by "API documentation" will be similar to this -> Example CampaignBehavior But this is community documentation and it's far more detailed than TW's documentation at the moment. And you can't simply rely on the documentation without decompiling the actual code since it's changing and names/usages are very very very vague in many cases.

Tl;dr: No documentation or whatsoever is released yet. You need to decompile the codes and read/understand on your own and then use that knowledge for your mod until the next patch arrives and then hope that previous knowledge is still relevant and not changed by TW.
 
Upvote 0

NamingIsHard

Regular
M&BWBWF&SNWVC
Modding for BL is not simply referencing Taleworlds DLLs and using those DLLs like you would do for most of the software projects. Modding would be cleaner and less painful in this scenario but it also limits people and code itself is nowhere there yet. And that's why even if they add annotations ( more specifically, generate XML documentation for the assembly ) you still won't get much information out of it because you still need to use decompiler for your "patches"

If you had a chance to reference the actual source code of the TW gameplay codes, then you would be able to do everything you want to do + read the code easily without using dirty tricks like dnSpy or dotPeek. If they had summaries for their functions that would also work out of the box without requiring them to generate XML for the summaries. So for that, you usually require open-sourced code so that you can have all the summary/comments for that and simply hover over to learn more about it. But I asked this question in here and then it become a thread in here which is rejected by TW.

What TW is saying by "API documentation" will be similar to this -> Example CampaignBehavior But this is community documentation and it's far more detailed than TW's documentation at the moment. And you can't simply rely on the documentation without decompiling the actual code since it's changing and names/usages are very very very vague in many cases.

Tl;dr: No documentation or whatsoever is released yet. You need to decompile the codes and read/understand on your own and then use that knowledge for your mod until the next patch arrives and then hope that previous knowledge is still relevant and not changed by TW.
I know we cant easily reference TW DLLs for making mod, but have a clear look on it will significantly help increase efficiency of modding process and compatibility of mods.
Since writing annotations and APIs are kind of basics for programming, and it would be very easy for TW to release such documentation if they did fulfill that requirement, I can only find two possibilities under this circumstance. 1. TW programmers are so bad that they can even fulfill this basic requirement, or 2. TW are not even trying to help improve quality of life for the modding community, even though their game relies heavily on work of the modding community.
Even the most dumb programmer should have known how painful it is to read and modify un-annotated code of others.Even worse, refer to the files I have read, TW programmers were not even following another basic rule of programming: assign meaningful name to variables, which makes the process even more painful for modders.
 
Upvote 0

Bloc

Archduke
WB
1. TW programmers are so bad that they can even fulfill this basic requirement, or 2. TW are not even trying to help improve quality of life for the modding community, even though their game relies heavily on work of the modding community.
I don't think the first one is the case, because if this is not defined in their task DoD, then it's not a requirement and they don't have to do that. Even if you are a top-notch engineer, you wouldn't do something outside of the scope of your sprint and enforce your own set of rules. Why this is not in their task DoD is another story though. Only their Tech Leads or PM can answer that, if they have such roles.

About the second one...well they simply don't care if you mod it easily or not ¯\_(ツ)_/¯ I'm sure that half of the team weren't probably even able to mod their own game because they don't know anything about it (I'm talking about modding in a way you and me do, without source code or whatsoever) So expecting a mod-friendly coding style from them wouldn't be logical. And I think documentation would be only become an "important" task for them after the full release, I don't think they care it in EA state.
I think we have substantial evidence that they are working in a chaotic environment and many things are not well-planned but rather ad-hoc things, but if you ask TW, they will say that they enforce good practices and they do want to help the modding community.

If you want them to generate an XML documentation for assembly ( so that you can hover over for function descriptions ) I think you should open a suggestion thread rather than question one in Q&A. Suggestion threads are checked by Dejan ( I guess ).
 
Upvote 0

NamingIsHard

Regular
M&BWBWF&SNWVC
I don't think the first one is the case, because if this is not defined in their task DoD, then it's not a requirement and they don't have to do that. Even if you are a top-notch engineer, you wouldn't do something outside of the scope of your sprint and enforce your own set of rules. Why this is not in their task DoD is another story though. Only their Tech Leads or PM can answer that, if they have such roles.
hmmmmm, refer to my own programming experience, primary purpose of annotations(at least in-line annotations) is improving quality of life for the writers, not something about DoD. I originally start to wrote those annotations because of school marking scheme; but as time goes on, I keep doing so even though I no longer need to worry about such thing. Those annotations helps me a lot when I want to modify or review my code later, and thus improve my quality of life as programmer.
But yes, after about 1 year and a half of EA state, I agree that
I think we have substantial evidence that they are working in a chaotic environment and many things are not well-planned but rather ad-hoc things
So this might be the case? If a programmer do not need to maintain his/her own code after completion, or programmer team of TW are changing fast and no programmer will stay in TW for a long time, annotations are useless for the writers if not specified in DoD.

So expecting a mod-friendly coding style from them wouldn't be logical.
hmmmmmm, not mod-friendly, I mean reader-friendly. The writers will also become readers when they need to modify or review the codes. This is the same as above.

If you want them to generate an XML documentation for assembly ( so that you can hover over for function descriptions ) I think you should open a suggestion thread rather than question one in Q&A. Suggestion threads are checked by Dejan ( I guess ).
I will try later, has been waiting for officials documentations since EA release.
 
Last edited:
Upvote 0

Bloc

Archduke
WB
. I originally start to wrote those annotations because of school marking
That's only you, though. Not everyone is working with the same principles. You can, however, enforce your entire team to do this if you define that as DoD. Otherwise, you have to be a positive thinker to assume that ~50 devs from different backgrounds will do it exactly how you wanted.

I agree that it increases the readability as well and not only for mods since you will now know the main purpose of the function you are working on if it comes to a point where you need to change something. But it could be that they never needed this before as a team and/or perhaps comments inside functions are enough for the team.

If you take a look at the code, you will also see that some functions and classes are not even used anywhere and just floating dead-code pieces. Even this somewhat gives an idea about current code-quality they have. But I think this is normal. Normal in sense of "if you use your shoes too often, it will tear down, it's normal" type of normal. Because they changed this exact codebase throughout the 8 years continuously and most likely without any properly defined guidelines.


Anyway, I don't want to go too off-topic here. You can request this as a suggestion in the modding section. And for the answer to your main question, you should occasionally check TW's documentation to see if they updated it.
 
Upvote 0
Top Bottom