Documentation feedback wanted - What would you like to see improved?

[KpoKec]

Documentation is often not detailed enough (like raycastresult detail in raycastall).
Sometimes there is not enough link to github with a class (like rigidbody layers and trigger research).
Sometimes description wrapped by using others naming (like material vs standartmaterial - where description with difference?).
May be create special topic with docs edit request?
Code examples in docs are good and do not cause additional questions ))

[yaustar]

Thanks @KpoKec!

@KpoKec

May be create special topic with docs edit request?

If it’s to do with the API, please post feedback on the engine repo as that’s generated by JS docs.

playcanvas/engine

Tutorials and the user manual feedback would be in this repo https://github.com/playcanvas/developer.playcanvas.com/issues

@KpoKec

like material vs standartmaterial - where description with difference?

Good point, we should really make that more clear which one should be used.

[plasmalasgun]

I would like to have detailed tutorials on using shaders, even though basic rendering dont need them, and the chunks used by playcanvas are listed on git and well optimized, it should be good to have examples ranging from simple vertex transforms, listing the attributes and uniforms, point light, direction light, bumpmapping… only when the programmer understand how these correctly be implemented on playcanvas then he can reinterpret more complex shaders or translate them to the specific glsl version that playcanvas use in comparison to the other types of available code (Ex. Attributes and Varying are considered deprecated, in and out are to be used, transformation matrices are automatically generated and passed to the shader (VP, Light matrices…)

[yaustar]

We are currently working a node based material editor to make this a lot easier. I talk with the developers to see if we can provide more documentation without effectively doing it twice when the new system is published.

[plasmalasgun]

After learning some shaders… ive just realized that they cannot be batched and models that use them cannot be merged as different graphnodes into of a single model (without reverse enginering the batching system) , otherwise we would need a draw call per object and if the model is imported merged as a single fbx object, there is the possibility of bloatness because you need to pass in the entire model that is made of duplicate geometry… being able to merge these models would allow you to ‘fake batch’ your shaders and allow to transform each graphnode addressing them individually

[Leonidas]

@plasmalasgun you can take a look at hardware instancing if you would like finer control over each instance (translation/shading):

https://playcanvas.github.io/#graphics/hardware-instancing.html

Hardware instancing and color

Hi, I’m building a football stadium with thousands of moving plane primitives in the stands, that comprise a card stunt system. Each one will be coloured with a single colour, and will basically act like a pixel in an image, and when assembled together, they’ll recreate that image. I also want to be able to change the image, so in a “wave”, cards will gradually flip around and change to a new colour to reveal a new image within a second or two. I’m using hardware instancing, as explained here:…

[plasmalasgun]

So if I want to use hardware instance, and I have a single model with all the desired parts stored in unique graphnodes… lets call them ‘part0’, ‘part’, ‘part2’… would I need to create 3 mesh instances each with their own vertex buffers to store the matrices of the transformations of each of the parts(3 passes, 1 pass per part)…or should i just cram all parts into a single model and render it with one pass despite duplicate ‘parts’… thanks!

[yaustar]

Could you use batching instead?

[Leonidas]

Hi @plasmalasgun,

For hardware instancing you enable it once per mesh instance. So say you have a tree model with two mesh instances, one for the bark and one for the leaves. You will create two instances arrays, two vertex buffers and enable instancing on each mesh instances.

Check this example on how the code should be structured:

https://playcanvas.github.io/#graphics/hardware-instancing.html

[plasmalasgun]

Can you batch with custom shaders?

[lloydevans]

I came to PlayCanvas with an existing background of web/game development. Here are some thoughts from me:

When I first started using PlayCanvas, I would generally be searching the docs to find out how to create or modify what I’d just set up in the editor via script. I’d often find an editor docs page, but then have to dig around to find relevant API docs. Perhaps links to relevant API pages in the editor docs and possibly the editor itself would be nice.

Another thing I’d commonly be searching for is event names and how the event systems work. It seems the documentation on this has improved and the type definitions also help.

I think improvements on the code editor and ability to use es5+ JS would help beginners a lot. If you are starting out coding the last thing you want to worry about is browser support for JS. At this point a lot of learning resources and code libs/examples are es6 JS so that’s going to be a point of confusion for people new to it.

Improvements to type definitions would be nice. I’ve encountered a handful of missing and incorrect types which I need to create issues for.

The docs search function is basic but does the job. The forum via Google will often be a source of info too.

My dream in terms of scripting environment would be ability to use ES6 and TS in an editor much like stackblitz (monokai). This puts most of the docs you’d ever need to look up right in the editor. Until then I set things up in an offline code editor unless it’s very small scripts.

The examples are awesome and do a great job of inspiring and showing what playcanvas can do. It seems a lot of the demo code is set up using playcanvas engine only, which is nice in that it’s totally self contained, but also a little inconvenient that you get some boilerplate code not really necessary for the example.

[yaustar]

Thanks for the detailed feedback!

@lloydevans

When I first started using PlayCanvas, I would generally be searching the docs to find out how to create or modify what I’d just set up in the editor via script. I’d often find an editor docs page, but then have to dig around to find relevant API docs.

Can you give an example on what you were looking for and where your search had led you?

@lloydevans

Until then I set things up in an offline code editor unless it’s very small scripts.

Out of interest, are you using our playcanvas-sync tool on GitHub?

@lloydevans

It seems a lot of the demo code is set up using playcanvas engine only, which is nice in that it’s totally self contained, but also a little inconvenient that you get some boilerplate code not really necessary for the example.

Just to clarify, are you referring to the examples at playcanvas.github.io and would you like to see the same or similar examples via the PlayCanvas Editor?

[lloydevans]

Can you give an example on what you were looking for and where your search had led you?

Thinking back I wasn’t familiar with playcanvas and how it adds objects on entity like sound, element etc. or the addComponent method on entity. There wasn’t the detailed info on the string type passed to addComponent when I was looking.

Say I add add a sound component in editor, what I need to know is something like:

entity.addComonent("sound");
entity.sound.volume = 0.5;

And the API page SoundComponent | PlayCanvas API Reference

My search to getting these things will be on the API docs finding the Entity and SoundComponent pages.

Out of interest, are you using our playcanvas-sync tool on GitHub?

Yea I am using it and it makes setting up the offline editor quite easy which is great.

Just to clarify, are you referring to the examples at playcanvas.github.io and would you like to see the same or similar examples via the PlayCanvas Editor?

Yes, those are the ones. Possibly would be nice, yes. I don’t mind either way but might make them a little more readable and also help ensure they are up to date with latest engine.

[underlight]

From perspective of a seasoned PlayCanvas developer - the biggest drag for me is obscure and unfinalized Shader Chunk API. Advanced commercial projects usually require custom shaders and postprocessing - and even though the basic examples can be found in tutorials I still have to go through program lib / shader sources every time I want to make something custom.

Another thing - the source code itself could be improved in terms of readibility and comment / code ratio (I mean not counting JS docs which serve different purpose). For example - Lightmapper.bake is huge monolithic function completely obscure to anyone willing to customize / improve it. GraphicsDevice, ForwardRenderer would also greatly benefit from splitting functions into simpler ones and commenting a majority of non-obvious steps.

Cheers!

[Gamer_Wael]

I wanted to play around with XR but I couldn’t find any documentation for pc.XRTRACKABLE_PLANE and pc.XRTRACKABLE_POINT. That would be helpful. Thanks!

[yaustar]

If you scroll down to options.entityTypes on this page, XrHitTest | PlayCanvas API Reference does that help?

[Gamer_Wael]

Ah yes! Thanks.

[Gurki]

for me as a kind of noob, I rather google for help insted of using Your search function becouse I get results from tutorials, forum and gitHub. I think I abuse the Your forum a little bit, Your feedback is so amazing, I rely to much on it (sorry)

[yaustar]

The developer.playcanvas.com search now includes the forum. Not 100% sure if usually l should include GitHub though

[moka]

Biggest feedback, is that I would move API Reference generation code, into https://github.com/playcanvas/developer.playcanvas.com/ repo, so it can be contributed to.