Ensure every visual script node has an unique documentation page with user tutorials and input

[jasperbrooks79]

Describe the project you are working on: A Tomb Raider game . .

Describe the problem or limitation you are having in your project:

This is about making the docs better, not visual script, wanted to ask separately . . This alone, is very important, imo . . I semi-asked this in another topic, but that was about making visual script better, the experience, not separate doc system . . I suspect the other stuff might not get made, but this is so important, I hope it gets done . . .

A problem with visual script is, the more complex boxes are very difficult to use . . I have suggested this before, but this is so important, I want to ask, for this alone . . It would be nice if there was a button, or maybe one could shift-double click a visual script node, to go to a dedicated page, for each box, with basic information, and examples . . This is a massive work, for the team making visual script, so my idea is, all users can add tutorials or, explanations to those pages, like on the Godot Q&A page, where one can add images, and animated gifs, to show how it works . . If the visual script experts simply made such a button, or a direct docs reference, on each box, the user community would fill it out, over time, meaning less work for the visual script team, and to focus on function and, power of visual script, and not documentation . . For instance, I could click on that page, and add a tutorial example, with static images, or even animated gifs, that'd be a NICE documentation update, or so . .

The problem is, making a video tutorial, about the whole visual script system, takes a lot of work, but when I had 30 minutes, or was on a break, between making levels, visual code, I could think about, having used a new or, difficult visual script box, how to make a nice, featured tutorial, like so . . That way, the official docs for visual script would get filled out, over time, and the team making it could focus less on that, and more on just making it amazing, thanks . .

Describe the feature / enhancement and how it helps to overcome the problem or limitation:

We need a better way, for the community to make simple, precise tutorials, atm the official docs for visual script are very lacking, in terms of examples, especially for more advanced boxes . . This feature, and this is really more about making the docs system more useful, which is maybe a wrong title, it's purely about making docs, anyway I'd love to contribute, over time, to making the docs better . . Each box just needs it's own web-page, ie. Math ADD has it's own, Math MULTIPLY has it's own, that can be accessed by clicking a page, or for the math boxes, a common page, since math boxes are mostly the same, changed through settings . . I needed to change a material, or texture from code, and it took me two days, with help . . I'd love to be able to write a little tutorial, using pictures, that then got ' connected ' to that box, for future users, that might need nicer docs . . If just one person figures something out, and writes a short 5 - 10 minute tutorial, visual script would be much more user-friendly, documentation-wise . . .

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams: Like before, if each box had a ' ? ', where one could go to official online docs, and then add written or, tutorials with pictures, it'd be a fun and, super-quick way, of making the docs complete, something that is missing, atm . . :O

If this enhancement will not be used often, can it be worked around with a few lines of script?: Not sure, I wanted to suggest this as a separate idea, as it would help the community, and from current official docs, I'd say it's so much work, it's like the core team has given up, to some extent . . Let the community help, it could be fun, I like to help, where I can . . .

Is there a reason why this should be core and not an add-on in the asset library?:

It would just be fun, and also an honor, to contribute to the engine, even in some small way, and it would mean, one wouldn't have to search the internet for 30 minutes, to find out how an obscure box worked, just click, and boom, you have it . . . :)

[jasperbrooks79]

I spend a lot of time asking questions, to learn the engine, and with this feature, the docs would more quickly fill out, and having figured something out once, I would not need to ask, so much, on the internet . . . <3

Also, I would love, to spend 30 min - 1 hour, thinking about, how to make a good tutorial, very informative, so nice . . And, to say I contributed a little bit, even only docs, to Godot, would make me feel good, about life <3 . .

Thx . . I many not be able to code, like, the engine, but being able to help in such a small way, it'd be awesome . . .

[fire]

There are two types of visual script nodes.

1. There are ones converted from the class db documentation. These are exactly the same as the gdscript function calls. I don't think we can do much here.

2. The visual script specific nodes. https://docs.godotengine.org/en/stable/classes/class_visualscriptnode.html#class-visualscriptnode

Edited:

What do you suggest?

[jasperbrooks79]

If you read those lists, ie basically all of those node boxes don't have a. examples of use-cases, and, b. the documentation is not very clear, for new users, ie it's basically lacking documentation . . As a first time users, even if I read the link you described, when I actually try and use visual script, I get pretty much nowhere . .

Also, take for instance, the visual script box, when you drag a texture in, if you want to animate or, shift it, with code, IF player certain distance, change color of, a sign, or so . .

That box is nowhere on that list, and to make it work, it needs and obj and, a link to the texture ' Preload ' .. It's pretty obvious the texture reference, is just drag the res folder texture in, one wants, but the obj, it took me two days to figure out, what that was . . With help, from the internet . .

