Nat_VS

Thanks again for the feedback guys! @Owling Yeah I certainly agree that mod pages should be separated into categories - The issue with simple a "JSON/C#" split is that there are numerous topics that are not related to either (or even potentially both). It can be hard to know what should require a proper tutorial, and what should have more of a reference/guide on how to use it. I'll have a think about the names of pages, too, that does seem important. @Domtron Vox So, the wiki is editable by anyone (they just need to get approved by a moderator first to edit it). I don't agree over having more than one wiki - As modding the game is a very fundamental part of what the game stands for, and it being on the main wiki means that anyone who visits the wiki will (hopefully) notice that this the "how to make mods" is on there. We do, however, have quite a few other sources of information. The API Docs, the JSON Docs, the source code on Github, and obviously the wiki itself. There's a couple other community driven places too. My point being that I don't think changing the system now would be more beneficial than just fixing it. The guides and tutorials separation are kind of similar to what you're explaining, too. The API & JSON Docs are used as 'reference', and we have step-by-step 'tutorials', as well as informational 'guides'. I do agree with having that having well-written tutorials is a good idea, though. @captanredbeard I appreciate the lengthy reply, it's given me some distinct things to think about and some ideas for how to make this more suitable for the future too. I will look into the templates on Linux - I haven't actually got around to setting them up myself yet. Admittedly, there is a good amount of documentation that takes a while to maintain, and some of it has been done in a way that only I know how to do. Perhaps opening that up to allow more community interaction would be a great idea and I will have a think about how I can do that. I'm also, with all my flaws, a perfectionist and the modding wiki and documentation has turned into my child that I must protect at any cost. I'll think about how I can establish a community that may be able to help with the modding documentation.

Something of interest that may be beneficial for you is the JSON Reference/Documentation. It contains all the JSON properties for documented classes. For content modders, this is generally better than trying to find them through the GitHub code. For example, for the instance of Nutrition Properties, you would go to https://apidocs.vintagestory.at/json-docs/jsondocs/Vintagestory.API.Common.FoodNutritionProperties.html and you can see that there is the "eatenstack", as well as properties such as "health", "intoxication", and "psychedelic"

Thanks everyone for the feedback so far! To keep things succinct, I'll reply in a single post. far @HugoCortell I think there is definitely some value in providing already-complete mods. Every content mod tutorial does link to a GitHub that contains the finished example version of the tutorial. Perhaps there could be a way that I can use these already to provide a "change this to do this" style of guide. A visual tree could be a nice addition, but I can't think of a feasible way of doing that unfortunately. Each relatively new tutorial contains a "prerequisites" section for essential reads, as well as sometimes a "recommended" section, despite my belief that many people may just ignore these @Be eM More information is always good, but everything that gets added needs to be kept up-to-date, which can become difficult to maintain. If maintaining the wiki takes up too much time, then actually adding to the wiki becomes more difficult. One issue with the current system is that adding a single new page can sometimes require a whole bunch of changes across the wiki to make it work in the navigation. I've been considering actually releasing the tutorial mods on the ModDB, do you think that would be more beneficial? I know GitHub can sometimes come across as intimidating for non-coders. @321BoltsOfLightning I'd very much like to hear more about the issues you faced when using the modding wiki, if you have the time to reply. It can be quite difficult to predict what a new modder might get caught out by. @Jadesy Thank you for the diagram! I do find that a lot of the issues that each person has when using the wiki can often be related to larger issues on the wiki as a whole. One difficult part of the main navigation is that the modding section of the wiki is used by people with a huge variety of skills and experience, and so it needs to be suitable for both beginners and experts. I certainly do like the idea of a specific section for mod setup. That way the people who just want to know how that essential setup information can get that, and then do what they want.

Thanks @fawndoe. A brief explanation: The choice of leaving out cooking recipes from the same page as the rest of the recipes was because of the significant increase in complexity for creating them when compared to the other recipe types, especially at the time I wrote that tutorial. There has always been the plan to make a cooking recipe tutorial and an alloy tutorial, but I just got round to it yet. When it does get created though, I might expect it to be its own page. However, in the mentioned tutorial I did write "This tutorial will also give some information on alloy and cooking recipes" which appears to not be true at all Ideally, when the content tutorials are complete, there will be at least one content tutorial for each type of asset that can be added.

