INSTANCE_CUSTOM information regarding accesibility only in vertex shader.

[DJLink]

Your Godot version:4.3

[Issue description:]
Today I spent some time trying to figure out why INSTANCE_CUSTOM was throwing errors until I bumped into this post explaining that INSTANCE_CUSTOM is only accessible in vertex shader and not fragment. I was searching docs but can't find it, so if it's not there I think there should be more information regarding this feature in shader docs or mesh instances.

godotengine/godot#57584 (comment)

[tetrapod00]

INSTANCE_CUSTOM is listed in the spatial shader vertex() built-ins table, and it's not listed in the spatial shader fragment() built-ins table in the same page. It's the same situation in the CanvasItem shader docs. So from that information I would not expect it to be available in fragment().

IMO this is already at least sufficiently documented, but the fact that you're not the first person to run into problems suggests it could be improved. Do you have any suggestions for where else you would be looking for the information? I can think of a few possibilities:

• Is there a place in the docs where INSTANCE_CUSTOM is used in another tutorial that you think could use clarification?
• Perhaps the CanvasItem and Spatial shader reference pages should include a note about not all built-ins being available everywhere, and tell you about using varyings.
• On the engine side, it would be nice if there was an specific error message for using a builtin that is recognized but not available in one function or another. But that's a whole other issue that's beyond the scope of docs :)

[DJLink]

@tetrapod00 Hi, thanks for checking this. I think my problem comes from trying to understand how MultiMeshInstance2D works, saw the set_instance_custom_data and moved from there "how can I get it on the shader side".

Because you are right, now that I see it, only vertex has it, but I was approaching my case from another situation and bumped into this.

• Is there a place in the docs where INSTANCE_CUSTOM is used in another tutorial that you think could use clarification?

Considering set_instance_custom_data() I would probably put some quick mention there, followed by "please see shader docs for detailed information" because it's there.

• Perhaps the CanvasItem and Spatial shader reference pages should include a note about not all built-ins being available everywhere, and tell you about using varyings.

Yes I think having a generic note saying that would alert people for that case, that's a good idea, for people that are just investigating shaders generally.

• On the engine side, it would be nice if there was an specific error message for using a builtin that is recognized but not available in one function or another. But that's a whole other issue that's beyond the scope of docs :)
  That would be nice but beyond this scope yeah :)

[tetrapod00]

In set_instance_custom_data we can specify that it's only in the vertex() function:

This custom instance data has to be manually accessed in your custom shader using INSTANCE_CUSTOM in vertex().

Unfortunately there's not great way to link to the manual (or a specific shader built-in) from the class reference, since the class reference is bundled in the engine we try to avoid fragile links to specific pages (besides the tutorial links at the top of the page). There's been talk of migrating the shader reference to the class reference for this reason

[DJLink]

This custom instance data has to be manually accessed in your custom shader using INSTANCE_CUSTOM in vertex().

May I suggest: (or something you think it's better)

This custom instance data can be accessed in your custom shader using INSTANCE_CUSTOM in vertex(). For access in fragment() you will have to set it manually via varying.

either way it's a good note to have moving forward imo.