The SET texture, after moving a texture into visual script canvas, is not described, on that list, again the already known list of visual script nodes, for new users, is almost useless, as it is a single line description, and then a list, of methods, but no examples, or use cases, ie tutorials, or images, or animated gifs, of HOW they work . . I read all those visual script node descriptions, and it made me about 2 - 4 % smarter, not 100 %, about what visual script can do . .

Imo, every box one can create in visual script needs a page, which could happen if each box got a link, by having a ' ? ' in it, somewhere, that took one to a unique page, since it's a lot of work . .

Point is, I read all the stuff, in that link, and to be honest, it didn't help, very much . . There's just not enough information or, examples, tutorials, or use-cases, ie one could use this box for so, and last, there's a TON of boxes, that isn't on that list, ie if you drag in a texture, from node inspector, into visual script, you get a box SET_texture, which it is difficult to make work, and is not on that list, so no explanation, in the docs . .

If you made so, each visual script box had separate web-page, and they just linked to a page, where people could write, tutorials, pictures, examples, over time EVERY box would get described, or so . . ie, you don't need to do more, than 5 % of the documentation, users will finish it for you, over time . . Thx . . .

[jasperbrooks79]

Imo, a web-page where users can add a, clear use-cases and, b. expand the documentation, would be really good, and that list of visualscript nodes, there's a lot more, in Godot, for instance how does one use the Get Scene Tree visual script box, in reality, you drag it in, then you have to drag out the obj port, to ' find ' the methods, inside . . It doesn't say this, on the page, ie there isn't an example, or tutorial, for a common use-case, below the official, brief description, result is, when you try to use the box, as a new user, you get stuck, because while it is ' there ', the information, it's so brief and, quick, one doesn't learn to use the box . .

I hope that makes sense, we need some tutorials, or common use cases, for each box, on all those pages, to see how they work, frankly put, the current docs don't help, if you're a new user, it's not, expanded enough . .

If users could write short tutorials, or upload images, or animated gifs, with good tutorials, the docs would actually help, instead of being a copy, of what GDScript says, without including how the visual script boxes actually work, in reality . . . :O :O

[jasperbrooks79]

Like we need, 1 - 3 tutorials, what are the most common uses, of a box, and how does on do that, so each page has some short, common use- case tutorials, maybe with 1 - 2 animated gifs, ie tutorials, examples, with pictures, and, longer description . . .