This is certainly something that needs work. There is a lot of code tutorial mods that exist on GitHub (https://github.com/anegostudios/vsmodexamples/tree/master/Code Mods) but these have not been turned into wiki tutorials yet.

Hi all! I'm looking for some feedback on some proposed plans for the modding section of the wiki in terms of how to make it more useful for everyone who uses it. If you have the time, I would love to hear your opinions on the following. I did write this as a message to some of the VS team, but it occurred to me that the wiki is made for the community, so you should have a say to express your opinions. I apologize in advance for the more casual tones this message has. ----- Okay, so first off the state of the wiki currently, there are a few distinct issues that I have been putting off because they are overwhelming me: 1. First and foremost, navigation to find specific pages is difficult. I took influence from the Starbound modding wiki, which separates navigation boxes to categorize everything. Unfortunately, this is only really helpful for step-by-step wiki guides, where categories don't really interfere with one another. But, our categories are highly interlinked, and this kind of navigation has just ended up resulting in a huge number of "landing pages". It takes several clicks to get to specific pages, and it's only really useful if you already know what you're looking for. 2. Second issue is the predominantly "Windows-heavy" content of the modding tutorials. It's very much a case of "do this in Windows and Visual Studio. If you aren't using those, then figure it out yourself." I thought this was a valid viewpoint to take initially, due to Linux users generally being more tech-savvy than the average person. After now using Linux myself and realising how difficult it can be, I have fully changed my mind and want to have specific tutorials on how to work with different OSs and IDEs. 3. Third issue is the variety of specificity across the modding pages. Some pages are obnoxiously broad and contain multiple sections. E.g. The "Developing a content mod" page contains "selecting an IDE", "Template/Example Mod Setup", "Manual Mod Setup" (which contains how to setup the mod workspace, modinfo, modicon, and assets folder), "Mod Domains", "Publishing a Content Mod", and "Updating a Content Mod to a new Game Version". If a user wants to know how to publish a content mod, they have to know that the information is contained within this page. This is countered by the fact that some pages are really specific, offering information on one specific topic, such as the "Types of Mod" page. The problem with the small pages is that they can very easily clog the wiki's navigation, making it generally harder to find specific pages - But smaller and specific pages are considerably easier to read, write, and maintain. I think those three are the largest issues that the modding section of the wiki faces. ----- The goal is to make all the information on the modding section easy to find, while also making it easier to maintain. I've come up with a number of solutions that I would like to implement to the modding wiki. Note that these do not necessarily match in order to the issues above: 1. Recreate the homepage navigation. Currently, the homepage has links for a "Quick Start Tutorial", an "All Modding Pages", and 7 distinct categories. The main page can be found here: https://wiki.vintagestory.at/Main_Page I would like to turn this into a table that is a cross between categories and specific pages. The table will contain the 7 categories, as well as an 'Other Resources' section. There will be greater emphasis on the 'Content Mods' and 'Code Mods' categories, as this is where the majority of mod content on the wiki is located. Each category's box in the table will contain its most useful pages, and then a link to view all the pages in the category. Note that it is unreasonable to list every mod page on the homepage. 2. Rewriting a number of the large and more chaotic pages into a set of smaller, more relevant and succinct pages. This will be done with an emphasis on avoiding duplicating information, as that is one of the hardest parts of maintaining the wiki. It will be beneficial for some of these smaller sections to be inside of landing pages, though. E.g. a wiki page called "Content Mod Essentials and Setup" may contain links to the pages for what a content mod is, how to create a content mod, how to update a content mod, and how to package a content mod. The goal is that ALL pages can be accessed within two clicks or less from the homepage. Each page will also be included in the category's "All pages", so there will hopefully be multiple ways of finding every page. 3. Split some pages into operating-system or IDE-specific pages. This is extremely relevant to the process of setting up code mods. It will double-up as a form of organization, but also show clarity for supporting various OSs and IDEs. 4. Deeply categorize pages to automatically generate "tag-based modding pages". i.e., any pages that give any details on creating, using, or modifying entities will have the "Modding Entities" category. As more pages have more categories, this will establish an "index" system, like the ones found in the back of any good informational book. (On a related note, I have also created a glossary page to help with terminology, but this is currently not linked anywhere.) 5. I would like to expand the navigation boxes at the bottom of the wiki pages to have one navbox per category that will contain all pages in that category. It is not practical to have a single navigation box for all modding pages, as there is simply too many pages now. The old system of having one navbox for content mods and one for code mods also doesn't work, as there's too many pages that don't fit into either of those categories. Having individual navboxes will also make it much easier for anyone to add new pages. ----- Thanks for spending the time to read this. I'm hoping to get feedback on: - If you have any of your own issues with the modding wiki. - Agreement or disagreement on any points I have made. - How valid you think the solutions I have given are. - Any further information on the solutions that you think may be relevant, or any solutions that I may not have considered.

Apologies for the slow response - I'm not certain on how much of the game systems are going to be using tags, so I cannot really give a solid answer I'm afraid. I am personally advocating for a lot more to be using the tags system. It is worth keeping in mind, too, that mods can register their own tags.

Collectible & Entity Tags (from 1.22.0) Hi all, The team has had some questions about the new tag system that is being used throughout the assets, so I have collated some information about what they are, what they do, and how/why you should be using them. What are tags? A tag is, simply put, a small piece of text (a string for the coders) that can be attached to an itemtype, blocktype, or entity type. Tags are quite arbitrary, and their purpose is usually determined through other JSON assets or specific pieces of code. In general, tags are being used to describe an object’s use, shape, size, color, crafting capabilities, and more. An item, block, or entity can have a number of tags listed in its appropriate JSON file. What do they do? Currently, tags are being used for satisfying certain conditions in other systems. The two primary examples of this are to satisfy items for recipes, and to satisfy valid entities for AI tasks that require a target. A set of one or more tags (called a ‘TagSet’) can be compared against other TagSets. Specifically, TagSets can either use a basic matching system (e.g. does TagSet A have any of the tags in TagSet B), or tags can be compared against a “ComplexTagCondition”. This allows a group of tags to be matched like boolean properties, using JSON properties like “anyOf”, “allOf”, or “noneOf. The capabilities of the tag system, however, go much further, and I am personally excited to see what directions this new system may take us in. Why should we use them? There are three major reasons that you should be using tags. Runtime efficiency, mod compatibility, and expandability Runtime Efficiency On the surface, tags may appear to be a set of strings that are compared with each other. However, they are programmed in such a way that makes them extremely efficient to be compared, with some parts of the system using a highly efficient method called SIMD. By restricting the maximum number of tags allowed (255 for entities and 65535 for collectibles), tags can be compared extremely quickly, much faster than matching codes and variants. Compatibility Mods can make great use of the tag system. As the tag system develops, certain functionality that requires multiple steps to add to an object may be done with a single tag. Take an example: Before 1.22, to make an axe that worked in the current axe recipes, you would have to either register the new axe item in the game domain, or create an entire new set of recipes for your modded axe. This is not ideal. It takes a lot of time to do, and is much more susceptible to bugs. Now, in 1.22, the new axe can have the “tool-axe” tag. All recipes that need an axe will now be satisfied by that item. No extra recipes, no changing domain, no problems later on. This isn’t all. Mods can define their own tags in recipes for other mods to make use of. In the same example, if Mod A created a recipe that required an object with the “tool-axe” tag, then the recipe will work for any vanilla axes, as well as any other mod that uses the “tool-axe” tag. Looking for a different tag in the recipe is simple, and mods can begin interacting with each other in much more effective ways by using the tags system. Expandability As mentioned earlier, tags allow the team and modders to add content much faster and easier than other implementations. By using tags instead of variants, we can satisfy lists of objects without having to search for block codes and variants. How can you use them? In Content Mods Content mods are likely going to see the most benefit from the tag system right now. As mentioned earlier, tags can be used in recipes for pattern matching, target-able AI tasks, and some others. See the “Using Tags (Content)” page on the wiki for more information and examples on how to use them in a content mod. This page also contains some relevant technical information. In Code Mods Code mods can define their own tag sets in code and use these to check for conditions, but all tags must be registered during or before RunPhase.AssetsReady. See the “Using Tags (Code)” page on the wiki for more information and examples on how to use them in a code mod. This page also contains some relevant technical information. Conclusion Tags are a new system that is quite different to how things have been working in the past, but they are worth using. Over time, more systems may end up using tags and I am hopeful that the advantages of using tags will outweigh the changes to the older systems. Lastly, make sure to take a read of the following pages for more information on using tags: https://wiki.vintagestory.at/Modding:Using_Tags_(Content) https://wiki.vintagestory.at/Modding:Using_Tags_(Code) If you have any questions about tags, or would like to give your opinion on the new system, then please reply to this post. Thanks, Nat

Thanks for writing this! Could you please move the post to https://www.vintagestory.at/forums/forum/35-modding-guides/?

Hmm... There appears to be two ways you can do this - The first is to, as you've said, use the HarvestableBlockBehavior. There is code inside of CollectibleBehaviorHandbookTextAndExtraInfo.cs that controls it being added to the handbook. Perhaps this will give you an idea as to why your previous code did not work?: List<ItemStack> harvestedStacks = []; if (stack.Block.GetBehavior<BlockBehaviorHarvestable>()?.harvestedStacks is BlockDropItemStack[] hStacks) harvestedStacks = [.. hStacks.Select(hStack => hStack?.ResolvedItemstack)]; if (harvestedStacks?.Count > 0) { bool haveText = components.Count > 0; AddHeading(components, capi, "handbook-dropswhen-harvested", ref haveText); components.Add(new ClearFloatTextComponent(capi, TinyPadding)); while (harvestedStacks.Count > 0) { ItemStack hstack = harvestedStacks[0]; harvestedStacks.RemoveAt(0); if (hstack == null) continue; SlideshowItemstackTextComponent comp = new SlideshowItemstackTextComponent(capi, hstack, harvestedStacks, 40, EnumFloat.Inline, (cs) => openDetailPageFor(GuiHandbookItemStackPage.PageCodeForStack(cs))); components.Add(comp); } components.Add(new ClearFloatTextComponent(capi, TinyPadding)); } The second option appears to be to use the 'ICustomHandbookPageContent' interface on your collectible. I haven't personally used it, but it appears to be able to do what you need it to do. It contains a single function 'OnHandbookPageComposed' that is called by the CollectibleBehaviorHandbookTextAndExtraInfo.cs. It appears you may be able to edit the components of the harvested stacks to add in what you need. Take a look at BlockFruitTreeBranch.cs for an example. Good luck!

Indeed; Most of these videos will be one-shot tutorials that are not linked to each other. Perhaps, in the future, we could do some long videos of zero to full mod kind of thing, but it will never be a particularly huge mod.

Hi all - I'm considering making some video tutorials for the existing modding tutorials that exist on the wiki. These will be updated and verified regularly to ensure they remain up-to-date. There is a poll attached that I would be very grateful if you could submit. Thanks!

I'm not 100% sure if it's leaves or grass. Either way, something is using a solid quad rather than its texture.

Mod Development FAQ Please check the following before posting your question! This is a growing list; please feel free to reply to this post for recommendations on any questions that should be added. (Coming soon, thanks for being patient.)

Mod Development Questions/Troubleshooting - Posting Rules, Guidelines & Templates This board is for enquiring about how to achieve something with modding, or for troubleshooting certain issues when making a mod. Rules Either search on the forum or google your issue to try and find if it has been asked before! See the (not yet existent) pinned FAQ post to see if it is on there. If not, then.... Please clearly state what version of the game you are modding. This can be done in the post title or body. Please use the 'solve' feature for when your issue is resolved! If you figure out the issue yourself, or answer your own question, please reply to your own post or edit the post with the answer. Guidelines If you are asking a question, use the 'question' tag. Otherwise, if troubleshooting an issue, use the 'troubleshooting' tag. If you have already tried certain things to solve your issue, note these in your post. It'll help people know what kind of issue you're facing. Template The following is a template that can be used for this channel. You don't have to use it, just as long as you follow the rules. Mod Version: _ Summary: _ Detailed description: _ Already Tried: _