Since Godot 4.0 might be getting a new visual script system, this might be redundant, ie changing the current docs, but in Godot 4.0, if visual script gets changed, I strongly suggest EACH box one can possibly make, has a ' ? ' button, if one clicks it, one goes to a separate page ( for MATH, since add and subtract, are basically the same box, it would be math it links to, ie one can change a subtract box, to add math box, by changing the math box, ie it's the same box, or so, logically ) . . On that page, users can add descriptions and, an example, of how it works, precisely . .

Without those examples, you might as well throw out the current list, it's basically useless, for new users, or people that don't know GDScript, and can code, so they know how everything works, anyway, thx . .

[jasperbrooks79]

Sry, it's tough to explain, the current docs aren't good enough, no examples or, tutorials, short ones . .

[jasperbrooks79]

Here's an example, on the Scene Tree page, it doesn't clearly show, or say, to make the box work, one needs to drag out the obj port, ie if I read the page, I won't be able to make the box work, ie there's not good tutorials, or examples, that would make it clear, exactly how the box works . .

Result is, when I start reading the docs, I still don't know how to actually use the box, ie, there's no tutorials, clear examples . .

IF each box got a ' ? ' on it, and if one clicked it, one went to a web-page, where there is a description, but also examples, even made by users, over time, the community would fill out the docs, for you, ie no work, you can focus on working, on the engine, instead of making docs . . . Which, is better, for all, ie you have more fun, and we get better docs . .

My proposal is, EVERY single box one makes ( some of them are grouped, ie MATH Add, and MATH Substract are, technically the same box, in visual script, one just changes in inspector, for it add instead, of subtract ) . . So, on that page, if it takes too long to make it, some day, when a user uses that box, and makes it work, he can make a little tutorial, or write some text, about maybe there is a bug, as there is in some boxes, then how to make it work, or a brief written example, like ' To make Get Scene Tree node to work, one needs to drag the obj port out, to access it's functions, or methods ' . . . That way, the docs actually teach you, HOW to use it, instead of what is happening right now, where after reading the official docs, one still can't make the nodes work, when one actually wants to, or so . . Hope, makes sense, thanks . . .

[jasperbrooks79]

Like, after reading the official docs, you don't actually know how to make the actual boxes work, after making them, in own projects, or so . . Because, there are no mini-tutorials, or so, if each box got a ' ? ', see above, which took to a page, where users could fill out docs, visual scripting would get documented much better, and there could even be tutorials, with animated gifs, or normal images, that show it . .

That way, when I've read that page, I know how to make the box work, and a few tutorials, of common use cases, as well . . . :O

ie, if you after making Scene Tree node, don't know you have to drag out, the obj on it ( see animated gif example above ), you will never be able to make it work, that isn't clear, on the page, on the list above, and it is confusing where to find, that information . . It took me 2 - 3 days, to figure that out, and asking on the internet, ie I feel the docs could be better, if AFTER the strict, basic information, there were written tutorials, possibly with pictures or, animated gifs, or so . .

By having a ' ? ' in each box, that takes one to a web-page, over time, users would complete the docs, for the boxes that don't have good enough documentation, like, that's the idea, thx . . That means, you can focus more on making more features, and less time documenting things . . ie, we get a better engine, and also better docs, for all users, also experienced . . :(

[jasperbrooks79]

Also, instead of making a 1-hour tutorial, on youtube, if one could add a simple, accurate example, for 1 - 2 pictures, and some text instead, of the docs page, it would be a lot easier, to make docs better, ie tutorials, since it takes a lot of planning, to make a good 1 - hour tutorial, or 30 minute one, but writing a clear example, for any visual script box, and making some images, it would take like 5 - 10 minutes, maybe 15 minutes, and booom, the official docs will work well, for all users . . . Thx . . .

So, after spending 2 - 3 days online, to figure out how a box work, I could spend 10 - 20 minutes writing about it, how it works . .

Here's a better example, this box looks simple, but what inputs it needs, it took me 2 days online, asking others, how it works . .

The point is, that is a very obscure box, but if Godot was set up, so every box you could make, had it's own page, where users could contribute, after making it work, I could spend 30 - 40 minutes, thinking of a good example, and add that, to docs . .

I didn't know what inputs the ' SET texture ' box needed, it turned out, to be really weird . . Since making all this documenation is, a. boring, and b. takes away, from engine makers to make the best features, it would make it easier, if the boxes had a ' ? ', so users could help fill out the docs, that way, after 2 - 3 days, trying to make it work, I could upload a animated gif, with a few words, as a user example, so the docs made sense, for all users . . .

Also, you can focus on making the engine run better, and users can fill out the docs, over time, that's the idea . .

[TheDuriel]

I'm sorry, but the issue here seems to be a lack of understanding of underlying GDScript Code, and programming in general. Rather than an issue with the visual script editor itself.

And the act of dragging out Connections to open the context sensitive new node dialogue, is clearly explained in the Docs.

In these last examples, when I see an obj output it is clear to me that this is the Texture Resource Object Reference.

This is your node in code: var mytexture: Texture = preload("filepath)

And the identifier of that variable mytexture, is the obj output of that node.

[jasperbrooks79]

That's exactly the point, one has to learn GDScript, to actually use visual script . . So, it's not for artists, or prototypes, or so, well, not sure . . .

That's the point, the two inputs, the lower is for the Res location, or preload, but to get the correct ' box ' for the upper obj input, I have to drag the material out, again, which makes no sense, since by dragging it out, I assume it is understood, it is that material, I want to change . . It actually took me two days, also asking on forums, to figure that out, so the boxes certainly work, but if there was a web-page, for each box, one could read it there, which I think makes sense . .

GDScript coders, with a ton of experience, will know what to do, but for new users, or artists, that just want to make a simple, easy game, with a controller and, a few effects, it is anything but logical . .

Adding a ' ? ' to each box, even changing textures, would mean anyone could start using visual script, anyway the more advanced boxes I use, this problem becomes bigger . . As I see it, this would solve, and experienced GDScript users wouldn't have to use it . . This way, visual script could become a way to learn or, make games in Godot, on a much greater level, ie people won't give up, or so . .

I understand the idea, that if you know GDScript, all this stuff won't be a problem, the reason I picked up visual script was, because I didn't want to learn code, to start making games, and to people like me, that want to start telling stories, and care less about the technical, the documentation could be better, hence, the proposal, thx . .

I suppose if the current scope, for visual script, is that it's mostly for people, that know GDScript, by doing this, and letting the community do most of the work, filling out the various boxes, over time, I'd LOVE to help, and make really thoughtful, and excellent tutorials, anyway, that is my proposal, so I can begin making games, and not asking questions on the internet all the time, when I move in a new box, and yes some of them are so complex, not everything can be explained, but IF tutorial section for visual script was like that, 98 % of, the questions new users have, would disappear, ie, no trouble, also it would mean users could use Godot even faster, also artists, which I don't see as a bad thing, I find coding intimidating, like a big hurdle, I plan to learn it, ASAP, but right now just using the engine, learning various stuff, has taken some energy, learning routines, or so . .

PLEASE, consider this, as it would be a way of lowering the entry level, for Godot, and would help artists, that focus more on story, or simple graphics or, sound to start making something, that works . . .

Thx . . :O

[jasperbrooks79]

As far as I remember, this is how the box actually works . .

It makes little sense, that I after dragging the texture I want to change in, that I have to tell it again, I want to change the texture, on that material . . IF the boxes had a docs page, with this animation on it, also a small explanation, then new users wouldn't have that problem, took me two days, also asking on the internet . . .

[jasperbrooks79]

I may have misunderstood the purpose of visual script, ie the people behind it always assumed, one would have to learn GDScript first, to really master it, make sense of it . .

If my idea, of having a ' ? ' in the top bad, or a lower bar, that can be expanded, or collapsed, and each box type had a unique web-page, then the community, I'd love to be of help, could actually help that happen, so you just have to set up the web-page, and give some guide-lines, for the tutorials, ie keep them short and, precise, to the point, sort of . . If you did that, visual script, beyond a basic level, would be a much better and, easier thing, to use, as an artist, wanting to make games, yet not knowing how, at all . .

Thx . . .

Again, as a person, who tries do use visual script, this would help me a lot, and I'd like to contribute, and also make visual script better, in other ways, ie making it easier, to learn GDScript from ( another proposal, here ) . .

For me, visual script is the primary way of making games, and THIS would make it 100 % easier, and, waste less time, googling, or asking on the internet, ie it makes sense, imo . . It would really be a big, big help, so please consider it, it would also be little work for you, as users would fill it in, for you . . . :O

[jasperbrooks79]

IF there was a ' ? ' on each box, somewhere, maybe in top bar, or in a corner, and I could go there, then after I have finally figured out, how to make a complex box, like change a singleton, from a scene work, which after asking online, is anything but easy, or intuitive, I could fill that out, and other people wouldn't have to search so much, or ask so many questions, the problem is, it often takes 2 - 3 days, to find someone who knows, or wants to take the time, to test it, and make it work, a written coder . .

Imo, that's not needed, and this system would wildly make visual script more useful, this feature alone, would save new users 100 days, of asking, for various boxes, in making a game . . . As someone who primarily ( exclusively ) uses visual script, this would be a boon, thx . . :''OO . .

It would mean a lot, and I'd love to help, making some truly amazing, and useful tutorials, or cases, for each box . .

[jasperbrooks79]

IF you don't want a ' ? ' mark, inside each box, you could make a ' HELP ' mode, where the mouse gets a ' ? ' next to it, or if you shift-ctrl click a box, it takes you to docs, or shift-ctrl double-click . . :) . .

That way, each time I figure out a difficult box, I can write a little tutorial, either just text, or maybe some animated gifs, if it's not already there, or the current docs, and other tutorials on the page, isn't enough, 1 - 2 tutorials for a box, a complex one, should be enough, to help people . . Please, consider . . .

I frickin love visual script, this would make it 140 % better . . :(( . . . .

Or, you could make a setting, where if one double-clicks a title or, top bar of a box, that takes on to docs, or so . . Having a separate mouse-mode, ie hold down a button, and a little ' ? ' is next to mouse, then if you click a box, it takes to docs and, examples, would be so nice . . It may not be useful to GDScript coders, but as a struggling artist, who loves Godot, this would make everything 200 % easier or, more . . . .

[jasperbrooks79]

The idea is, if someone like me, a more artist-minded person, wanted to make a game, instead of spending 2 - 4 months asking questions, googling for really obscure answers, or just waiting for someone to answer, which doesn't always happen, having something like this, would speed up this tremendously, and it makes sense, why not have a description, of every box, that takes one to a doc page, in the editor, it seems logical, and easy, for the engine devs, as well, if the community can fill it out, no work . .

For me, it would have saved a ton, of time, basically . . . Thx . .

Just write on the intro page, since the dev team doesn't have time, to write all the tutorials, that go with official docs, it takes away from making the engine, the community can add these, as they are needed, either written, or written with pictures, or animated gifs . . Then, it works, like fast, easy . . Sry . .

[YuriSizov]

Closing this proposal as we have officially discontinued the VisualScript module. It may return in future as an engine extension, then all the feedback can be reevaluated by maintainers of that extension.

Thanks for your suggestion nonetheless!